Documentação da API

Contatos

Esta página documenta apenas as rotas para listar e adicionar contatos, seguindo um layout de documentação profissional e enxuto.

Visão geral

Base URL
https://api.whatsapp.fluxki.com.br
Autenticação obrigatória: todas as rotas desta seção exigem os cabeçalhos Authorization, Content-Type e X-Token-Type: external-app.

Headers obrigatórios

Authorization: Bearer <SEU_TOKEN_DE_ACESSO>
Content-Type: application/json
X-Token-Type: external-app

Rotas incluídas

Método Rota Descrição
GET /contacts Lista os contatos disponíveis na conta.
POST /contacts Cria ou atualiza um contato com base no número informado.

1. Listar contatos

GET
/contacts

Retorna a lista de contatos da conta autenticada.

Exemplo de requisição

curl -X GET "https://api.whatsapp.fluxki.com.br/contacts" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>" \
  -H "Content-Type: application/json" \
  -H "X-Token-Type: external-app"

Exemplo de resposta

{
  "contacts": [
    {
      "id": "5511999999999",
      "name": "João Silva",
      "number": "+55 11 99999-9999"
    }
  ]
}

2. Adicionar contato

POST
/contacts

Cria um contato novo ou atualiza um já existente, usando o número como referência principal.

Corpo da requisição

Campos obrigatórios: name e number. Os demais são opcionais. 

{
  "cmsId": 123,
  "name": "Fulano da Silva",
  "number": "+55 11 99999-9999",
  "comments": "Cliente prioritário",
  "birthday": "1990-01-01",
  "addresses": [
    {
      "city": "São Paulo",
      "country": "Brasil",
      "country_code": "BR",
      "state": "SP",
      "street": "Rua Exemplo, 123",
      "type": "home",
      "zip": "01000-000"
    }
  ],
  "emails": [
    {
      "email": "fulano@email.com",
      "type": "work"
    }
  ],
  "org": {
    "company": "Empresa X",
    "department": "Comercial",
    "title": "Gerente"
  },
  "phones": [
    {
      "phone": "+55 11 98888-7777",
      "wa_id": "5511988887777",
      "type": "mobile"
    }
  ],
  "urls": [
    {
      "url": "https://site.com",
      "type": "website"
    }
  ],
  "cmsGroupsIds": [1, 2, 3]
}

Campos do contato

Campo Tipo Obrigatório Descrição
cmsId number Não ID do contato no CMS.
name string Sim Nome do contato.
number string Sim Número de telefone em formato internacional.
comments string | null Não Observações do contato.
birthday string Não Data de nascimento.
addresses array Não Lista de endereços do contato.
emails array Não Lista de e-mails.
org object Não Dados da empresa/cargo.
phones array Não Outros telefones do contato.
urls array Não Links relacionados ao contato.
cmsGroupsIds number[] Não IDs dos grupos do CMS associados ao contato.

Estruturas auxiliares

Objeto Campos
addresses[] city, country, country_code, state, street, type, zip
emails[] email, type
org company, department (opcional), title (opcional)
phones[] phone, wa_id (opcional), type
urls[] url, type

Exemplo de requisição

curl -X POST "https://api.whatsapp.fluxki.com.br/contacts" \
  -H "Authorization: Bearer <SEU_TOKEN_DE_ACESSO>" \
  -H "Content-Type: application/json" \
  -H "X-Token-Type: external-app" \
  -d '{
    "name": "João Silva",
    "number": "+55 11 99999-9999",
    "comments": "Novo cliente",
    "cmsGroupsIds": [1, 2]
  }'

Exemplo de resposta de sucesso

{
  "contact": {
    "id": "5511999999999",
    "name": "João Silva",
    "number": "+55 11 99999-9999",
    "comments": "Novo cliente"
  }
}

Erros comuns

Status Quando acontece Exemplo de mensagem
401 Token ausente, inválido ou sem permissão. Não autenticado
422 Número de telefone inválido. O número de telefone é inválido...
400 Falha ao validar ou salvar o contato. Não foi possível salvar o contato
Dica: use sempre o número em formato internacional para evitar erro de validação.