Pular para o conteúdo principal

Instruções de Boleto

Este endpoint permite enviar instruções a um boleto já registrado, como prorrogação de vencimento, atualização de juros e multa, inclusão de descontos, abatimento, baixa e solicitação de protesto.

Disponível em
PerfilHostPermissão exigida
Gestoramanager-apiLeitura e escrita
Consultoriaconsultant-apiLiberada pelo time de integração

URL base de cada host: Ambientes (Hosts).

Quais boletos aceitam instrução

Só boletos em pending_registration ou registered, emitidos pela QI Tech (configuração com tipo de emissor internal; veja configurações de boleto), aceitam instrução. Para os demais, a API devolve BSC000009 (boleto fora desses status) ou BSC000106 (outro emissor).

Request​

ENDPOINT
/bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_configuration/BANKSLIP_CONFIGURATION_KEY/bankslip/BANKSLIP_KEY
MÉTODO
PUT

Path Parameters​

CampoTipoDescriçãoCaracteres
fund_class_keyuuidv4Chave única de identificação da classe de fundo, no formato uuid v436
bankslip_configuration_keyuuidv4Chave única de identificação da configuração do boleto, no formato uuid v436
bankslip_keyuuidv4Chave única de identificação do boleto, no formato uuid v436

Request Body Params​

O campo occurrence_type define qual instrução será enviada ao boleto. O campo occurrence_data contém os dados específicos da instrução, quando aplicável.

CampoTipoDescriçãoCaracteres
occurrence_typestringTipo da instrução a ser enviada ao boleto.Enumerador occurrence_type
occurrence_dataobjectDados da instrução. Obrigatório para os tipos que exigem parâmetros adicionais.Varia conforme o occurrence_type

Enumeradores occurrence_type​

EnumeradorDescrição
due_date_extensionProrrogação da data de vencimento
delay_interest_updateAtualização dos juros de mora
delay_fine_updateAtualização da multa por atraso
rebateAplicação de abatimento
rebate_withdrawnCancelamento do abatimento
discount_inclusionInclusão de descontos
write_offBaixa do boleto
protest_requestSolicitação de protesto

Instrução: due_date_extension — Prorrogação de Vencimento​

Request Body
{
  "occurrence_type": "due_date_extension",
  "occurrence_data": {
    "due_date": "2026-12-31"
  }
}

Objeto occurrence_data — due_date_extension​

CampoTipoDescriçãoCaracteres
due_datestringNova data de vencimento do boleto (formato YYYY-MM-DD)10

Instrução: delay_interest_update — Atualização de Juros de Mora​

Request Body
{
  "occurrence_type": "delay_interest_update",
  "occurrence_data": {
    "interest": {
      "method": "pre_fixed",
      "pre_fixed": {
        "monthly_rate": 0.015,
        "calendar_base": "calendar_360"
      }
    }
  }
}

Objeto occurrence_data — delay_interest_update​

CampoTipoDescrição
interestobjectConfiguração dos juros de mora (ver abaixo).

Objeto interest​

CampoTipoDescrição
methodstringMétodo de cálculo dos juros. Valor: pre_fixed
pre_fixedobjectParâmetros para o cálculo de juros pré-fixados (ver abaixo).

Objeto pre_fixed​

CampoTipoDescrição
monthly_ratenumberTaxa mensal de juros em decimal (0.015 = 1,5% ao mês).
calendar_basestringBase de calendário para cálculo. Enumerador calendar_base

Enumeradores calendar_base​

EnumeradorDescrição
calendar_360Base de 360 dias
workdaysDias úteis
calendar_365Base de 365 dias

Instrução: delay_fine_update — Atualização de Multa por Atraso​

Request Body
{
  "occurrence_type": "delay_fine_update",
  "occurrence_data": {
    "fine": {
      "fine_type": "percentage",
      "percentage_value": 2.0
    }
  }
}

Objeto occurrence_data — delay_fine_update​

CampoTipoDescrição
fineobjectConfiguração da multa por atraso (ver abaixo).

Objeto fine​

CampoTipoDescrição
fine_typestringTipo da multa. Valor: percentage
percentage_valuenumberPercentual da multa. Deve ser maior que 0.

Instrução: rebate — Abatimento​

Request Body
{
  "occurrence_type": "rebate",
  "occurrence_data": {
    "rebate": 50.00
  }
}

Objeto occurrence_data — rebate​

CampoTipoDescrição
rebatenumberValor do abatimento a ser aplicado.

Instrução: rebate_withdrawn — Cancelamento de Abatimento​

Esta instrução não requer occurrence_data.

Request Body
{
  "occurrence_type": "rebate_withdrawn"
}

Instrução: discount_inclusion — Inclusão de Descontos​

Request Body
{
  "occurrence_type": "discount_inclusion",
  "occurrence_data": {
    "discounts": [
      {
        "discount_type": "percentage",
        "discount_number": 1,
        "discount_limit_date": "2026-11-30",
        "discount_amount": 5.0
      }
    ]
  }
}

Objeto occurrence_data — discount_inclusion​

CampoTipoDescrição
discountsarrayLista de descontos a serem aplicados (ver abaixo).

Objeto discount (item do array discounts)​

CampoTipoDescriçãoCaracteres
discount_typestringTipo do desconto. Enumerador discount_type-
discount_numbernumberNúmero sequencial do desconto.-
discount_limit_datestringData limite para aplicação do desconto (formato YYYY-MM-DD).10
discount_amountnumberValor do desconto.-

Enumeradores discount_type​

EnumeradorDescrição
absoluteValor fixo
percentagePorcentagem fixa
anticipation_workdays_daily_amountValor diário de antecipação sobre dias úteis
anticipation_workdays_daily_percentagePorcentagem diária de antecipação sobre dias úteis
anticipation_calendar_days_daily_amountValor diário de antecipação sobre dias corridos
anticipation_calendar_days_daily_percentagePorcentagem diária de antecipação sobre dias corridos

Instrução: write_off — Baixa do Boleto​

Esta instrução não requer occurrence_data.

Request Body
{
  "occurrence_type": "write_off"
}

Instrução: protest_request — Solicitação de Protesto​

Request Body
{
  "occurrence_type": "protest_request",
  "occurrence_data": {
    "protest_type": "protest"
  }
}

Objeto occurrence_data — protest_request​

CampoTipoDescrição
protest_typestringTipo do protesto. Enumerador protest_type

Enumeradores protest_type​

EnumeradorDescrição
protestProtesto padrão
bankruptcy_protestProtesto por falência

Response​

STATUS
201
Response Body
Response Body
{
  "bankslip_key": "c9eb109c-800f-4cf5-b209-2119c9d77a72",
  "external_participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG",
  "bankslip_configuration": {
    "bankslip_configuration_key": "1b382eb7-7006-4389-975b-afa76b0ad7b4",
    "bankslip_profile": {
      "bankslip_profile_key": "5910d4a3-f5df-432a-902f-849a1a77cd86",
      "bankslip_profile_code": "329-09-0001-4993010",
      "bankslip_profile_number": 1,
      "bankslip_provider": "qi_scd",
      "additional_information": {
        "external_beneficiary_key": "2666e7a3-0bd7-46fc-8f6b-725f2ef9b13f"
      },
      "internal_account_key": "6b5335ed-1380-4348-9520-8998ca6e388b",
      "fund_class": {
        "fund_class_key": "7f03069e-1854-4cee-8e59-a6a548976015",
        "document_number": "11.222.333/0001-81",
        "name": "Sample Fund Class",
        "manager": {
          "name": "Sample Manager",
          "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153",
          "document_number": "11.222.333/0001-81"
        }
      }
    }
  },
  "due_date": "2026-12-31",
  "face_value": 629.33,
  "status": "registered",
  "participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG",
  "borrower": {
    "document_number": "969.698.790-03",
    "name": "Tomador Exemplo",
    "person_type": "natural_person",
    "address": {
      "postal_code": "05425-020"
    }
  },
  "assignor": {
    "name": "Cedente LTDA",
    "document_number": "33.444.555/0001-81",
    "person_type": "legal_person"
  },
  "bankslip_type": "simple_collection",
  "collection_type": "standard",
  "delay": null,
  "our_number": 12345,
  "our_number_digit": "6",
  "digitable_line": "32991.23456 78901.234567 89012.345678 9 00010000062933",
  "barcode": "32999000010000062933123456789012345678901234",
  "occurrences": [
    {
      "occurrence_key": "e9898e50-cd2b-492f-9201-7e5c5f231853",
      "status": "pending_submission",
      "type": "due_date_extension",
      "occurrence_data": {
        "due_date": "2026-12-31"
      }
    }
  ],
  "settlement_instructions": [
    {
      "settlement_instruction_key": "fe419363-bf04-4b3a-90bd-185618baa720",
      "status": "pending_bankslip_payment",
      "asset_type": "duplicata_mercantil",
      "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
      "issue_date": "2025-01-17",
      "maturity_date": "2026-12-31",
      "face_value": 629.33,
      "order_number": "49761-1"
    }
  ]
}

Bankslip​

CampoTipoDescrição
bankslip_keystringIdentificador único do boleto.
external_participant_control_numberstringNúmero de controle externo do participante.
bankslip_configurationobjectConfiguração do boleto (ver abaixo).
due_datedateData de vencimento do boleto.
face_valuenumberValor nominal do boleto.
statusstringStatus atual do boleto.
participant_control_numberstringNúmero de controle interno do participante.
borrowerobjectObjeto que representa o tomador (sacado).
assignorobjectObjeto que representa o cedente do recebível.
bankslip_typestringTipo do boleto: simple_collection ou non_vinculated.
collection_typestringModalidade de cobrança: standard ou qr_code_allowed.
delayobjectDados de mora do boleto, quando aplicável.
order_numberstringNúmero do pedido, quando disponível.
our_numbernumberNosso número, quando disponível.
our_number_digitstringDígito verificador do nosso número, quando disponível.
digitable_linestringLinha digitável do boleto, quando disponível.
barcodestringCódigo de barras do boleto, quando disponível.
occurrencesarrayLista de ocorrências relacionadas ao boleto (cada item é um objeto).
settlement_instructionsarrayLista de instruções de liquidação relacionadas ao boleto.

Bankslip Configuration​

CampoTipoDescrição
bankslip_configuration_keystringChave de configuração do boleto.
bankslip_profileobjectPerfil de boleto associado.

Bankslip Profile​

CampoTipoDescrição
bankslip_profile_keystringIdentificador do perfil de boleto.
bankslip_profile_codestringCódigo do perfil.
bankslip_profile_numbernumberNúmero do perfil.
bankslip_providerstringProvedor do boleto.
additional_informationobjectInformações adicionais do perfil.
internal_account_keystringIdentificador da conta interna associada.
fund_classobjectObjeto representando a classe de fundo (ver abaixo).

Fund Class​

CampoTipoDescriçãoCaracteres
fund_class_keystringChave única de identificação da classe de fundo36
document_numberstringCNPJ da classe de fundo-
namestringNome da classe de fundoaté 255

Borrower​

CampoTipoDescrição
namestringNome do tomador.
document_numberstringDocumento (CPF/CNPJ).
person_typestringTipo de pessoa.
addressobjectEndereço do tomador.

Assignor​

CampoTipoDescrição
namestringNome do cedente.
document_numberstringDocumento (CNPJ).
person_typestringTipo de pessoa.

Occurrences​

Cada item do array é um objeto com os seguintes campos:

CampoTipoDescrição
occurrence_keystringIdentificador da ocorrência.
statusstringStatus da ocorrência.
typestringTipo da ocorrência.
occurrence_dataobjectDados adicionais da ocorrência.

Settlement Instructions​

Cada item do array é um objeto com os seguintes campos:

CampoTipoDescrição
settlement_instruction_keystringIdentificador da instrução de liquidação.
statusstringStatus da instrução de liquidação.
asset_typestringTipo do ativo.
asset_keystringChave única do ativo no sistema.
issue_datedateData de emissão.
maturity_datedateData de vencimento.
face_valuenumberValor de face do ativo.
order_numberstringNúmero do contrato.

Erros​

StatusCódigoQuando acontece
404BSC000009O boleto não existe nesta configuração, ou não está em pending_registration ou registered.
400BSC000106O boleto não foi emitido pela QI Tech; instruções não são aceitas.
400BSC000115 / BSC000116due_date_extension com nova data no passado ou não posterior ao vencimento atual.
400BSC000123Instrução com valor zerado (por exemplo, monthly_rate ou percentage_value igual a 0).
404BSC000006A fund_class_key não existe.
403BSC000036O fundo não pertence ao seu perfil.
400QIT000001Corpo inválido para o occurrence_type informado.

Erros de autenticação, permissão e host: veja Erros da API.