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 alist_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, useclose_lead. - Si una llamada devuelve
STAGE_NOT_FOUND, la empresa cambió el embudo: llame de nuevo alist_pipelinesy revise el mapa.
2. Carga inicial
Traiga sus leads consync_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:- Aplique cada ítem en su sistema (búsquelo por
external_id+source, o porid). - Mientras
has_moreseatrue, llame de nuevo concursor=next_cursor(mismos filtros). - Cuando
has_moreseafalse, guardesync_watermarky úselo como el próximoupdated_since.
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:
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:
- Ignore sus propios cambios: si
change_source.api_key_ides el ID de su clave, es el eco de su escritura. - Ignore noticias viejas: si ya aplicó una
versionigual o mayor de ese lead, sáltela. Las entregas pueden repetirse y llegar fuera de orden. - Aplíquela, o simplemente llame a
get_leady aplique el lead actual.
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_keycon 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_versioncon la últimaversionvista. Si alguien cambió el lead en SalesOS mientras tanto, recibe409 VERSION_CONFLICTy 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_MISSINGindica qué falta (details), y202 pending_approvalsignifica 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.
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 consync_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:readyleads:write - Mapa de etapas por ID, actualizado ante
STAGE_NOT_FOUND - Feed con
updated_since= últimosync_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 conexpected_version -
409 VERSION_CONFLICT,422 STAGE_REQUIREMENT_MISSINGy202 pending_approvalresueltos - Los webhooks (si se usan) ignoran la propia clave y las versiones viejas; el feed sigue corriendo

