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 - id файла, загруженного через POST /uploads (Файлы). reasonCode вне своего списка - 400; для LEAD_LOST с other поле text обязательно (без него 400); для STAGE_ROLLBACK text сохраняется только с other.
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 - лид после перехода, replay: true - если это повтор с тем же Idempotency-Key. Шаги клиента через 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 - см. Вебхуки. Контактов клиента в событиях нет никогда.