Retornos

O arquivo de retorno é a resposta do banco: ele informa, linha a linha, o que aconteceu com cada título ou pagamento (registro confirmado ou rejeitado, liquidação, baixa, alteração aceita ou recusada). Ao processar um retorno, a Kobana atualiza os boletos e os comandos correspondentes.

Onde fica no painel

Integrações → Kobana → Bancos e Serviços → EDI → Arquivos CNAB → Retorno. No menu lateral das telas de EDI aparecem Arquivos de Retorno e Registros de Retorno. Na tela de uma carteira de cobrança, a aba Retornos lista os retornos daquela carteira.

Como o retorno chega

Origem	Como funciona
Envio manual	Você sobe o arquivo em Arquivos de Retorno.
Conexão EDI com o banco	Com uma caixa EDI ativa, a Kobana baixa os retornos do banco sozinha. Um arquivo com conteúdo idêntico a outro já recebido é ignorado.
Caixa Postal do tipo EDI	Arquivos colocados na caixa de entrada de uma Caixa Postal do tipo EDI (CNAB Remessa/CNAB Retorno) viram retornos.
API	Seu sistema envia o arquivo pela API.

Enviar um retorno pelo painel

1. Em Arquivos de Retorno, clique no ícone de adição ao lado do título (ou em Envie o seu primeiro arquivo!, se a lista estiver vazia).
2. A tela Enviar retorno tem dois formulários. Use o que corresponde ao arquivo:

Boletos Bancários (Carteira): retorno de boletos de uma carteira de cobrança.

Campo	Obrigatório	Descrição
Arquivo CNAB	Sim	O arquivo de retorno recebido do banco.
Carteira	Não	A carteira do retorno. Se ficar em branco, a Kobana identifica a carteira pelos dados bancários do arquivo.

Pagamentos (Conta Financeira): retorno de pagamentos ou de extrato de uma conta financeira.

Campo	Obrigatório	Descrição
Arquivo CNAB	Sim	O arquivo de retorno recebido do banco.
Conta Financeira	Sim	A conta financeira a que o retorno pertence.

3. Clique em Enviar arquivo retorno. O painel mostra "Retorno enviado." e o processamento começa em segundo plano.

Processamento

O retorno é criado em Aguardando e processado em segundo plano. A Kobana lê o arquivo, detecta o banco e o formato (CNAB 400 ou CNAB 240) e localiza a carteira ou a conta financeira.

Situação	Significado
Aguardando	O arquivo foi recebido e ainda não foi processado.
Processado	O arquivo foi lido e as linhas foram enviadas para processamento.
Não é um CNAB de retorno válido ou Carteira de Cobrança/Conta Financeira não encontrada.	A Kobana não reconheceu o arquivo como retorno ou não encontrou a carteira ou conta dele. Nenhuma linha é processada.

Aguardando -> Processado
Aguardando -> Não é um CNAB de retorno válido ou Carteira de Cobrança/Conta Financeira não encontrada.

O que cada linha faz com o boleto

Em um retorno de carteira, cada linha é casada com um boleto pelo nosso número e tratada conforme a ocorrência informada pelo banco:

Ocorrência do banco	Efeito na Kobana
Entrada confirmada	O comando de registro do boleto é confirmado.
Entrada rejeitada	O comando de registro do boleto é marcado como falho.
Liquidação	O pagamento é registrado no boleto, com data de pagamento, valor pago, data e valor de crédito. Se o pagamento já existia (por exemplo, avisado antes pelo banco), a Kobana completa os dados em vez de criar outro.
Alteração confirmada ou rejeitada	O comando de alteração pendente do boleto é confirmado ou marcado como falho.
Baixa confirmada	O comando de cancelamento pendente é confirmado. Sem comando pendente, o boleto é marcado como cancelado pelo banco.
Baixa rejeitada	O comando de cancelamento pendente é marcado como falho.

Quando o mesmo boleto aparece em mais de uma linha do arquivo, a confirmação do registro é processada antes das demais ocorrências dele.

Regras:

• Linhas de boletos cancelados há mais de 7 dias são ignoradas.
• Uma linha cujo nosso número não corresponde a nenhum boleto da Kobana gera o alerta crítico Boleto não cadastrado na Kobana, com o banco, o ID do retorno e o nosso número. Os alertas ficam em Administração → Históricos → Alertas.

Em um retorno de conta financeira, cada linha é casada com um pagamento, transferência ou lançamento de extrato da conta, e o Tipo de Operação do retorno fica Pagamento ou Extrato.

Arquivos de Retorno

A lista mostra: UID, ID Externo, Origem do Recurso (carteira ou conta financeira), Nome, Tipo de Operação (Recebimento, Pagamento ou Extrato), Formato CNAB, Total de Títulos, Enviado em, Processado em e Situação. Um ícone marca os retornos enviados pela API.

Filtros: Tipo de Operação e, conforme a escolha, Carteira ou Conta Financeira, Situação e Enviado (de/até).

A tela do retorno tem duas abas:

• Registros: as linhas do arquivo. Em retorno de carteira: ID, Nosso Número, pagador, Detalhes (a ocorrência e, quando houver, o motivo do erro), Data da Ocorrência, Valor Pago, Data de Crédito, Valor Crédito, Taxa, Acréscimos, Descontos, status do boleto e o botão Ver Boleto. Em retorno de conta financeira: ID, recurso, Operação, Ocorrência, Seu Número, Nosso Número, Código da Transação, Data da Transação e Processado em.
• Detalhes: Situação, carteira ou conta financeira ("(não detectada)" quando não foi encontrada), Processado em e Enviado em.

Ações sobre um retorno

No menu Ações da tela do retorno:

Ação	Quando aparece	O que faz
Download	Sempre	Baixa o arquivo original.
Quitar boletos	Retorno de carteira com situação Processado	Envia para pagamento os boletos com linha de liquidação no arquivo que ainda não estão pagos. Boletos cancelados há mais de 7 dias ficam de fora. O painel mostra "Boletos marcados para pagamento."
Reprocessar	Retorno de carteira com situação Processado	Pede confirmação e processa de novo todas as linhas do arquivo.
Excluir	Quando a carteira do retorno não tem Envio de Remessa por EDI ativo	Pede confirmação e apaga o retorno.

Registros de Retorno

Lista cada linha de retorno processada: Retorno, Origem do Retorno (carteira ou conta financeira), Tipo do Retorno (o boleto ou recurso), Criado em e Processado em.

Filtros: Origem do Retorno (Carteira ou Conta Financeira), ID do Retorno, ID da Origem do Retorno, ID do Tipo de Retorno, Criado em e Processado em.

Permissões

Permissão Recebimentos → CNAB:

Ação no painel	Ação da permissão
Ver Arquivos e Registros de Retorno	Ações Básicas
Enviar retorno	Criar
Download	Fazer Download
Quitar boletos, Reprocessar	Processar
Excluir	Excluir

Eventos de webhook

Código	Quando
discharge.created	O retorno foi recebido.
discharge.processed	O retorno passou para Processado.
discharge.deleted	O retorno foi excluído.
bank_billet_discharge.created, bank_billet_discharge.updated, bank_billet_discharge.deleted	Uma linha de retorno de boleto foi criada, alterada ou removida.

Pela API

Retornos e registros de retorno têm endpoints na API v2 e na API v1.