Emissão de boletos em lote
Para registrar bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que os boletos serão registrados.
A emissão de boletos em lote é feita somente de maneira assíncrona. Caso um dos boletos falhe na validação das informações fornecidas, nenhum dos boletos será registrado nessa mesma requisição.
Como tratam-se de um registros assíncronos, o solicitante é notificado via webhook assim que cada um dos boletos mudar de status de accepted
para registered
ou rejected
.
Request
Path parameters
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
account_key | uuidv4 | Chave única de identificação da conta, no formato uuid v4 | 36 |
requester_profile_key | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36 |
Request Body
{
"bank_slips": [
{
"request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
"our_number": 123456789,
"document_number": "DOC4561237",
"amount": 5000.00,
"expiration": "2025-01-01",
"bank_teller_instructions": "Confirm payment",
"protest_data": {"days_to_protest": 7},
"bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
"max_payment_days": 45,
"fine_data": {"fine_type": "absolute", "fine_amount": 100.00, "days_to_fine": 10},
"interest_data": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10.00,
"days_to_interest": 2,
},
"write_off_data": {"days_to_write_off": 365},
"rebate_amount": 200.00,
"discounts_data": [
{
"discount_amount": 50.00,
"discount_number": 1,
"discount_type": "absolute",
"discount_limit_date": "2025-01-01",
}
],
"payer_data": {
"name": "Global Tech",
"contact": {
"email": "finance@globaltech.com",
"phone": {"international_dial_code": "055", "area_code": "11", "number": "987654321"},
},
"address": {
"street": "101 High St.",
"neighborhood": "Tech Park",
"number": "202",
"postal_code": "49069234",
"city": "Innovation City",
"state": "SP",
"complement": "Building A",
},
"document_number": "12345678000195",
"person_type": "legal",
},
"guarantor_data": {
"name": "Jane Doe",
"contact": {
"email": "jane.doe@qitech.com.br",
"phone": {"international_dial_code": "055", "area_code": "11", "number": "999999999"},
},
"address": {
"street": "202 Elm St.",
"neighborhood": "Quiet Neighborhood",
"number": "303",
"postal_code": "35700854",
"city": "Peaceful Town",
"state": "RJ",
"complement": "House 1",
},
"document_number": "23456789012",
"person_type": "natural",
},
"pix_key": "78252991-d26d-4d6b-8c50-be3233ffabf7",
"notification": {
"document_number": "12345678000195",
"name": "Global Tech",
"email": "finance@globaltech.com",
"phone": {"international_dial_code": "055", "area_code": "11", "number": "987654321"},
"send_2_way": true,
"send_before_due_date": true,
"send_after_due_date": true,
"send_on_protest": true
}
},
{
"request_control_key": "b3a428fd-58ee-4d6f-8872-633874ebf5e2",
"our_number": 987654321,
"document_number": "DOC4561237",
"amount": 5000.00,
"expiration": "2025-01-01",
"bank_teller_instructions": "Confirm payment",
"protest_data": {"days_to_protest": 7},
"bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
"max_payment_days": 45,
"fine_data": {"fine_type": "absolute", "fine_amount": 100.00, "days_to_fine": 10},
"interest_data": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10.00,
"days_to_interest": 2
},
"write_off_data": {"days_to_write_off": 365},
"rebate_amount": 200.00,
"discounts_data": [
{
"discount_amount": 50.00,
"discount_number": 1,
"discount_type": "absolute",
"discount_limit_date": "2025-01-01"
}
],
"payer_data": {
"name": "Global Tech",
"contact": {
"email": "finance@globaltech.com",
"phone": {"international_dial_code": "055", "area_code": "11", "number": "987654321"},
},
"address": {
"street": "101 High St.",
"neighborhood": "Tech Park",
"number": "202",
"postal_code": "79071231",
"city": "Innovation City",
"state": "SP",
"complement": "Building A"
},
"document_number": "12345678000195",
"person_type": "legal"
},
"guarantor_data": {
"name": "Jane Doe",
"contact": {
"email": "jane.doe@qitech.com.br",
"phone": {"international_dial_code": "055", "area_code": "11", "number": "999999999"},
},
"address": {
"street": "202 Elm St.",
"neighborhood": "Quiet Neighborhood",
"number": "303",
"postal_code": "65066380",
"city": "Peaceful Town",
"state": "RJ",
"complement": "House 1"
},
"document_number": "23456789012",
"person_type": "natural"
}
}
]
}
Request Body Params
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
bank_slips * | Array de Objeto bank_slip | Lista de boletos a serem registrados | - |
Objeto bank_slip
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
request_control_key * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
our_number | integer | Número único de identificação do boleto junto à carteira. Pode ser enviado pelo cliente e, caso não seja, a QI Tech irá gerar um | 11 |
document_number | string | Número de identificação do boleto | 10 |
participant_control_number | string | Nº Controle do Participante | |
25 | |||
amount * | float | Valor base do boleto | - |
expiration * | string | Data de vencimento | 10 |
bank_teller_instructions | string | Instruções adicionais de registro, que constarão no PDF do boleto | 320 |
rebate_amount | float | Valor de abatimento do boleto, que será aplicado em cima do valor base | - |
max_payment_days | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | - |
write_off_data | object | Configuração de baixa | Objeto write_off_data |
protest_data | object | Configuração de protesto | Objeto protest_data |
bankruptcy_protest_data | object | Configuração de protesto falimentar | Objeto bankruptcy_protest_data |
fine_data | object | Configuração de multa | Objeto fine_data |
interest_data | object | Configuração de juros | Objeto interest_data |
discounts_data | object array | Descontos | Objeto discount |
payer_data * | object | Dados do pagador | Objeto payer_data |
guarantor_data | object | Dados do sacador avalista | Objeto guarantor_data |
pix_key | uuidv4 | Chave pix do tipo aleatória | 36 |
Caso o parâmetro pix_key
, opcional, seja enviado na request, será gerado um bolePix. BolePix é um boleto cujo pagamento é vinculado a um QR Code Pix. Sendo assim, o pagador pode realizar o pagamento do boleto tanto utilizando a linha digitável do mesmo, quanto através da leitura do QR Code Pix vinculado. Caso o pagamento seja feito via QR Code, a liquidação financeira se dá instantaneamente, enquanto os retornos bancários e webhooks envolvidos na liquidação serão gerados assim como é feito para um boleto comum.
Importante: para registrar um bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que boleto será registrado.
Caso cada um dos campos max_payment_days
, write_off_data
, protest_data
, bankruptcy_protest_data
, fine_data
, interest_data
e pix_key
não sejam enviados na request e a carteira possua configurações padrão (i.e. max_payment_days
, write_off_settings
, protest_settings
, bankruptcy_protest_settings
, fine_settings
, interest_settings
e qr_code_settings
, respectivamente, no configuration_data
do requester_profile
), serão utilizadas tais configurações padrão para a emissão do título.
Objeto write_off_data
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
days_to_write_off * | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente | - |
Objeto protest_data
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
days_to_protest * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente | - |
Objeto bankruptcy_protest_data
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
days_to_bankruptcy_protest * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente | - |
Objeto fine_data
Opção 1: multa em valor absoluto (fine_type=absolute
)
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
fine_type * | string | Tipo da multa | Enumeradores fine_type |
fine_amount * | float | Valor absoluto da multa | - |
days_to_fine * | integer | Dias, após o vencimento, para que a multa seja cobrada | - |
fine_type=percentage
)
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
fine_type * | string | Tipo da multa | Enumeradores fine_type |
fine_percentage * | integer | Valor percentual da multa, de 1 a 100 | - |
days_to_fine * | integer | Dias, após o vencimento, para que a multa seja cobrada | - |
Enumeradores fine_type
Enumerador | Descrição |
---|---|
absolute | valor absoluto |
percentage | valor percentual |
Objeto interest_data
Opção 1: juros utilizando valores absolutos (interest_type=calendar_days_daily_amount
ou interest_type=workdays_daily_amount
)
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
interest_type * | string | Tipo de juros | Enumeradores interest_type |
interest_amount * | float | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | - |
days_to_interest * | integer | Dias, após o vencimento, para que comece a cobrar os juros | - |
interest_type=calendar_days_monthly_percentage
)
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
interest_type * | string | Tipo de juros | Enumeradores interest_type |
interest_percentage * | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos) | - |
days_to_interest * | integer | Dias, após o vencimento, para que comece a cobrar os juros | - |
Enumeradores interest_type
Enumerador | Descrição |
---|---|
calendar_days_daily_amount | Valor diário sobre dias corridos |
workdays_daily_amount | Valor diário sobre dias úteis |
calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |
Objeto discount
Opção 1: descontos utilizando valores absolutos (discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]
)
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
discount_amount * | float | Valor absoluto de desconto por unidade de tempo | - |
discount_number * | integer | Número do desconto | - |
discount_type * | string | Configuração do desconto em valores absolutos | Enumerador discount_type |
discount_limit_date * | string | Data limite para aplicação do desconto | 10 |
discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]
)
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
discount_percentage * | float | Valor percentual de desconto por unidade de tempo | - |
discount_number * | integer | Número do desconto | - |
discount_type * | string | Configuração do desconto em valores percentuais | Enumerador discount_type |
discount_limit_date * | string | Data limite para aplicação do desconto | 10 |
O boleto pode ter até três descontos, sendo que os descontos devem ser todos do mesmo tipo, isto é, devem ter o mesmo discount_type
. Os descontos devem ser numerados de 1 a 3, de maneira crescente e começando necessariamente em 1. Ou seja, caso sejam enviados dois descontos na requisição, devem necessariamente ser numerados com 1 e 2.
Enumeradores discount_type
Enumerador | Descrição |
---|---|
absolute | Valor fixo |
anticipation_calendar_days_daily_amount | Valor diário de desconto de antecipação, sobre dias corridos |
anticipation_workdays_daily_amount | Valor diário de desconto de antecipação, sobre dias úteis |
percentage | Porcentagem fixa |
anticipation_calendar_days_daily_percentage | Porcentagem mensal de desconto de antecipação, com base em dias corridos |
anticipation_workdays_daily_percentage | Porcentagem anual de desconto de antecipação, com base em dias úteis |
Objetos payer_data e guarantor_data
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
name * | string | Nome completo | 100 |
document_number * | string | Número do documento (CPF/CNPJ) | 11 ou 14 |
person_type * | string | Tipo da pessoa (física ou jurídica) | Enumeradores person_type |
contact | object | Informações de contato | Objeto contact |
address | object | Endereço | Objeto address |
Enumeradores person_type
Enumerador | Descrição |
---|---|
natural | pessoa física |
legal | pessoa jurídica |
Objeto contact
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
email | string | E-mail de contato | 320 |
phone | object | Telefone de contato | Objeto phone |
Objeto phone
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
international_dial_code * | string | Código DDI (Discagem Direta Internacional) | 3 |
area_code * | string | Código DDD (Discagem Direta à Distância) | 2 |
number * | string | Complemento | 9 |
Objeto address
Campo | Tipo | Descrição | Caracteres |
---|---|---|---|
street * | string | Logradouro | 500 |
number * | string | Número | 6 |
complement | string | Complemento | 500 |
neighborhood * | string | Bairro | 100 |
postal_code * | string | CEP | 8 |
city * | string | Cidade | 100 |
state * | string | Estado (UF) | Enumerador state |