> ## Documentation Index
> Fetch the complete documentation index at: https://docs.play2sell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sincronización en los dos sentidos

> Mantenga su sistema y SalesOS sincronizados en los dos sentidos, sin bucles, sin duplicados y sin sobrescrituras.

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](https://docs.play2sell.com/es/api/integrations/leads.md). Cubre los cuatro problemas de toda sincronización de este tipo:

| Problema | Qué lo resuelve |
| - | - |
| Cambios que se pierden | Feed de cambios con marca de agua segura (`list_leads` + `sync_watermark`) |
| Bucles (su propia escritura volviendo a usted) | `exclude_own_changes` y el `change_source` del historial y de los webhooks |
| Duplicados cuando se reintenta una llamada | `idempotency_key` y su `external_id` |
| Sobrescribir el cambio de otra persona | `expected_version` |

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`](https://docs.play2sell.com/es/api/integrations/leads#accion-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`](https://docs.play2sell.com/es/api/integrations/leads#accion-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`](https://docs.play2sell.com/es/api/integrations/leads#accion-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`](https://docs.play2sell.com/es/api/integrations/leads#accion-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:

```json theme={null}
{
  "action": "list_leads",
  "filters": { "updated_since": "2026-11-20T10:00:00.000Z", "exclude_own_changes": true, "include_archived": true },
  "limit": 500
}
```

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`](https://docs.play2sell.com/es/api/integrations/leads#accion-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](https://docs.play2sell.com/es/api/integrations/webhooks.md)):

| Evento | Cuándo |
| - | - |
| `lead_sync.created` | Se creó un lead en el embudo de leads (app, API o integración) |
| `lead_sync.updated` | Cambiaron campos del lead |
| `lead_sync.stage_changed` | El lead cambió de etapa, incluido ganado/perdido |
| `lead_sync.archived` | El lead se archivó |
| `lead_sync.restored` | Un lead archivado volvió |

En el **Payload Template** del webhook están disponibles estos campos:

```json theme={null}
{
  "lead_id": "{{lead_id}}",
  "external_id": "{{external_id}}",
  "source": "{{source}}",
  "kind": "{{kind}}",
  "version": "{{version}}",
  "changes": "{{changes}}",
  "change_source": "{{change_source}}",
  "change_id": "{{change_id}}"
}
```

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:

| De su lado | Acción |
| - | - |
| Lead nuevo | `sync_leads` |
| Contacto, responsable, valor, etiquetas, campos personalizados | `update_lead` |
| Cambio de estado | `move_lead_stage` con el `stage_id` mapeado |
| Ganado / perdido | `close_lead` |
| Eliminado o descartado | `archive_lead` |

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`](https://docs.play2sell.com/es/api/integrations/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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.