Criar lote via JSON

Cria um lote de até 1000 negociações a partir de um array JSON, com validação item a item.

POSThttps://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations/batches/json
AutenticaçãoX-API-KEYSíncrono — a resposta já traz o resultado

Cria uma campanha de negociação a partir de um array de objetos. Cada item vira uma negociação conduzida pelo agente do lote — ou por um agente próprio, se você sobrescrever.

Antes de montar o payload, consulte Obter um agente para saber quais variáveis são obrigatórias.

Body
agenteIduuidobrigatório

Agente padrão aplicado a todos os itens. Pode ser sobrescrito por item.

startModestringobrigatório

NOW inicia todas as negociações imediatamente. SCHEDULED exige scheduledFor.

valoresNOWSCHEDULED
itemsarrayobrigatório

Itens de negociação. Mínimo 1, máximo 1000 por chamada.

scheduledForstringopcional

Data e hora de início em ISO 8601. Obrigatório quando startMode é SCHEDULED.

titlestringopcional

Título de exibição do lote, até 255 caracteres. Gerado automaticamente se omitido.

batchCodestringopcional

Código único do lote, até 50 caracteres. Chave de idempotência.

items[]
externalIdstringobrigatório

Identificador do registro no seu sistema. Chave de idempotência por item, até 255 caracteres.

counterpartyobjectobrigatório

Dados de contato da contraparte deste item.

agenteInputobjectopcional

Variáveis do agente para este item. Sobrescreve ou complementa os valores padrão do lote.

agenteIduuidopcional

Sobrescreve o agente para este item. Se omitido, herda o agente do lote.

items[].counterparty
cpfCnpjstringobrigatório

CPF (11 dígitos) ou CNPJ (14 dígitos).

namestringobrigatório

Nome completo da contraparte, até 255 caracteres.

phonestringobrigatório

Telefone em formato internacional.

emailstringopcional

E-mail da contraparte.

Status do lote na resposta

statusQuando
PROCESSINGstartMode: NOW com pelo menos um item válido
PENDINGstartMode: SCHEDULED
FAILEDTodos os itens foram rejeitados na validação

Resultado por item

statusSignificado
VALIDATEDItem aceito. negociacaoId e itemId preenchidos
INVALIDItem rejeitado. Veja errors
Item rejeitado
{
  "externalId": "contrato-8844",
  "status": "INVALID",
  "errors": [
    {
      "code": "MISSING_REQUIRED_BASE_FIELD",
      "field": "counterparty.phone",
      "message": "Telefone é obrigatório"
    }
  ]
}

Idempotência

Com batchCode informado, um lote já existente é devolvido com 200 em vez de duplicado. Isso torna o retry seguro e permite dividir campanhas grandes em chamadas sucessivas com o mesmo código.

Acima de 1000 itens

Faça chamadas sucessivas com o mesmo batchCode — os itens são agregados ao mesmo lote — ou use o upload de planilha, que aceita um arquivo único.

NOW dispara na hora

Com startMode: "NOW", os agentes começam a atuar assim que o lote é criado — as mensagens saem imediatamente. Se quiser revisar antes, use SCHEDULED ou o fluxo de upload de planilha + confirmação.

Erros

CódigoCausa
400Corpo inválido, ou agente não encontrado/inativo
401API key ausente, inválida ou inativa
429Limite de requisições excedido
Requisição
curl -X POST "https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations/batches/json" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: arb_live_SUA_CHAVE" \
  -d '{
    "agenteId": "3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c",
    "title": "Campanha agosto/2026",
    "batchCode": "campanha-2026-08",
    "startMode": "NOW",
    "items": [
      {
        "externalId": "contrato-8842",
        "counterparty": {
          "cpfCnpj": "12345678900",
          "name": "Maria Souza",
          "phone": "+5511999999999"
        },
        "agenteInput": {
          "valor_pleiteado": 1500.75,
          "piso": 1200.00
        }
      },
      {
        "externalId": "contrato-8843",
        "counterparty": {
          "cpfCnpj": "98765432100",
          "name": "João Pereira",
          "phone": "+5521988888888"
        },
        "agenteInput": {
          "valor_pleiteado": 890.00,
          "piso": 700.00
        }
      }
    ]
  }'
Resposta
{
  "success": true,
  "data": {
    "batchId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "batchCode": "campanha-2026-08",
    "totalItems": 2,
    "totalValid": 2,
    "totalInvalid": 0,
    "status": "PROCESSING",
    "items": [
      {
        "externalId": "contrato-8842",
        "negociacaoId": "7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
        "itemId": "2b3c4d5e-6f7a-4b9c-8d1e-2f3a4b5c6d7e",
        "status": "VALIDATED"
      },
      {
        "externalId": "contrato-8843",
        "negociacaoId": "8d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
        "itemId": "3c4d5e6f-7a8b-4c0d-9e2f-3a4b5c6d7e8f",
        "status": "VALIDATED"
      }
    ]
  }
}