github.com/mundipagg/boleto-api@v0.0.0-20230620145841-3f9ec742599f/README-US-ENG.md (about)

     1  [![Build Status](https://mundipagg.visualstudio.com/Processing%20and%20Reconciliation/_apis/build/status/Banking/Boleto/boleto-api%20-%20PRODUCTION?branchName=master)](https://mundipagg.visualstudio.com/Processing%20and%20Reconciliation/_build/latest?definitionId=319&branchName=master)
     2  [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=mundipagg_boleto-api&metric=alert_status)](https://sonarcloud.io/dashboard?id=mundipagg_boleto-api)
     3  [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=mundipagg_boleto-api&metric=coverage)](https://sonarcloud.io/dashboard?id=mundipagg_boleto-api)
     4  
     5  # boleto-api [ENG-US](./README-US-ENG.md)/[PT-BR](./README.md)
     6  
     7  What is the Online Registered "Boleto" API?
     8  --------------
     9  
    10  BoletoOnline is an API for boleto's online register in banks and boleto's creation for payments.
    11  
    12  Currently, we support the following banks:
    13  * Banco do Brasil
    14  * Caixa
    15  * Citibank
    16  * Santander 
    17  * BradescoShopFacil
    18  * BradescoNetEmpresas
    19  * Itau
    20  
    21  The integration order will follow the list above but we may have changes considering our clients demands.
    22  
    23  API Building
    24  --------------
    25  
    26  The API was developed using GO language and therefore it is necessary to install the language tools in case you need to compile the application from the source.
    27  
    28  GO can be downloaded [here](https://golang.org/dl/go1.13.15.windows-amd64.msi)
    29  
    30  Before cloning the Project, you should create the file path inside $GOPATH
    31  
    32  	% mkdir -p "$GOPATH/src/github.com/mundipagg"
    33  	% cd $GOPATH/src/github.com/mundipagg 
    34  	% git clone https://github.com/mundipagg/boleto-api
    35  
    36  
    37  Before compiling the application, you should install the [Glide](http://glide.sh/), which is the application dependency manager.
    38  
    39  After installing GO, do:
    40  
    41  	% cd devops
    42  	% ./build
    43  
    44  The build.sh script will download the application dependencies and install wkhtmltox, which is necessary to create boleto's in PDF format.
    45  
    46  Running the application
    47  -------------
    48  
    49  Running the API with default configurations
    50  Eg:
    51  
    52  Linux (*NIX):
    53  
    54  	% ./boleto-api
    55  	
    56  Windows:
    57  
    58  	% boleto-api.exe
    59  
    60  If you want to run the API in dev mode, which will load all standard environment variables, you should execute the application like this:
    61  
    62  	% ./boleto-api -dev
    63  
    64  In case you want to run the application in mock mode using in memory database instead of bank integration, you should use the mock option:
    65  
    66  	% ./boleto-api -mock
    67  
    68  In case you want to run the application with log turned off, you should use the option -nolog:
    69  
    70  	% ./boleto-api -nolog
    71  
    72  You can combine all these options and, in case you want to use them altogether, you can simply use the -airplane-mode option
    73  
    74  	% ./boleto-api -airplane-mode
    75  
    76  By default, boleto api will up and running a https server but you can run in http mode with the following option
    77  
    78  	% ./boleto-api -http-only
    79  	
    80  
    81  Using Boleto API Online
    82  ------------------
    83  
    84  You can use [Postman](https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop) to request the API's services or even the curl
    85  See following examples
    86  ### Banco do Brasil
    87  ```curl
    88  % curl -X POST \
    89    http://localhost:3000/v1/boleto/register \
    90    -d '{
    91      "Authentication" : {
    92          "Username":"user",
    93          "Password":"pass"
    94      },
    95      "Agreement":{
    96          "AgreementNumber":11111,
    97          "WalletVariation":19,
    98          "Wallet":17,
    99          "Agency":"123",
   100          "AgencyDigit":"2",
   101          "Account":"1231231",
   102          "AccountDigit":"3"
   103      },
   104      "Title":{
   105        "ExpireDate": "2017-05-25",
   106          "AmountInCents":200,
   107          "OurNumber":101405187,
   108          "Instructions":"Instruções"
   109      },
   110      "Buyer":{
   111          "Name":"BoletoOnlione",
   112          "Document": {
   113              "Type":"CNPJ",
   114              "Number":"73400584000166"
   115          },
   116          "Address":{
   117              "Street":"Rua Teste",
   118              "Number": "11",
   119              "Complement":"",
   120              "ZipCode":"12345678",
   121              "City":"Rio de Janeiro",
   122              "District":"Melhor bairro",
   123              "StateCode":"RJ"
   124          }
   125      },
   126      "Recipient":{
   127          "Name":"Nome do Recebedor",
   128          "Document": {
   129              "Type":"CNPJ",
   130              "Number":"12312312312366"
   131          },
   132          "Address":{
   133              "Street":"Rua do Recebedor",
   134              "Number": "322",
   135              "Complement":"2º Piso loja 404",
   136              "ZipCode":"112312342",
   137              "City":"Rio de Janeiro",
   138              "District":"Outro bairro",
   139              "StateCode":"RJ"
   140          }
   141      },
   142      "BankNumber":1
   143  }
   144  ```
   145  ### Response Banco do Brasil
   146  ```
   147  {
   148    "Url": "http://localhost:3000/boleto?fmt=html&id=g8HXWatft9oMLdTMAqzxbnPYFv3sqgV_KD0W7j8Cy9nkCLZMIK1WH2p9JwP1Jzz4ZtohmQ==",
   149    "DigitableLine": "00190000090101405100500066673179971340000010000",
   150    "BarCodeNumber": "00199713400000100000000001014051000006667317",
   151    "Links": [
   152      {
   153        "href": "http://localhost:3000/boleto?fmt=html&id=wOKZh6K_moLwXTW0Xr3oelh9YkYWXdl3VyURiQ-bu6TcuDzxdZI52BnQnuzNpGeh4TapUA==",
   154        "rel": "html",
   155        "method": "GET"
   156      },
   157      {
   158        "href": "http://localhost:3000/boleto?fmt=pdf&id=wOKZh6K_moLwXTW0Xr3oelh9YkYWXdl3VyURiQ-bu6TcuDzxdZI52BnQnuzNpGeh4TapUA==",
   159        "rel": "pdf",
   160        "method": "GET"
   161      }
   162    ]
   163  }
   164  
   165  ```
   166  ### Caixa
   167  ```curl
   168  curl -X POST \
   169    http://localhost:3000/v1/boleto/register \
   170    -H 'cache-control: no-cache' \
   171    -H 'content-type: application/json' \
   172    -H 'postman-token: 1bc1dd5f-cc34-0716-3d56-f18798d3fb39' \
   173    -d '{
   174      "BankNumber": 104,
   175      "Agreement": {
   176          "AgreementNumber": 200656,
   177          "Agency":"1679"
   178      },
   179      "Title": {
   180          "ExpireDate": "2017-08-30",
   181          "AmountInCents": 1000,
   182          "OurNumber": 0,
   183          "Instructions": "Mensagem",
   184          "DocumentNumber": "NPC160517"
   185      },
   186      "Buyer": {
   187          "Name": "TESTE PAGADOR 001",
   188          "Document": {
   189              "Type": "CPF",
   190              "Number": "57962014849"
   191          },
   192          "Address": {
   193              "Street": "SAUS QUADRA 03",
   194              "Number": "",
   195              "Complement": "",
   196              "ZipCode": "20520051",
   197              "City": "Rio de Janeiro",
   198              "District": "Tijuca",
   199              "StateCode": "RJ"
   200          }
   201      },
   202      "Recipient": {
   203          "Document": {
   204              "Type": "CNPJ",
   205              "Number": "00732159000109"
   206          }
   207      }
   208  }'
   209  ```
   210  ### Response
   211  ```
   212  {
   213      "id": "e1EVv1KRwuGX6OXOo7PNGYR-ePD1VPtjv5iqya1LJiLiaIKozN11YMiePNk-WebdgP4eIA==",
   214      "digitableLine": "10492.00650 61000.100042 09922.269841 3 72670000001000",
   215      "barCodeNumber": "10493726700000010002006561000100040992226984",
   216      "ourNumber": "14000000099222698",
   217      "links": [
   218          {
   219              "href": "https://200.201.168.67:8010/ecobranca/SIGCB/imprimir/0200656/14000000099222698",
   220              "rel": "pdf",
   221              "method": "GET"
   222          }
   223      ]
   224  }
   225  ```
   226  In case of Caixa, the impress of boleto will be handled by Caixa. So API will return the Caixa's boleto URL.
   227  
   228  
   229  The API's response will have the following pattern if any error occur:
   230  ```
   231  {
   232    "Errors": [
   233      {
   234        "Code": "MPExpireDate",
   235        "Message": "Data de expiração não pode ser menor que a data de hoje"
   236      }
   237    ]
   238  }
   239  ```
   240  
   241  API Installation
   242  -----------------
   243  
   244  For installation of the executable it's only necessary environment variables configured and the compiled application.
   245  
   246  Edit file $HOME/.bashrc.sh
   247  ```
   248      export API_PORT="3000"
   249      export API_VERSION="0.0.1"
   250      export ENVIRONMENT="Development"
   251      export SEQ_URL="http://example.mundipagg.com"
   252      export SEQ_API_KEY="API_KEY"
   253      export ENABLE_REQUEST_LOG="false"
   254      export ENABLE_PRINT_REQUEST="true"
   255      export URL_BB_REGISTER_BOLETO="https://cobranca.desenv.bb.com.br:7101/registrarBoleto"
   256      export URL_BB_TOKEN="https://oauth.desenv.bb.com.br:43000/oauth/token"
   257      export MONGODB_URL="10.0.2.15:27017"
   258      export APP_URL="http://localhost:8080/boleto"
   259  ```
   260      % go build && mv boleto-api /usr/local/bin
   261  
   262  Then the application will be installed locally.
   263  
   264  API Installation using Docker
   265  -----------------
   266  
   267  Before deploying, you should open the file [docker-compose](/devops/docker-compose.yml) and configure the information which is relevant to the environment. After setting up the docker-compose, you can install the application using the file deploy.sh
   268  
   269      % cd devops
   270      % ./build.sh
   271      % ./deploy.sh . local
   272  
   273  The script will create the Docker's volume directories, compile the application, mount the API's and MongoDB's images and upload the containers.
   274  For more information about docker-compose, see [doc](https://docs.docker.com/compose/). 
   275  
   276  The parameters sent to the script show that the deploy will run locally and not via TFS. In case you don't send the argument "local", the script will use docker-compose.release.yml.
   277  
   278  After being deployed, the application can be stoped or started.
   279      
   280      % cd devops/
   281      % ./stop.sh
   282      % ./start.sh
   283   
   284  Backup & Restore
   285  ----------------- 
   286  
   287  Run the following command to backup the database:
   288  
   289      % cd devops
   290      % ./doBackup.sh
   291  
   292  The generated backups, by default, will be stored in the diretory `$HOME/backups` with the name `bck_boleto-api-YYYY-MM-DD.tar`.
   293  To restore a backup:
   294      
   295      % cd devops
   296      % ./doRestore.sh
   297  
   298  To do the restoration of the database it'll be asked for the restoration file date in the following pattern: `YYYY-MM-DD`.
   299      
   300  Contributing
   301  -----------------
   302  
   303  To contribute, see [CONTRIBUTING](CONTRIBUTING.md)
   304  
   305  
   306  Using Mongo in Dev
   307  --------------------
   308  You can use mongo in dev on Docker by using the following command
   309  
   310       % docker run --name mongo-boleto -p 27017:27017 -d mongo
   311  
   312  For more information
   313  -----------------
   314  
   315  See [FAQ](./FAQ.md)