API REST — Visão geral, autenticação e convenções
Ponto de partida para integrar com a API REST do Contrate 360: base URL, autenticação por Bearer Token (Sanctum), pré-requisitos de licença e addon, rate limit, paginação e padrões de resposta.
API REST do Contrate 360 — Visão geral
A API REST permite que sistemas externos (n8n, integrações próprias, automações) leiam e gravem dados do CRM de forma programática: contatos, conversas/mensagens de WhatsApp, faturas, propostas, agendamentos, produtos e webhooks.



Base URL
https://contrate360.com/api/v1
A documentação interativa fica em Configurações → API Docs (/app/settings/api-docs) e a gestão de tokens em Configurações → API Tokens.
Pré-requisitos (3 portões de acesso)
Toda requisição passa pelo middleware api.tenant, que valida, nesta ordem, antes de chegar ao controller:
- Autenticação — token Sanctum válido. Sem token ⇒
401 Unauthenticated. - Tenant — o usuário do token precisa estar vinculado a um tenant. Sem tenant ⇒
403 Tenant not found. - Licença — o plano precisa ter
api_enabled. Caso contrário ⇒403 API access is not available on this license. - Addon — o tenant precisa ter o addon
api_accessativo (Loja de Aplicativos). Caso contrário ⇒403 API Access addon is not active.
Ou seja: além do token, a conta precisa ter a API liberada no plano e o addon de API ativado.
Autenticação
A API usa Bearer Tokens (Laravel Sanctum). Crie o token em Configurações → API Tokens e envie-o no header Authorization de toda requisição:
curl https://contrate360.com/api/v1/contacts \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Accept: application/json"
Sempre envie também Accept: application/json para garantir respostas JSON (inclusive em erros de validação). Para corpos JSON em POST/PUT, envie Content-Type: application/json.
Rate limit
60 requisições por minuto, por token. O contador é por tenant + token e reinicia a cada 60 segundos. As respostas incluem:
X-RateLimit-Limit— o teto (60).X-RateLimit-Remaining— quantas requisições restam na janela atual.
Ao estourar o limite, a API responde 429 Too Many Requests com header Retry-After: 60. Planeje retries com backoff respeitando esse header.
Limite diário por empresa
Além do limite por minuto, cada empresa tem uma cota de chamadas por dia, somada entre todos os tokens. Ela zera à meia-noite (horário de Brasília) e conta cada requisição aceita.
- Com limite, as respostas incluem
X-Daily-LimiteX-Daily-Remaining. - Quando a cota acaba, a API responde
429com"error": "daily_limit_reached"eRetry-Afterem segundos até a meia-noite. - Se o administrador da plataforma pausar a API da empresa, as chamadas recebem
403com"error": "api_paused". - O uso de hoje aparece em Configurações › API Tokens e em Cobrança e Plano.
Paginação
Os endpoints de listagem (index) retornam dados paginados com um bloco meta:
{
"data": [ /* ...itens... */ ],
"meta": {
"current_page": 1,
"last_page": 5,
"per_page": 50,
"total": 230
}
}
per_page— itens por página. Padrão 50, máximo 100 (valores maiores são reduzidos a 100).page— número da página desejada (padrão 1).
Exceção: a listagem de mensagens (GET /conversations/{id}/messages) usa paginação por cursor (before_id / after_id) e retorna has_more em vez de meta. A listagem de webhooks (GET /webhooks) retorna todos os registros sem paginação.
Ordenação e filtros
Listagens aceitam sort_by e sort_dir (asc/desc). Apenas colunas de uma allowlist são aceitas em cada recurso (veja o artigo de cada endpoint); valores fora da lista são ignorados e a ordenação padrão é aplicada. Filtros são passados como query string (ex: ?status=open&per_page=25).
Convenções de resposta
- Recurso único:
{ "data": { ... } }. - Criação/atualização:
{ "data": { ... }, "message": "..." }. - Exclusão:
{ "message": "... deleted successfully." }(soft delete na maioria dos recursos). - Datas/horas em ISO 8601 (ex:
2026-03-15T10:30:00-03:00); datas puras emYYYY-MM-DD. - Valores monetários como
float; moeda padrãoBRL. - Isolamento por tenant: você só enxerga e altera dados do seu próprio tenant. Tentar acessar um ID de outro tenant retorna
404.
Recursos disponíveis
- Contatos —
/contacts - Conversas —
/conversations - Mensagens —
/conversations/{id}/messages,/messages/send - Faturas —
/invoices(+ pagamentos) - Gateways de pagamento —
/payment-gateways(descoberta dos IDs para usar em faturas) - Propostas —
/proposals - Agendamentos —
/appointments - Produtos —
/products - Webhooks (outbound) —
/webhooks - WhatsApp Connector —
/wa-connector(canais, templates e envio de templates da API Oficial Meta)
Cada recurso tem um artigo dedicado com todos os parâmetros, validações e exemplos de payload.