Contatos

O recurso /contacts permite ler, criar, atualizar e apagar contatos da própria conta.

Campos

Identidades de outros canais são somente leitura. A v1 cria contatos apenas por telefone.

Sobre o cpf: ele sai aqui, mas não sai nos webhooks. A diferença é o caminho. Aqui a consulta é feita pela sua chave, fica registrada e você escolhe a hora. No webhook o dado sairia sozinho e passaria por lugares que ninguém controla depois: o log do seu servidor, o log do seu gateway e ferramentas de automação no meio (Make, n8n, Zapier). Como o documento é do seu cliente e não da sua empresa, ele fica no caminho que deixa rastro.

Se você recebe um evento e precisa do CPF, use o id do contato que veio no evento e consulte aqui.

Endpoints

Listar contatos

Filtros disponíveis:

curl --request GET \
  --url "https://api.octosolve.com.br/api/v1/contacts?status=ativo&tag=vip&limit=50" \
  --header "Authorization: Bearer osk_live_exemplo_ficticio_00000000000000000000000000" \
  --header "Accept: application/json"

Consultar um contato

curl --request GET \
  --url "https://api.octosolve.com.br/api/v1/contacts/11111111-1111-4111-8111-111111111111" \
  --header "Authorization: Bearer osk_live_exemplo_ficticio_00000000000000000000000000" \
  --header "Accept: application/json"

Um UUID inexistente ou pertencente a outra conta responde o mesmo 404 not_found.

Criar um contato

curl --request POST \
  --url "https://api.octosolve.com.br/api/v1/contacts" \
  --header "Authorization: Bearer osk_live_exemplo_ficticio_00000000000000000000000000" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: contato_erp_12345" \
  --data '{
    "telefone": "5511999998888",
    "nome": "Pessoa Exemplo",
    "email": "pessoa.exemplo@example.com",
    "cidade": "São Paulo",
    "data_nascimento": "1990-05-20",
    "observacoes": "Prefere contato à tarde.",
    "tags": ["vip", "site"],
    "status": "ativo"
  }'

O telefone é normalizado para dígitos e identifica o contato dentro da conta. Se já existir um contato com o mesmo telefone, a API responde 409 conflict:

{
  "error": {
    "code": "conflict",
    "message": "Já existe um contato com este telefone.",
    "details": [
      {
        "existing_id": "11111111-1111-4111-8111-111111111111"
      }
    ],
    "request_id": "0123456789abcdef0123456789abcdef"
  }
}

Idempotência na criação

O header opcional Idempotency-Key aceita até 128 caracteres e evita repetir uma criação quando há timeout ou nova tentativa. Use uma chave estável e única para a mesma operação de origem.

O registro é durável e fica retido por 24 horas:

• Mesma chave e mesmo pedido: devolve a resposta original, inclusive o status HTTP.
• Mesma chave com corpo, método ou rota diferente: 409 idempotency_conflict.
• Pedido original ainda em andamento: 409 idempotency_in_progress. Aguarde e tente novamente com a mesma chave e o mesmo corpo.

Atualizar um contato

curl --request PATCH \
  --url "https://api.octosolve.com.br/api/v1/contacts/11111111-1111-4111-8111-111111111111" \
  --header "Authorization: Bearer osk_live_exemplo_ficticio_00000000000000000000000000" \
  --header "Content-Type: application/json" \
  --data '{
    "nome": "Pessoa Exemplo Atualizada",
    "observacoes": null,
    "tags": ["vip", "retorno"]
  }'

No PATCH, um campo ausente não muda. Um null explícito limpa um campo que aceita null. Atualizações concorrentes usam a regra da última gravação, sem bloqueio otimista. Use updated_at da resposta se a sua integração precisar detectar uma alteração posterior.

Apagar um contato

curl --request DELETE \
  --url "https://api.octosolve.com.br/api/v1/contacts/11111111-1111-4111-8111-111111111111" \
  --header "Authorization: Bearer osk_live_exemplo_ficticio_00000000000000000000000000" \
  --header "Accept: application/json"

Resposta 200:

{
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "cobrancas_canceladas": 2,
    "cobrancas_com_falha": 0,
    "cliente_mascarado": true
  }
}

A exclusão é definitiva. Ela cancela toda cobrança pendente do contato no Asaas, e o resumo mostra quantas foram canceladas em cobrancas_canceladas e quantas falharam ao cancelar em cobrancas_com_falha. Quando o regulatório impede apagar o cliente no Asaas, ele é mascarado em vez de removido, e cliente_mascarado vem true.

O registro financeiro não é apagado, é anonimizado: o histórico de pagamento continua existindo para fins contábeis e fiscais, sem o dado pessoal do contato.

Uma segunda chamada no mesmo id responde 404 not_found, porque o contato já não existe. Chamar duas vezes ao mesmo tempo cancela a cobrança pendente uma única vez: uma chamada responde 200, a outra 404.

Apagar um contato pela API dispara o evento de webhook contact.deleted. Veja o payload em Webhooks.

Receita para Make ou n8n

Para sincronizar contatos de um CRM ou formulário:

1. Receba o registro de origem e normalize o telefone com DDI e DDD.
2. Faça GET /contacts?telefone=NUMERO com uma chave write.
3. Se data estiver vazio, envie POST /contacts com Content-Type: application/json.
4. No POST, preencha Idempotency-Key com um identificador estável, como crm_contato_ID_DA_ORIGEM. Não gere outro valor a cada nova tentativa da mesma execução.
5. Se o contato existir, envie PATCH /contacts/{id} apenas com os campos que deseja alterar.
6. Trate 409 conflict usando error.details[0].existing_id para localizar o contato já criado.
7. Em idempotency_in_progress, espere e repita o mesmo POST, com a mesma chave e o mesmo corpo.
8. Para importar muitos contatos, respeite as três janelas de limites de requisições.