Swipe Match 为客户寻找经纪人，并依次把线索推送给经纪人。通过 API，合作经纪人（或机构）可以看到推送给自己和分配给自己的线索，并报告与客户之间的进展。读取需要 leads:read 权限范围，事件需要 leads:write。不收费。
线索
curl "https://developers.grem.capital/api/v1/match/leads?view=active&limit=20" \
-H "Authorization: Bearer gsk_live_xxx"
GET /match/leads：
| 参数 | 说明 |
|---|---|
view | active（默认）：分配给您的线索；inbox：向您开放的推送。机构密钥可看到机构经纪人的线索和推送 |
stage | 按阶段筛选 |
page、limit | 页码；limit 最多 50，默认 20；limit 或 page 小于 1、limit 超过 50 或 page 超过 1000 返回 400 |
GET /match/leads/{id}：单条线索；GET /match/leads/{id}/events：其历史（您的事件和推送；不含资金或系统事件，也不含客户评价）。他人的线索：404。
在您的账户开放 Swipe Match 的 API 访问之前，这些请求返回 409，带 code: not_available。
线索字段：
| 字段 | 说明 |
|---|---|
id、stage | ID 和阶段 |
clientType | buyer 或 seller |
country、objectId、objectIds | 国家和需求涉及的房源 |
budget | min、max、currency |
answers | 客户的回答：budget、timeline、payment |
qualScore、qualBand | 线索质量评分 |
clientInitial | 客户姓名的首字母 |
offer | 您的未结推送：id、wave、offeredAt、deadline |
contactDeadline、meetingDeadline | 联系和见面的截止时间 |
deal、reservation、dealObjects | 交易和预订数据 |
client | 客户的 name 和 phone：仅在线索分配给您并公开联系方式之后 |
brokerId | 当前视图所属的经纪人 |
fee | 平台对此线索向您收取的费用：none、percent（您所得佣金的该百分比，见 percent）或 contract（按协议）；不含金额 |
阶段（stage）：new、offered、intro、match、contact、meeting_scheduled、meeting_held、contract、deal、closed、lost。
您在线索上的操作
POST /match/leads/{id}/events：仅适用于分配给您的线索。模块会检查该步骤在当前阶段是否允许。
event | 字段 | 含义 |
|---|---|---|
FIRST_CONTACT | channel：phone（默认）或 messenger | 您已联系上客户 |
RESERVATION | amount、currency（3 个字母）、date；documentFileId 可选 | 客户已支付预订金 |
STAGE_ROLLBACK | reasonCode：client_withdrew、seller_withdrew、financing_failed、documents、other；text 最多 500 | 将线索退回上一阶段 |
LEAD_LOST | reasonCode：client_refused、client_unreachable、bought_elsewhere、not_target、other；text。其他原因返回 400 | 线索流失 |
DEAL_CLOSED | objectId、amount、currency、date、documentFileId；commissionReceived、commissionCurrency 可选 | 交易完成 |
documentFileId：通过 POST /uploads 上传的文件 ID（文件）。reasonCode 不在其列表中返回 400；LEAD_LOST 使用 other 时 text 为必填（缺少则返回 400）；STAGE_ROLLBACK 仅在使用 other 时保存 text。
curl -X POST https://developers.grem.capital/api/v1/match/leads/LEAD_ID/events \
-H "Authorization: Bearer gsk_live_xxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: fc-LEAD_ID-1" \
-d '{"event":"FIRST_CONTACT","channel":"phone"}'
响应：lead 为转换后的线索；如果是使用同一个 Idempotency-Key 的重试，则为 replay: true。客户方的步骤不通过 API 发送。这里的 Idempotency-Key 为 8-128 个字符：字母、数字、_ . : -；其他格式返回 400 validation。
拒绝以 409 返回，带 title: business_rule，原因在 code 中：
| 原因 | code |
|---|---|
| 当前阶段不允许该步骤 | invalid_transition |
| 属于客户事件，经纪人不应发送 | client_event_rejected |
| 模块尚未向 API 开放 | not_available |
事件
match.lead.offered、match.lead.offer_closed、match.lead.matched、match.lead.updated、match.lead.unassigned：见 Webhooks。事件中永远不含客户的联系方式。