Emissão de boleto único (instantânea)
Para registrar bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que os boletos serão registrados.
No caso do registro de boleto único de forma instantânea, a resposta da requisição de criação (resposta síncrona) já retorna o boleto registrado (ou não, para casos de rejeição). O tempo de confirmação/rejeição da Nuclea/CIP, a respeito do registro do boleto, está incluso no tempo de resposta desse endpoint.
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
{
"request_control_key": "0d496b4d-01f6-48cd-8ec9-9ead1e43f156",
"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": "2024-12-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": "01001000",
"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": "01001000",
"city": "Peaceful Town",
"state": "RJ",
"complement": "House 1",
},
"document_number": "23456789012",
"person_type": "natural",
},
"pix_key": "06797774-e050-419e-a91a-c64c919b52c7",
"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": false,
"send_after_due_date": false,
"send_on_protest": false
}
}
Request Body Params
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. Pode ser o número da nota fiscal eletrônica | 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 | Observações ao pagador 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 objeto qr_code_settings
seja enviado na request, essa carteira terá como configuração padrão a geração de bolePix. BolePix são boletos cujo pagamento é vinculado a um QR Code Pix. Sendo assim, o pagador pode realizar o pagamento dos boletos tanto utilizando as linhas digitáveis dos mesmos, quanto através da leitura dos QR Codes Pix vinculados. Caso o pagamento seja feito via QR Code, a liquidação financeira se dá instantaneamente. Já em relação às notificações, são enviados dois webhooks: um no ato da transferência PIX (aviso de pagamento, boleto vai para o status payment_notice
); e outro alguns segundos ou minutos depois, após a confirmação da baixa na CIP/Nuclea (pago, boleto vai para o status paid
).
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 |