Acompanhar o processamento

Todo arquivo enviado termina num desfecho: concluido, erro ou duplicado (veja Estados). Você fica sabendo por três caminhos, que se complementam:

Caminho	Como funciona	Bom para
Recibo no bucket	um JSON gravado pela Zabit na sua pasta `recibo/`	a verdade final de cada envio, para conciliar e auditar
Webhook	a Zabit avisa o seu endpoint quando o lote chega ao desfecho	reagir na hora, sem consultar
API de status	você consulta o estado de um arquivo ou de um processamento	conferir sob demanda, sem ler o bucket

No app da Zabit, todos os envios (portal e bucket) aparecem em Monitoramento › Processamentos, com o estado, o motivo e as contagens de cada lote.

Recibo no bucket

O formato completo do recibo está em O recibo. Para lê-lo direto no bucket, a sua role precisa das permissões de leitura opcionais.

# lista os recibos do mês
aws s3api list-objects-v2 \
  --region sa-east-1 \
  --bucket <BUCKET> \
  --prefix ws/<WSID>/recibo/2026/10/

# lê um recibo
aws s3api get-object \
  --region sa-east-1 \
  --bucket <BUCKET> \
  --key ws/<WSID>/recibo/2026/10/diario-20261028.zip.json \
  recibo.json

A listagem precisa de --prefix dentro de concluido/, erro/ ou recibo/ da sua pasta; sem ele, a resposta é AccessDenied.

Webhooks de lote

A Zabit emite um evento por desfecho de lote:

Evento (`type`: `zabit.<evento>.v1`)	Quando	`data.estado`
`monitoring.batch.processado`	o lote terminou com sucesso	`concluido`
`monitoring.batch.rejeitado`	o arquivo foi recusado, ou o processamento falhou ou foi cancelado	`erro`
`monitoring.batch.duplicado`	o mesmo conteúdo já havia sido recebido (é o desfecho normal de um reenvio). Não é erro	`duplicado`

O cadastro do endpoint, o envelope, a verificação da assinatura, os novos envios e a idempotência são os mesmos de todos os eventos da Zabit: siga Receber webhooks e assine os três tipos monitoring.batch.* em Configurações › Integrações. Roteie pelo type: um duplicado não deve disparar o mesmo alarme de um rejeitado.

O data não contém dado pessoal: só identificadores, a chave do arquivo (com documentos e sequências longas de dígitos mascarados), o estado, o código do motivo, contagens agregadas e horários.

{
  "objeto_id": "0b6f1c1e-3f6e-4a53-9f43-2c1f1d5f9a10",
  "execution_id": "7c1d0b56-0f0e-4a53-9f43-2c1f1d5f9a10",
  "chave": "ws/<WSID>/entrada/diario-20261028.zip",
  "estado": "erro",
  "tamanho_bytes": 184372123,
  "recebido_em": "2026-10-28T19:02:11Z",
  "concluido_em": "2026-10-28T19:03:40Z",
  "motivo": "processamento.falhou"
}

Campo	Em quais eventos	Significado
`objeto_id`	os três	o identificador do envio; também é o `subject` do envelope
`execution_id`	os três	o processamento. `null` quando o arquivo foi recusado antes de existir processamento. No `duplicado`, aponta o processamento original
`chave`	os três	o caminho do arquivo na entrada, com o nome que você deu
`estado`	os três	`concluido`, `erro` ou `duplicado`
`tamanho_bytes`, `recebido_em`, `concluido_em`	os três	tamanho do arquivo e horários
`contagens`	`processado`	`registros`, `alertas` e `casos` apurados no lote. Uma contagem ausente não quer dizer zero
`motivo`	`rejeitado`, `duplicado`	o código estável do motivo

A entrega é at-least-once e sem garantia de ordem. Se o aviso não chegar, o recibo e a API de status continuam sendo a referência.

API de status

Duas rotas de leitura:

Rota	Para quê
`GET /monitoring/v1/objects?key=<chave>`	o estado do arquivo que você enviou, pela chave que você conhece
`GET /monitoring/v1/processings/{id}`	o estado de um processamento, pelo identificador dele

Chave de API. As rotas usam o header x-api-key, como o resto da API (veja Autenticação e chaves). A chave precisa ter a permissão monitoring.status.read. Essa permissão é separada da de KYC: quem só acompanha o processamento não ganha o poder de abrir dossiês. A chave com essa permissão é combinada na habilitação do canal. Uma chave sem ela recebe 403 forbidden.

Pelo arquivo. Passe em key a chave inteira (ws/<WSID>/entrada/diario-20261028.zip), entrada/diario-20261028.zip ou só diario-20261028.zip. Se você reenviou um arquivo com o mesmo nome, a resposta é a do envio mais recente.

curl -s "https://api.v3.zabit.com.br/monitoring/v1/objects?key=diario-20261028.zip" \
  -H "x-api-key: zbt_SUA_CHAVE"

{
  "objeto_id": "0b6f1c1e-3f6e-4a53-9f43-2c1f1d5f9a10",
  "chave": "ws/<WSID>/entrada/diario-20261028.zip",
  "estado": "concluido",
  "tamanho": 184372123,
  "recebido_em": "2026-10-28T19:02:11Z",
  "atualizado_em": "2026-10-28T19:05:40Z",
  "processing_id": "7c1d0b56-0f0e-4a53-9f43-2c1f1d5f9a10",
  "contagens": { "registros": 1200, "alertas": 7, "casos": 2 },
  "motivo": null
}

Pelo processamento. Com o processing_id da resposta acima:

curl -s https://api.v3.zabit.com.br/monitoring/v1/processings/7c1d0b56-0f0e-4a53-9f43-2c1f1d5f9a10 \
  -H "x-api-key: zbt_SUA_CHAVE"

{
  "id": "7c1d0b56-0f0e-4a53-9f43-2c1f1d5f9a10",
  "estado": "erro",
  "recebido_em": "2026-10-29T12:00:00Z",
  "iniciado_em": "2026-10-29T12:00:05Z",
  "finalizado_em": "2026-10-29T12:03:41Z",
  "contagens": null,
  "motivo": {
    "codigo": "processamento.falhou",
    "proximo_passo": "corrigir e reenviar com nome novo"
  }
}

estado: recebido, processando, concluido ou erro; em /objects, também duplicado.
contagens vem só em concluido. motivo vem só em erro e, em /objects, em duplicado. Programe sobre motivo.codigo; o proximo_passo é texto para leitura humana e pode mudar.
processing_id é null enquanto o arquivo ainda não foi aceito para processamento, e também em arquivos recusados antes disso.
A resposta não traz dado pessoal, nem o conteúdo do arquivo: só estado, motivo, contagens e horários.
404 not_found para o que não existe, não é do seu espaço de trabalho ou tem identificador mal formado. A resposta é a mesma nos três casos, de propósito.
As rotas são de leitura e não consomem cota, mas há limite de requisições por minuto. Ao exceder, a resposta é 429. Não consulte com frequência maior que a cada alguns segundos; prefira o webhook a um polling apertado.
Os demais erros seguem {"error": {"code": "...", "message": "..."}}; veja Erros.

Em breve: resumo por e-mail

Um e-mail de resumo por lote (processado, rejeitado ou duplicado), enviado aos endereços que você cadastrar, está a caminho. Esta página será atualizada quando ele estiver disponível.

E o resultado do monitoramento?

O recibo, o webhook e a API de status dizem o que aconteceu com o arquivo: se foi processado e quantos registros, alertas e casos o lote gerou. Os alertas e casos em si (com os sujeitos, as regras acionadas e a análise) ficam no app da Zabit, nos módulos de monitoramento e de casos, e o andamento dos casos também é avisado pelos eventos de caso. A Zabit não devolve dados de alertas em arquivo de retorno.

Recibo no bucket​

Webhooks de lote​

API de status​

E o resultado do monitoramento?​

Recibo no bucket

Webhooks de lote

API de status

E o resultado do monitoramento?