> ## 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.

# Sincronização nos dois sentidos

> Mantenha o seu sistema e o SalesOS sincronizados nos dois sentidos, sem laço, sem duplicata e sem sobrescrever.

Este guia mostra como manter os leads sincronizados entre o seu sistema (um CRM, um ERP, um robô de planilha) e o SalesOS **nos dois sentidos**, com a [API de Leads](https://docs.play2sell.com/pt/api/integrations/leads.md). Cobre os quatro problemas de toda sincronização assim:

| Problema | O que resolve |
| - | - |
| Mudança que se perde | Feed de mudanças com marca d'água segura (`list_leads` + `sync_watermark`) |
| Laço (a sua própria gravação voltando para você) | `exclude_own_changes` e o `change_source` do histórico e dos webhooks |
| Duplicata quando a chamada é repetida | `idempotency_key` e o seu `external_id` |
| Sobrescrever a mudança de outra pessoa | `expected_version` |

É preciso uma chave com **`leads:read`** e **`leads:write`**. Use **uma chave por integração**: é pela chave que o SalesOS separa as suas mudanças das dos outros.

## 1. Mapeie funis e etapas uma vez

Chame [`list_pipelines`](https://docs.play2sell.com/pt/api/integrations/leads#acao-list_pipelines) e associe as **suas** situações aos **IDs de etapa** do SalesOS. Regras:

* Mapeie por `stage.id`, nunca pelo nome: cada empresa dá nome e ordem às etapas como quiser, e renomeia.
* Leia ganho/perdido em `stage.outcome` (`open`, `won`, `lost`). Para marcar ganho ou perdido sem saber a etapa, use [`close_lead`](https://docs.play2sell.com/pt/api/integrations/leads#acao-close_lead).
* Se uma chamada devolver `STAGE_NOT_FOUND`, a empresa mudou o funil: chame `list_pipelines` de novo e revise o mapa.

## 2. Carga inicial

Traga os seus leads com [`sync_leads`](https://docs.play2sell.com/pt/api/integrations/leads#acao-sync_leads), 100 por chamada, cada um com o seu `external_id` e o mesmo `source` (por exemplo `my-crm`). Daí em diante, qualquer lead pode ser apontado por `external_id` + `source`, sem guardar o ID do SalesOS.

Para ler o que já existe no SalesOS, pagine [`list_leads`](https://docs.play2sell.com/pt/api/integrations/leads#acao-list_leads) até `has_more` ser `false`.

## 3. SalesOS → seu sistema: o feed de mudanças

A cada poucos minutos, peça o que mudou desde o último ponto de controle:

```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 item no seu sistema (ache por `external_id` + `source`, ou por `id`).
2. Enquanto `has_more` for `true`, chame de novo com `cursor` = `next_cursor` (mesmos filtros).
3. Quando `has_more` for `false`, **guarde o `sync_watermark`** e use como próximo `updated_since`.

Por que o `sync_watermark` e não a hora da chamada: uma mudança gravada por uma operação longa pode ter `updated_at` um pouco no passado. O `sync_watermark` já leva isso em conta, então nenhuma mudança fica para trás. Alguns itens podem vir duas vezes entre rodadas; aplicá-los de novo não deve fazer nada (compare a `version`).

`exclude_own_changes` tira os leads cuja última mudança foi feita **pela sua chave**, para as suas gravações não voltarem para você. `include_archived` faz os arquivados aparecerem, para você arquivar do seu lado também.

Para saber **o que** mudou num lead, e não só que mudou, chame [`get_lead_history`](https://docs.play2sell.com/pt/api/integrations/leads#acao-get_lead_history): cada entrada traz os campos com `old` e `new`, e o `change_source` diz se veio do app ou de qual chave de API.

## 4. Tempo real com webhooks (opcional)

O feed basta para sincronizar. Para reagir em segundos, assine também os eventos de sincronização de leads em **Integrações → Webhooks** (veja [Webhooks](https://docs.play2sell.com/pt/api/integrations/webhooks.md)):

| Evento | Quando |
| - | - |
| `lead_sync.created` | Um lead foi criado no funil de leads (app, API ou integração) |
| `lead_sync.updated` | Campos do lead mudaram |
| `lead_sync.stage_changed` | O lead mudou de etapa, inclusive ganho/perda |
| `lead_sync.archived` | O lead foi arquivado |
| `lead_sync.restored` | Um lead arquivado voltou |

No **Payload Template** do webhook, estes campos estão disponíveis:

```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}}"
}
```

Um placeholder sozinho no valor mantém o tipo: `version` chega como número e `changes` como objeto (`{ "stage_id": { "old": "…", "new": "…" } }`). Confira com **Preview** e **Test** antes de salvar.

Quando uma entrega chegar:

1. **Ignore as suas próprias mudanças:** se `change_source.api_key_id` é o ID da sua chave, é o eco da sua gravação.
2. **Ignore notícia velha:** se você já aplicou uma `version` igual ou maior daquele lead, pule. Entregas podem se repetir e chegar fora de ordem.
3. Aplique, ou simplesmente chame `get_lead` e aplique o lead atual.

Os webhooks são entregues em melhor esforço, com novas tentativas. Mantenha o feed rodando mesmo assim, com menos frequência, para pegar o que uma entrega perdeu.

## 5. Seu sistema → SalesOS: gravar sem laço e sem sobrescrever

Quando algo mudar do seu lado, chame a ação correspondente:

| Do seu lado | Ação |
| - | - |
| Lead novo | `sync_leads` |
| Contato, responsável, valor, etiquetas, campos personalizados | `update_lead` |
| Mudança de situação | `move_lead_stage` com o `stage_id` mapeado |
| Ganho / perdido | `close_lead` |
| Excluído ou descartado | `archive_lead` |

Em toda gravação:

* **Mande `idempotency_key`** com um ID único daquela mudança do seu lado (por exemplo o ID do evento ou da auditoria). Se a rede falhar, repita com a mesma chave: é feito uma vez só.
* **Mande `expected_version`** com a última `version` vista. Se alguém mudou o lead no SalesOS nesse meio-tempo, vem `409 VERSION_CONFLICT` e nada é sobrescrito: leia o lead, decida (juntar campo a campo, ou deixar a mais recente vencer) e grave de novo.
* **Conte com as regras da etapa.** Avançar segue as exigências da etapa exatamente como no app. `422 STAGE_REQUIREMENT_MISSING` diz o que falta (`details`), e `202 pending_approval` significa que o líder do lead precisa aprovar: o lead fica onde estava até lá, e a mudança aparece no feed quando aprovada.

As suas gravações não voltam no feed (com `exclude_own_changes`) nem como um eco irreconhecível (`change_source.api_key_id` nos webhooks e no histórico).

## 6. Pontos e missões

O que muda pela API atualiza o lead, a etapa e o histórico, mas **não pontua**. Se o seu sistema é onde os corretores trabalham, mande o que deve pontuar como atividades com [`sync_activities`](https://docs.play2sell.com/pt/api/integrations/activities), mapeadas para missões no Dashboard. Assim os pontos contam uma vez só, mesmo quando o mesmo lead se move dos dois lados.

## Checklist

* [ ] Uma chave de API para esta integração, com `leads:read` e `leads:write`
* [ ] Mapa de etapas por ID, atualizado no `STAGE_NOT_FOUND`
* [ ] Feed com `updated_since` = último `sync_watermark`, `exclude_own_changes: true`, `include_archived: true`
* [ ] Aplicar o mesmo item duas vezes não muda nada (compare a `version`)
* [ ] Toda gravação com `idempotency_key`; edições com `expected_version`
* [ ] `409 VERSION_CONFLICT`, `422 STAGE_REQUIREMENT_MISSING` e `202 pending_approval` tratados
* [ ] Webhooks (se usados) ignoram a própria chave e versões velhas; o feed continua rodando


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