Skip to main content

Bankslip Instructions

This endpoint allows you to send instructions to an already registered bankslip, such as a due date extension, an update of interest and fine, the inclusion of discounts, a rebate, a write-off and a protest request.

Available on
ProfileHostRequired permission
Managermanager-apiRead and write
Consultantconsultant-apiGranted by the integration team

Base URL for each host: Environments (Hosts).

Which bankslips accept instructions

Only bankslips in pending_registration or registered, issued by QI Tech (configuration with issuer type internal; see bankslip configurations), accept instructions. For the others, the API returns BSC000009 (bankslip outside these statuses) or BSC000106 (another issuer).

Request​

ENDPOINT
/bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_configuration/BANKSLIP_CONFIGURATION_KEY/bankslip/BANKSLIP_KEY
METHOD
PUT

Path Parameters​

FieldTypeDescriptionCharacters
fund_class_keyuuidv4Unique identification key of the fund class, in the uuid v4 format36
bankslip_configuration_keyuuidv4Unique identification key of the bankslip configuration, in the uuid v4 format36
bankslip_keyuuidv4Unique identification key of the bankslip, in the uuid v4 format36

Request Body Params​

The occurrence_type field defines which instruction will be sent to the bankslip. The occurrence_data field contains the specific data of the instruction, when applicable.

FieldTypeDescriptionCharacters
occurrence_typestringType of the instruction to be sent to the bankslip.occurrence_type enumerators
occurrence_dataobjectData of the instruction. Required for the types that need extra parameters.Varies according to the occurrence_type

occurrence_type enumerators​

EnumeratorDescription
due_date_extensionExtension of the due date
delay_interest_updateUpdate of the late payment interest
delay_fine_updateUpdate of the late payment fine
rebateApplication of a rebate
rebate_withdrawnCancellation of the rebate
discount_inclusionInclusion of discounts
write_offWrite-off of the bankslip
protest_requestProtest request

Instruction: due_date_extension — Due Date Extension​

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

occurrence_data object — due_date_extension​

FieldTypeDescriptionCharacters
due_datestringNew due date of the bankslip (YYYY-MM-DD format)10

Instruction: delay_interest_update — Late Payment Interest Update​

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

occurrence_data object — delay_interest_update​

FieldTypeDescription
interestobjectConfiguration of the late payment interest (see below).

interest object​

FieldTypeDescription
methodstringInterest calculation method. Value: pre_fixed
pre_fixedobjectParameters for the pre-fixed interest calculation (see below).

pre_fixed object​

FieldTypeDescription
monthly_ratenumberMonthly interest rate as a decimal (0.015 = 1.5% per month).
calendar_basestringCalendar base for the calculation. calendar_base enumerators

calendar_base enumerators​

EnumeratorDescription
calendar_360360-day base
workdaysBusiness days
calendar_365365-day base

Instruction: delay_fine_update — Late Payment Fine Update​

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

occurrence_data object — delay_fine_update​

FieldTypeDescription
fineobjectConfiguration of the late payment fine (see below).

fine object​

FieldTypeDescription
fine_typestringFine type. Value: percentage
percentage_valuenumberPercentage of the fine. It must be greater than 0.

Instruction: rebate — Rebate​

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

occurrence_data object — rebate​

FieldTypeDescription
rebatenumberValue of the rebate to be applied.

Instruction: rebate_withdrawn — Rebate Cancellation​

This instruction does not require occurrence_data.

Request Body
{
  "occurrence_type": "rebate_withdrawn"
}

Instruction: discount_inclusion — Inclusion of Discounts​

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

occurrence_data object — discount_inclusion​

FieldTypeDescription
discountsarrayList of discounts to be applied (see below).

discount object (item of the discounts array)​

FieldTypeDescriptionCharacters
discount_typestringDiscount type. discount_type enumerators-
discount_numbernumberSequential number of the discount.-
discount_limit_datestringLimit date for the application of the discount (YYYY-MM-DD format).10
discount_amountnumberValue of the discount.-

discount_type enumerators​

EnumeratorDescription
absoluteFixed value
percentageFixed percentage
anticipation_workdays_daily_amountDaily anticipation value over business days
anticipation_workdays_daily_percentageDaily anticipation percentage over business days
anticipation_calendar_days_daily_amountDaily anticipation value over calendar days
anticipation_calendar_days_daily_percentageDaily anticipation percentage over calendar days

Instruction: write_off — Bankslip Write-Off​

This instruction does not require occurrence_data.

Request Body
{
  "occurrence_type": "write_off"
}

Instruction: protest_request — Protest Request​

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

occurrence_data object — protest_request​

FieldTypeDescription
protest_typestringProtest type. protest_type enumerators

protest_type enumerators​

EnumeratorDescription
protestStandard protest
bankruptcy_protestBankruptcy protest

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​

FieldTypeDescription
bankslip_keystringUnique identifier of the bankslip.
external_participant_control_numberstringExternal control number of the participant.
bankslip_configurationobjectConfiguration of the bankslip (see below).
due_datedateDue date of the bankslip.
face_valuenumberNominal value of the bankslip.
statusstringCurrent status of the bankslip.
participant_control_numberstringInternal control number of the participant.
borrowerobjectObject representing the drawee (borrower).
assignorobjectObject representing the assignor of the receivable.
bankslip_typestringBankslip type: simple_collection or non_vinculated.
collection_typestringCollection type: standard or qr_code_allowed.
delayobjectLate payment data of the bankslip, when applicable.
order_numberstringOrder number, when available.
our_numbernumber"Nosso número", when available.
our_number_digitstringCheck digit of the "nosso número", when available.
digitable_linestringDigitable line of the bankslip, when available.
barcodestringBarcode of the bankslip, when available.
occurrencesarrayList of occurrences related to the bankslip (each item is an object).
settlement_instructionsarrayList of settlement instructions related to the bankslip.

Bankslip Configuration​

FieldTypeDescription
bankslip_configuration_keystringConfiguration key of the bankslip.
bankslip_profileobjectAssociated bankslip profile.

Bankslip Profile​

FieldTypeDescription
bankslip_profile_keystringIdentifier of the bankslip profile.
bankslip_profile_codestringCode of the profile.
bankslip_profile_numbernumberNumber of the profile.
bankslip_providerstringProvider of the bankslip.
additional_informationobjectAdditional information of the profile.
internal_account_keystringIdentifier of the associated internal account.
fund_classobjectObject representing the fund class (see below).

Fund Class​

FieldTypeDescriptionCharacters
fund_class_keystringUnique identification key of the fund class36
document_numberstringCNPJ of the fund class-
namestringName of the fund classup to 255

Borrower​

FieldTypeDescription
namestringName of the drawee.
document_numberstringDocument (CPF/CNPJ).
person_typestringPerson type.
addressobjectAddress of the drawee.

Assignor​

FieldTypeDescription
namestringName of the assignor.
document_numberstringDocument (CNPJ).
person_typestringPerson type.

Occurrences​

Each item of the array is an object with the following fields:

FieldTypeDescription
occurrence_keystringIdentifier of the occurrence.
statusstringStatus of the occurrence.
typestringType of the occurrence.
occurrence_dataobjectAdditional data of the occurrence.

Settlement Instructions​

Each item of the array is an object with the following fields:

FieldTypeDescription
settlement_instruction_keystringIdentifier of the settlement instruction.
statusstringStatus of the settlement instruction.
asset_typestringAsset type.
asset_keystringUnique key of the asset in the system.
issue_datedateIssue date.
maturity_datedateMaturity date.
face_valuenumberFace value of the asset.
order_numberstringContract number.

Errors​

StatusCodeWhen it happens
404BSC000009The bankslip does not exist in this configuration, or is not in pending_registration or registered.
400BSC000106The bankslip was not issued by QI Tech; instructions are not accepted.
400BSC000115 / BSC000116due_date_extension with a new date in the past or not later than the current due date.
400BSC000123Instruction with a zero value (for example, monthly_rate or percentage_value equal to 0).
404BSC000006The fund_class_key does not exist.
403BSC000036The fund does not belong to your profile.
400QIT000001Invalid body for the given occurrence_type.

Authentication, permission and host errors: see API errors.