Arquivo de Retorno CNAB

O arquivo de retorno é um arquivo de texto no formato CNAB (Centro Nacional de Automação Bancária) que contém as informações enviadas pelo banco sobre os boletos: confirmações de registro, pagamentos, baixas, protestos e outras ocorrências.

O Que é o Arquivo de Retorno?

Característica	Descrição
Origem	Banco/PSP
Formato	CNAB 240 ou CNAB 400 (conforme banco)
Conteúdo	Ocorrências dos boletos (pagamentos, registros, baixas, etc.)
Frequência	Definida por cada instituição financeira (pode haver múltiplos arquivos por dia)
Processamento	Via API ou automaticamente (plano personalizado)

Características dos Arquivos de Retorno

Aspecto	Descrição
Múltiplos Retornos	O banco pode gerar arquivos de retorno sempre que houver eventos de movimentação (baixas, pagamentos, protestos), resultando em vários arquivos ao longo de um único dia
PIX e Pagamentos	Pagamentos via PIX costumam ser gerados em um arquivo CNAB separado dos outros pagamentos
CNAB 240 vs 400	O padrão CNAB 240, mais moderno, é mais flexível para múltiplas transações diárias do que o antigo 400, facilitando a conciliação automática
Frequência	A frequência de envio de arquivos é definida por cada instituição financeira e pode ser configurada junto ao banco

Boletos retornados

Para o plano gratuito, apenas boletos que existem na plataforma Boleto Cloud serão incluídos no JSON de resposta. Para o plano personalizado, todos os títulos do arquivo são retornados — aqueles que não correspondam a boletos cadastrados terão o campo token com valor null.

---

Formas de Processamento

A API oferece três formas de trabalhar com arquivos de retorno, dependendo do seu plano e configuração:

Plano	Método	Descrição
Gratuito	Upload manual	Você envia o arquivo de retorno via POST e recebe o JSON processado
Personalizado (VAN)	Automático	O arquivo é recepcionado automaticamente pela VAN e fica disponível para consulta
Personalizado (API Bancária)	Automático	As informações são recebidas via API do banco e disponibilizadas como retorno virtual

---

Endpoints Disponíveis

Processar Retorno (POST)Envie um arquivo de retorno CNAB para processamento manual

Obter Retorno (GET)Recupera o JSON de um retorno já processado através do token

Listar Retornos (GET)Lista os arquivos de retorno disponíveis por data e conta

Plano Personalizado

Os endpoints de Obter Retorno e Listar Retornos estão disponíveis apenas para contas no plano personalizado com integração automatizada (VAN ou API Bancária).

---

Ciclo de Vida do Boleto

O processamento de retorno se encaixa na etapa final do ciclo, após o banco processar os boletos:

┌─────────────────────────────────────────────────────────────────────┐
│                         CRIAÇÃO DOS BOLETOS                         │
│                                                                     │
│   POST /boletos, /carnes, /batch/boletos                            │
│   ► Boletos criados com boleto.conta.token                          │
└────────────────────────────────────┬────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    REGISTRO NO BANCO                                │
│                                                                     │
│   Via CNAB Remessa, API Bancária ou VAN                             │
│   ► Boletos enviados para registro                                  │
└────────────────────────────────────┬────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    BANCO PROCESSA                                   │
│                                                                     │
│   ► Confirma registros                                              │
│   ► Recebe pagamentos                                               │
│   ► Processa baixas/protestos                                       │
└────────────────────────────────────┬────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────┐
│              ★ PROCESSAR ARQUIVO DE RETORNO ★                       │
│                                                                     │
│   POST /arquivos/cnab/retornos (manual)                             │
│   GET /arquivos/cnab/retornos/{token} (automático)                  │
│                                                                     │
│   ► Boletos atualizados: REGISTRADO, PAGO, BAIXADO, etc.            │
└─────────────────────────────────────────────────────────────────────┘

---

Tipos de Ocorrência

O arquivo de retorno pode conter diversos tipos de ocorrência:

Situação	Descrição	Ação Recomendada
LIQUIDACAO	Boleto foi pago	Dar baixa no sistema, liberar produto/serviço
REGISTRO_CONFIRMADO	Registro confirmado pelo banco	Boleto está ativo para pagamento
REGISTRO_REJEITADO	Registro rejeitado pelo banco	Verificar motivos e corrigir dados
BAIXA	Boleto foi baixado	Atualizar status no sistema
PROTESTO	Boleto foi protestado	Atualizar status, notificar cliente
CANCELAMENTO_PROTESTO	Protesto foi cancelado	Atualizar status
ABATIMENTO	Abatimento concedido	Atualizar valor do boleto
CANCELAMENTO_ABATIMENTO	Abatimento cancelado	Restaurar valor original
ALTERACAO_VENCIMENTO	Vencimento alterado	Atualizar data no sistema

---

Estrutura do JSON de Retorno

Todos os endpoints retornam um JSON com a seguinte estrutura:

{
  "arquivo": {
    "meta": {
      "token": "token-do-arquivo",
      "criado": "2024-01-15T10:30:00Z"
    },
    "protocolo": {
      "banco": {
        "codigo": "237",
        "nome": "BRADESCO"
      },
      "numero": 12345,
      "gravacao": "2024-01-14"
    },
    "titulos": [
      {
        "token": "token-do-boleto",
        "numero": "00000000001-0",
        "documento": "DOC-001",
        "valor": 150.00,
        "vencimento": "2024-01-20",
        "ocorrencias": [...]
      }
    ]
  }
}

---

Fluxo Recomendado

Plano Gratuito (Upload Manual)

1. Baixar arquivo do Internet Banking do banco
2. Enviar arquivo via Processar Retorno
3. Receber JSON com as ocorrências processadas
4. Atualizar sistema com base nas ocorrências (pagamentos, baixas, etc.)

Plano Personalizado (Automático)

1. Consultar retornos via Listar Retornos informando data e conta
2. Para cada token retornado, chamar Obter Retorno
3. Processar JSON com as ocorrências
4. Atualizar sistema com base nas informações recebidas

Frequência de consulta

A frequência de disponibilização de arquivos é definida por cada instituição financeira. Dependendo da configuração junto ao banco, podem haver múltiplos arquivos de retorno por dia, especialmente para ocorrências de registro. Algumas instituições já fornecem arquivos com pagamentos no mesmo dia (liquidados até 13:30). Recomenda-se consultar periodicamente ao longo do dia.

---

Veja Também

Visão Geral CNABConceitos gerais sobre arquivos CNAB

Remessa CNABEnviar boletos para registro no banco

Criar BoletoCriar boletos com token da conta bancária

Status & ErrosTratamento de erros da API