É 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
Chamelist_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, useclose_lead. - Se uma chamada devolver
STAGE_NOT_FOUND, a empresa mudou o funil: chamelist_pipelinesde novo e revise o mapa.
2. Carga inicial
Traga os seus leads comsync_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 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:- Aplique cada item no seu sistema (ache por
external_id+source, ou porid). - Enquanto
has_morefortrue, chame de novo comcursor=next_cursor(mesmos filtros). - Quando
has_moreforfalse, guarde osync_watermarke use como próximoupdated_since.
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: 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):
No Payload Template do webhook, estes campos estão disponíveis:
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:
- Ignore as suas próprias mudanças: se
change_source.api_key_idé o ID da sua chave, é o eco da sua gravação. - Ignore notícia velha: se você já aplicou uma
versionigual ou maior daquele lead, pule. Entregas podem se repetir e chegar fora de ordem. - Aplique, ou simplesmente chame
get_leade aplique o lead atual.
5. Seu sistema → SalesOS: gravar sem laço e sem sobrescrever
Quando algo mudar do seu lado, chame a ação correspondente:
Em toda gravação:
- Mande
idempotency_keycom 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_versioncom a últimaversionvista. Se alguém mudou o lead no SalesOS nesse meio-tempo, vem409 VERSION_CONFLICTe 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_MISSINGdiz o que falta (details), e202 pending_approvalsignifica que o líder do lead precisa aprovar: o lead fica onde estava até lá, e a mudança aparece no feed quando aprovada.
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 comsync_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:readeleads:write - Mapa de etapas por ID, atualizado no
STAGE_NOT_FOUND - Feed com
updated_since= últimosync_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 comexpected_version -
409 VERSION_CONFLICT,422 STAGE_REQUIREMENT_MISSINGe202 pending_approvaltratados - Webhooks (se usados) ignoram a própria chave e versões velhas; o feed continua rodando

