Guia de PIX em lote

O PIX em lote resolve o caso em que você tem uma planilha — folha de pagamento, repasse a fornecedores, comissões, reembolsos — e quer pagar tudo de uma vez sem escrever um loop de POST /pix/out. Você sobe as linhas, a API confere chaves, duplicidades, saldo e limites antes de qualquer débito, e só depois do seu aceite explícito cada linha vira um PIX out comum, com os mesmos limites, políticas, webhooks e lançamentos no extrato de PIX Out.

Como funciona

Três decisões de desenho que valem para toda a superfície:

• Somente API (M2M). As rotas exigem credencial com escopo pix_out.create (ou api2/write legado). Token de usuário humano não cria nem dispara lote; o Portal e o Internet Banking não expõem essa superfície. Uma credencial só-leitura (read) consegue acompanhar lotes (GET), baixar o modelo e comprovantes, mas não cria, edita nem dispara.
• Habilitação em dois níveis. A CorpX liga a feature pix_batch no tenant e a seção pixBatch.enabled = true na policy da conta. Sem a primeira a API responde 403 feature_disabled; sem a segunda, 403 pix_batch_account_disabled. Peça a ativação ao seu gerente de conta informando as contas que vão operar em lote.
• Nada sai sem conferência e aceite. O dispatch exige lote REVIEWED, zero itens inválidos, saldo suficiente e acknowledged: true no corpo. O resumo da conferência existe para ser mostrado a quem aprova.

Pré-requisitos

Início rápido

Cinco chamadas levam um arquivo do zero ao pagamento. Nos exemplos, $BASE é https://tenant.api.corpx.com/v1/accounts/{accountId} e os cabeçalhos Authorization: Bearer $TOKEN e X-Tenant-Id estão implícitos.

curl "$BASE/pix/batches/template" -o pix-lote-modelo.csv

curl -X POST "$BASE/pix/batches" \
  -H "Idempotency-Key: folha-2026-09" \
  -H "Content-Type: application/json" \
  -d '{"name": "Folha de setembro"}'
# 201 → {"batchId": "pxb_…", "status": "DRAFT", …}

curl -X POST "$BASE/pix/batches/$BATCH/items/csv" \
  -H "Content-Type: text/csv" \
  --data-binary @folha-setembro.csv
# 200 com o lote e os itens; 400 com errors[] se alguma linha estiver errada (nada é salvo)

curl -X POST "$BASE/pix/batches/$BATCH/review"      # 202, status REVIEWING
curl "$BASE/pix/batches/$BATCH"                      # repita até status REVIEWED; leia "review"

curl -X POST "$BASE/pix/batches/$BATCH/dispatch" \
  -H "Content-Type: application/json" \
  -d '{"acknowledged": true}'
# 202, status QUEUED. Aguarde o webhook pix.batch.completed.

Rotas

Todas sob /v1/accounts/{accountId}/pix/batches. A coluna Escopo indica o que a credencial precisa ter; read acompanha, pix_out.create opera.

A referência campo a campo está em Referência da API → PIX em lote.

1. O arquivo

GET .../pix/batches/template devolve pix-lote-modelo.csv: UTF-8 com BOM e separador ;, que o Excel em português abre direto. O conteúdo é exatamente este:

identifier;amount;description;pixKeyType;pixKey;receiverName;receiverDocument;bankIspb;bankCode;branch;accountNumber;accountType
folha-set-001;1436.85;Pagamento setembro;CPF;12345678909;;;;;;;
folha-set-002;2500.00;Fornecedor;;;EMPRESA EXEMPLO LTDA;12345678000195;60701190;341;0001;123456;CHECKING

Cada linha é um PIX e preenche um dos dois blocos de destinatário:

2. Criar o lote

curl -X POST "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/batches" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Idempotency-Key: folha-2026-09" \
  -H "Content-Type: application/json" \
  -d '{"name": "Folha de setembro"}'

• Idempotency-Key (até 128 caracteres) é obrigatório; repetir a mesma chave na mesma conta devolve o lote existente com 200 em vez de criar outro. Use algo que identifique o fechamento (folha-2026-09), não um UUID aleatório — assim um retry do seu lado nunca abre lote duplicado.
• name é opcional (até 120 caracteres) e aparece nas listagens e no resumo.csv dos comprovantes.

Resposta 201:

{
  "batchId": "pxb_3f9c2a1b7d4e5f60718293a4b5c6d7e8",
  "name": "Folha de setembro",
  "status": "DRAFT",
  "totalItems": 0,
  "totalAmount": "0.00",
  "completedItems": 0,
  "failedItems": 0,
  "limits": { "maxItems": 50, "source": "default" },
  "statistics": {
    "total": 0, "pending": 0, "processing": 0, "completed": 0, "failed": 0,
    "reviewedOk": 0, "invalid": 0,
    "totalAmount": "0.00", "validAmount": "0.00", "completedAmount": "0.00", "failedAmount": "0.00",
    "progressPercentage": 0
  },
  "items": [],
  "page": 1, "pageSize": 50, "totalPages": 0, "hasNext": false,
  "createdAt": "2026-09-30T13:00:00Z",
  "updatedAt": "2026-09-30T13:00:00Z"
}

limits.maxItems é o tamanho máximo deste lote nesta conta e limits.source diz de onde veio (default = 50, tenant ou account, até 5.000). Valores monetários são sempre strings decimais com duas casas ("1436.85"), nunca números de ponto flutuante.

3. Enviar os itens

Você pode misturar os dois métodos no mesmo lote, em quantas chamadas precisar, enquanto o lote estiver DRAFT ou REVIEWED.

curl -X POST ".../pix/batches/{batchId}/items/csv" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-suaempresa" \
  -H "Content-Type: text/csv" \
  --data-binary @folha-setembro.csv

{
  "errorCode": "pix_batch_csv_invalid",
  "message": "one or more rows are invalid; nothing was saved",
  "errors": [
    { "line": 3, "field": "amount", "message": "must be a positive amount" },
    { "line": 7, "field": "pixKey", "message": "use either pixKey or the bank account columns, not both" },
    { "line": 9, "field": "identifier", "message": "duplicated identifier (first seen on line 4)" }
  ],
  "docs": "https://docs.api.corpx.com/baas/guias/referencia/erros#pix_batch_csv_invalid"
}

Regras comuns aos dois métodos

• Idempotência por linha. Repetir um identifier com o mesmo conteúdo é ignorado (não duplica, não dá erro). Repetir com conteúdo diferente é 409 pix_batch_item_conflict e a chamada inteira é recusada — corrija o arquivo em vez de contar com sobrescrita.
• Remover. DELETE .../items/{itemId} tira um item; o itemId (pxi_…) vem em items[] do lote.
• Estados editáveis. Só DRAFT e REVIEWED aceitam itens ou remoção. Qualquer alteração num lote REVIEWED o devolve a DRAFT e zera a conferência: você precisa revisar de novo antes de disparar. Em REVIEWING ou depois do dispatch, 409 pix_batch_not_editable.
• Tamanho. O total de itens do lote nunca passa de limits.maxItems; a chamada que estouraria o teto é recusada inteira com 400 pix_batch_too_large.

4. Conferir (review)

POST /v1/accounts/{accountId}/pix/batches/{batchId}/review   → 202, status REVIEWING

A conferência é assíncrona e roda antes de qualquer débito. Repetir o POST enquanto está REVIEWING só devolve o estado atual. Por item, nesta ordem:

No modo chave o DICT resolve nome, documento e banco do recebedor, que passam a aparecer em items[].receiver — é o que você mostra para quem aprova. As consultas usam o cache de 24 h da conta e contam na janela de consultas DICT como GET /pix/key/{pixKey}; leia Consultas de chave PIX antes de conferir milhares de chaves novas. Itens em dados bancários são aceitos como enviados; a validação da conta destino acontece no liquidante, na execução.

Acompanhe com GET .../pix/batches/{batchId}. Quando status vira REVIEWED, review traz o resumo:

{
  "reviewedAt": "2026-09-30T13:09:30Z",
  "totalItems": 120, "validItems": 118, "invalidItems": 2,
  "totalAmount": "143685.00", "validAmount": "141200.00",
  "balance": { "available": "150000.00", "sufficient": true, "checked": true },
  "limits": [
    { "window": "daily_out", "enforced": true, "limit": "500000.00", "used": "12000.00", "available": "488000.00", "sufficient": true },
    { "window": "monthly", "enforced": false, "limit": "0.00", "used": "0.00", "available": "0.00", "sufficient": true }
  ],
  "warnings": []
}

• balance e limits são um retrato do momento. O saldo é checado de novo no dispatch e cada PIX passa pelos limites por janela na execução. limits[].window é daily_out (6h–20h) ou nightly_out (20h–6h) conforme a hora da conferência, mais monthly; enforced: false significa que a conta não tem teto configurado naquela janela.
• balance.checked: false quer dizer que o liquidante não respondeu; o aviso vai para warnings[] e não bloqueia.
• warnings[] não bloqueia o aceite (ex.: saldo insuficiente agora — pode entrar dinheiro até o dispatch). Itens INVALID bloqueiam.
• Se a conferência não conseguir rodar, o lote volta a DRAFT e review traz um campo error; basta chamar review de novo.

Um item reprovado fica assim em items[]:

{
  "itemId": "pxi_9b1c…", "line": 17, "identifier": "folha-set-017",
  "mode": "KEY", "amount": "980.00", "description": "Pagamento setembro",
  "status": "PENDING", "reviewStatus": "INVALID",
  "receiver": { "name": "", "documentNumber": "", "keyType": "EMAIL", "key": "ex-funcionario@empresa.com", "bankCode": "", "bankIspb": "" },
  "reviewError": { "errorCode": "key_not_found", "message": "chave PIX não encontrada no DICT" },
  "createdAt": "2026-09-30T13:02:11Z", "updatedAt": "2026-09-30T13:09:28Z"
}

Para corrigir, baixe só as linhas reprovadas, ajuste e suba de novo (o identifier igual com conteúdo novo é recusado — remova o item antes com DELETE, ou use um identifier novo), depois confira outra vez:

GET /v1/accounts/{accountId}/pix/batches/{batchId}/items/export?status=invalid
GET /v1/accounts/{accountId}/pix/batches/{batchId}?reviewStatus=invalid

5. Disparar (dispatch)

curl -X POST ".../pix/batches/{batchId}/dispatch" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-suaempresa" \
  -H "X-Acting-Document: 12345678909" \
  -H "X-Transaction-Pin: 123456" \
  -H "Content-Type: application/json" \
  -d '{"acknowledged": true}'

acknowledged: true é a declaração de que o resumo da conferência foi lido e aprovado — grave do seu lado quem aprovou e quando. Sem ele a API responde 409 pix_batch_acknowledgement_required. O dispatch ainda exige, nesta ordem:

1. Lote REVIEWED (409 pix_batch_not_reviewed).
2. Ao menos um item (409 pix_batch_empty) e total dentro de limits.maxItems (400 pix_batch_too_large).
3. Nenhum item INVALID e todos conferidos (409 pix_batch_has_invalid_items / 409 pix_batch_not_reviewed).
4. Saldo disponível maior ou igual ao total do lote no momento do dispatch (422 pix_batch_insufficient_balance — nada é iniciado).

Resposta 202 com status: QUEUED e dispatchedAt. Repetir o dispatch de um lote já disparado é idempotente (200 com o estado atual), então um retry por timeout de rede é seguro.

6. Acompanhar

Cada item vira um PixOut.Workflow próprio — o mesmo que atende POST /pix/out — com identifier igual ao da linha e idempotência {batchId}_{itemId}. Ele passa pelas mesmas políticas, limites por janela e registro no extrato de um PIX avulso, e emite os mesmos pix.out.completed, pix.out.failed ou pix.out.timeout. O lote paga até 5 itens em paralelo (configuração CorpX) e só avança quando o liquidante responde; um item lento não trava os demais.

Estados do lote

Estados do item

GET .../pix/batches/{batchId} traz statistics e os itens paginados (page, pageSize até 200), filtráveis por status (pending, processing, completed, failed) e reviewStatus (pending, ok, invalid):

{
  "batchId": "pxb_3f9c2a1b7d4e5f60718293a4b5c6d7e8",
  "status": "PROCESSING",
  "totalItems": 120, "totalAmount": "141200.00",
  "completedItems": 87, "failedItems": 2,
  "statistics": {
    "total": 120, "pending": 0, "processing": 31, "completed": 87, "failed": 2,
    "reviewedOk": 120, "invalid": 0,
    "totalAmount": "141200.00", "validAmount": "141200.00",
    "completedAmount": "102340.00", "failedAmount": "1960.00",
    "progressPercentage": 74.17
  },
  "items": [
    {
      "itemId": "pxi_1a2b…", "line": 1, "identifier": "folha-set-001",
      "mode": "KEY", "amount": "1436.85", "description": "Pagamento setembro",
      "status": "COMPLETED", "reviewStatus": "OK",
      "receiver": { "name": "JOAO ANTONIO DA CONCEICAO", "documentNumber": "12345678909", "keyType": "CPF", "key": "12345678909", "bankCode": "341", "bankIspb": "60701190" },
      "paymentId": "pay_1f2e3d4c", "endToEndId": "E5087192120260930131200abcdef0123",
      "transactionId": "9f8e7d6c-5b4a-4321-8765-43210fedcba9",
      "completedAt": "2026-09-30T13:12:01Z",
      "createdAt": "2026-09-30T13:02:11Z", "updatedAt": "2026-09-30T13:12:01Z"
    }
  ],
  "page": 1, "pageSize": 50, "totalPages": 3, "hasNext": true,
  "reviewedAt": "2026-09-30T13:09:30Z",
  "acknowledgedAt": "2026-09-30T13:10:02Z",
  "dispatchedAt": "2026-09-30T13:10:02Z",
  "createdAt": "2026-09-30T13:00:00Z", "updatedAt": "2026-09-30T13:12:01Z"
}

Webhook de fechamento

Ao final a API envia pix.batch.completed. Ele é o fechamento do lote e não substitui os eventos por item: para reconciliar linha a linha use pix.out.completed / pix.out.failed (o identifier do evento é o da sua linha) ou a lista de itens.

{
  "id": "pix-batch-pxb_3f9c2a1b7d4e5f60718293a4b5c6d7e8-completed",
  "type": "pix.batch.completed",
  "occurredAt": "2026-09-30T13:12:40.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-suaempresa",
  "accountId": "acc_123456",
  "data": {
    "batchId": "pxb_3f9c2a1b7d4e5f60718293a4b5c6d7e8",
    "accountId": "acc_123456",
    "status": "PARTIAL_FAILED",
    "statistics": {
      "total": 120, "completed": 118, "failed": 2,
      "totalAmount": "141200.00", "completedAmount": "139240.00", "failedAmount": "1960.00"
    }
  }
}

Assine com authType: HMAC, valide X-Signature sobre os bytes brutos e deduplique pelo id — detalhes em Webhooks.

7. Corrigir e reenviar

GET /v1/accounts/{accountId}/pix/batches/{batchId}/items/export?status=failed

Devolve, no mesmo formato do modelo, só as linhas que falharam na execução ou foram marcadas inválidas na conferência, com duas colunas a mais no fim: errorCode e errorMessage. O cabeçalho X-Total-Rows diz quantas linhas vieram.

identifier;amount;description;pixKeyType;pixKey;receiverName;receiverDocument;bankIspb;bankCode;branch;accountNumber;accountType;errorCode;errorMessage
folha-set-017;980.00;Pagamento setembro;EMAIL;ex-funcionario@empresa.com;;;;;;;;key_not_found;chave PIX não encontrada no DICT
folha-set-044;1200.00;Pagamento setembro;;;MARIA DA SILVA;98765432100;;001;1234;56789-0;CHECKING;limit_exceeded_daily;limite diário de saída excedido

Corrija e suba o arquivo como está em um novo lote — o parser ignora as colunas de erro. Um identifier que falhou pode ser reutilizado; um que liquidou não (a conferência o apontaria como identifier_conflict), o que protege contra pagar duas vezes a mesma linha.

separator=comma troca ; por , para ferramentas em inglês.

8. Comprovantes

Os comprovantes são PDFs no padrão CorpX (logo do tenant quando configurada, pagador, recebedor com documento mascarado, valor, descrição, identifier, endToEndId, data de liquidação em horário de Brasília).

Um item — resposta direta em application/pdf, só para itens COMPLETED (409 pix_batch_receipt_unavailable):

GET /v1/accounts/{accountId}/pix/batches/{batchId}/items/{itemId}/receipt

Lote inteiro — para lotes encerrados (COMPLETED, PARTIAL_FAILED ou FAILED com ao menos um item liquidado; senão 409 pix_batch_no_receipts):

curl -X POST ".../pix/batches/{batchId}/receipts" \
  -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-suaempresa"

{
  "exportId": "exp_7c1d2e3f-…",
  "accountId": "acc_123456",
  "batchId": "pxb_3f9c2a1b7d4e5f60718293a4b5c6d7e8",
  "type": "pix_batch_receipts",
  "format": "zip",
  "status": "PENDING",
  "receipts": 118,
  "download": "/v1/accounts/acc_123456/exports/exp_7c1d2e3f-…/download",
  "createdAt": "2026-09-30T13:15:00Z"
}

O ZIP é gerado em segundo plano. Chame a rota em download: enquanto o job roda ela responde 409 not_ready; quando termina, devolve downloadUrl pré-assinada (válida por expiresIn segundos) e checksumMd5. O arquivo traz um PDF por item liquidado e um resumo.csv com as colunas linha, identificador, destinatario, valor, endToEnd, data, arquivo e erro (preenchida só se algum PDF não pôde ser gerado).

Os PDFs seguem o padrão {AAAA-MM-DD}_{HHMM}_PIX_{valor}_{destinatario}_{identifier}_{endToEnd}.pdf — por exemplo 2026-09-30_1312_PIX_1436-85_JOAO-ANTONIO-DA-CONCEICAO_folha-set-001_E5087192120260930131200abcdef0123.pdf — sem acentos e com sufixo -2, -3… em caso de colisão.

Boas práticas

• Uma Idempotency-Key por fechamento. folha-2026-09, fornecedores-2026-09-30… Assim um retry da criação nunca abre um segundo lote, e você consegue reencontrar o lote pelo seu próprio calendário.
• identifier determinístico e único por linha. Monte-o a partir dos seus dados ({folha}-{matricula}), nunca de um contador em memória. É ele que liga o PIX ao seu sistema no extrato, nos webhooks e no arquivo de correção — e é ele que impede pagar a mesma linha duas vezes.
• Confira sempre antes de pedir aprovação. Mostre review (totais, saldo, limites, inválidos) a quem aprova e só então envie acknowledged: true. Guarde quem aprovou, quando e o reviewedAt que estava na tela.
• Separe quem monta de quem dispara. Uma credencial read pode acompanhar; só a credencial com pix_out.create dispara. Se a conta usa PIN transacional, o dispatch exige o PIN do operador que aprova.
• Trate PARTIAL_FAILED como rotina, não exceção. Chaves excluídas e contas encerradas acontecem em qualquer folha grande. Baixe items/export?status=failed, corrija e suba um novo lote; não refaça o lote inteiro.
• Reconcilie por identifier e endToEndId. O pix.out.completed de cada item e a linha em items[] trazem os dois; o endToEndId é o comprovante perante o Banco Central.
• Respeite as janelas de limite. O review mostra daily_out/nightly_out e monthly. Um lote maior que o limite disponível do dia não é bloqueado no dispatch — os itens excedentes falham na execução com limit_exceeded_*. Se for o caso, divida em lotes por dia ou peça ajuste de limite.
• Lotes grandes. Para milhares de linhas, suba por CSV (uma chamada) em vez de dezenas de chunks JSON, e peça à CorpX o maxItems adequado antes do fechamento.

Perguntas frequentes

Erros

A lista completa, com âncoras, está em Tratamento de erros.

Veja também

• PIX Out — o pagamento avulso que cada linha do lote executa.
• Consultas de chave PIX — cota e cache do DICT usados na conferência.
• Segurança da conta — travas, PIN transacional e cabeçalhos de cash out.
• Idempotência — como a Idempotency-Key se comporta em toda a API.
• Webhooks — pix.batch.completed e os eventos pix.out.* por item.