Criar lote de instruções

Permite o envio, em uma única requisição, de múltiplas instruções de mesmo tipo (baixa, abatimento, prorrogação, protesto etc.) sobre boletos distintos. A QI Tech valida o lote inteiro e, ou todos os itens são aceitos, ou nenhum é processado.

• Se qualquer item falhar na validação semântica, nenhum item do lote é processado. A resposta de erro detalha, por item rejeitado, o motivo da rejeição.
• Se todos os itens passarem, as ocorrências são criadas e processadas individualmente, de forma assíncrona. O solicitante é notificado via webhook à medida que cada ocorrência muda de status.

Idempotência

A request_control_key do lote garante idempotência no nível do lote: reenviar a mesma chave retorna o lote já criado, sem duplicação.

Cada item do lote também possui sua própria request_control_key e é idempotente individualmente. Reenviar um item com request_control_key já existente faz o lote inteiro ser rejeitado.

Atenção!

Esta operação está disponível apenas para carteiras registradas na instituição registradora QI SCD.

Request

ENDPOINT

/v2/bank_slip/account/ACCOUNT_KEY/requester_profile/REQUESTER_PROFILE_KEY/occurrence_batches

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": "614a451d-3b82-460e-bcc0-2caf3dde711f",
  "occurrence_type": "extension",
  "items": [
    {
      "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5",
      "request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
      "new_due_date": "2026-08-15"
    },
    {
      "bank_slip_key": "5e3a1b2c-7d9f-4e88-9012-3a4b5c6d7e8f",
      "request_control_key": "b3a428fd-58ee-4d6f-8872-633874ebf5e2",
      "new_due_date": "2026-08-20"
    }
  ]
}

Request Body Params

Campo	Tipo	Descrição	Caracteres
request_control_key *	string	Chave única do lote, definida pelo cliente. Garante idempotência do lote	1–64
occurrence_type *	string	Tipo de instrução aplicada a todos os itens. Veja Enumeradores occurrence_type	-
items *	Array de Objeto item	Lista de instruções (mínimo 1, máximo 10000)	-

Enumeradores occurrence_type

Enumerador	Descrição
extension	Prorrogação de vencimento — requer new_due_date no item
rebate	Concessão de abatimento — requer rebate_amount no item
cancel_rebate	Cancelamento de abatimento
write_off	Baixa do boleto
protest_request	Pedido de protesto
protest_cancel_request	Desistência (sustação) do pedido de protesto
protest_remove_request	Remoção (cancelamento) do protesto

Objeto item

Campo	Tipo	Descrição	Caracteres
bank_slip_key *	uuidv4	Chave do boleto sobre o qual a instrução será aplicada	36
request_control_key *	string	Chave única do item, definida pelo cliente. Garante idempotência por item	1–64
new_due_date	string	Nova data de vencimento (YYYY-MM-DD). Obrigatório para occurrence_type=extension	10
rebate_amount	float	Valor de abatimento. Obrigatório para occurrence_type=rebate	-

Response

STATUS

201

Response Body

{
  "batch_key": "f2d3e1b9-4a5c-46e7-8f12-9a8b7c6d5e4f",
  "occurrence_quantity": 2,
  "accepted_quantity": 2,
  "semantic_errors": []
}

Response Body Params

Campo	Tipo	Descrição	Caracteres
batch_key *	uuidv4	Chave única do lote. Utilize para consultar o detalhe do lote	36
occurrence_quantity *	integer	Quantidade total de itens enviados no lote	-
accepted_quantity *	integer	Quantidade de itens aceitos no lote	-
semantic_errors *	array	Lista vazia em caso de sucesso. Em caso de rejeição semântica, ver Error Response	-

Error Response

STATUS

4xx

Response Body: Error

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

Em caso de rejeição semântica (BLP000112), o campo reasons da resposta detalha cada item rejeitado:

Response Body: Rejeição semântica

{
  "title": "Unprocessable Entity",
  "description": "Rejected Remittance",
  "translation": "Remessa Rejeitada",
  "code": "BLP000112",
  "reasons": [
    {
      "occurrence_sequence": "0",
      "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5",
      "request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
      "errors": [
        {
          "reason_code": "15",
          "translation_pt_br": "Boleto não encontrado",
          "translation_en_us": "Bank slip not found",
          "created_at": "2026-06-09T17:08:33"
        }
      ]
    }
  ]
}

Campos do objeto reasons[]

Campo	Tipo	Descrição
occurrence_sequence *	string	Posição do item no array items da requisição (começando em "0")
bank_slip_key *	uuidv4	Chave do boleto do item rejeitado
request_control_key *	string	Chave de controle informada pelo cliente para o item
errors *	array	Lista de motivos da rejeição (um item pode ter múltiplos motivos)
errors[].reason_code *	string	Código do motivo de rejeição (padrão Febraban)
errors[].translation_pt_br	string	Descrição em português do motivo
errors[].translation_en_us	string	Descrição em inglês do motivo
errors[].created_at	string	Data/hora de cadastro do motivo no catálogo

Códigos de erro

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
400	BKS000141	Bad Request	Bank slip registration is restricted to QI SCD.	Registro de boleto permitido apenas para QI SCD.
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>
422	BLP000112	Unprocessable Entity	Rejected Remittance	Remessa Rejeitada