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.

Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.
Página de documentação da API REST, com URL base, autenticação por token e o menu de seções por recurso.
Aba de Webhooks da documentação, listando os eventos disponíveis para notificação em tempo real.
Aba de Webhooks da documentação, listando os eventos disponíveis para notificação em tempo real.
Lista de tokens de API ativos da equipe, com data de criação, último uso e validade de cada um.
Lista de tokens de API ativos da equipe, com data de criação, último uso e validade de cada um.

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:

  1. Autenticação — token Sanctum válido. Sem token ⇒ 401 Unauthenticated.
  2. Tenant — o usuário do token precisa estar vinculado a um tenant. Sem tenant ⇒ 403 Tenant not found.
  3. Licença — o plano precisa ter api_enabled. Caso contrário ⇒ 403 API access is not available on this license.
  4. Addon — o tenant precisa ter o addon api_access ativo (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-Limit e X-Daily-Remaining.
  • Quando a cota acaba, a API responde 429 com "error": "daily_limit_reached" e Retry-After em segundos até a meia-noite.
  • Se o administrador da plataforma pausar a API da empresa, as chamadas recebem 403 com "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 em YYYY-MM-DD.
  • Valores monetários como float; moeda padrão BRL.
  • 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.

api rest autenticação sanctum token integração developer

Este artigo foi útil?

Artigos Relacionados