Saltar al contenido principal
Esta guía muestra cómo mantener los leads sincronizados entre su sistema (un CRM, un ERP, un robot de planillas) y SalesOS en los dos sentidos, con la API de Leads. Cubre los cuatro problemas de toda sincronización de este tipo: Necesita una clave con leads:read y leads:write. Use una clave por integración: es por la clave que SalesOS separa sus cambios de los de los demás.

1. Mapee embudos y etapas una vez

Llame a list_pipelines y asocie sus estados a los IDs de etapa de SalesOS. Reglas:
  • Mapee por stage.id, nunca por el nombre: cada empresa nombra y ordena sus etapas como quiere, y las renombra.
  • Lea ganado/perdido en stage.outcome (open, won, lost). Para marcar ganado o perdido sin conocer la etapa, use close_lead.
  • Si una llamada devuelve STAGE_NOT_FOUND, la empresa cambió el embudo: llame de nuevo a list_pipelines y revise el mapa.

2. Carga inicial

Traiga sus leads con sync_leads, 100 por llamada, cada uno con su external_id y el mismo source (por ejemplo my-crm). A partir de ahí, cualquier lead se identifica por external_id + source, sin guardar el ID de SalesOS. Para leer lo que ya existe en SalesOS, pagine list_leads hasta que has_more sea false.

3. SalesOS → su sistema: el feed de cambios

Cada pocos minutos, pida lo que cambió desde el último punto de control:
  1. Aplique cada ítem en su sistema (búsquelo por external_id + source, o por id).
  2. Mientras has_more sea true, llame de nuevo con cursor = next_cursor (mismos filtros).
  3. Cuando has_more sea false, guarde sync_watermark y úselo como el próximo updated_since.
Por qué sync_watermark y no la hora de la llamada: un cambio grabado por una operación larga puede tener un updated_at un poco en el pasado. sync_watermark ya lo tiene en cuenta, así que ningún cambio queda atrás. Algunos ítems pueden llegar dos veces entre corridas; aplicarlos de nuevo no debe hacer nada (compare la version). exclude_own_changes quita los leads cuyo último cambio lo hizo su clave, para que sus escrituras no vuelvan a usted. include_archived hace que aparezcan los archivados, para archivarlos también de su lado. Para saber qué cambió en un lead, y no solo que cambió, llame a get_lead_history: cada entrada trae los campos con old y new, y change_source indica si vino de la app o de qué clave de API.

4. Tiempo real con webhooks (opcional)

El feed alcanza para sincronizar. Para reaccionar en segundos, suscríbase también a los eventos de sincronización de leads en Integraciones → Webhooks (vea Webhooks): En el Payload Template del webhook están disponibles estos campos:
Un placeholder solo en el valor mantiene su tipo: version llega como número y changes como objeto ({ "stage_id": { "old": "…", "new": "…" } }). Verifíquelo con Preview y Test antes de guardar. Cuando llegue una entrega:
  1. Ignore sus propios cambios: si change_source.api_key_id es el ID de su clave, es el eco de su escritura.
  2. Ignore noticias viejas: si ya aplicó una version igual o mayor de ese lead, sáltela. Las entregas pueden repetirse y llegar fuera de orden.
  3. Aplíquela, o simplemente llame a get_lead y aplique el lead actual.
Los webhooks se entregan con el mejor esfuerzo, con reintentos. Mantenga el feed corriendo igual, con menos frecuencia, para capturar lo que una entrega haya perdido.

5. Su sistema → SalesOS: escribir sin bucles ni sobrescrituras

Cuando algo cambie de su lado, llame a la acción correspondiente: En cada escritura:
  • Envíe idempotency_key con un ID único de ese cambio de su lado (por ejemplo el ID del evento o de la auditoría). Si la red falla, reintente con la misma clave: se hace una sola vez.
  • Envíe expected_version con la última version vista. Si alguien cambió el lead en SalesOS mientras tanto, recibe 409 VERSION_CONFLICT y no se sobrescribe nada: lea el lead, decida (combinar campo por campo, o dejar que gane el más reciente) y escriba de nuevo.
  • Cuente con las reglas de la etapa. Avanzar sigue los requisitos de la etapa exactamente como en la app. 422 STAGE_REQUIREMENT_MISSING indica qué falta (details), y 202 pending_approval significa que el líder del lead debe aprobar: el lead queda donde estaba hasta entonces, y el cambio aparece en el feed cuando se aprueba.
Sus escrituras no vuelven en el feed (con exclude_own_changes) ni como un eco irreconocible (change_source.api_key_id en webhooks e historial).

6. Puntos y misiones

Lo que cambia por la API actualiza el lead, la etapa y el historial, pero no suma puntos. Si su sistema es donde trabajan los vendedores, envíe lo que debe puntuar como actividades con sync_activities, mapeadas a misiones en el Dashboard. Así los puntos cuentan una sola vez, aunque el mismo lead se mueva de los dos lados.

Checklist

  • Una clave de API para esta integración, con leads:read y leads:write
  • Mapa de etapas por ID, actualizado ante STAGE_NOT_FOUND
  • Feed con updated_since = último sync_watermark, exclude_own_changes: true, include_archived: true
  • Aplicar el mismo ítem dos veces no cambia nada (compare la version)
  • Toda escritura con idempotency_key; las ediciones con expected_version
  • 409 VERSION_CONFLICT, 422 STAGE_REQUIREMENT_MISSING y 202 pending_approval resueltos
  • Los webhooks (si se usan) ignoran la propia clave y las versiones viejas; el feed sigue corriendo