Contatos

O recurso /contacts permite ler, criar e atualizar contatos da própria conta. Não existe DELETE na v1. A exclusão continua no fluxo protegido do painel.

Campos

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

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/018f6d6e-7b55-7d61-8bd0-1b2c3d4e5f60" \
  --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": "Maria Silva",
    "email": "maria@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": "018f6d6e-7b55-7d61-8bd0-1b2c3d4e5f60"
      }
    ],
    "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/018f6d6e-7b55-7d61-8bd0-1b2c3d4e5f60" \
  --header "Authorization: Bearer osk_live_exemplo_ficticio_00000000000000000000000000" \
  --header "Content-Type: application/json" \
  --data '{
    "nome": "Maria de Souza",
    "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.

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.