Saltar para o conteúdo principal
Teste requisições assinadas no navegador no API Sandbox: cole a chave e o segredo, e o playground assina sozinho.
Os exemplos mostram o cabeçalho Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE como vai na rede. Para calcular a assinatura no seu código, use o signedRequest de Autenticação.
A API de Leads deixa o seu sistema trabalhar com os leads da empresa da chave: listar e ler, criar e atualizar, mover pelo funil, marcar ganho ou perdido, arquivar e registrar notas e atividades. Manter dois sistemas sincronizados está passo a passo em Sincronização nos dois sentidos.

Antes de começar

  • Um endpoint, uma ação por chamada. Toda chamada é um POST para https://api.play2sell.com/functions/v1/default-integration com "action" no corpo. Filtros também vão no corpo, porque a assinatura cobre o corpo e não a query string (veja Convenções).
  • Escopos. Ler exige leads:read; gravar exige leads:write. Um não inclui o outro, e nenhum dos dois abre sync_collaborators ou sync_activities. Chave sem o escopo recebe 403 com code: "scope_insufficient". As chaves são criadas em Admin > Integrações > Chaves de API.
  • Cada empresa tem o próprio funil. Nomes e ordem das etapas são configurados por empresa e podem mudar a qualquer momento. Use sempre o ID da etapa que vem de list_pipelines e leia ganho/perdido em stage.outcome (open, won, lost), nunca no nome.
  • Pontos ficam com Missões. O que muda por esta API atualiza o lead, a etapa e o histórico, mas não pontua em missões nem campanhas. Pontos de integração vêm só de sync_activities.

O lead

Toda ação que devolve um lead devolve este formato.

Como apontar um lead

As ações de escrita e o get_lead aceitam uma das formas:
  • lead_id: o ID do SalesOS (UUID);
  • external_id + source: o seu ID, dentro do source usado na criação (padrão api).
Mandar as duas dá 400. Lead de outra empresa nunca é encontrado: a resposta é 404 LEAD_NOT_FOUND.

Leitura

Acao: list_pipelines

Funis e etapas da empresa, em ordem. Chame uma vez, guarde e atualize quando um ID de etapa for recusado.
requirements diz o que o move_lead_stage vai pedir quando um lead avançar para aquela etapa.

Acao: list_lead_fields

Os campos do lead da empresa na ordem da tela, inclusive os personalizados. path diz onde o valor aparece no lead (null = não exposto pela API).

Acao: get_lead

string
ID do SalesOS (UUID). Ou mande external_id.
string
O seu ID (até 255).
string
Junto com external_id. Padrão api.
A resposta é sempre 200: { "data": { "found": true, "lead": { … } } }, ou { "found": false, "lead": null } quando o lead não existe na empresa.

Acao: list_leads

object
Todos opcionais, combinados com E. Filtro desconhecido dá 400, para um erro de digitação nunca devolver tudo.
object
{ "by": "updated_at" | "created_at", "direction": "asc" | "desc" }. Padrão: updated_at crescente quando há updated_since; senão, os mais novos primeiro.
integer
1–500, padrão 100. Acima de 500, vira 500.
string
O next_cursor da página anterior.
O cursor fica preso aos filtros e à ordem que o geraram. Mudar no meio da paginação dá 400 (cursor): recomece sem cursor. Feed de mudanças. Com updated_since, a lista vem em updated_at crescente e a resposta traz sync_watermark. Quando has_more for false, use o sync_watermark como próximo updated_since: nenhuma mudança anterior a ele aparece depois. Veja Sincronização nos dois sentidos.

Acao: get_lead_history

Cada mudança do lead, da mais antiga para a mais nova: o que mudou (antes/depois), o tipo de mudança e quem fez.
kind é created, updated, stage_changed, archived ou restored. changes traz só os campos que mudaram, cada um com old e new. O registro vale para os leads do funil de leads.

Escrita

Toda ação de escrita:
  • responde com o lead como ficou depois da mudança, mais result;
  • aceita idempotency_key e expected_version, opcionais;
  • roda numa transação só: grava tudo ou nada.
O add_lead_activity responde com a atividade em vez do lead e não usa expected_version.

Acao: sync_leads

Cria ou atualiza até 100 leads por chamada: formulário do site, landing page, outro sistema. O lead novo entra no funil de leads padrão da empresa, na primeira etapa ou na stage_id enviada.

Como o lead é reconhecido

Para cada item, procuramos um lead ativo da empresa nesta ordem:
  1. o mesmo external_id no mesmo source (duas origens nunca se misturam);
  2. o mesmo email (sem diferenciar maiúsculas);
  3. o mesmo phone.
Achou: atualiza. Não achou: cria. Se o e-mail é de um lead e o telefone de outro, o item volta com IDENTITY_CONFLICT e nada é gravado para ele. A mesma pessoa duas vezes no lote cria um lead e atualiza esse mesmo lead na segunda.

O que uma atualização faz

Pedido

string
De onde vêm os leads, em minúsculas: letras, números, _ . - (até 60). Padrão api.
string
Opcional. Veja Repetir sem duplicar.
array
obrigatório
Lista de leads (até 100).
string
obrigatório
ID único do lead no seu sistema (até 255).
string
Até 200. Para criar, mande pelo menos um entre name, email e phone.
string
E-mail do cliente.
string
Com DDI, ex.: +5511987654321. Sem DDI, vale o país da empresa.
string
CPF (11) ou CNPJ (14) dígitos; a pontuação é ignorada.
string
Até 200.
string
Até 300.
string[]
Até 20 etiquetas, 60 caracteres cada.
string
Responsável. Desconhecido ou inativo: o lead vai para o responsável padrão, com aviso.
string
Opcional, só para lead novo: uma etapa aberta do funil de leads sem exigências (veja list_pipelines). Fora disso, o item falha com STAGE_NOT_ALLOWED_ON_CREATE ou STAGE_NOT_FOUND.
object
Rótulo → texto. Até 50 campos, 1.000 caracteres cada.
object
utm_source, utm_medium, utm_campaign, utm_term, utm_content, landing_page, referrer, form_id (500 caracteres cada).

Resposta (200)

Um resultado por lead, na ordem do pedido. Item com problema não derruba o lote: volta com status: "error" e os outros seguem.
Erros do lote inteiro (leads vazio ou acima de 100, source ou idempotency_key inválidos) respondem 400 VALIDATION_ERROR.

Acao: update_lead

Muda só os campos enviados. null limpa um campo opcional. Campo desconhecido dá 400.
object
obrigatório
name (não pode ser limpo), email, phone, document, company_name, product, value (≥ 0), expected_close_date (AAAA-MM-DD), priority (low, medium, high, urgent), notes (até 5.000), buying_moment, is_important, is_starred, owner_email, custom_fields (rótulo → texto, ou null para tirar o campo; até 50), add_tags, remove_tags (até 20 cada).
Resposta: 200 com { "data": { "result": "updated", "lead": { … } } }.

Acao: move_lead_stage

Move o lead para stage_id, uma etapa do próprio funil do lead. Avançar segue as regras da etapa exatamente como no app; recuar é sempre livre.
string
obrigatório
ID da etapa, de list_pipelines.
string
Quando a etapa exige documento: link http(s) dele.
string | number
Quando a etapa exige um campo (requirements.field).
string
Quando a etapa de destino tem outcome: "lost" (1–500 caracteres).
number
Atualiza o valor do lead junto com a mudança.
string
Recado ao líder quando a etapa exige aprovação (até 1.000).
Exigência faltando dá 422 STAGE_REQUIREMENT_MISSING, e details diz o que mandar:

Acao: close_lead

Marca o lead como ganho ou perdido pelo resultado, seja qual for o nome das etapas. Leva o lead para a primeira etapa do funil com aquele outcome, com as mesmas regras do move_lead_stage.
string
obrigatório
won ou lost.
string
Só com lost.
number
Valor final.
Funil sem etapa com esse resultado: 422 NO_STAGE_FOR_OUTCOME. Para reabrir, use move_lead_stage para uma etapa aberta.

Acao: archive_lead / restore_lead

archive_lead tira o lead do funil (status: "archived") sem apagar nada. restore_lead traz de volta com a situação que ele tinha. Respondem result: "archived", "restored" ou "unchanged". Lead arquivado não pode ser alterado nem movido (409 LEAD_ARCHIVED) até ser restaurado.

Notas e atividades

Acao: add_lead_activity

Registra algo que aconteceu com o lead. Aparece na linha do tempo do lead no app, como as atividades registradas lá, e não pontua (pontos vêm de sync_activities).
string
O lead. Ou mande lead_external_id + lead_source.
string
O seu ID do lead (com lead_source, padrão api).
string
obrigatório
note, call, whatsapp, email, meeting ou visit.
string
Até 5.000 caracteres. Obrigatória em note.
string
Quando aconteceu (ISO 8601). Padrão: agora. Não pode ser no futuro.
string
Quem fez: usuário ativo da empresa. Padrão: o responsável pelo lead.
string
O seu ID desta atividade (com source, padrão api). Mandar o mesmo par de novo devolve a atividade existente (result: "existing", 200) em vez de criar outra.
string
inbound ou outbound (ligações, mensagens).
integer
0–86.400.
Resposta 201 (criada) ou 200 (já existia):

Acao: list_lead_activities

A linha do tempo de um lead (lead_id, ou external_id + source), ou todas as atividades da empresa a partir de since. Inclui o que foi registrado no app e por integrações, da mais antiga para a mais nova. Mudança de etapa vem como type: "status_change", com stage_change.from_stage_id / to_stage_id.
string
ISO 8601. Obrigatório quando nenhum lead é informado. Filtra por occurred_at: atividade registrada depois com occurred_at no passado não aparece num feed que já passou daquela data.
string[]
Só estes tipos, ex.: ["note", "call"].
integer
1–500, padrão 100.
string
O next_cursor da página anterior.
Resposta: { "data": { "found": true, "items": [ … ], "next_cursor": null, "has_more": false } }. Para lead que não existe, found é false.

Repetir sem duplicar: idempotency_key

A rede falha. Para repetir uma escrita sem fazê-la duas vezes, mande uma idempotency_key (8–255 caracteres: letras, números, _ . : -) única para aquela operação, como o ID do evento no seu sistema. A chave vale por chave de API: duas chaves nunca compartilham. Ela vai no corpo, que é assinado, e não num cabeçalho.

Evitar sobrescrever: expected_version

Para mudar um lead só se ninguém mexeu nele desde a sua leitura, mande a version lida como expected_version. Se o lead já estiver em outra versão, nada é gravado e a resposta é 409 VERSION_CONFLICT, com details.current_version. Leia de novo, junte as mudanças e repita.

Erros

Erros de autenticação (401, e 403 scope_insufficient quando falta leads:read ou leads:write na chave) e de limite de chamadas (429) têm formato próprio, o mesmo em todos os endpoints: veja Autenticação.