Ingerir processo

Cria ou reutiliza um processo judicial e suas partes, com idempotência pelo número do processo.

POSThttps://external-api.arbitralis.com.br/api/external/v1/processes

AutenticaçãoX-API-KEYSíncrono — a resposta já traz o resultado

Cria um processo judicial no workspace, junto com as partes envolvidas. Se já existir um processo com o mesmo numero na empresa, ele é reutilizado — a resposta indica isso em idempotent.

Registrar o telefone das partes é o que permite o auto-vínculo da conversa: quando a pessoa responde por WhatsApp, a mensagem é associada automaticamente ao processo correto.

Body

tipostringobrigatório

Tipo do vínculo. Este endpoint aceita apenas PROCESSO.

valoresPROCESSO

numerostringobrigatório

Número do processo. Chave de idempotência por empresa.

canalDeEnviostringobrigatório

Canal de comunicação — por exemplo WHATSAPP.

iniciostringobrigatório

Data de início do processo, em ISO 8601.

requerentesarrayobrigatório

Partes requerentes. Ao menos uma. Cadastradas como AUTOR.

requeridosarrayobrigatório

Partes requeridas. Ao menos uma. Cadastradas como RÉU.

advogadoRequerentearrayopcional

Advogados do requerente. Cadastrados como ADVOGADO.

tipoProcessostringopcionalpadrão CUMPRIMENTO

Tipo do processo judicial.

valoresEXECUCAO_TITULOEXECUCAO_SENTENCACUMPRIMENTO

titulostringopcional

Título do processo. Se omitido, usa o numero.

valorstringopcional

Valor da causa, como texto. Convertido para número internamente.

breveRelatostringopcional

Descrição do processo.

ritostringopcional

Rito processual. Guardado em dados adicionais.

metodostringopcional

Método. Guardado em dados adicionais.

idUnicostringopcional

Identificador de origem no sistema externo, para rastreio.

Parte (requerentes[], requeridos[], advogadoRequerente[])

nomestringobrigatório

Nome completo da parte.

documentostringopcional

CPF ou CNPJ. Quando ausente, a pessoa é deduplicada pelo nome.

telefonestringopcional

Telefone da parte. Recomendado — habilita o auto-vínculo da conversa.

emailstringopcional

E-mail da parte.

Campos da resposta

Campo	Descrição
`processoId`	Identificador do processo criado ou reutilizado
`numeroProcesso`	Número do processo
`partesCount`	Total de partes vinculadas — requerentes + requeridos + advogados
`idempotent`	`true` se o processo já existia e foi reutilizado

Idempotência pelo número

O numero é a chave. Repetir a chamada com o mesmo número devolve o processo existente com idempotent: true, em vez de criar um duplicado. Isso torna o retry seguro.

Uma reingestão não atualiza o processo

Quando o processo já existe, os dados enviados não sobrescrevem os do cadastro. Para corrigir informações de um processo já ingerido, use o painel da Arbitralis.

Papéis das partes

Campo do payload	Papel no processo
`requerentes[]`	AUTOR
`requeridos[]`	RÉU
`advogadoRequerente[]`	ADVOGADO

Sempre informe o telefone do requerido

O telefone da parte requerida é o que permite associar automaticamente as conversas de WhatsApp ao processo. Sem ele, as mensagens recebidas chegam sem vínculo e precisam ser associadas manualmente.

Deduplicação de pessoas

Com documento — a pessoa é localizada pelo CPF/CNPJ e reaproveitada se já existir.
Sem documento — a deduplicação é feita pelo nome, o que é menos preciso. Informe o documento sempre que possível.

Erros

Código	Causa
`401`	API key ausente, inválida ou inativa
`422`	Campo obrigatório ausente, CPF/CNPJ inválido, data mal formatada, ou lista de partes vazia
`429`	Limite de requisições excedido

Requisição

curl -X POST "https://external-api.arbitralis.com.br/api/external/v1/processes" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: arb_live_SUA_CHAVE" \
  -d '{
    "tipo": "PROCESSO",
    "numero": "0001234-56.2026.8.26.0100",
    "canalDeEnvio": "WHATSAPP",
    "inicio": "2026-08-01T00:00:00Z",
    "tipoProcesso": "CUMPRIMENTO",
    "titulo": "Cumprimento de sentença - Contrato 8842",
    "valor": "15000.00",
    "breveRelato": "Cumprimento de sentença referente ao contrato 8842",
    "requerentes": [
      {
        "nome": "Empresa Credora LTDA",
        "documento": "12345678000190",
        "email": "[email protected]"
      }
    ],
    "requeridos": [
      {
        "nome": "Maria Souza",
        "documento": "12345678900",
        "telefone": "+5511999999999",
        "email": "[email protected]"
      }
    ],
    "advogadoRequerente": [
      {
        "nome": "Dr. Carlos Advogado",
        "documento": "98765432100",
        "email": "[email protected]"
      }
    ]
  }'

const response = await fetch('https://external-api.arbitralis.com.br/api/external/v1/processes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'arb_live_SUA_CHAVE',
  },
  body: JSON.stringify({
    tipo: 'PROCESSO',
    numero: '0001234-56.2026.8.26.0100',
    canalDeEnvio: 'WHATSAPP',
    inicio: '2026-08-01T00:00:00Z',
    requerentes: [{ nome: 'Empresa Credora LTDA', documento: '12345678000190' }],
    requeridos: [
      {
        nome: 'Maria Souza',
        documento: '12345678900',
        telefone: '+5511999999999',
      },
    ],
  }),
});

const { data } = await response.json();

if (data.idempotent) {
  console.log('Processo já existia, reutilizado');
}

import requests

response = requests.post(
    "https://external-api.arbitralis.com.br/api/external/v1/processes",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "arb_live_SUA_CHAVE",
    },
    json={
        "tipo": "PROCESSO",
        "numero": "0001234-56.2026.8.26.0100",
        "canalDeEnvio": "WHATSAPP",
        "inicio": "2026-08-01T00:00:00Z",
        "requerentes": [{"nome": "Empresa Credora LTDA", "documento": "12345678000190"}],
        "requeridos": [
            {
                "nome": "Maria Souza",
                "documento": "12345678900",
                "telefone": "+5511999999999",
            }
        ],
    },
)

data = response.json()["data"]

Resposta

{
  "success": true,
  "data": {
    "processoId": "9f8e7d6c-5b4a-4928-9706-f5e4d3c2b1a0",
    "numeroProcesso": "0001234-56.2026.8.26.0100",
    "partesCount": 3,
    "idempotent": false
  },
  "message": "Criado com sucesso"
}

{
  "success": true,
  "data": {
    "processoId": "9f8e7d6c-5b4a-4928-9706-f5e4d3c2b1a0",
    "numeroProcesso": "0001234-56.2026.8.26.0100",
    "partesCount": 3,
    "idempotent": true
  },
  "message": "Criado com sucesso"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "CPF/CNPJ inválido",
    "details": [
      {
        "code": "custom",
        "path": ["requeridos", 0, "documento"],
        "message": "CPF/CNPJ inválido"
      }
    ],
    "errorEventId": "b1f3c6d8-2a44-4d9e-9f10-7c5b8e2a1d33"
  }
}