Saltar para o conteúdo principal
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. Cobre os quatro problemas de toda sincronização assim: É 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 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.
  • 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, 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:
  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: 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:
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: 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, 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