API pública do Receptia (v1)

Introdução

A API pública do Receptia tem duas frentes:

• API v1 de leitura — relatórios agregados e leads da sua organização, autenticada por chave. Somente leitura: nenhuma mensagem ou conversa individual é exposta.
• Webhook de entrada de leads — recebimento de contatos enviados por sistemas externos (formulários, landing pages, outras plataformas) direto para o CRM do Receptia.

URL base da API v1: https://receptia-production.up.railway.app/api/public/v1

A lista completa de endpoints, com parâmetros e schemas de resposta, fica na referência interativa, gerada a partir do próprio código — é sempre a versão no ar.

Autenticação

Cada chave pertence a uma organização e é enviada como Bearer token. Os dados retornados são sempre os da organização dona da chave, independentemente de qualquer parâmetro extra.

curl "https://receptia-production.up.railway.app/api/public/v1/reports/overview?start=2026-05-01&end=2026-06-01" \
  -H "Authorization: Bearer rcpt_live_a1b2c3d4.SEU_SEGREDO"

Como gerar, rotacionar e revogar chaves

No aplicativo, em Configurações → Empresa → API. Apenas usuários com papel owner ou admin têm acesso à seção.

• A chave em claro é exibida uma única vez, no momento da geração — o Receptia guarda apenas um hash. Se ela for perdida, use Rotacionar para emitir uma nova.
• Rotacionar cria a chave nova antes de revogar a antiga, para a integração não ficar sem chave válida no intervalo. Atualize o sistema consumidor assim que copiar a nova.
• Revogar invalida a chave imediatamente: as chamadas seguintes recebem 401.

Escopos

Cada credencial declara para que tipo de consumidor foi emitida, e o tipo define quais escopos ela pode carregar. Uma Integração de dados (BI, ERP, planilhas) autentica por Authorization: Bearer; uma Gestão com IA (Claude, ChatGPT) autentica pela URL do conector. Um escopo gravado na credencial mas proibido para o tipo dela não vale — a chamada responde 403, assim como uma chamada sem o escopo exigido pelo endpoint.

Endpoints

Todos os endpoints da v1 são GET e ficam sob https://receptia-production.up.railway.app/api/public/v1. Parâmetros, filtros, paginação e schemas completos estão na referência interativa.

Erros

Corpo de erro padrão:

{ "detail": "Chave de API inválida ou revogada" }

Limites

• Janela máxima por requisição: 92 dias entre start e end. Para períodos maiores, divida em múltiplas chamadas.
• Rate limit por chave: as chamadas são limitadas por janela de tempo, com limites próprios para relatórios e para leads. Ao exceder, a API responde 429 com o header Retry-After em segundos.
• Volume diário de leads: a leitura de leads tem um teto diário de linhas por chave.
• Proteção anti-abuso por IP: tentativas repetidas com chaves inválidas bloqueiam temporariamente o IP de origem (429).
• Somente leitura: a API v1 não escreve nada e não expõe mensagens nem conversas.

Webhook de entrada de leads

Para enviar contatos ao Receptia, use o webhook público de leads. A autenticação é feita pela chave secreta embutida na URL — obtenha a URL completa no aplicativo (Configurações → Integrações) ou via GET /api/leads/ingest/config (JWT). A chave pode ser trocada a qualquer momento com POST /api/leads/ingest/regenerate-key.

curl -X POST "https://receptia-production.up.railway.app/api/webhooks/leads/SUA_WEBHOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "name": "Maria Silva",
        "phone": "5511999990000",
        "email": "maria@exemplo.com.br",
        "source": "landing-page",
        "tags": ["campanha-junho"],
        "custom_data": { "curso_interesse": "RLM" }
      }
    ],
    "duplicate_strategy": "skip",
    "source": "webhook"
  }'

{
  "total": 1,
  "imported": 1,
  "updated": 0,
  "skipped": 0,
  "errors": 0,
  "error_details": []
}