Emissão de boleto único (instantânea)

Importante

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

ENDPOINT

/account/ACCOUNT_KEY/requester_profile/REQUESTER_PROFILE_KEY/bank_slip/instant

MÉTODO

POST

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",
}

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
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

Atenção!

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).

Atenção!

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	-

Opção 2: multa em valor percentual (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	-

Opção 2: juros utilizando valores percentuais (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

Opção 2: descontos utilizando valores percentuais (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

Atenção!

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

Enumeradores state

Enumerador	Descrição
AC	Acre
AL	Alagoas
AM	Amazonas
AP	Amapá
BA	Bahia
CE	Ceará
DF	Distrito federal
ES	Espírito Santo
GO	Goiás
MA	Maranhão
MG	Minas Gerais
MS	Mato Grosso do Sul
MT	Mato Grosso
PA	Pará
PB	Paraíba
PE	Pernambuco
PI	Piauí
PR	Paraná
RJ	Rio de Janeiro
RN	Rio Grande do Norte
RO	Rondônia
RR	Roraima
RS	Rio Grande do Sul
SC	Santa Catarina
SE	Sergipe
SP	São Paulo
TO	Tocantins
EX	Exceção

Response

STATUS

201

Response Body: Boleto registrado

{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "bank_slip_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "bank_slip_status": "registered"
}

STATUS

202

Response Body: Boleto pendente de registro

{
  "request_control_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
  "bank_slip_key": "e8599844-5cad-40b4-8716-cb4770d415b4",
  "bank_slip_status": "accepted"
}

Informação

Caso seja retornado HTTP Status 202 com o campo bank_slip_status com valor accepted, a emissão não deve ser retentada.

Esta emissão será processada assincronamente. É necessário verificar o status do boleto por meio da consulta de boleto, ou aguardar o recebimento do webhook de confirmação descrito na página de webhooks.

Response 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
bank_slip_key *	uuidv4	Chave única de identificação do boleto no formato uuid v4	36
bank_slip_status *	string	Status do boleto	Enumeradores bank_slip_status

Enumeradores bank_slip_status

Enumerador	Descrição
accepted	Boleto aceito mas ainda não registrado
registered	Boleto registrado

Error Response

STATUS

4xx

Response Body: Error

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}

Código HTTP status	Código QI code	Título title	Descrição (eng) description	Descrição (pt-br) translation
400	QIT000001	Bad Request	Schema Error	Schema Inválido
404	BKS000004	Not Found	Pix key not found: {pix_key}	Chave pix não encontrada: {pix_key}
403	BKS000005	Forbidden	User is not allowed to do this action	Usuário não tem autorização para fazer essa ação
404	BKS000006	Not Found	The source account key was not found.	A chave da conta de origem não foi encontrada.
400	BKS000007	Bad Request	It was not possible to consult the source account at this time. Please try again in a few minutes.	Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.
400	BKS000008	Bad Request	The source account is closed.	A conta de origem está fechada.
400	BKS000009	Bad Request	The source account is blocked.	A conta de origem está bloqueada.
403	BKS000010	Forbidden	The pix key owner does not match the account owner.	O proprietário da chave pix não corresponde ao proprietário da conta.
404	BKS000013	Not Found	Requester profile not found	Carteira não encontrada
409	BKS000014	Conflict	Request control key already sent or duplicated sent: {request_control_key}	Chave de controle da requisição já utilizada ou enviada duplicada: {request_control_key}
400	BKS000016	Bad Request	Expiration date must be greater than the current date and have a maximum of 3650 days from the current date.	A data de vencimento deve ser maior que a data atual e possuir no máximo 3650 dias corridos a partir da data atual.
409	BKS000017	Conflict	Our number already used or duplicated sent: {our_number}	Nosso número já utilizado ou enviado duplicado: {our_number}
400	BKS000018	Bad Request	The discount dates must be less than the expiration date and increasing.	A data dos descontos devem ser menores que a de expiração e crescentes.
400	BKS000019	Bad Request	Payer address is required for protest.	Endereço do pagador é obrigatório para protesto.
500	BKS000021	Internal Server Error	Error while trying to generate QR Code.	Erro ao tentar gerar QR Code de pagamento.
400	BKS000022	Bad Request	Requester profile is not opened.	Carteira não está aberta.
400	BKS000023	Bad Request	The amount must be greater than zero.	O valor deve ser maior que zero.
400	BKS000024	Bad Request	Error while registering bank slip.	Erro ao registrar boleto.
400	BKS000026	Bad Request	Guarantor address is required for protest.	Endereço do sacador é obrigatório para protesto.
404	BKS000028	Not Found	Notary office attended region not found for postal code: {postal_code}	Região de cartório não encontrada para o CEP: {postal_code}
400	BKS000043	Bad Request	Invalid discount numbering. Discounts must be numbered in ascending order and start on 1.	Numeração dos descontos inválida. Os descontos devem ser numerados em ordem crescente e começar em 1.
400	BKS000045	Bad Request	Rebate amount cannot be greater than the bank slip amount.	O valor do rebate não pode ser maior que o valor do boleto.
400	BKS000047	Bad Request	It was not possible to consult the sent pix key at this time. Please try again in a few minutes.	Não foi possível consultar a chave pix enviada no momento. Por favor, tente novamente em alguns minutos.