Introdução

Introdução

Bem vindo. Esta wiki vai mostrar como contribuir com o projeto e introduzir os conceitos necessários para se trabalhar com retornos e remessas. Vale lembrar que esse projeto depende do projeto cnab_yaml, um projeto que guarda as informações de posições dos arquivos CNAB em Yaml.

O que é CNAB?

Os bancos usam o padrão FEBRABAN - Federação Brasileira de Bancos de CNAB - Centro Nacional de Automação Bancária - 400 ou 240 para receber (remessa) e enviar (retorno) informações para as empresas clientes usando arquivos. O objetivo desses arquivos é fazer o intercâmbio de informações digitalmente entre o sistema do banco e o do cliente.

O CNAB pode servir para troca de informações de cobrança (boletos bancários), pagamentos, extrato (para conciliação), débito em conta, vendor e custódia de cheques. Cada uma dessas trocas tem seu próprio fluxo de informação e portanto um layout diferente.

Geralmente, o arquivo CNAB contém texto puro e colunas fixas definidas pela FEBRABAN e cada banco, por possuir suas próprias peculiaridades, tem suas variações que são previstas dentro do padrão, gerando diferentes layouts para cada instituição bancária. Os arquivos são enviados ou recebidos de diversas formas mas principalmente pelo site do banco.

Para segurança de dados, o arquivo CNAB não deve ser compactado para ser encaminhado ao banco. A empresa que ainda não dispõe desse recurso deve entrar em contato com seu banco para saber qual o meio disponibilizado para envio desse arquivo e qual layout deverá utilizar.

O que são retornos e remessas CNAB?

O CNAB é o formato padrão regulado pela Febraban para troca de informações de boleto. Esses arquivos geralmente iniciam com um header que descreve informações da empresa emitindo/recebendo como Número da Conta, Agencia, Data de Processamento no Banco. Esse header também pode ter informações que variam de banco para banco, como código de convênio no Banco do Brasil. Já os arquivos de detalhe contém informações do boleto como nosso número, valor e informações do pagador.

Quero contribuir com o Banco X, e agora?

Agora você precisa saber qual a versão do CNAB usada pelo banco (240 ou 400) e baixar a documentação com as particularidades do seu banco. Como o CNAB é um formato padronizado poucos campos mudam de banco para banco. Com essas informações você pode começar a conferir se o projeto cnab_yaml está de acordo com seu banco, pois alguns bancos usam campos com tamanhos diferentes ou usam novos campos.

Como alterar o CNAB Yaml?

Os arquivos Yaml são separados em pastas de acordo com a versão e com o número do banco. Para cada versão existem arquivos na basta "generic" que são usados como base para todos os bancos. Desta forma, os arquivos das pastas com o código do banco são usados apenas para definir as particularidades de cada banco. O ideal é começar olhando se os arquivos yaml da pasta generic são compatíveis com seu banco e os campos que não forem compatíveis podem ser colocados na pasta do seu banco em um arquivo yaml com o mesmo nome. Exemplo:

cnab240
    generic
        retorno
            detalhe_segmento_t.yml
            detalhe_segmento_u.yml
        header_arquivo.yml
        header_lote.yml
    001
        header_arquivo.yml

Os arquivos yaml acima seguem um formato como o seguinte, que define as posições iniciais e finais de cada campo, junto com uma picture que define que o campo é numérico e aceita nove posições.

codigo_convenio:
  pos: [33, 41]
  picture: '9(9)'

Você pode conferir detalhes sobre a edição dos arquivos Yaml olhando o projeto andersondanilo/cnab_yaml

Como testar?

Os testes unitários são feitos com PHPUnit e costumam usar um arquivo de retorno como exemplo. Você pode procurar um arquivo de retorno do seu banco no google e realizar um teste unitário que confirme que os campos estão sendo identificados corretamente. Já para as remessas, é necessário gerar um arquivo de exemplo e enviar para a homologação do seu banco.

Dica: Digitando "Retorno banco do brasil filetype:ret" é possível encontrar vários arquivos de retorno de exemplo.