Requisições e respostas

Os 150 endpoints da v1 respondem no mesmo formato, que chamamos de envelope. Assim, você escreve o cliente HTTP uma vez e reaproveita em toda a API.

O envelope

Item
Lista
Erro

Um recurso vem sempre dentro de data:

{
  "data": {
    "id": 1042,
    "name": "Marina Alves",
    "number": "5511999999999"
  }
}

Listas trazem data como array e um meta com os dados de paginação:

{
  "data": [
    { "id": 1042, "name": "Marina Alves" },
    { "id": 1043, "name": "Rafael Nunes" }
  ],
  "meta": { "page": 1, "perPage": 20, "hasMore": true }
}

Erros nunca vêm em data. O corpo tem um único campo error:

{
  "error": {
    "code": "ERR_API_VALIDATION",
    "message": "Informe ao menos um destes campos: name, number.",
    "details": null
  }
}

Leia sempre o recurso em resposta.data, nunca na raiz do corpo. O envelope pode ganhar campos novos no futuro.

Enviando dados

application/json

O padrão para criar e editar. Use em todo POST e PUT que não envolva arquivo.

multipart/form-data

Necessário quando a requisição leva arquivo, como mídia de mensagem, imagem de produto, anexo de anotação do CRM ou planilha de campanha. Os campos de texto vão no mesmo formulário.

Os endpoints que recebem arquivo aceitam os dois formatos. Sem arquivo, envie JSON puro. Com arquivo, envie o formulário. Quando os dois formatos existem, a referência do endpoint mostra ambos.

Códigos de status

Código	Quando acontece
`200`	Leitura ou alteração concluída.
`201`	Recurso criado. O corpo traz o registro novo.
`202`	Aceito para processamento assíncrono (hoje, o envio de mensagem). O corpo traz o `jobId`.
`204`	Concluído, sem corpo na resposta. Comum em exclusões.
`400`	Requisição malformada ou campo obrigatório ausente.
`401`	Problema com o token. Veja Autenticação.
`403`	Empresa inativa, plano sem API ou token sem a permissão necessária.
`404`	O recurso não existe ou pertence a outra empresa.
`409`	Conflito de estado, incluindo reuso de `Idempotency-Key`.
`422`	O corpo está bem formado, mas viola uma regra de negócio.
`429`	A empresa atingiu o limite de requisições por minuto.

Ordem de verificação

Antes de chegar ao endpoint, cada requisição passa por cinco verificações, nesta ordem. Você recebe o erro da primeira que falhar, o que ajuda a encontrar o problema mais rápido.

Token

O token existe, é válido, não foi revogado nem expirou, e a origem da chamada está na allowlist de IPs. Se falhar, a resposta é 401.

Empresa ativa

A empresa dona do token está ativa e dentro da validade. Se falhar, a resposta é 403.

API liberada no plano

O plano contratado inclui a API pública. Se falhar, a resposta é 403 ERR_API_NOT_ENABLED.Essa verificação não se aplica a instalações on-premise.

Rate limit

A empresa está dentro do limite de requisições por minuto. Se falhar, a resposta é 429.

Permissão do token

O token tem permissão para aquele método naquele módulo. Se falhar, a resposta é 403 ERR_API_FORBIDDEN_SCOPE.

Identificadores e escopo

Todo recurso tem um id numérico, e cada id vale apenas dentro da empresa do token. Se você pedir um id que pertence a outra empresa, recebe 404, como se o registro não existisse.

Os ids não são globais, e não há como prever qual id um registro terá em outro ambiente. Não copie ids de homologação para produção. Busque o registro pelo campo natural (número do contato, SKU do produto, e-mail do usuário) e guarde o id que vier na resposta.

Comece aqui

Fundamentos

Guias

Requisições e respostas

O envelope

Enviando dados

Códigos de status

Ordem de verificação

Identificadores e escopo

​O envelope

​Enviando dados

​Códigos de status

​Ordem de verificação

​Identificadores e escopo

O envelope

Enviando dados

Códigos de status

Ordem de verificação

Identificadores e escopo