API Pública — Ricisoares ADV

Como obter uma API Key

Faça login no Ricisoares ADV como administrador do escritório.
Acesse Integrações → API Keys.
Clique em Gerar nova key, dê um nome e selecione os escopos.
Copie a key — ela só será mostrada uma vez.

Autenticação

Todas as chamadas a /api/public/* exigem o header:

X-API-Key: cxa_live_xxxxxxxxxxxxxxxxxxxxxxxx

Sem o header (ou com key inválida/expirada/revogada): 401 Unauthorized.

Com a key porém sem o escopo necessário: 403 Forbidden.

Endpoints disponíveis

Método	Endpoint	Escopo	Descrição
GET	/api/public/processos	`processos:read`	Lista processos do escritório.
GET	/api/public/processos/{id}	`processos:read`	Detalhe de um processo.
GET	/api/public/clientes	`clientes:read`	Lista clientes do escritório.
GET	/api/public/intimacoes	`intimacoes:read`	Lista intimações capturadas pelo DJEN.
GET	/api/public/audiencias	`audiencias:read`	Lista audiências (filtro `?futuras=true`).
GET	/api/public/prazos	`prazos:read`	Lista prazos.
POST	/api/public/leads	`leads:write`	Cria lead — ideal para formulários do site institucional.

Exemplos

Listar processos

curl https://seu-dominio/api/public/processos \
  -H "X-API-Key: cxa_live_xxxxxxxx"

Criar lead a partir do site

curl -X POST https://seu-dominio/api/public/leads \
  -H "X-API-Key: cxa_live_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "Maria da Silva",
    "email": "maria@exemplo.com",
    "telefone": "+5511999999999",
    "interesse": "Trabalhista — rescisão indireta",
    "origem": "site"
  }'

Webhooks

O Ricisoares ADV expõe alguns webhooks de entrada (callbacks de provedores externos):

POST /api/asaas-webhook — eventos de cobrança Asaas (HMAC).
POST /api/assinatura-webhook — callbacks de ZapSign / D4Sign (HMAC).
POST /api/monitoramento/whatsapp/webhook — mensagens recebidas (Z-API/Evolution/Meta).

Webhooks de saída (notificar seu sistema quando algo muda no Ricisoares ADV) estão no roadmap.

Rate limit

Cada API key tem um limite configurável de requisições por minuto (padrão 60). Excedido o limite a chamada retorna 401.

Você pode ajustar o limite por key em Integrações → API Keys.

Códigos de erro

Código	Significado
200 / 201	OK
400	Requisição malformada (corpo inválido, campo obrigatório ausente).
401	API key ausente, inválida, expirada ou rate limit excedido.
403	API key sem o escopo necessário.
404	Recurso não encontrado (ou pertence a outro escritório).
500	Erro interno — reportar com timestamp.

Limites e princípios

Multi-tenant rigoroso: a API key define o escritório — toda query é filtrada automaticamente.
Escopos mínimos: dê apenas os scopes que sua integração realmente usa.
Read-mostly: a maioria dos endpoints é leitura. Escrita por enquanto só em /leads.
IP whitelist opcional por key — recomendamos pra integrações server-to-server.

Ricisoares ADV — versão da API documentada em /openapi.json.