Swipe Match busca un agente para un cliente y ofrece el lead a los agentes por turnos. Por API, un agente asociado (o una agencia) ve los leads que se le ofrecen y se le asignan, e informa de sus pasos con el cliente. La lectura requiere el ámbito leads:read; los eventos, leads:write. No se cobra.
Leads
curl "https://developers.grem.capital/api/v1/match/leads?view=active&limit=20" \
-H "Authorization: Bearer gsk_live_xxx"
GET /match/leads:
| Parámetro | Descripción |
|---|---|
view | active (por defecto): leads asignados a usted; inbox: ofertas abiertas para usted. Una clave de agencia ve los leads y ofertas de los agentes de la agencia |
stage | filtro por etapa |
page, limit | página; limit hasta 50, 20 por defecto; limit o page menores de 1, limit mayor de 50 o page mayor de 1000: 400 |
GET /match/leads/{id}: un lead; GET /match/leads/{id}/events: su historial (sus eventos y ofertas; sin eventos de dinero o de servicio ni valoraciones del cliente). Un lead ajeno, 404.
Mientras Swipe Match no esté abierto a la API en su cuenta, estas solicitudes responden 409 con code: not_available.
Campos del lead:
| Campo | Descripción |
|---|---|
id, stage | id y etapa |
clientType | buyer o seller |
country, objectId, objectIds | país y los inmuebles a los que se refiere la solicitud |
budget | min, max, currency |
answers | las respuestas del cliente: budget, timeline, payment |
qualScore, qualBand | puntuación de calidad del lead |
clientInitial | la primera letra del nombre del cliente |
offer | su oferta abierta: id, wave, offeredAt, deadline |
contactDeadline, meetingDeadline | plazo para contactar y para reunirse |
deal, reservation, dealObjects | datos de la operación y de la reserva |
client | name y phone del cliente: solo cuando el lead se le ha asignado y el contacto se ha revelado |
brokerId | el agente cuya vista se muestra |
fee | la comisión de la plataforma sobre este lead para usted: none, percent (ese porcentaje de la comisión que usted recibe, en percent) o contract (según contrato); nunca importes |
Etapas (stage): new, offered, intro, match, contact, meeting_scheduled, meeting_held, contract, deal, closed, lost.
Sus pasos con un lead
POST /match/leads/{id}/events: solo para un lead asignado a usted. El módulo comprueba que el paso está permitido en la etapa actual.
event | Campos | Significado |
|---|---|---|
FIRST_CONTACT | channel: phone (por defecto) o messenger | ha contactado con el cliente |
RESERVATION | amount, currency (3 letras), date; documentFileId, opcional | el cliente ha pagado una reserva |
STAGE_ROLLBACK | reasonCode: client_withdrew, seller_withdrew, financing_failed, documents, other; text, hasta 500 | devolver el lead a una etapa anterior |
LEAD_LOST | reasonCode: client_refused, client_unreachable, bought_elsewhere, not_target, other; text. Otro motivo: 400 | el lead se ha perdido |
DEAL_CLOSED | objectId, amount, currency, date, documentFileId; commissionReceived, commissionCurrency, opcionales | la operación se ha cerrado |
documentFileId: el id de un archivo subido con POST /uploads (Archivos). Un reasonCode fuera de su lista es 400; para LEAD_LOST con other el text es obligatorio (sin él, 400); para STAGE_ROLLBACK el text solo se guarda con 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"}'
Respuesta: lead, el lead tras la transición; replay: true, cuando es una repetición con el mismo Idempotency-Key. Los pasos del cliente no se envían por API. Aquí Idempotency-Key tiene 8-128 caracteres: letras, dígitos, _ . : -; otro formato es 400 validation.
Los rechazos llegan como 409 con title: business_rule y el motivo en code:
| Motivo | code |
|---|---|
| el paso no está disponible en la etapa actual | invalid_transition |
| un evento del cliente, los agentes no lo envían | client_event_rejected |
| el módulo aún no está abierto a la API | not_available |
Eventos
match.lead.offered, match.lead.offer_closed, match.lead.matched, match.lead.updated, match.lead.unassigned: vea Webhooks. Los eventos nunca contienen los contactos del cliente.