Referência técnica

Documentação da API de Leads do Capturama

A API pública de leads é read-only e permite que sistemas externos leiam leads/clientes do Capturama usando token de integração.

Bearer tokenGET /public/v1/leadsCursor

Visão geral

A API pública de Leads do Capturama permite consultar leads/clientes de forma automatizada. Ela não cria, edita ou remove dados.

Use a API para alimentar CRM, ERP, n8n, BI, Google Sheets ou sistemas próprios, mantendo o token seguro no sistema externo.

Autenticação

Todas as chamadas autenticadas usam token Bearer no header Authorization.

Authorization: Bearer SEU_TOKEN_AQUI

Endpoints disponíveis

GET /public/v1/leads

Lista leads com limit, cursor, updated_since e include_deleted.

Abrir referência

GET /public/v1/leads/{lead_id}

Consulta um lead específico por ID.

Abrir referência

GET /public/v1/leads/schema

Consulta o schema público de campos.

Abrir referência

GET /public/v1/integration/health

Verifica disponibilidade da integração.

Listar leads

Use GET /public/v1/leads para carga inicial ou sincronização incremental. A resposta traz data e page_info para continuar a paginação quando necessário.

Abrir referência de listagem

Consultar lead por ID

Use GET /public/v1/leads/{lead_id} quando uma integração precisa recuperar ou validar um registro específico dentro do escopo associado ao token.

Abrir consulta por ID

Sincronização incremental

Na primeira sincronização, o sistema externo pode buscar todos os leads. Nas próximas execuções, deve buscar apenas registros novos ou atualizados usando updated_since ou cursor.

Ver sincronização incremental

Paginação por cursor

Quando page_info.has_more for true, use page_info.next_cursor na próxima chamada. Não fabrique cursor no cliente.

Ver paginação por cursor

Schema de campos

O contrato público inclui campos de identificação, contato, status, datas, prospecção e remoção. Dados sensíveis ou internos não fazem parte da resposta pública inicial.

Ver campos disponíveis

Códigos de erro

Status	Código	Quando acontece	Ação recomendada
400	invalid_parameter	Um parâmetro não reconhecido ou incompatível foi enviado.	Revise nomes, tipos e combinação de parâmetros.
400	invalid_cursor	O cursor informado não pode ser lido ou não pertence à consulta atual.	Use apenas o valor retornado em page_info.next_cursor.
400	invalid_updated_since	A data de updated_since não está em formato aceito.	Envie uma data ISO 8601, por exemplo 2026-05-06T00:00:00Z.
400	invalid_limit	O limit está fora do intervalo aceito ou não é numérico.	Ajuste o tamanho da página antes de repetir a chamada.
401	unauthorized	O token está ausente, inválido ou revogado.	Confira o header Authorization e gere novo token se necessário.
404	not_found	O lead consultado não existe no escopo associado ao token.	Confirme o lead_id e a loja ou conta ligada ao token.
503	integration_disabled	A integração está desabilitada para a conta ou token.	Reative a integração no painel ou fale com o responsável pela conta.
500	internal_error	Ocorreu erro inesperado ao processar a chamada.	Registre horário, endpoint, request_id se houver e tente novamente.

Exemplos rápidos

curl -X GET "URL_DA_API/public/v1/leads?limit=100" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

GET /public/v1/leads?limit=100&cursor=NEXT_CURSOR_AQUI
GET /public/v1/leads?limit=100&include_deleted=true
GET /public/v1/leads/123
GET /public/v1/leads/schema
GET /public/v1/integration/health

Próximos passos

Leia autenticação, depois implemente listagem e paginação antes de avançar para CRM, ERP ou n8n.

Ver autenticação Ver integração com n8n