Skip to main content

Remittance files (CNAB) - Introduction

info

The file transmitted in this call must follow the QI Tech Collection File Layout standard with 400 positions. Here is the link to download the manual: Layout de Cobrança - QI Tech versão 2.1.

Remittance files (CNAB) offer the possibility to send multiple boleto record instructions, along with other types of instructions (extension, discount, cancellation, etc.), for different boletos, in a single file. When sending instructions such as those mentioned (extension, discount, etc.) for existing boletos, the boleto is identified by the portfolio code (requester_profile_code) and by our number (our_number).

When uploading a CNAB file, if the request is successful (response code 202), a temporary CNAB file (TemporaryCNABFile) will be created. It is possible to check the file processing status --- as well as possible errors, both in the file itself and in its occurrences ---, using the endpoints for temporary CNAB file query and its occurrences.

The file will be rejected if any syntactic error is found. However, it is read entirely, or until a limit of 100 errors is reached, so that all errors can be returned and corrected in a more practical and efficient manner.

While the file is being read, temporary occurrences are created, which will only be processed if it is accepted. That is, if the file is rejected (status rejected), all its occurrences will also be. Furthermore, if the file is rejected, no more temporary occurrences are created for it. Therefore, it is common for rejected file entries to have fewer occurrences than the number of occurrences sent in the file.

On the other hand, when the file is completely read and accepted (status read), the creation of definitive occurrences begins, which will be the instructions that will actually take effect. If a temporary occurrence shows the status rejected, it means that some semantic error was found in it --- that is, some error in its content. In this case, there will be an error_data object along with it, which provides details about the reason for rejection. In contrast, if it shows the status processed, it means that the definitive occurrence has already been created and sent to CIP/Nuclea. More details about each of these entities are provided in the subsequent pages for querying files and temporary occurrences.

Credit Split via CNAB

To inform credit split (split payment) in CNAB files:

  • QI SCD (CNAB400 - QI Tech v2.1 layout): detail record with identificacao_registro = 3. Full details in the Layout de Cobrança - QI Tech v2.1.
  • Bradesco (CNAB400 and CNAB240): detail record type 3.
  • Itaú (CNAB400 and CNAB240): detail record type 4.
  • Santander: does not support credit split via CNAB. Use the REST endpoint Credit Split Update or include split_payment_data in the issuance via API.

How to map N recipients: Each split record fits up to 3 additional accounts (account number + check digit + percentage). For more than 3 recipients, add multiple split records in sequence after the bank slip's main record — they are accumulated in the same occurrence. Example: 7 accounts = 3 records (3 + 3 + 1).

Restrictions (all banks):

  • Only percentage-based calculation is supported (calculation code = 2).
  • The sum of percentages (beneficiary + splits) must be exactly 100.
  • Total recipient limit follows the same as the REST API (up to 10 additional accounts).
  • The beneficiary_max_amount field (split with maximum beneficiary amount and surplus directed to the first rule) is REST API exclusive. It is not supported via CNAB. For this scenario, use the REST endpoint for issuance or for credit split update.