Arquivo de Reembolso em lote

Versão 1.2 — Especificação do arquivo CSV de reembolso em lote: estrutura dos registros, regras de validação e comportamento do processamento.

#1. Introdução

#1.1 Objetivo

Descrever a estrutura do arquivo de reembolso em lote e o fluxo de funcionamento do envio de registros. A documentação das rotas da API (geração do link de upload, consulta de arquivos e de reembolsos) está na seção de referência da API e não é repetida aqui.

#1.2 Convenções do arquivo

#1.3 Nome do arquivo

<Tipo do Arquivo>_<id do arquivo de controle>.csv

O id do arquivo de controle e o nome completo são devolvidos ao solicitar o link de upload. Não é necessário montar o nome manualmente.

Exemplo:

REFUND_fdf613d2-187e-4d49-aaaf-9a1fb2d33297.csv

#1.4 Fluxo de funcionamento

1. Solicitar o link de upload informando o tipo de processamento: Simplificado ou Detalhado. O tipo é fixado nesse momento e não é deduzido pelo conteúdo do arquivo.

2. Enviar o arquivo CSV pelo link recebido. O link tem validade curta e aceita um único arquivo. Para reenviar um arquivo corrigido, solicitar um novo link.

3. Validação e processamento. O arquivo passa por validação de tipo, tamanho e integridade. Aprovado, é processado linha a linha conforme o tipo escolhido. Reprovado, recebe um status de falha e não é processado.

4. Acompanhar o status do arquivo até sair de NEW. O resultado final é PROCESSED, INVALID_LAYOUT ou INVALID_TYPE, acompanhado do detalhe dos erros quando houver (seções 5 e 6).

Os reembolsos criados a partir do arquivo seguem o ciclo normal de um reembolso individual e são acompanhados pela consulta de reembolsos.

#2. Tipos de arquivo

#3. Layout Simplificado

#3.1 Campos

#3.2 Exemplo de arquivo

PED-2025-000123
PED-2025-000124
98765

#3.3 Regras

• A transação é localizada pelo número do pedido entre as vendas do subadquirente autenticado.

• Só gera reembolso quando a transação está aprovada e é de crédito ou PIX. Débito e boleto não são contemplados neste layout.

• O reembolso criado é sempre TOTAL, operação normal, com a descrição Reembolso criado.

• Pedido não localizado ou não elegível é ignorado. O arquivo termina como PROCESSED e não há erro por linha. Para confirmar o que foi criado, usar a consulta de reembolsos.

• Linha com mais de uma coluna interrompe o processamento com INVALID_LAYOUT. Os reembolsos das linhas anteriores já criados permanecem.

#4. Layout Detalhado

#4.1 Campos

As 8 colunas devem estar sempre presentes, mesmo vazias. Uma linha sem split termina com ;.

#4.2 Tabelas de domínio

Tabela 1 – Tipo de registro

Tabela 2 – Tipo de reembolso

Tabela 3 – Modalidade

Boleto não é suportado em lote. Usar o reembolso individual.

Tabela 4 – Tipo de operação

#4.3 Split Data

Formato de cada parte:

<CPF ou CNPJ>:<valor em centavos>

Várias partes na mesma célula são separadas por , (vírgula).

• Documento sem máscara: CPF com 11 dígitos; CNPJ com 14 caracteres, numérico ou alfanumérico no novo padrão da RFB.

• Valor inteiro em centavos: R$ 15,00 → 1500; R$ 0,10 → 10.

• Em PARTIAL, o valor total do reembolso é a soma das partes.

#4.4 Exemplos de linha

Reembolso total de crédito e-commerce:

C;3f9c2a1e-7b4d-4e0a-9c11-5d2f8a6b7c90;2025031210293847;TOTAL;CREDIT;Cliente desistiu da compra;0;

Reembolso parcial com split para dois participantes:

C;8d1e4b7a-2c3f-4a5e-b6d7-0f1e2d3c4b5a;2025031210293911;PARTIAL;CREDIT;Devolucao de 1 item;0;05643319000159:1500,12345678909:250

Reembolso total de PIX:

C;c0ffee12-3456-4789-abcd-ef0123456789;2025031210301122;TOTAL;PIX;Pix em duplicidade;0;

Reembolso administrativo de venda POS (transaction id em SHA-256):

C;9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08;000123456789;TOTAL;DEBIT;Baixa administrativa venda POS;1;

Chargeback de débito:

C;5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d;2025031210311234;TOTAL;DEBIT;Contestacao do portador;2;

Descrição contendo ;:

C;3f9c2a1e-7b4d-4e0a-9c11-5d2f8a6b7c90;2025031210293847;TOTAL;CREDIT;"Estorno; solicitado via SAC";0;

#4.5 Exemplo de arquivo completo

REFUND_fdf613d2-187e-4d49-aaaf-9a1fb2d33297.csv:

C;3f9c2a1e-7b4d-4e0a-9c11-5d2f8a6b7c90;2025031210293847;TOTAL;CREDIT;Cliente desistiu da compra;0;
C;8d1e4b7a-2c3f-4a5e-b6d7-0f1e2d3c4b5a;2025031210293911;PARTIAL;CREDIT;Devolucao de 1 item;0;05643319000159:1500,12345678909:250
C;c0ffee12-3456-4789-abcd-ef0123456789;2025031210301122;TOTAL;PIX;Pix em duplicidade;0;
C;9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08;000123456789;TOTAL;DEBIT;Baixa administrativa venda POS;1;
C;5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d;2025031210311234;TOTAL;DEBIT;Contestacao do portador;2;

#4.6 Regras de validação

O arquivo detalhado é validado em duas fases. Em ambas o comportamento é tudo ou nada: qualquer erro impede a criação de todos os reembolsos do arquivo.

Fase 1 – Layout. Cada linha é interpretada. Na primeira linha fora do layout o processamento para, o status vira INVALID_LAYOUT e um único erro é reportado, apenas com a linha.

Fase 2 – Regras de negócio. Todas as linhas são avaliadas e os erros acumulados. Havendo ao menos um, o status vira INVALID_TYPE e até 24 erros são reportados, cada um com linha, coluna e campo.

Fase 3 – Criação. Com o arquivo válido, cada linha gera um reembolso pelo mesmo fluxo do reembolso individual, sujeito às mesmas regras: idempotência (transação com reembolso em andamento é rejeitada) e bloqueio de operação 0 ou 2 para transações POS. Os reembolsos criados seguem o ciclo individual (NEW → PROCESSING → SCHEDULED → DONE).

#5. Status do arquivo

Quando INVALID_TYPE vier com detalhe de erros, a origem é o processamento. Quando vier sem, a origem é o upload.

#6. Detalhe dos erros

Cada erro reportado na consulta do arquivo traz:

• Linha do arquivo, começando em 1.

• Coluna do campo com erro, começando em 1 (posição na Tabela de campos da seção 4.1). Vazia em erro de layout.

• Campo com erro. Vazio em erro de layout.

• Descrição do erro, conforme as tabelas da seção 4.6.

Erro de layout reporta uma única ocorrência. Erros de negócio reportam até 24 ocorrências.

#7. Resumo do comportamento

• O tipo de processamento é fixado ao solicitar o link. Enviar um arquivo detalhado num link Simplificado (ou vice-versa) resulta em INVALID_LAYOUT.

• Cada arquivo é processado uma única vez. Só arquivos em NEW são processados.

• Detalhado: tudo ou nada. Nenhum reembolso é criado se houver qualquer erro de layout ou de negócio.

• Simplificado: linhas não elegíveis são puladas silenciosamente. Linha fora do layout interrompe, mas o que já foi criado permanece.

• Os reembolsos criados são independentes do arquivo a partir da criação. Falhas posteriores aparecem no status do reembolso, não no status do arquivo.

#Histórico de revisões