Visão geral

A API externa da Arbitralis permite que o seu sistema crie e acompanhe notificações extrajudiciais (WhatsApp, e-mail e carta física), inicie e gerencie negociações conduzidas por agentes de IA e ingira processos judiciais — tudo de forma programática, sem passar pela interface web.

Todas as rotas ficam abaixo de /api/external/v1 e são autenticadas por API key.

Início rápido

1. Peça a um administrador do seu workspace para gerar a API key no painel da Arbitralis (ver Autenticação).
2. Guarde a chave em um cofre de segredos — ela é exibida uma única vez.
3. Faça a primeira chamada. O exemplo abaixo lista os agentes disponíveis e confirma que a chave está ativa.

curl -X GET "https://external-api.arbitralis.com.br/api/external/v1/agents" \
  -H "X-API-KEY: arb_live_SUA_CHAVE"

{
  "success": true,
  "data": [
    {
      "agenteId": "3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c",
      "nome": "Cobrança amigável",
      "descricao": "Negociação de dívidas em atraso via WhatsApp",
      "canal": "WHATSAPP",
      "agenteVariables": []
    }
  ]
}

Estrutura das rotas

Todos os caminhos abaixo são relativos à base URL e já incluem o prefixo de versão.

Isolamento por workspace

Cada API key pertence a um workspace (o escritório/câmara contratante). Toda chamada opera exclusivamente dentro desse workspace: os recursos criados nascem nele e as consultas só enxergam dados dele. Não existe forma de acessar dados de outro workspace com a sua chave.

Por isso você não precisa enviar identificadores de escritório ou empresa nos payloads — o contexto vem da própria chave.

Métodos HTTP

Cada endpoint usa um método HTTP que indica a intenção da operação. A regra rápida é: GET só busca (lê) dados; os outros métodos alteram algo.

Em toda esta documentação, cada endpoint aparece com um selo do método logo abaixo do título.

Operações síncronas e assíncronas

Além do método, cada operação pode ser síncrona ou assíncrona:

• Síncrona — a resposta já traz o resultado final. É o caso das consultas (GET) e da criação de recursos simples.
• Assíncrona — a API valida, aceita e devolve um identificador; o processamento continua em segundo plano. É o caso do upload de planilhas, do disparo de envios e da execução de lotes.

Padrão de resposta

Toda resposta segue um envelope previsível.

{
  "success": true,
  "data": {},
  "message": "Opcional"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Descrição legível do problema",
    "details": [],
    "errorEventId": "b1f3c6d8-2a44-4d9e-9f10-7c5b8e2a1d33"
  }
}

O campo errorEventId também vem no header X-Error-Event-Id de toda resposta de erro. Guarde esse valor nos seus logs — é com ele que o suporte da Arbitralis localiza a ocorrência exata.

Os formatos de listagem paginada estão em Paginação.

Formatos de dados

Por onde começar

O primeiro passo depende do seu caso de uso — em ambos, você descobre o identificador antes de enviar qualquer coisa:

Em seguida, consulte o detalhe (template ou agente) para saber exatamente quais variáveis a sua integração precisa enviar.