Batches and Billings

Sumário

Fluxos de Processamento

Validação de Arquivos

Processamento de Lotes

Modificação de Status de Boletos

Rotas da API

Lotes e Boletos

POST {account_id}/batches - Lista todos os lotes de boletos.

GET {account_id}/batch/{uuid} - Visualiza detalhes de um lote específico.

POST {account_id}/billings - Lista todos os boletos.

GET {uuid}/billing - Visualiza detalhes de um boleto específico.

Envio e Validação de Arquivos

POST {file_type}/validate-shipment - Valida um arquivo de remessa.

POST {account_id}/file-type/{file_type}/send-shipment - Envia boletos via arquivos CNAB ou CSV.

POST {account_id}/send-shipment-with-json - Envia boletos com JSON no corpo da requisição.

Download de Arquivos de Retorno

GET {account_id}/batch/{batch_id}/return-file/{format} - Baixa arquivo de retorno de um lote.

GET {account_id}/start/{start}/end/{end}/return-file/{format} - Baixa arquivo de retorno de um período.

Tipos de Arquivos Aceitos

Remessa

CNAB/CSV (lotes): txt, rem, csv

JSON (boleto avulso): Dados enviados diretamente no corpo da requisição.

Retorno

Formatos aceitos: txt, rem, csv, json

Filtros aplicáveis para gerar relatórios

Relatório de títulos emitidos

Consultar por data de emissão (created_at)

Data de vencimento (due_date)

Relatório de títulos pagos

Consultar por data de pagamento (payment_date)

Por cliente-CNPJ/CPF (taxid_number)

Nosso número (our_number)

Consultar por status do título (BillingSlipStatusEnum)

Em aberto

Liquidados

A vencer

Vencidos

Baixados

Com instrução

Exemplos de filtros

Rota: POST {account_id}/batches

{
  "sort": [
    {
      "field": "created_at",
      "direction": "desc"
    }
  ],
  "filters": [
    {
      "field": "uuid",
      "operator": "=",
      "value": "df03c599-c18b-4435-9212-3951b910b546"
    },
    {
      "field": "status",
      "operator": "=",
      "value": "processing"
    }
  ],
  "date_filters": [
    {
      "field": "payment_date",
      "operator": "=",
      "value": "2025-02-20"
    },
    {
      "field": "created_at",
      "operator": ">=",
      "value": "2025-01-01"
    },
    {
      "fields": ["created_at", "created_at"],
      "operator": "between",
      "value": ["2025-01-01", "2025-12-31"]
    }
  ]
}

Rota: POST {account_id}/billings

{
  "sort": [
    {
      "field": "created_at",
      "direction": "desc"
    }
  ],
  "search": {
    "field": "sender_name",
    "operator": "like",
    "value": "%posto%"
  },
  "filters": [
    {
      "field": "status",
      "operator": "=",
      "value": "processing"
    },
    {
      "field": "our_number",
      "operator": "=",
      "value": "10080454"
    },
    {
      "field": "sender_tax_id_number",
      "operator": "=",
      "value": "11852329000520"
    }
  ],
  "date_filters": [
    {
      "field": "created_at",
      "operator": ">=",
      "value": "2025-01-01"
    },
    {
      "field": "due_date",
      "operator": ">=",
      "value": "2025-01-01"
    },
    {
      "fields": ["created_at", "created_at"],
      "operator": "between",
      "value": ["2025-01-01", "2025-12-31"]
    }
  ]
}

Padrões de Arquivos

CNAB

Para envio de arquivos no formato CNAB400, siga o layout do Banco Itaú:
LAYOUT CNAB400 PADRÃO BANCO ITAÚ

CSV

Cabeçalho (ordem das colunas)

codigo_inscricao,numero_inscricao,agencia,conta,dac,uso_empresa,nosso_numero,qtde_moeda,num_carteira,uso_banco,carteira,cod_ocorrencia,num_documento,vencimento,valor_titulo,codigo_banco,agencia_cobradora,especie,aceite,data_emissao,instrucao_1,instrucao_2,juros_1_dia,desconto_ate,valor_desconto,valor_iof,abatimento,codigo_inscricao_pagador,numero_inscricao_pagador,nome_pagador,logradouro,bairro,cep,cidade,estado,sacador_avalista,data_mora,prazo,cod_multa,data_multa,multa_valor_percentual

Exemplo (2 linhas válidas)

codigo_inscricao,numero_inscricao,agencia,conta,dac,uso_empresa,nosso_numero,qtde_moeda,num_carteira,uso_banco,carteira,cod_ocorrencia,num_documento,vencimento,valor_titulo,codigo_banco,agencia_cobradora,especie,aceite,data_emissao,instrucao_1,instrucao_2,juros_1_dia,desconto_ate,valor_desconto,valor_iof,abatimento,codigo_inscricao_pagador,numero_inscricao_pagador,nome_pagador,logradouro,bairro,cep,cidade,estado,sacador_avalista,data_mora,prazo,cod_multa,data_multa,multa_valor_percentual
02,37511258000162,3100,04134,5,167362,17784990,0,109,,I,01,0000167362,010825,2500.45,341,00001,01,N,010825,05,93,0,000000,0,0,0,02,47216831000169,PSJ AMERICO BRASILIENSE COMERC,ROD ANTONIO MACHADO SANTANA, S/N,ZONA RURAL,14820000,AMERICO BRASILI,SP,MULTA 2.00% PARTIR 02.08.25,010825,00,2,02082025,2.00
02,37511258000162,3100,04134,5,167363,17784991,0,109,,I,01,0000167363,010825,3750.67,341,00001,01,N,010825,05,93,0,000000,0,0,0,02,29906010000172,P S J GUARIBA COMERCIO DE COMB,ROD BRIGADEIRO FARIA LIMA , SN,ZONA RURAL,14840000,GUARIBA,SP,MULTA 2.00% PARTIR 02.08.25,010825,00,2,02082025,2.00

O arquivo CSV deve conter as seguintes colunas:

Campo	Tipo/Formato esperado	Observações
`codigo_inscricao`	numérico (string), 2–2 dígitos, preservar zeros à esquerda
`numero_inscricao`	numérico (string), 14–14 dígitos, preservar zeros à esquerda	Somente números (sem pontos/traços).
`agencia`	numérico (string), 4–4 dígitos, preservar zeros à esquerda
`conta`	numérico (string), 5–5 dígitos, preservar zeros à esquerda
`dac`	numérico (string), 1–1 dígitos, preservar zeros à esquerda
`uso_empresa`	numérico (string), 6–6 dígitos, preservar zeros à esquerda
`nosso_numero`	numérico (string), 8–8 dígitos, preservar zeros à esquerda	Preservar zeros à esquerda; não usar formato numérico do Excel.
`qtde_moeda`	numérico (string), 1–1 dígitos, preservar zeros à esquerda
`num_carteira`	numérico (string), 3–3 dígitos, preservar zeros à esquerda
`uso_banco`	string
`carteira`	string
`cod_ocorrencia`	numérico (string), 2–2 dígitos, preservar zeros à esquerda
`num_documento`	numérico (string), 10–10 dígitos, preservar zeros à esquerda
`vencimento`	numérico (string), 6–6 dígitos, preservar zeros à esquerda
`valor_titulo`	decimal (string), ponto como separador, sem milhar	Use ponto como separador decimal (ex: 2500.45).
`codigo_banco`	numérico (string), 3–3 dígitos, preservar zeros à esquerda
`agencia_cobradora`	numérico (string), 5–5 dígitos, preservar zeros à esquerda
`especie`	numérico (string), 2–2 dígitos, preservar zeros à esquerda
`aceite`	string
`data_emissao`	numérico (string), 6–6 dígitos, preservar zeros à esquerda	Sem separadores; preferir ddmmaa ou ddmmaaaa conforme integração.
`instrucao_1`	numérico (string), 2–2 dígitos, preservar zeros à esquerda
`instrucao_2`	numérico (string), 2–2 dígitos, preservar zeros à esquerda
`juros_1_dia`	numérico (string), 1–1 dígitos, preservar zeros à esquerda
`desconto_ate`	numérico (string), 6–6 dígitos, preservar zeros à esquerda
`valor_desconto`	numérico (string), 1–1 dígitos, preservar zeros à esquerda	Use ponto como separador decimal (ex: 2500.45).
`valor_iof`	numérico (string), 1–1 dígitos, preservar zeros à esquerda	Use ponto como separador decimal (ex: 2500.45).
`abatimento`	numérico (string), 1–1 dígitos, preservar zeros à esquerda
`codigo_inscricao_pagador`	numérico (string), 2–2 dígitos, preservar zeros à esquerda
`numero_inscricao_pagador`	numérico (string), 14–14 dígitos, preservar zeros à esquerda	Somente números (sem pontos/traços).
`nome_pagador`	string
`logradouro`	string
`bairro`	string
`cep`	numérico (string), 8–8 dígitos, preservar zeros à esquerda	Somente números (8 dígitos).
`cidade`	string
`estado`	string
`sacador_avalista`	string
`data_mora`	numérico (string), 6–6 dígitos, preservar zeros à esquerda	Sem separadores; preferir ddmmaa ou ddmmaaaa conforme integração.
`prazo`	numérico (string), 2–2 dígitos, preservar zeros à esquerda
`cod_multa`	numérico (string), 1–1 dígitos, preservar zeros à esquerda
`data_multa`	numérico (string), 8–8 dígitos, preservar zeros à esquerda	Sem separadores; preferir ddmmaa ou ddmmaaaa conforme integração.
`multa_valor_percentual`	decimal (string), ponto como separador, sem milhar

Consulte o layout CNAB400 para mais detalhes sobre os tipos de dados.

JSON

Exemplo de payload para envio via JSON:

{
  "billing_instrument_description": "slip", // Obrigatório
  "slip_type": "in_cash", // Obrigatório
  "shipping_format": "print", // Obrigatório
  "wallet_code": "109", // Obrigatório
  "due_type_code": 3, // Obrigatório
  "species_code": "01", // Obrigatório
  "accepted_code": "S", // Obrigatório (S para aceito e N para não aceito)
  "partial_payment": true, // Obrigatório
  "partial_maximum_quantity": 2, // Obrigatório quando partial_payment = true
  "payer": {
    "taxid_number": "86692588111", // Obrigatório
    "taxid_country": "BRA", // Obrigatório
    "name": "Clevisson Amorim Bravo", // Obrigatório
    "email": "contabilidade.cormack@geradornv.com.br", // Obrigatório quando shipping_format = email
    "address": {
      "street": "Avenida João Valério", // Obrigatório
      "number": "474", // Obrigatório
      "complement": "Lote 1", // Opcional
      "district": "Santa Luzia", // Obrigatório
      "city": "Itacoatiara", // Obrigatório
      "state": "AM", // Obrigatório
      "zip_code": "69104018", // Obrigatório
      "country": "BRA" // Obrigatório
    }
  },
  "final_beneficiary": {
    "uuid": "b9d543fc-710c-424d-beff-1dbf00b4c616", // Obrigatório
    "exclusion_of_final_beneficiary": false // Obrigatório quando for para excluir o benefeciario final
  },
  "individual_data_bill": [
    {
      "total_amount": "9.38", // Obrigatório
      "due_date": "2025-09-17", // Obrigatório
      "payment_deadline": "2025-10-17", // Opcional
      "text_your_number" : "ABC1234567" // Opcional
    }
  ],
  "fees": {
    "interest_type_code": "90", // Obrigatório
    "amount_of_interest_days": 1, // Opcional
    "interest_value": "1.23", // Opcional
    "interest_percentage": "1.23", // Opcional
    "interest_date": "2025-09-11" // Opcional
  },
  "fine": {
    "code_type_fine": "01", // Obrigatório
    "number_of_days_fine": 1, // Opcional
    "amount_of_fine": "1.35", // Opcional
    "percentage_of_fine": "1.25" // Opcional
  },
  "discount": {
    "discount_type_code": "01", // Obrigatório
    "discounts": [
      {
        "discount_date": "2025-09-16", // Opcional
        "discount_value": "1.55", // Opcional
        "discount_percentage": "1.52" // Opcional
      }
    ]
  },
  "billing_instruction": [
    {
      "billing_instruction_code": "02", // Opcional
      "number_of_billing_instruction_days": 10, // Opcional
      "useful_day": true // Opcional
    }
  ],
  "protest": {
    "protest": true, // Opcional
    "protest_type_code": 1, // Opcional
    "number_of_protest_days": 1, // Opcional
    "bankruptcy_protest": true // Opcional
  },
  "negativation": {
    "negativation": true, // Opcional
    "code_type_negation": 1, // Opcional
    "amount_of_negative_days": 2 // Opcional
  },
  "divergent_receipt": {
    "authorization_type_code": 1, // Obrigatório
    "receipt_type_code": "V", // Opcional
    "minimum_value": "999999999999999.00", // Opcional
    "minimum_percentage": "9999999.00000", // Opcional
    "maximum_value": "999999999999999.00", // Opcional
    "maximum_percentage": "9999999.00000" // Opcional
  },
  "allowed_actions": {
    "issue_second_copy": true, // Opcional e
    "command_instruction_change_billing_data": true // Opcional e
  }
}

Download de Arquivo de Retorno

Por Lote Específico

Acessar a aba de boletos no IBK.

Na lista de lotes (exceto com status failed), clique em Baixar arquivo de retorno.

Escolha o formato desejado: CNAB, CSV ou JSON.

O arquivo será disponibilizado para download.

Por Período

Acesse a aba de boletos no IBK.

Clique em Baixar arquivo de retorno.

Informe as datas inicial e final.

Escolha o formato desejado.

Clique em Baixar agora.

O arquivo será disponibilizado para download.

iBaaS Lotes e Boletos

Sumário#

Fluxos de Processamento#

Validação de Arquivos#

Processamento de Lotes#

Modificação de Status de Boletos#

Rotas da API#

Lotes e Boletos#

Envio e Validação de Arquivos#

Download de Arquivos de Retorno#

Tipos de Arquivos Aceitos#

Remessa#

Retorno#

Filtros aplicáveis para gerar relatórios#

Exemplos de filtros#

Padrões de Arquivos#

CNAB#

CSV#

Cabeçalho (ordem das colunas)#

Exemplo (2 linhas válidas)#

JSON#

Download de Arquivo de Retorno#

Por Lote Específico#

Por Período#