{"id":22307947,"url":"https://github.com/akretion/boleto_cnab_api","last_synced_at":"2025-03-31T08:09:23.639Z","repository":{"id":40745203,"uuid":"94553512","full_name":"akretion/boleto_cnab_api","owner":"akretion","description":"API server for brcobranca (Brazilian boleto/CNAB electronic payment project)","archived":false,"fork":false,"pushed_at":"2024-10-07T23:30:57.000Z","size":56,"stargazers_count":49,"open_issues_count":2,"forks_count":36,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-22T18:56:16.172Z","etag":null,"topics":["banco","boleto","brasil","brcobranca","cnab","docker","erp","java","microservice","python"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akretion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-16T14:47:51.000Z","updated_at":"2025-02-08T16:13:42.000Z","dependencies_parsed_at":"2024-01-31T23:37:02.905Z","dependency_job_id":"cfaa36ad-f622-44e8-b912-690322693076","html_url":"https://github.com/akretion/boleto_cnab_api","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Fboleto_cnab_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Fboleto_cnab_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Fboleto_cnab_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akretion%2Fboleto_cnab_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akretion","download_url":"https://codeload.github.com/akretion/boleto_cnab_api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246436393,"owners_count":20776995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["banco","boleto","brasil","brcobranca","cnab","docker","erp","java","microservice","python"],"created_at":"2024-12-03T20:12:38.476Z","updated_at":"2025-03-31T08:09:23.597Z","avatar_url":"https://github.com/akretion.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sobre o projeto boleto_cnab_api\n\nO projeto de gestão de Boletos, Remessas e Retornos Bancários https://github.com/kivanio/brcobranca é muito bem feito, bem testado e mantido.\n\nÉ interessante poder usar o projeto BRCobranca (escrito em Ruby) a partir de outras linguagens na forma de um micro-serviço REST.\nMais especificamente, a [Akretion](http://www.akretion.com) que é a empresa que lidera a localização do Odoo no Brasil desde 2009 https://github.com/OCA/l10n-brazil e co-criou a fundação [OCA](https://odoo-community.org/) usa esse projeto para gerenciar Boletos, Remessas e Retornos a partir do ERP Odoo (feito em Python, módulo específico https://github.com/OCA/l10n-brazil/tree/14.0/l10n_br_account_payment_brcobranca).\n\nA imagem usada no projeto é do OS [Alpine](https://hub.docker.com/_/alpine), o motivo é que por ser um Micro-Serviço quanto menor a imagem melhor e apesar de existir dentro das imagens [Ruby](https://hub.docker.com/_/ruby) tanto a opção Debian quanto Alpine a imagem criada a partir da versão \"pura\" acaba sendo menor( Ruby-Debian 746MB | Ruby-Alpine 565MB | Alpine 523MB ), existem diferenças entre o [Debian](https://pt.wikipedia.org/wiki/Debian) e o [Alpine](https://pt.wikipedia.org/wiki/Alpine_Linux) basicamente \"na superfície\" são alguns nomes de pacote e o instalador de pacotes, no Debian apt-get e no Alpine apk, outros comandos Linux são iguais, em caso de algum erro complexo o Debian pode acabar sendo usado.\n\n# Funcionalidades\n\nImprime **Boletos**, gera arquivos de **Remessa** e lê os arquivos de **Retorno** nos formatos CNAB 240, CNAB 400 para os 16 principais bancos do Brasil (Banco do Brasil, Banco do Nordeste, Banestes, Santander, Banrisul, Banco de Brasília, Caixa, Bradesco, Itaú, HSBC, Sicredi, Sicoob, AILOS, Unicred, CREDISIS e Citibank). Mas o grande barato desse projeto é que fazemos isso com menos de 200 linhas de código! Já comparou quantas linhas de de código você tem que manter sozinho ou quase se for re-fazer na linguagem que você quer tudo que o BRCobranca já faz? Seriam dezenas de milhares de linhas e você nunca teria uma qualidade tão boa...\n\n# API\n\n```ruby\n# Validar os dados de um Boleto:\nGET /boleto/validate\n        requires :bank, type: String, desc: 'Bank'\n        requires :data, type: String, desc: 'Boleto data as a stringified json'\n\n# Obter o nosso_numero de um Boleto:\nGET /boleto/nosso_numero\n        requires :bank, type: String, desc: 'Bank'\n        requires :data, type: String, desc: 'Boleto data as a stringified json'\n\n# Imprimir um Boleto apenas:\nGET /boleto/get\n        requires :bank, type: String, desc: 'Bank'\n        requires :type, type: String, desc: 'Type: pdf|jpg|png|tif'\n        requires :data, type: String, desc: 'Boleto data as a stringified json'\n\n# Imprimir uma lista de Boletos:\nPOST /boleto/multi\n        requires :type, type: String, desc: 'Type: pdf|jpg|png|tif'\n        requires :data, type: File, desc: 'json of the list of boletos, including the \"bank\" key'\n\n# Gerir um arquivo de Remessa CNAB 240 ou CNAB 400:\nPOST /remessa\n        requires :bank, type: String, desc: 'Bank'\n        requires :type, type: String, desc: 'Type: cnab400|cnab240'\n        requires :data, type: File, desc: 'json of the list of pagamentos'\n\n# Transformar um arquivo de Retorno CNAB 240 ou CNAB 400 em JSON:\nPOST /retorno\n        requires :bank, type: String, desc: 'Bank'\n        requires :type, type: String, desc: 'Type: cnab400|cnab240'\n        requires :data, type: File, desc: 'txt of the retorno file'\n```\n\nNota: os campos datas devem estar no formato YYYY/MM/DD\n\nO API está documentado com mais detalhes no código aqui: https://github.com/akretion/boleto_cnab_api/blob/master/lib/boleto_api.rb\n\n# Como rodar o micro-serviço\n\n```bash\ndocker run -p 9292:9292 ghcr.io/akretion/boleto_cnab_api\n```\n\n# Exemplos de como consumir o serviço usando sua linguagem preferida:\n\n## Bash\n\nPor exemplo, para imprimir uma lista de Boletos é preciso criar um arquivo temporario com os Boletos em formato JSON e depois fazer um POST do arquivo:\n```bash\necho '[{\"valor\":5.0,\"cedente\":\"Kivanio Barbosa\",\"documento_cedente\":\"12345678912\",\"sacado\":\"Claudio Pozzebom\",\n\"sacado_documento\":\"12345678900\",\"agencia\":\"0810\",\"conta_corrente\":\"53678\",\"convenio\":12387,\"nosso_numero\":\"12345678\",\"bank\":\"itau\"},\n{\"valor\": 10.00,\"cedente\": \"PREFEITURA MUNICIPAL DE VILHENA\",\"documento_cedente\": \"04092706000181\",\"sacado\": \"João Paulo Barbosa\",\n\"sacado_documento\": \"77777777777\",\"agencia\": \"1825\",\"conta_corrente\": \"0000528\",\"convenio\": \"245274\",\"nosso_numero\": \"000000000000001\",\"bank\":\"caixa\"}]'\\\n\u003e /tmp/boletos_data.json\ncurl -X POST -F type=pdf -F 'data=@/tmp/boletos_data.json' localhost:9292/api/boleto/multi \u003e /tmp/boletos.pdf\n```\nVocê pode então conferir os Boletos gerados no arquivo ```/tmp/boletos.pdf```\n\n## Python\n\n```\nTODO\n```\n(Ver os exemplos nos módulos Odoo: https://github.com/OCA/l10n-brazil/tree/14.0/l10n_br_account_payment_brcobranca)\n\n## Java\n\n```\nTODO (contribuições bem vindas)\n```\n\n## Testar alterações na imagem sem necessidade de commit\n\nNo arquivo Gemfile.lock é possível alterar o repositório e o commit específico que será usado na criação da imagem, o que é necessário durante uma correção, atualização ou implementação de um novo caso, um exemplo simples pode ser visto nesse PR https://github.com/akretion/boleto_cnab_api/pull/11/files , mas também é possível alterar o Dockerfile para criar uma imagem de teste onde seja possível editar os arquivos dentro do container (o que evita subir um commit desnecessário ou com erro), para isso no arquivo Dockerfile são feitas as seguintes alterações:\n\nInstalar algum editor de texto, por exemplo VIM ou Nano (por padrão o VI já está instalado mas caracteres UTF-8 não são mostrados corretamente) e alterar o usuário **app** para o **root** para poder editar os arquivos\n```bash\n            git \\\n            ruby-dev \\\n+           vim \\\n+           nano \\\n         \u0026\u0026 rm -rf /var/cache/apk/* \\\n         ;\n\n-USER app\n+USER root\n```\n\nCriação da imagem\n```bash\n$ docker build -t akretion/boleto_cnab_api-teste .\n```\n\nDepois de iniciar a imagem podemos entrar dentro do container\n```bash\nLocalizar o container ID\n\n$ docker ps\nCONTAINER ID   IMAGE                             COMMAND                  CREATED             STATUS             PORTS                                                 NAMES\n1ea95da3a3c3   akretion/boleto_cnab_api-teste   \"/bin/sh -c 'bundle …\"   4 minutes ago   Up 4 minutes   0.0.0.0:9292-\u003e9292/tcp, :::9292-\u003e9292/tcp   eloquent_noether\n```\n\nAcessando o container (No Debian usa /bin/bash no Alpine /bin/sh)\n```bash\n$ docker exec -it \u003ccontainer-id\u003e /bin/sh\n\nO valor \u003ccontainer-id\u003e varia, nesse exemplo o comando seria\n\n$ docker exec -it 1ea95da3a3c3 /bin/sh\n```\n\nDentro do container é preciso localizar a pasta onde está instalada a biblioteca, no exemplo é usado o comando **find** e a partir disso é possível realizar alterações necessárias\n```bash\n/usr/src/app # find /usr -name unicred.rb\n/usr/lib/ruby/gems/3.3.0/bundler/gems/brcobranca-cd928e87554b/lib/brcobranca/retorno/cnab400/unicred.rb\n/usr/lib/ruby/gems/3.3.0/bundler/gems/brcobranca-cd928e87554b/lib/brcobranca/remessa/cnab240/unicred.rb\n/usr/lib/ruby/gems/3.3.0/bundler/gems/brcobranca-cd928e87554b/lib/brcobranca/remessa/cnab400/unicred.rb\n```\n\nA partir disso é possível realizar alterações necessárias, por exemplo verificar o valor de alguma variável \"imprimindo\" no LOG com o comando \"puts\" (algumas referencias https://www.dotnetperls.com/console-ruby https://www.rubyguides.com/2018/10/puts-vs-print/ http://ruby-for-beginners.rubymonstas.org/writing_methods/printing.html )\n```bash\n/usr/src/app # vim /usr/lib/ruby/gems/3.3.0/bundler/gems/brcobranca-cd928e87554b/lib/brcobranca/\nboleto/unicred.rb\n\n      def codigo_barras_segunda_parte\n        puts \"TESTE puts algum valor qualquer \" + \"#{agencia}\"\n        \"#{agencia}#{conta_corrente}#{conta_corrente_dv}#{nosso_numero}#{nosso_numero_dv}\"\n      end\n    end\n```\n\nNesse exemplo ao criar um Boleto do UNICRED é possível ver no LOG o resultado do \"puts\"\n```bash\n$ docker logs -f 28f2881e4dd7\nPuma starting in single mode...\n* Puma version: 6.4.2 (ruby 3.3.3-p89) (\"The Eagle of Durango\")\n*  Min threads: 0\n*  Max threads: 5\n*  Environment: development\n*          PID: 1\n* Listening on http://0.0.0.0:9292\nUse Ctrl-C to stop\nTESTE puts algum valor qualquer 1234\n```\n\nSe a imagem estiver sendo iniciada dentro de um **Docker Compose**, por exemplo por um projeto Odoo é possível ver o LOG usando:\n```bash\n$ docker logs -f 28f2881e4dd7\nPuma starting in single mode...\n* Puma version: 6.4.2 (ruby 3.3.3-p89) (\"The Eagle of Durango\")\n*  Min threads: 0\n*  Max threads: 5\n*  Environment: development\n*          PID: 1\n* Listening on http://0.0.0.0:9292\nUse Ctrl-C to stop\n- Gracefully stopping, waiting for requests to finish\n=== puma shutdown: 2024-07-05 19:50:05 +0000 ===\n- Goodbye!\n```\n\n**IMPORTANTE:** por algum motivo as alterações dentro do container só tem efeito na primeira vez que o arquivo é Salvo, uma segunda alteração não tem efeito, isso pode ser algo referente ao comportamento da imagem, ou do Docker ou do Docker Compose, já que nos testes realizados esse container é iniciado e usado por outro container rodando o Odoo, é preciso investigar melhor para entender se isso é algo normal e já esperado ou se teria uma forma de corrigir, porque devido a isso para testar dessa forma está sendo necessário alterar uma vez e se for preciso fazer outra alteração sair do container fazer um kill e inicia-lo novamente.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakretion%2Fboleto_cnab_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakretion%2Fboleto_cnab_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakretion%2Fboleto_cnab_api/lists"}