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.Antes de começar
- Um endpoint, uma ação por chamada. Toda chamada é um
POSTparahttps://api.play2sell.com/functions/v1/default-integrationcom"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 exigeleads:write. Um não inclui o outro, e nenhum dos dois abresync_collaboratorsousync_activities. Chave sem o escopo recebe403comcode: "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_pipelinese leia ganho/perdido emstage.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 oget_lead aceitam uma das formas:
lead_id: o ID do SalesOS (UUID);external_id+source: o seu ID, dentro dosourceusado na criação (padrãoapi).
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
200: { "data": { "found": true, "lead": { … } } }, ou { "found": false, "lead": null } quando o lead não existe na empresa.
Acao: list_leads
Todos opcionais, combinados com E. Filtro desconhecido dá
400, para um erro de digitação nunca devolver tudo.{ "by": "updated_at" | "created_at", "direction": "asc" | "desc" }. Padrão: updated_at crescente quando há updated_since; senão, os mais novos primeiro.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_keyeexpected_version, opcionais; - roda numa transação só: grava tudo ou nada.
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 nastage_id enviada.
Como o lead é reconhecido
Para cada item, procuramos um lead ativo da empresa nesta ordem:- o mesmo
external_idno mesmosource(duas origens nunca se misturam); - o mesmo
email(sem diferenciar maiúsculas); - o mesmo
phone.
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
Opcional. Veja Repetir sem duplicar.
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.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 comstatus: "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.
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).200 com { "data": { "result": "updated", "lead": { … } } }.
Acao: move_lead_stage
Move o lead parastage_id, uma etapa do próprio funil do lead. Avançar segue as regras da etapa exatamente como no app; recuar é sempre livre.
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 aqueleoutcome, com as mesmas regras do move_lead_stage.
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 desync_activities).
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.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.
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.{ "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 umaidempotency_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 aversion 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.
