Obter um lote

Retorna o resumo de um lote de negociações com as contagens agregadas de itens por status.

GEThttps://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations/batches/{id}

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

Retorna o resumo de um lote de negociações: título, status e contagens agregadas por situação dos itens. É o endpoint de acompanhamento depois de criar um lote ou enviar uma planilha.

Parâmetros de rota

iduuidobrigatório

Identificador do lote.

Status do lote

Status	Significado
`PENDING`	Aguardando confirmação. Chame Confirmar lote
`VALIDATING`	Planilha em leitura e validação
`PROCESSING`	Agentes em execução nos itens válidos
`COMPLETED`	Processamento concluído
`FAILED`	Falha no processamento
`CANCELED`	Lote cancelado

Campo	Significado
`total`	Total de itens no lote
`pending`	Aguardando processamento
`valid`	Passaram na validação
`processing`	Sendo processados agora
`existing`	Ignorados — já existe negociação ativa para a contraparte
`conflict`	Conflito de telefone — outra negociação ativa usa o mesmo número
`error`	Falharam na validação ou no processamento

Esses dois números refletem a proteção contra abordagem duplicada: a contraparte já está em uma negociação ativa. Não é falha da sua integração — é o comportamento esperado de idempotência. Ver Idempotência.

Acompanhando o processamento

Polling até concluir

const TERMINAIS = ['COMPLETED', 'FAILED', 'CANCELED'];

async function aguardarConclusao(batchId, apiKey, maxTentativas = 30) {
  const base = 'https://external-api.arbitralis.com.br/api/external/v1';

  for (let tentativa = 0; tentativa < maxTentativas; tentativa += 1) {
    const response = await fetch(`${base}/extrajudicial/negotiations/batches/${batchId}`, {
      headers: { 'X-API-KEY': apiKey },
    });

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

    if (TERMINAIS.includes(data.status)) {
      return data;
    }

    await new Promise((resolve) => setTimeout(resolve, 15_000));
  }

  throw new Error(`Lote ${batchId} não concluiu no tempo esperado`);
}

Espace as verificações

Um lote grande leva minutos para processar. Verificar a cada 15 ou 30 segundos é suficiente e preserva o seu limite de 60 requisições por minuto.

Erros

Código	Causa
`401`	API key ausente, inválida ou inativa
`404`	Lote não encontrado neste workspace
`429`	Limite de requisições excedido

Requisição

curl -X GET "https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations/batches/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" \
  -H "X-API-KEY: arb_live_SUA_CHAVE"

const batchId = '1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d';

const response = await fetch(
  `https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations/batches/${batchId}`,
  { headers: { 'X-API-KEY': 'arb_live_SUA_CHAVE' } }
);

const { data: lote } = await response.json();
console.log(`${lote.totals.valid} de ${lote.totals.total} itens válidos`);

import requests

batch_id = "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"

response = requests.get(
    f"https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations/batches/{batch_id}",
    headers={"X-API-KEY": "arb_live_SUA_CHAVE"},
)

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

Resposta

{
  "success": true,
  "data": {
    "batchId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "title": "Campanha agosto/2026",
    "status": "PROCESSING",
    "totals": {
      "total": 250,
      "pending": 0,
      "valid": 231,
      "processing": 12,
      "existing": 8,
      "conflict": 3,
      "error": 8
    },
    "createdAt": "2026-08-07T14:32:10.000Z",
    "updatedAt": "2026-08-07T15:10:44.000Z"
  }
}

Status do lote

Contagens

Acompanhando o processamento

Erros