Saltar al contenido
Datos y eventos

API de consulta

Lee los datos de la organización desde tu propio sistema: un tablero de BI, tu ERP, el sitio web o un informe a la medida. Para crear o actualizar datos está la API de escritura, y para solo enviar leads, la API de leads.

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:

PermisoQué permite
webhooks:writeEnviar leads, tareas y citas (API de leads).
leads:readLeer leads, embudos, etapas e historial de etapas.
inventory:readLeer proyectos, inmuebles y unidades.
appointments:readLeer citas y visitas.
payments:readLeer los pagos recibidos en los negocios (cartera).
leads:writeCrear y actualizar leads, moverlos de etapa, notas (API de escritura).
tasks:writeCrear tareas.
appointments:writeAgendar citas.

Las claves que ya existen no cambian

Una clave creada antes de que existieran los permisos solo tiene webhooks: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
curl https://api.yavehome.com/api/v1/external/me \
  -H "X-API-Key: yave_3f9a…c21e"
200
{
  "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.

limitnumber
Resultados por página, de 1 a 100. Por defecto 50.
cursorstring
El nextCursor de la página anterior. Sin él, empieza desde el principio.

Leads#

GET/external/leadsleads:read
sort-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 8601
Solo leads creados o modificados desde esa fecha.
pipelineId · stageIdstring
Filtra por embudo o por etapa (ids de /external/pipelines).
phonestring
Busca por teléfono en cualquier formato; se normaliza igual que al crear el lead.
emailstring
Busca por correo.
200
{
  "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.

GET/external/leads/{id}leads:read

El 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

  1. La primera vez, recorre /external/leads?sort=updatedAt hasta que nextCursor sea null.
  2. Guarda el updatedAt más reciente que recibiste.
  3. 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 por id.

Embudos y etapas#

GET/external/pipelinesleads:read
200
{
  "data": [
    {
      "id": "default",
      "name": "Ventas",
      "isDefault": true,
      "stages": [
        { "id": "NEW", "name": "Nuevo" },
        { "id": "s-visita", "name": "Visita agendada" },
        { "id": "WON", "name": "Ganado" }
      ]
    }
  ]
}

Inventario#

GET/external/projectsinventory:read

Proyectos 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
"stages": [
  {
    "id": "cm6e…",
    "name": "Torre 2",
    "code": "T2",
    "status": "PRESALE",
    "estimatedDeliveryDate": "2028-06-30T00:00:00.000Z"
  }
]
GET/external/propertiesinventory:read

Inmuebles 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).

projectIdstring
Unidades de un proyecto.
projectStageIdstring
Unidades de una etapa del proyecto (ids de stages en /external/projects).
statusenum
AVAILABLE, RESERVED, SOLD, RENTED, FROZEN, BLOCKED, INACTIVE.
listingTypeSALE | RENT
Venta o arriendo.
updatedSinceISO 8601
Solo lo que cambió desde esa fecha.

Citas#

GET/external/appointmentsappointments:read
from · toISO 8601
Rango por fecha de inicio. Por defecto, los próximos 30 días. Máximo 92 días por consulta.
leadIdstring
Citas de un lead.
statusenum
SCHEDULED, CONFIRMED, COMPLETED, CANCELLED, NO_SHOW.

Pagos recibidos#

GET/external/paymentspayments:read

Los 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 8601
Rango por fecha del pago: desde from (incluida) hasta antes de to. Por ejemplo, el recaudo de octubre es from=2026-10-01&to=2026-11-01.
updatedSinceISO 8601
Solo pagos registrados o modificados desde esa fecha.
dealId · projectId · leadIdstring
Pagos de un negocio, de los negocios de un proyecto o de los negocios de un comprador.
kindCAPITAL | NON_CAPITAL
CAPITAL abona al precio del inmueble y baja el saldo. NON_CAPITAL son intereses, mora u otros cobros que no lo bajan.
verifiedtrue | false
true: solo los que cartera ya verificó. false: solo los que esperan verificación.
200
{
  "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
}
  • amount va en la moneda del negocio (currency), como número.
  • paymentMethod es 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.
  • installment es la cuota a la que se aplicó el pago (SEPARATION, DOWN_PAYMENT, EXTRAORDINARY, DELIVERY, FINANCING o ADJUSTMENT); es null si 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 por updatedSince 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, recibes 429 con Retry-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.