API de consulta
Permisos de la API key#
Usa la misma API key de la organización, pero cada clave solo puede hacer lo que un administrador le haya permitido en Configuración → Integraciones → API Key → Permisos:
| Permiso | Qué permite |
|---|---|
webhooks:write | Enviar leads, tareas y citas (API de leads). |
leads:read | Leer leads, embudos, etapas e historial de etapas. |
inventory:read | Leer proyectos, inmuebles y unidades. |
appointments:read | Leer citas y visitas. |
payments:read | Leer los pagos recibidos en los negocios (cartera). |
leads:write | Crear y actualizar leads, moverlos de etapa, notas (API de escritura). |
tasks:write | Crear tareas. |
appointments:write | Agendar citas. |
Las claves que ya existen no cambian
Una clave creada antes de que existieran los permisos solo tienewebhooks:write: sigue enviando leads igual que siempre y no puede leer nada hasta que un administrador le active un permiso de lectura. Lo más seguro es crear una clave aparte para cada sistema que lee.La clave va en el encabezado X-API-Key o como Authorization: Bearer yave_…. Si le falta un permiso, la respuesta es 403 y el mensaje dice cuál.
curl https://api.yavehome.com/api/v1/external/me \
-H "X-API-Key: yave_3f9a…c21e"{
"organization": {
"id": "cm1…",
"name": "Constructora Ejemplo",
"slug": "constructora-ejemplo",
"countryCode": "CO",
"currency": "COP",
"timezone": "America/Bogota"
},
"apiKey": {
"id": "cm8…",
"name": "Tablero de BI",
"scopes": ["leads:read", "inventory:read"]
}
}Paginación#
Los listados devuelven { "data": [...], "nextCursor": "…" }. Para la página siguiente, repite la petición con cursor=<nextCursor>. Cuando nextCursor es null, no hay más. El cursor no se salta ni repite registros aunque entren leads nuevos mientras recorres las páginas.
limitnumbercursorstringnextCursor de la página anterior. Sin él, empieza desde el principio.Leads#
/external/leadsleads:readsort-createdAt | updatedAt-createdAt (por defecto): los más nuevos primero. updatedAt: del cambio más viejo al más reciente, para sincronizar (ver abajo).createdSince · updatedSinceISO 8601pipelineId · stageIdstring/external/pipelines).phonestringemailstring{
"data": [
{
"id": "cm9k2…",
"name": "Laura Gómez",
"email": "[email protected]",
"phone": "+573001234567",
"source": "LANDING",
"channel": "WEB",
"pipeline": { "id": "default", "name": "Ventas" },
"stage": { "id": "s-visita", "name": "Visita agendada" },
"opportunityStatus": "ACTIVE",
"lostReason": null,
"score": 72,
"budget": 350000000,
"projectId": "cm4p…",
"projectStage": { "id": "cm6e…", "name": "Torre 2", "code": "T2" },
"assignedTo": { "id": "cm2u…", "name": "Carlos Ruiz", "email": "[email protected]" },
"utmSource": "facebook",
"utmMedium": "paid",
"utmCampaign": "torre-2-preventa",
"utmContent": null,
"utmTerm": null,
"tags": ["Torre 2", "Preventa"],
"createdAt": "2026-09-28T15:04:12.511Z",
"updatedAt": "2026-09-29T10:22:40.100Z",
"lastContactAt": "2026-09-29T10:20:00.000Z",
"convertedAt": null
}
],
"nextCursor": "MjAyNi0wOS0yOFQxNTowNDoxMi41MTFafGNtOWsy…"
}stage es la etapa del embudo. projectStage es otra cosa: la etapa del proyecto que le interesa al lead (Etapa 1, Torre 2…), o null si no se ha marcado.
/external/leads/{id}leads:readEl mismo lead, más stageHistory: sus últimos 100 cambios de etapa (from, to, by y at), el más reciente primero. by dice quién lo movió: USER, AI, WORKFLOW, WEBHOOK, etc.
Sincronizar sin traer todo cada vez
- La primera vez, recorre
/external/leads?sort=updatedAthasta quenextCursorseanull. - Guarda el
updatedAtmás reciente que recibiste. - En las siguientes corridas pide
?sort=updatedAt&updatedSince=<ese valor>: llegan solo los leads nuevos o modificados. Un lead puede repetirse en el borde; actualízalo porid.
Embudos y etapas#
/external/pipelinesleads:read{
"data": [
{
"id": "default",
"name": "Ventas",
"isDefault": true,
"stages": [
{ "id": "NEW", "name": "Nuevo" },
{ "id": "s-visita", "name": "Visita agendada" },
{ "id": "WON", "name": "Ganado" }
]
}
]
}Inventario#
/external/projectsinventory:readProyectos activos: nombre, ubicación, imágenes, enlaces (video, tour, brochure), fecha de entrega y moneda. Cada proyecto trae stages, sus etapas en orden comercial.
"stages": [
{
"id": "cm6e…",
"name": "Torre 2",
"code": "T2",
"status": "PRESALE",
"estimatedDeliveryDate": "2028-06-30T00:00:00.000Z"
}
]/external/propertiesinventory:readInmuebles y unidades en todos sus estados (a diferencia del catálogo público, que solo muestra lo disponible). Ordenados por updatedAt ascendente, así sirven para sincronizar la disponibilidad. Cada unidad trae projectStage (id, name y code de la etapa del proyecto, o null) y building (torre, edificio o bloque).
projectIdstringprojectStageIdstringstages en /external/projects).statusenumAVAILABLE, RESERVED, SOLD, RENTED, FROZEN, BLOCKED, INACTIVE.listingTypeSALE | RENTupdatedSinceISO 8601Citas#
/external/appointmentsappointments:readfrom · toISO 8601leadIdstringstatusenumSCHEDULED, CONFIRMED, COMPLETED, CANCELLED, NO_SHOW.Pagos recibidos#
/external/paymentspayments:readLos pagos registrados en los negocios de cartera de la organización: lo que el comprador abonó, cuándo, por qué medio, a qué cuota y a qué negocio. Sirve para llevar el recaudo a tu ERP o a tu contabilidad, o para conciliar contra el banco. Llegan los pagos que cartera ya verificó y los que esperan verificación; verified dice cuál es cuál.
sort-paymentDate | updatedAt-paymentDate (por defecto): los pagos más recientes primero. updatedAt: del cambio más viejo al más reciente, para sincronizar igual que los leads.from · toISO 8601from (incluida) hasta antes de to. Por ejemplo, el recaudo de octubre es from=2026-10-01&to=2026-11-01.updatedSinceISO 8601dealId · projectId · leadIdstringkindCAPITAL | NON_CAPITALCAPITAL abona al precio del inmueble y baja el saldo. NON_CAPITAL son intereses, mora u otros cobros que no lo bajan.verifiedtrue | falsetrue: solo los que cartera ya verificó. false: solo los que esperan verificación.{
"data": [
{
"id": "cmp7x…",
"amount": 15000000,
"currency": "COP",
"paymentDate": "2026-10-15T00:00:00.000Z",
"paymentMethod": "BANK_TRANSFER",
"kind": "CAPITAL",
"reference": "TRX-889123",
"bankName": "Bancolombia",
"receiptNumber": "RC-0042",
"verified": true,
"verifiedAt": "2026-10-16T14:02:11.000Z",
"registeredBy": { "id": "cm2u…", "name": "María Pérez", "email": "[email protected]" },
"installment": {
"id": "cmi3…",
"number": 4,
"type": "DOWN_PAYMENT",
"dueDate": "2026-10-10T00:00:00.000Z"
},
"deal": {
"id": "cmd1…",
"dealNumber": "NEG-012",
"status": "IN_PAYMENT",
"projectId": "cm4p…",
"projectStage": { "id": "cm6e…", "name": "Torre 2", "code": "T2" },
"propertyId": "cm5u…",
"buyer": { "id": "cm9k2…", "name": "Laura Gómez" }
},
"createdAt": "2026-10-15T16:40:02.000Z",
"updatedAt": "2026-10-16T14:02:11.000Z"
}
],
"nextCursor": null
}amountva en la moneda del negocio (currency), como número.paymentMethodes uno de los medios de pago que la organización configuró en cartera (BANK_TRANSFER,CASH,PSE,NEQUI, etc.); cada organización puede crear los suyos.installmentes la cuota a la que se aplicó el pago (SEPARATION,DOWN_PAYMENT,EXTRAORDINARY,DELIVERY,FINANCINGoADJUSTMENT); esnullsi no se aplicó a una cuota.- No se exponen las notas internas de cartera ni el comprobante que subió el comprador.
Un pago anulado desaparece
Si cartera anula (reversa) un pago, se borra y deja de aparecer: la sincronización porupdatedSince no te avisa. Para cuadrar un período, vuelve a pedir su rango completo con from y to y reemplaza lo que tenías de esas fechas.Límites y privacidad#
- 120 peticiones por minuto por clave, además de los límites por IP. Cada respuesta trae
X-RateLimit-Remaining; si te pasas, recibes429conRetry-After. - Todo está limitado a la organización de la clave: un id de otra organización responde
404. - La API expone datos de contacto de personas. Guárdala en tu servidor, nunca en un navegador ni en una app, y dale a cada sistema solo los permisos que necesita.
