Datos y eventos

API de escritura

Actualiza YAVE desde tu sistema: tu ERP marca que el cliente pagó la separación, tu call center mueve el lead de etapa, tu sistema de agendamiento crea la visita. Cada cambio pasa por las mismas reglas que si lo hiciera un asesor en el CRM: asignación, embudos, automatizaciones e historial.

¿Solo necesitas enviar leads?

La API de leads (/webhooks/custom) sigue igual y es lo más simple. Esta API es para lo demás: actualizar, mover, anotar y agendar.

Permisos#

Un administrador los activa en Configuración → Integraciones → API Key → Permisos. Sin el permiso, la respuesta es 403 y dice cuál falta.

  • leads:write: crear y actualizar leads, moverlos de etapa y agregarles notas.
  • tasks:write: crear tareas.
  • appointments:write: agendar citas.

Reintentos seguros: Idempotency-Key#

Si una petición se corta (timeout, red), no sabes si alcanzó a crear el registro. Manda un encabezado Idempotency-Key con un valor único por operación (un UUID o tu propio id): si reintentas con la misma clave en las siguientes 24 horas, YAVE responde lo mismo que la primera vez, con el encabezado Idempotent-Replayed: true, y no vuelve a crear nada.

  • La misma clave con un cuerpo distinto responde 422.
  • Si la primera todavía se está procesando, 409: espera y reintenta.
  • Si la primera falló, la clave queda libre y el reintento se procesa.

Leads#

Crear

POST/external/leadsleads:write

Igual que la API de leads: si el teléfono ya existe en la organización no crea un duplicado y responde "created": false con el lead existente. Responde el lead completo, igual que GET /external/leads/{id}.

namestringrequerido
Nombre completo.
phonestring
Muy recomendado: es la llave de deduplicación. Para números extranjeros envía el + y el indicativo.
emailstring
Correo.
source · sourceIdstring
Origen y tu id del lead.
budgetnumber
Presupuesto.
utmSource · utmMedium · utmCampaign · utmContent · utmTermstring
Atribución.
tagsstring[]
Hasta 20 etiquetas.
customFieldsobject
Hasta 50 campos libres.
cURL
curl -X POST https://api.yavehome.com/api/v1/external/leads \
  -H "X-API-Key: yave_3f9a…c21e" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: erp-cliente-88121" \
  -d '{ "name": "Laura Gómez", "phone": "+57 300 123 4567", "source": "ERP" }'

Actualizar

PATCH/external/leads/{id}leads:write

Solo cambia los campos que envíes: name, phone, email, budget, assignedToId (un usuario de la organización), los utm* y tags (se agregan, no reemplazan las existentes). Para la etapa usa el endpoint de abajo.

Mover de etapa

POST/external/leads/{id}/stageleads:write
stageIdstringrequerido
Una etapa del embudo del lead (ver /external/pipelines).
lostReasonCode · lostReasonstring
Motivo de pérdida, si mueves a LOST y la etapa lo pide.
  • Se respetan las reglas de entrada que el equipo configuró en el embudo (por ejemplo, “no pasa a Visita sin una cita agendada”). Si el lead no las cumple, responde 422 con "code": "STAGE_TRIGGER_BLOCKED" y el motivo. Una integración no puede forzarlas.
  • Reservado y Ganado no se pueden poner por API (422, STAGE_CRM_ONLY): abren una reserva o una venta, con unidad, valores y plan de pagos, y eso se hace desde el CRM.
  • El movimiento queda en el historial del lead como hecho por la integración, y dispara las automatizaciones y conversiones igual que en el CRM.

Notas

POST/external/leads/{id}/notesleads:write

Cuerpo: { "content": "Pagó la separación" } (hasta 5.000 caracteres). En el CRM aparece con el nombre de la API key al inicio para que se sepa de dónde vino.

Tareas#

POST/external/taskstasks:write
titlestringrequerido
Título.
descriptionstring
Detalle.
leadIdstring
Lead al que pertenece.
assigneeIdstring
Responsable. Si no lo envías, el asesor del lead.
dueAtISO 8601
Vencimiento.
priorityLOW | MEDIUM | HIGH | URGENT
Por defecto MEDIUM.

Citas#

POST/external/appointmentsappointments:write
titlestringrequerido
Título.
startAtISO 8601requerido
Inicio.
endAtISO 8601
Fin. Por defecto, una hora después.
leadIdstring
Lead de la cita.
agentIdstring
Asesor. Si no lo envías, el asesor del lead.
typeVISIT | CALL | VIDEO_CALL | FOLLOWUP | OTHER
Por defecto VISIT.
location · descriptionstring
Lugar y detalle.

Errores frecuentes#

  • 400: un campo que no existe o con formato inválido; el mensaje dice cuál.
  • 404: el lead no existe o es de otra organización.
  • 422: la regla del embudo no se cumple, o la etapa es solo del CRM.

Los límites son los mismos de la API de consulta: 120 peticiones por minuto por clave.

AnteriorAPI de consultaSiguiente Eventos (webhooks firmados)