Acompanhar status (SSE)

Abre uma conexão Server-Sent Events para receber atualizações de status do lote em tempo real.

GEThttps://external-api.arbitralis.com.br/api/external/v1/notifications/batches/{batchId}/status-stream

AutenticaçãoX-API-KEYAssíncrono — o processamento continua depois da resposta

Abre uma conexão Server-Sent Events (SSE) que entrega as mudanças de status do lote em tempo real. Alternativa ao polling em Obter um lote — e mais econômica, já que uma conexão aberta consome apenas uma requisição do seu limite.

O primeiro evento traz o estado atual do lote; os seguintes chegam a cada mudança.

Parâmetros de rota

batchIduuidobrigatório

Identificador do lote.

Formato do evento

Todos os eventos usam o nome status e trazem o payload em JSON:

Frame SSE

event: status
data: {"loteId":"1a2b…","empresaId":"9f8e…","status":"ENVIANDO","totais":{…},"dataAtualizacao":"2026-08-07T15:02:11.000Z"}

Campo	Descrição
`loteId`	Identificador do lote
`empresaId`	Empresa dona do lote
`escritorioId`	Workspace dono do lote
`status`	Status atual
`totais`	Contagens de itens por situação
`dataAtualizacao`	Momento da atualização (ISO 8601)

Headers da conexão

Header	Valor
`Content-Type`	`text/event-stream`
`Cache-Control`	`no-cache`
`Connection`	`keep-alive`

Boas práticas

Encerre a conexão ao receber um status terminal (ENVIADO, FINALIZADO) — conexões abertas indefinidamente consomem recursos dos dois lados.
Reconecte com backoff se a conexão cair. Ao reconectar, o primeiro evento traz o estado atual, então você não perde o contexto.
Não abra um stream por item — o stream é por lote.

Streaming pode estar indisponível

Se a infraestrutura de streaming estiver fora do ar, o endpoint responde 503. Trate esse caso caindo para o polling em Obter um lote.

Ambientes serverless

Em funções serverless com timeout curto, SSE raramente é a melhor escolha — a conexão morre junto com a função. Prefira polling com intervalo crescente nesses ambientes.

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
`503`	Streaming de status temporariamente indisponível

Requisição

curl -N -X GET "https://external-api.arbitralis.com.br/api/external/v1/notifications/batches/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/status-stream" \
  -H "X-API-KEY: arb_live_SUA_CHAVE" \
  -H "Accept: text/event-stream"

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

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

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { value, done } = await reader.read();

  if (done) {
    break;
  }

  buffer += decoder.decode(value, { stream: true });

  const frames = buffer.split('\n\n');
  buffer = frames.pop() ?? '';

  for (const frame of frames) {
    const linhaDeDados = frame.split('\n').find((linha) => linha.startsWith('data: '));

    if (!linhaDeDados) {
      continue;
    }

    const evento = JSON.parse(linhaDeDados.slice(6));
    console.log(evento.status, evento.totais);

    if (['ENVIADO', 'FINALIZADO'].includes(evento.status)) {
      await reader.cancel();
      break;
    }
  }
}

import json
import requests

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

with requests.get(
    f"https://external-api.arbitralis.com.br/api/external/v1/notifications/batches/{batch_id}/status-stream",
    headers={
        "X-API-KEY": "arb_live_SUA_CHAVE",
        "Accept": "text/event-stream",
    },
    stream=True,
) as response:
    for linha in response.iter_lines(decode_unicode=True):
        if not linha or not linha.startswith("data: "):
            continue

        evento = json.loads(linha[6:])
        print(evento["status"], evento["totais"])

        if evento["status"] in ("ENVIADO", "FINALIZADO"):
            break

Resposta

{
  "loteId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "empresaId": "9f8e7d6c-5b4a-4928-9706-f5e4d3c2b1a0",
  "escritorioId": "2b3c4d5e-6f7a-4b9c-8d1e-2f3a4b5c6d7e",
  "status": "PROCESSANDO",
  "totais": {
    "totalItens": 250,
    "validos": 0,
    "invalidos": 0,
    "enviados": 0,
    "pendentes": 250
  },
  "dataAtualizacao": "2026-08-07T14:32:10.000Z"
}

{
  "loteId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "status": "ENVIANDO",
  "totais": {
    "totalItens": 250,
    "validos": 243,
    "invalidos": 7,
    "enviados": 118,
    "pendentes": 125
  },
  "dataAtualizacao": "2026-08-07T15:02:11.000Z"
}