Geração de Retornos¶

O arquivo de retorno é o documento que o sistema VAN gera e envia de volta ao cedente (empresa) após processar os títulos de cobrança ou pagamentos junto ao banco/administrador financeiro. Ele contém informações sobre o que aconteceu com cada transação solicitada.

Visão Geral¶

flowchart LR
    A["📊 Títulos\nProcessados"] --> B["🔄 Conversão de\nOcorrências"]
    B --> C["📝 Geração do\nArquivo CNAB"]
    C --> D["📤 Envio ao\nCedente"]

    style A fill:#e1f5ff
    style D fill:#d4edda

O processo de geração de retornos acontece automaticamente quando:

• ✅ Todos os títulos de um arquivo foram processados pelo administrador
• ✅ As ocorrências de retorno (confirmação, liquidação, rejeição, etc.) estão registradas no banco de dados
• ✅ O mapeamento de ocorrências está configurado corretamente para o layout de destino

Tipos de Retorno¶

🧾 Retorno de Cobranças (CNAB 400)¶

Usado para informar o resultado do processamento de boletos de cobrança enviados anteriormente.

Ocorrências comuns:

Estrutura do arquivo:

Header do Arquivo (1 linha)
  ↓
Detalhes - um para cada título (N linhas)
  ↓
Trailer do Arquivo (1 linha)

Cada detalhe contém: - Nosso número (identificador do título) - Data de ocorrência - Código da ocorrência - Valor do título - Valor pago (se liquidado) - Tarifas cobradas - Data de vencimento - Data de crédito (quando o dinheiro entra na conta)

💸 Retorno de Pagamentos (CNAB 240)¶

Usado para informar o resultado de pagamentos (fornecedores, tributos, salários, etc.) que foram solicitados.

Ocorrências comuns:

Estrutura do arquivo:

Header do Arquivo (1 linha)
  ↓
Header do Lote (1 linha por lote)
  ↓
Segmento A - dados do pagamento (1 linha por título)
  ↓
Segmento B - dados do beneficiário (1 linha por título)
  ↓
Trailer do Lote (1 linha por lote)
  ↓
Trailer do Arquivo (1 linha)

Cada segmento A contém: - Código de barras ou identificação do pagamento - Data de pagamento - Valor nominal - Valor efetivamente pago - Ocorrência do pagamento

Como Funciona a Geração¶

1. Consolidação dos Títulos¶

O sistema busca todos os títulos vinculados ao arquivo de remessa original que já possuem uma ocorrência de retorno registrada:

SELECT * FROM Titulo
WHERE ArquivoId = @arquivoId
  AND OcorrenciaRetorno IS NOT NULL
  AND StatusProcessamento IN ('Confirmado', 'Rejeitado', 'Liquidado', 'Baixado')

2. Conversão de Ocorrências¶

As ocorrências internas do sistema (padronizadas) são convertidas de volta para os códigos específicos do layout CNAB que o cedente espera.

flowchart LR
    A["Ocorrência Interna\n(EntradaConfirmada)"]
    B[("Mapa de\nOcorrências")]
    C["Código CNAB\npara o banco\n(02)"]

    A -->|Consulta| B
    B -->|Traduz| C

Exemplo de mapeamento:

3. Montagem do Arquivo¶

O sistema utiliza writers especializados por layout para gerar cada linha do arquivo:

// Pseudocódigo simplificado
var retorno = new RetornoCnab400BB();

// Header
retorno.AdicionarHeader(conta, dataGeracao, sequencial);

// Detalhes
foreach (var titulo in titulos)
{
    var codigoCnab = ObterCodigoCnabRetorno(titulo.OcorrenciaInterna, layout);
    retorno.AdicionarDetalhe(titulo, codigoCnab);
}

// Trailer
retorno.AdicionarTrailer(totalTitulos, totalValores);

// Serializa para arquivo texto posicional
var conteudo = retorno.GerarArquivo();

Cada linha é formatada seguindo exatamente as especificações do layout: - Campos em posições fixas - Alinhamento à direita (numéricos) ou esquerda (alfanuméricos) - Preenchimento com zeros ou espaços - Linha com tamanho exato (400 ou 240 caracteres)

4. Validação e Armazenamento¶

Antes de enviar, o arquivo gerado passa por validações:

✔️ Quantidade de linhas corresponde ao total de títulos + header + trailer ✔️ Todas as linhas têm o tamanho correto ✔️ Sequência numérica está correta ✔️ Totalizadores do trailer batem com a soma dos detalhes

O arquivo validado é: 1. Armazenado no Azure Blob Storage 2. Referenciado na tabela Arquivo com tipo Retorno 3. Vinculado ao arquivo de remessa original

5. Envio ao Cedente¶

O arquivo é disponibilizado ao cedente através do mesmo canal de entrada:

Tempo de Geração¶

O tempo para geração do retorno varia conforme o administrador:

Exemplos¶

Exemplo 1: Retorno de Cobrança BB (CNAB 400)¶

Cenário: Cedente enviou arquivo com 3 boletos. Todos foram confirmados pelo banco.

Arquivo de Retorno:

0000000001... (Header - identifica conta, data, sequencial)
1001002... Nosso Número: 123456 | Ocorrência: 02 (Confirmado) | Valor: 100,00
1001002... Nosso Número: 123457 | Ocorrência: 02 (Confirmado) | Valor: 250,00
1001002... Nosso Número: 123458 | Ocorrência: 02 (Confirmado) | Valor: 500,00
9999999999... (Trailer - total: 3 títulos, R$ 850,00)

Exemplo 2: Retorno de Pagamento CNAB 240¶

Cenário: Empresa solicitou pagamento de 2 fornecedores. 1 foi pago, 1 foi rejeitado.

Arquivo de Retorno:

001... (Header do Arquivo)
001... (Header do Lote)
A... Código de Barras: 12345 | Ocorrência: 00 (Pago) | Valor: 1.000,00
B... Favorecido: Fornecedor A | CNPJ: 12.345.678/0001-90
A... Código de Barras: 67890 | Ocorrência: BD (Rejeitado) | Motivo: Saldo Insuficiente
B... Favorecido: Fornecedor B | CNPJ: 98.765.432/0001-10
9... (Trailer do Lote - 2 pagamentos, 1 confirmado)
9... (Trailer do Arquivo)

Monitoramento e Logs¶

Toda a geração de retorno é registrada:

Em caso de erro, o sistema registra: - Título que causou o problema - Motivo da falha (ocorrência sem mapeamento, validação incorreta, etc.) - Stack trace para debugging

Perguntas Frequentes¶