# QI Tech — Banking-as-a-Service › Boletos
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
57 página(s).
Índice:
- 创建钱包 (/zh-Hans/documentation/boletos/carteira/criar_carteira)
- 编辑钱包 (/zh-Hans/documentation/boletos/carteira/editar_carteira)
- 列出账户钱包 (/zh-Hans/documentation/boletos/carteira/listar_carteiras)
- 查询临时文件 (/zh-Hans/documentation/boletos/cnab/consulta_por_chave)
- 汇款文件（CNAB）- 简介 (/zh-Hans/documentation/boletos/cnab/introducao)
- 列出临时汇款文件 (/zh-Hans/documentation/boletos/cnab/listar_arquivos_temporarios)
- 列出临时记录 (/zh-Hans/documentation/boletos/cnab/listar_ocorrencias_temporarias)
- 上传汇款文件（CNAB） (/zh-Hans/documentation/boletos/cnab/upload_de_arquivo_remessa)
- 通过密钥查询 Boleto (/zh-Hans/documentation/boletos/consulta/consulta_por_chave)
- Boleto 列表查询 (/zh-Hans/documentation/boletos/consulta/listar_boletos)
- Excel 格式日常仓位报告 (/zh-Hans/documentation/boletos/consultar_v1/posicao_diaria_excel)
- JSON 格式日常仓位报告 (/zh-Hans/documentation/boletos/consultar_v1/posicao_diaria_json)
- 申请票据补发 (/zh-Hans/documentation/boletos/consultar_v1/segunda_via_de_boleto)
- 单张 Boleto 发行（即时） (/zh-Hans/documentation/boletos/emissao/emissao_boleto_unico_instantanea)
- 单张 Boleto 发行（标准） (/zh-Hans/documentation/boletos/emissao/emissao_boleto_unico_padrao)
- 批量 Boleto 发行 (/zh-Hans/documentation/boletos/emissao/emissao_em_lote)
- 取消折让 (/zh-Hans/documentation/boletos/instrucoes/abatimento/cancelar_abatimento)
- 创建折让 (/zh-Hans/documentation/boletos/instrucoes/abatimento/criar_abatimento)
- 注销 (/zh-Hans/documentation/boletos/instrucoes/baixa)
- 折扣 (/zh-Hans/documentation/boletos/instrucoes/desconto)
- 编辑 (/zh-Hans/documentation/boletos/instrucoes/edicao)
- 延期 (/zh-Hans/documentation/boletos/instrucoes/extensao)
- 利息 (/zh-Hans/documentation/boletos/instrucoes/juros)
- 查询指令批次 (/zh-Hans/documentation/boletos/instrucoes/lote/consultar_lote_de_instrucoes)
- 创建指令批次 (/zh-Hans/documentation/boletos/instrucoes/lote/criar_lote_de_instrucoes)
- 列出指令批次 (/zh-Hans/documentation/boletos/instrucoes/lote/listar_lotes_de_instrucoes)
- 罚款 (/zh-Hans/documentation/boletos/instrucoes/multa)
- 部分付款 (/zh-Hans/documentation/boletos/instrucoes/pagamento_parcial)
- 查询抗议工具文件 (/zh-Hans/documentation/boletos/instrucoes/protesto/consulta_instrumento_de_protesto)
- 通过键查询抗议 (/zh-Hans/documentation/boletos/instrucoes/protesto/consulta_por_chave)
- 撤回（中止）抗议 (/zh-Hans/documentation/boletos/instrucoes/protesto/desistencia_de_protesto)
- 撤回（中止）抗议并核销票据 (/zh-Hans/documentation/boletos/instrucoes/protesto/desistencia_de_protesto_e_baixa_do_boleto)
- 简介 (/zh-Hans/documentation/boletos/instrucoes/protesto/introducao)
- 列出抗议 (/zh-Hans/documentation/boletos/instrucoes/protesto/listar_protestos)
- 抗议申请 (/zh-Hans/documentation/boletos/instrucoes/protesto/pedido_de_protesto)
- 撤销抗议 (/zh-Hans/documentation/boletos/instrucoes/protesto/sustacao_de_protesto)
- 信用分账更新 (/zh-Hans/documentation/boletos/instrucoes/rateio_de_credito)
- 金额 (/zh-Hans/documentation/boletos/instrucoes/valor)
- 简介 (/zh-Hans/documentation/boletos/introducao)
- 列出清算组 (/zh-Hans/documentation/boletos/liquidacao/listar_grupos_de_liquidacao)
- 列出清算记录 (/zh-Hans/documentation/boletos/liquidacao/listar_liquidacoes)
- 清算场景模拟 (/zh-Hans/documentation/boletos/liquidacao/simulacao_de_cenarios_de_liquidacao)
- 列出返回文件 (/zh-Hans/documentation/boletos/retorno/listar_arquivos_retorno)
- Boleto Webhooks (/zh-Hans/documentation/boletos/webhooks/boleto)
- 票据钱包 Webhooks (/zh-Hans/documentation/boletos/webhooks/carteira)
- 清算 Webhooks (/zh-Hans/documentation/boletos/webhooks/liquidacao)
- 返回文件 Webhooks (/zh-Hans/documentation/boletos/webhooks/retorno)
- 开启票据 tombamento 批次 (/zh-Hans/documentation/troca_de_titularidade/abrir_lote)
- 批准票据 tombamento 批次 (/zh-Hans/documentation/troca_de_titularidade/aprovar_lote)
- 取消票据 tombamento 批次 (/zh-Hans/documentation/troca_de_titularidade/cancelar_lote)
- 将票据加入 tombamento 批次 (/zh-Hans/documentation/troca_de_titularidade/incluir_boletos)
- 简介 (/zh-Hans/documentation/troca_de_titularidade/introducao)
- 列出 tombamento 批次中的票据 (/zh-Hans/documentation/troca_de_titularidade/listar_boletos_lote)
- 列出票据 tombamento 批次 - 目标方 (/zh-Hans/documentation/troca_de_titularidade/listar_lotes_destino)
- 列出票据 tombamento 批次 - 来源方 (/zh-Hans/documentation/troca_de_titularidade/listar_lotes_origem)
- 从 tombamento 批次中移除票据 (/zh-Hans/documentation/troca_de_titularidade/remover_boletos)
- 发送票据 tombamento 批次 (/zh-Hans/documentation/troca_de_titularidade/validar_lote_e_enviar)
---
# 创建钱包
URL: /zh-Hans/documentation/boletos/carteira/criar_carteira
:::danger 重要
要登记 bolePix，账户中必须存在一个有效的随机 PIX 密钥，票据将在该账户中登记。
:::
票据钱包具有唯一识别码（`requester_profile_code`）以及票据支付、核销、抗议等特定默认配置。同一账户可拥有多个票据钱包，允许用户创建具有不同默认配置的多个钱包。这种机制简化了票据的生成，使不同配置的票据可以更快速、自动地生成。
:::info 信息
所有账户在创建时都会自动生成一个带有客户默认配置的票据钱包。该默认配置可通过联系我们的支持团队（suporte.baas@qitech.com.br）进行更改。账户创建后，也可以使用[**费率配置端点**](/documentation/contas/consulta_de_tarifas)修改账户费率。
:::
:::caution 注意！
钱包创建是异步流程。在 CIP/Núclea 批准或拒绝钱包创建后，申请人将通过 [**webhook**](/documentation/boletos/v2/webhooks/carteira) 收到相关结果通知。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile
MÉTODO POST
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
Request Body
```json
{
"request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
"configuration_data": {
"max_payment_days": 1,
"protest_settings": {
"days_to_protest": 0
},
"bankruptcy_protest_settings": {
"days_to_bankruptcy_protest": 0
},
"write_off_settings": {
"days_to_write_off": 0
},
"fine_settings": {
"fine_type": "absolute",
"fine_amount": 10,
"days_to_fine": 0
},
"interest_settings": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10,
"days_to_interest": 0
},
"qr_code_settings": {
"pix_key": "5df7a433-bd61-4f98-9515-df9aedc2980c",
"qr_code_on_discharge_enabled": false
},
"cnab_settings": {
"default_bank": "qi_scd",
"preferred_layout": "400"
}
}
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `configuration_data` * | object | 钱包默认配置 | **[Objeto configuration_data](#objeto-configuration_data)** |
### Objeto configuration_data
| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|------------------------------------------------------------------------------|--------|
| `max_payment_days` * | integer | 票据到期后可供付款的最大日历天数（最多 365 天） | - |
| `write_off_settings` | object | 默认核销配置 | **[Objeto write_off_settings](#objeto-write_off_settings)** |
| `protest_settings` | object | 默认抗议配置 | **[Objeto protest_settings](#objeto-protest_settings)** |
| `bankruptcy_protest_settings` | object | 默认破产抗议配置 | **[Objeto bankruptcy_protest_settings](#objeto-bankruptcy_protest_settings)** |
| `fine_settings` | object | 默认罚款配置 | **[Objeto fine_setings](#objeto-fine_settings)** |
| `interest_settings` | object | 默认利息配置 | **[Objeto interest_settings](#objeto-interest_settings)** |
| `qr_code_settings` | object | PIX QR Code 默认配置（用于 bolePix） | **[Objeto qr_code_settings](#objeto-qr_code_settings)** |
| `cnab_settings` | object | CNAB 文件默认配置 | **[Objeto cnab_settings](#objeto-cnab_settings)** |
### Objeto write_off_settings
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_write_off` * | integer | 到期后自动核销票据的天数 | - |
### Objeto protest_settings
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_protest` * | integer | 到期后自动抗议票据的天数 | - |
### Objeto bankruptcy_protest_settings
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------------|---------|---------------------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | 到期后自动启动破产抗议流程的天数 | - |
### Objeto fine_settings
选项 1：绝对值罚款（`fine_type=absolute`）
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|-----------------------------------------------|----------------------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_amount` * | float | 罚款绝对值 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
选项 2：百分比罚款（`fine_type=percentage`）
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|-----------------------------------------------|-------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | 罚款百分比值，1 到 100 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
### Enumeradores fine_type
| 枚举值 | 描述 |
|--------------------|------------------|
| absolute | 绝对值 |
| percentage | 百分比值 |
### Objeto interest_settings
选项 1：使用绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|---------------------------------------------------------------|------------------------------------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` * | float | 按指定时间单位（工作日或日历日）收取的金额 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
选项 2：使用百分比利息（`interest_type=calendar_days_monthly_percentage`）
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|---------|---------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | 按指定时间单位（工作日或日历日）收取的百分比 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
### Enumeradores interest_type
| 枚举值 | 描述 |
|------------------------------------|-----------------------------------------------|
| calendar_days_daily_amount | 基于日历日的每日金额 |
| workdays_daily_amount | 基于工作日的每日金额 |
| calendar_days_monthly_percentage | 基于日历日按月收取的利息百分比 |
### Objeto qr_code_settings
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `pix_key` * | uuidv4 | 随机类型的 PIX 密钥 | 36 |
| `qr_code_on_discharge_enabled` * | boolean | 确定 QR Code 信息是否包含在退款文件（CNAB）中 | - |
:::info 信息
PIX 复制粘贴将在 CNAB 文件的第 029 至 105 位置返回。
:::
:::caution 注意！
若在请求中发送 `qr_code_settings` 对象，该钱包将以生成 bolePix 作为 默认配置 。bolePix 是一种支付与 PIX QR Code 绑定的票据。因此，付款人可以通过票据的可输入行或扫描绑定的 PIX QR Code 进行支付。若通过 QR Code 支付，财务清算将即时完成。关于通知，将发送两个 webhook：一个在 PIX 转账时（支付通知，票据转为 `payment_notice` 状态）；另一个在 CIP/Núclea 确认核销后几秒或几分钟后（已支付，票据转为 `paid` 状态）。
:::
### Objeto cnab_settings
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `default_bank` | string | 处理 CNAB 文件的默认银行布局 | **[Enumeradores default_bank](#enumeradores-default_bank)** |
| `preferred_layout` | string | CNAB 文件首选布局 | **[Enumeradores preferred_layout](#enumeradores-preferred_layout)** |
### Enumeradores default_bank
| 枚举值 | 描述 |
|--------------------|------------------|
| santander | Banco Santander |
| itau | Banco Itaú |
| bradesco | Banco Bradesco |
| qi_scd | QI SCD |
### Enumeradores preferred_layout
| 枚举值 | 描述 |
|--------------------|------------------|
| 400 | CNAB 400 布局 |
| 240 | CNAB 240 布局 |
## Response
STATUS 202
Response Body
```json
{
"requester_profile_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
"requester_profile_code": "329-04-2338-2625918",
"request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
"account_key": "0494902f-b21c-4ae6-b37e-854cfe883402",
"requester_profile_status": "pending",
"configuration_data": {
"max_payment_days": 1,
"protest_settings": {
"days_to_protest": 0
},
"bankruptcy_protest_settings": {
"days_to_bankruptcy_protest": 0
},
"write_off_settings": {
"days_to_write_off": 0
},
"fine_settings": {
"fine_type": "absolute",
"fine_amount": 10,
"days_to_fine": 0
},
"interest_settings": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10,
"days_to_interest": 0
},
"qr_code_settings": {
"pix_key": "5df7a433-bd61-4f98-9515-df9aedc2980c",
"qr_code_on_discharge_enabled": false
},
"cnab_settings": {
"default_bank": "qi_scd",
"preferred_layout": "400"
}
}
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|---------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` * | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_code` * | string | 钱包唯一识别码 | 19 |
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `account_key` * | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_status` * | string | 钱包状态 | **[Enumeradores requester_profile_status](#enumeradores-requester_profile_status)** |
| `configuration_data` * | object | 钱包默认配置 | **[Objeto configuration_data](#objeto-configuration_data)** |
### Enumeradores profile_status
| 枚举值 | 描述 |
|------------------------------------|-----------------------------------------------|
| pending | 钱包已接受，等待确认 |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000001 | Not Found | Person not found with key: {`person_key`}` | Pessoa não encontrada com a chave: {`person_key`}` |
| 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. |
| 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 | 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. |
---
# 编辑钱包
URL: /zh-Hans/documentation/boletos/carteira/editar_carteira
编辑钱包将覆盖票据钱包的默认配置（`configuration_data`）及其所有子对象。
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY
MÉTODO PUT
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
Request Body
```json
{
"max_payment_days": 1,
"protest_settings": {
"days_to_protest": 0
},
"bankruptcy_protest_settings": {
"days_to_bankruptcy_protest": 0
},
"write_off_settings": {
"days_to_write_off": 0
},
"fine_settings": {
"fine_type": "absolute",
"fine_amount": 10,
"days_to_fine": 0
},
"interest_settings": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10,
"days_to_interest": 0
},
"qr_code_settings": {
"pix_key": "248ebea3-9bdd-44b3-a8b9-7f2bd34cd7bf",
"qr_code_on_discharge_enabled": false
},
"cnab_settings": {
"default_bank": "qi_scd",
"preferred_layout": "400"
}
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|------------------------------------------------------------------------------|--------|
| `max_payment_days` * | integer | 票据到期后可供付款的最大日历天数（最多 365 天） | - |
| `write_off_settings` | object | 默认核销配置 | **[Objeto write_off_settings](#objeto-write_off_settings)** |
| `protest_settings` | object | 默认抗议配置 | **[Objeto protest_settings](#objeto-protest_settings)** |
| `bankruptcy_protest_settings` | object | 默认破产抗议配置 | **[Objeto bankruptcy_protest_settings](#objeto-bankruptcy_protest_settings)** |
| `fine_settings` | object | 默认罚款配置 | **[Objeto fine_setings](#objeto-fine_settings)** |
| `interest_settings` | object | 默认利息配置 | **[Objeto interest_settings](#objeto-interest_settings)** |
| `qr_code_settings` | object | PIX QR Code 默认配置（用于 bolePix） | **[Objeto qr_code_settings](#objeto-qr_code_settings)** |
| `cnab_settings` | object | CNAB 文件默认配置 | **[Objeto cnab_settings](#objeto-cnab_settings)** |
### Objeto write_off_settings
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_write_off` * | integer | 到期后自动核销票据的天数 | - |
### Objeto protest_settings
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_protest` * | integer | 到期后自动抗议票据的天数 | - |
### Objeto bankruptcy_protest_settings
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------------|---------|---------------------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | 到期后自动启动破产抗议流程的天数 | - |
### Objeto fine_settings
选项 1：绝对值罚款（`fine_type=absolute`）
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|-----------------------------------------------|----------------------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_amount` * | float | 罚款绝对值 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
选项 2：百分比罚款（`fine_type=percentage`）
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|-----------------------------------------------|-------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | 罚款百分比值，1 到 100 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
### Enumeradores fine_type
| 枚举值 | 描述 |
|--------------------|------------------|
| absolute | 绝对值 |
| percentage | 百分比值 |
### Objeto interest_settings
选项 1：使用绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|---------------------------------------------------------------|------------------------------------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` * | float | 按指定时间单位（工作日或日历日）收取的金额 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
选项 2：使用百分比利息（`interest_type=calendar_days_monthly_percentage`）
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|---------|---------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | 按指定时间单位（工作日或日历日）收取的百分比 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
### Enumeradores interest_type
| 枚举值 | 描述 |
|------------------------------------|-----------------------------------------------|
| calendar_days_daily_amount | 基于日历日的每日金额 |
| workdays_daily_amount | 基于工作日的每日金额 |
| calendar_days_monthly_percentage | 基于日历日按月收取的利息百分比 |
### Objeto qr_code_settings
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `pix_key` * | uuidv4 | 随机类型的 PIX 密钥 | 36 |
| `qr_code_on_discharge_enabled` * | boolean | 确定 QR Code 信息是否包含在退款文件（CNAB）中 | - |
:::info 信息
PIX 复制粘贴将在 CNAB 文件的第 029 至 105 位置返回。
:::
:::caution 注意！
若在请求中发送 `qr_code_settings` 对象，该钱包将以生成 bolePix 作为 默认配置 。bolePix 是一种支付与 PIX QR Code 绑定的票据。因此，付款人可以通过票据的可输入行或扫描绑定的 PIX QR Code 进行支付。若通过 QR Code 支付，财务清算将即时完成。关于通知，将发送两个 webhook：一个在 PIX 转账时（支付通知，票据转为 `payment_notice` 状态）；另一个在 CIP/Núclea 确认核销后几秒或几分钟后（已支付，票据转为 `paid` 状态）。
:::
### Objeto cnab_settings
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `default_bank` | string | 处理 CNAB 文件的默认银行布局 | **[Enumeradores default_bank](#enumeradores-default_bank)** |
| `preferred_layout` | string | CNAB 文件首选布局 | **[Enumeradores preferred_layout](#enumeradores-preferred_layout)** |
### Enumeradores default_bank
| 枚举值 | 描述 |
|--------------------|------------------|
| santander | Banco Santander |
| itau | Banco Itaú |
| bradesco | Banco Bradesco |
| qi_scd | QI SCD |
### Enumeradores preferred_layout
| 枚举值 | 描述 |
|--------------------|------------------|
| 400 | CNAB 400 布局 |
| 240 | CNAB 240 布局 |
## Response
STATUS 200
Response Body
```json
{
"requester_profile_key": "c92e8666-e310-4a72-b15e-753525684ae2",
"requester_profile_code": "329-48-2628-2625918",
"request_control_key": "727a5f00-1f86-4a7a-9aa5-c45cf8a2394c",
"account_key": "e0089187-ab08-42c0-82f2-259d40726117",
"requester_profile_status": "pending",
"configuration_data": {
"max_payment_days": 1,
"protest_settings": {
"days_to_protest": 0
},
"bankruptcy_protest_settings": {
"days_to_bankruptcy_protest": 0
},
"write_off_settings": {
"days_to_write_off": 0
},
"fine_settings": {
"fine_type": "absolute",
"fine_amount": 10,
"days_to_fine": 0
},
"interest_settings": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10,
"days_to_interest": 0
},
"qr_code_settings": {
"pix_key": "248ebea3-9bdd-44b3-a8b9-7f2bd34cd7bf",
"qr_code_on_discharge_enabled": false
},
"cnab_settings": {
"default_bank": "qi_scd",
"preferred_layout": "400"
}
}
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|---------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` * | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_code` * | string | 钱包唯一识别码 | 19 |
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `account_key` * | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_status` * | string | 钱包状态 | **[Enumeradores requester_profile_status](#enumeradores-requester_profile_status)** |
| `configuration_data` * | object | 钱包默认配置 | **[Objeto configuration_data](#objeto-configuration_data)** |
### Enumeradores profile_status
| 枚举值 | 描述 |
|------------------------------------|-----------------------------------------------|
| pending | 钱包已接受，等待确认 |
| opened | 钱包已开启 |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000001 | Not Found | Person not found with key: {`person_key`}` | Pessoa não encontrada com a chave: {`person_key`}` |
| 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. |
| 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 | 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. |
---
# 列出账户钱包
URL: /zh-Hans/documentation/boletos/carteira/listar_carteiras
钱包列表将返回符合请求中发送的 查询参数 的所有账户票据钱包。
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profiles
MÉTODO GET
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
### Query parameters
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|---------------------------------------------------------------------|--------|
| `request_control_key` | uuidv4 | 请求唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 票据钱包唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_code` | string | 钱包唯一识别码 | 19 |
| `page` | integer| 页码 | - |
| `page_size` | integer| 每页大小 | - |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"requester_profile_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
"requester_profile_code": "329-04-2338-2625918",
"request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
"account_key": "0494902f-b21c-4ae6-b37e-854cfe883402",
"requester_profile_status": "pending",
"configuration_data": {
"max_payment_days": 1,
"protest_settings": {
"days_to_protest": 0
},
"bankruptcy_protest_settings": {
"days_to_bankruptcy_protest": 0
},
"write_off_settings": {
"days_to_write_off": 0
},
"fine_settings": {
"fine_type": "absolute",
"fine_amount": 10,
"days_to_fine": 0
},
"interest_settings": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10,
"days_to_interest": 0
},
"qr_code_settings": {
"pix_key": "5df7a433-bd61-4f98-9515-df9aedc2980c",
"qr_code_on_discharge_enabled": false
},
"cnab_settings": {
"default_bank": "qi_scd",
"preferred_layout": "400"
}
}
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Parameters
| 字段 | 类型 | 描述 | 字符数 |
|----------------|--------------|--------------------------|-----------------------------------------------------------|
| `data` * | object array | 票据钱包列表 | **[Objeto requester_profile](#objeto-requester_profile)** |
| `pagination` * | object | 分页信息 | **[Objeto pagination](#objeto-pagination)** |
### Objeto requester_profile
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|---------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` * | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_code` * | string | 钱包唯一识别码 | 19 |
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `account_key` * | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_status` * | string | 钱包状态 | **[Enumeradores requester_profile_status](#enumeradores-requester_profile_status)** |
| `configuration_data` * | object | 钱包默认配置 | **[Objeto configuration_data](#objeto-configuration_data)** |
### Enumeradores requester_profile_status
| 枚举值 | 描述 |
|------------------------------------|-----------------------------------------------|
| pending | 钱包已接受，等待确认 |
| opened | 钱包已开启 |
### Objeto pagination
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|----------------------------|--------|
| `current_page` * | integer | 当前页码 | - |
| `rows_per_page` * | integer | 每页记录数 | - |
### Objeto configuration_data
| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|---------|------------------------------------------------------------------------------|--------|
| `max_payment_days` * | integer | 票据到期后可供付款的最大日历天数（最多 365 天） | - |
| `write_off_settings` | object | 默认核销配置 | **[Objeto write_off_settings](#objeto-write_off_settings)** |
| `protest_settings` | object | 默认抗议配置 | **[Objeto protest_settings](#objeto-protest_settings)** |
| `bankruptcy_protest_settings` | object | 默认破产抗议配置 | **[Objeto bankruptcy_protest_settings](#objeto-bankruptcy_protest_settings)** |
| `fine_settings` | object | 默认罚款配置 | **[Objeto fine_setings](#objeto-fine_settings)** |
| `interest_settings` | object | 默认利息配置 | **[Objeto interest_settings](#objeto-interest_settings)** |
| `qr_code_settings` | object | PIX QR Code 默认配置（用于 bolePix） | **[Objeto qr_code_settings](#objeto-qr_code_settings)** |
| `cnab_settings` | object | CNAB 文件默认配置 | **[Objeto cnab_settings](#objeto-cnab_settings)** |
### Objeto write_off_settings
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_write_off` * | integer | 到期后自动核销票据的天数 | - |
### Objeto protest_settings
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_protest` * | integer | 到期后自动抗议票据的天数 | - |
### Objeto bankruptcy_protest_settings
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------------|---------|---------------------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | 到期后自动启动破产抗议流程的天数 | - |
### Objeto fine_settings
选项 1：绝对值罚款（`fine_type=absolute`）
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|-----------------------------------------------|----------------------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_amount` * | float | 罚款绝对值 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
选项 2：百分比罚款（`fine_type=percentage`）
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|-----------------------------------------------|-------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | 罚款百分比值，1 到 100 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
### Enumeradores fine_type
| 枚举值 | 描述 |
|--------------------|------------------|
| absolute | 绝对值 |
| percentage | 百分比值 |
### Objeto interest_settings
选项 1：使用绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|---------------------------------------------------------------|------------------------------------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` * | float | 按指定时间单位（工作日或日历日）收取的金额 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
选项 2：使用百分比利息（`interest_type=calendar_days_monthly_percentage`）
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|---------|---------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | 按指定时间单位（工作日或日历日）收取的百分比 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
### Enumeradores interest_type
| 枚举值 | 描述 |
|------------------------------------|-----------------------------------------------|
| calendar_days_daily_amount | 基于日历日的每日金额 |
| workdays_daily_amount | 基于工作日的每日金额 |
| calendar_days_monthly_percentage | 基于日历日按月收取的利息百分比 |
### Objeto qr_code_settings
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `pix_key` * | uuidv4 | 随机类型的 PIX 密钥 | 36 |
| `qr_code_on_discharge_enabled` * | boolean | 确定 QR Code 信息是否包含在退款文件（CNAB）中 | - |
### Objeto cnab_settings
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------|---------|---------------------------------------------------|--------|
| `default_bank` | string | 处理 CNAB 文件的默认银行布局 | **[Enumeradores default_bank](#enumeradores-default_bank)** |
| `preferred_layout` | string | CNAB 文件首选布局 | **[Enumeradores preferred_layout](#enumeradores-preferred_layout)** |
### Enumeradores default_bank
| 枚举值 | 描述 |
|--------------------|------------------|
| santander | Banco Santander |
| itau | Banco Itaú |
| bradesco | Banco Bradesco |
| qi_scd | QI SCD |
### Enumeradores preferred_layout
| 枚举值 | 描述 |
|--------------------|------------------|
| 400 | CNAB 400 布局 |
| 240 | CNAB 240 布局 |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 400 | BKS000025 | Bad Request | Invalid bank slip status. | Status de boleto inválido. |
---
# 查询临时文件
URL: /zh-Hans/documentation/boletos/cnab/consulta_por_chave
通过键查询临时 CNAB 文件，可返回有关该文件的详细信息，例如已处理的记录数量以及文件中发现的可能错误。
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file/ TEMPORARY_CNAB_FILE_KEY
MÉTODO GET
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|--------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `temporary_cnab_file_key` | uuidv4 | 临时 CNAB 文件唯一标识键，uuid v4 格式 | 36 |
## Response
STATUS 200
Response Body: 文件已接受（无错误）
```json
{
"temporary_cnab_file_key": "fa4f094d-8475-4828-9105-99756914e14f",
"temporary_cnab_file_name": "240827463_t.REM",
"temporary_cnab_file_status": "read",
"occurrence_quantity": 6,
"total_processed_occurrences": 6,
"created_at": "2024-08-28T15:09:30Z"
}
```
Response Body: 文件已拒绝（有错误）
```json
{
"temporary_cnab_file_key": "c16baa13-0969-46a7-a85f-6f975d266d9f",
"temporary_cnab_file_name": "240905623.REM",
"temporary_cnab_file_status": "rejected",
"occurrence_quantity": 0,
"total_processed_occurrences": 0,
"created_at": "2024-09-10T15:59:25Z",
"error_data": [
{
"code": "BKS000063",
"title": "Bad Request",
"description": "Invalid file code.",
"translation": "Codigo de arquivo invalido.",
"extra_fields": {
"details": "Invalid file code. Expected: '1'. Got: '0'.",
"file_line": 1,
"details_pt_br": "Código de arquivo inválido. Esperado: '1'. Recebido: '0'.",
"cnab_file_name": "240905623.REM",
"cnab_inline_end_position": 2,
"cnab_inline_start_position": 2
}
},
{
"code": "BKS000069",
"title": "Bad Request",
"description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
"translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
"extra_fields": {
"details": "Invalid beneficiary account header on header. Expected: '1927400'. Got: '3;53179'.",
"file_line": 1,
"details_pt_br": "Conta do beneficiário inválida no header. Esperado: '1927400'. Recebido: '3;53179'.",
"cnab_file_name": "240905623.REM",
"cnab_inline_end_position": 46,
"cnab_inline_start_position": 40
}
},
{
"code": "BKS000064",
"title": "Bad Request",
"description": "Invalid bank code (014).",
"translation": "Codigo do banco invalido (014).",
"extra_fields": {
"details": "Invalid bank code. Expected: '329'. Got: '014'",
"bank_code": "014",
"details_pt_br": "Código do banco inválido. Esperado: '329'. Recebido: '014'",
"cnab_file_name": "240905623.REM"
}
},
{
"code": "BKS000056",
"title": "Bad Request",
"description": "Invalid record sequence.",
"translation": "Sequencia invalida de registros.",
"extra_fields": {
"cnab_line": 1,
"cnab_file_name": "240905623.REM"
}
},
{
"code": "BKS000056",
"title": "Bad Request",
"description": "Invalid record sequence.",
"translation": "Sequencia invalida de registros.",
"extra_fields": {
"cnab_line": 2,
"cnab_file_name": "240905623.REM"
}
},
{
"code": "BKS000086",
"title": "Bad Request",
"description": "File missing trailler record.",
"translation": "Arquivo sem registro trailler.",
"extra_fields": {
"file_line": 3,
"cnab_file_name": "240905623.REM"
}
}
]
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------------|--------------|----------------------------------------------------------------------------|--------------------------------------------------|
| `temporary_cnab_file_key` * | uuidv4 | 临时 CNAB 文件唯一标识键，uuid v4 格式 | 36 |
| `temporary_cnab_file_name` * | uuidv4 | 文件名 | 100 |
| `temporary_cnab_file_status` * | string | 临时 CNAB 文件状态 | **[Enumeradores temporary_cnab_file_status](#enumeradores-temporary_cnab_file_status)** |
| `occurrence_quantity` * | integer | 文件中的记录数量 | - |
| `total_processed_occurrences` *| integer | 已处理的记录数量 | - |
| `error_data` | object array | 文件中发现的错误对象（JSON 格式），与 API 返回格式相同 | **[Objeto error_data](#objeto-error_data)** |
| `created_at` * | string | 文件在数据库中创建的时间戳，ISO Zulu 格式 | 20 |
### Enumeradores temporary_cnab_file_status
| 枚举值 | 描述 |
|------------------------------|--------------------------------------------------------------|
| uploaded | 上传成功，但文件尚未开始处理 |
| processing | 文件正在读取中 |
| read | 文件已读取并接受 |
| rejected | 文件已读取并因语法错误被拒绝 |
### Objeto error_data
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|---------|----------------------------|--------------------------------------------------|
| `code` * | string | 错误代码 | 9 |
| `title` * | string | 错误标题 | 100 |
| `description` * | string | 错误描述（英文） | 100 |
| `translation` * | integer | 错误描述翻译 | 100 |
| `extra_fields` | object | 关于错误的附加信息 | - |
:::danger 重要
`extra_fields` 对象中返回的字段用于提供关于错误的附加信息，可能有所不同。因此，不应以严格限定的方式进行映射。
:::
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 404 | BKS000054 | Not Found | Remittance not found with key: `{temporary_cnab_file_key}` | Remessa não encontrada com a chave: `{temporary_cnab_file_key}` |
---
# 汇款文件（CNAB）- 简介
URL: /zh-Hans/documentation/boletos/cnab/introducao
:::info
本次调用传输的文件必须遵循 QI Tech 400 位收款文件布局标准。
手册下载链接：[收款布局 - QI Tech 版本 2.1.](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)
:::
汇款文件（CNAB）提供了在单个文件中发送多条票据登记指令以及其他类型指令（延期、减免、核销等）的可能性，这些指令可针对不同的票据。发送上述指令（延期、减免等）用于已有票据时，票据通过钱包代码（`requester_profile_code`）和我方号码（`our_number`）进行识别。
上传 CNAB 文件后，若请求成功（响应代码 `202`），将创建一个临时 CNAB 文件（`TemporaryCNABFile`）。可以使用[**临时 CNAB 文件查询**](/documentation/boletos/cnab/consulta_por_chave)和[**其记录**](/documentation/boletos/cnab/listar_ocorrencias_temporarias)端点来查看文件处理状态以及可能的错误（包括文件本身及其记录的错误）。
如果发现任何语法错误，文件将被拒绝。但文件将被完整读取，或读取至发现 100 个错误为止，以便能够以更实用、高效的方式返回并修正所有错误。
文件读取时会创建 临时记录 ，只有在文件被接受时才会处理这些记录。也就是说， 如果文件被拒绝（状态为 `rejected`），其所有记录也将被拒绝 。此外，文件被拒绝后，将不再为其创建临时记录。因此，被拒绝文件的记录条目通常少于文件中发送的记录数量。
另一方面，当文件被完整读取并接受（状态为 `read`）时，将开始创建最终记录，这些记录将是实际生效的指令。如果临时记录显示状态为 `rejected`（已拒绝），则表示其中存在语义错误——即内容错误。此时，将附带一个 `error_data` 对象，提供拒绝原因的详细信息。反之，如果状态为 `processed`，则表示最终记录已创建并发送至 CIP/Núclea。有关这些实体的更多详情，请参阅后续关于查询文件和临时记录的页面。
:::tip 通过 CNAB 进行信用分账
在 CNAB 文件中提供[**信用分账**](/documentation/boletos/instrucoes/rateio_de_credito)（分账支付）信息：
- **QI SCD（CNAB400 - QI Tech v2.1 布局）：** 明细记录中 `identificacao_registro = 3`。完整细节请参阅 **[收款布局 - QI Tech v2.1](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)**。
- **Bradesco（CNAB400 与 CNAB240）：** 明细记录类型 `3`。
- **Itaú（CNAB400 与 CNAB240）：** 明细记录类型 `4`。
- **Santander：** 不支持通过 CNAB 进行信用分账。请使用 REST 接口[**信用分账更新**](/documentation/boletos/instrucoes/rateio_de_credito)，或在通过 API 发行时携带 `split_payment_data`。
**如何映射 N 个分账账户：** 每条分账记录可包含最多 **3 个附加账户**（账户号 + 校验位 + 百分比）。如需超过 3 个分账账户，可在 Boleto 主记录之后**按顺序添加多条分账记录**——它们将累积到同一笔记录中。例如：7 个账户 = 3 条记录（3 + 3 + 1）。
**限制（所有银行）：**
- 仅支持**百分比**计算方式（`计算代码 = 2`）。
- 各百分比之和（受益人 + 分账）必须正好等于 **100**。
- 分账账户总数遵循 REST API 的相同限制（最多 10 个附加账户）。
- `beneficiary_max_amount`（受益人最高金额、超出部分分配给第一条规则的分账模式）**仅支持 REST API**，不支持通过 CNAB 设置。如需此场景，请使用 REST 接口[**发行**](/documentation/boletos/emissao/emissao_boleto_unico_padrao)或[**信用分账更新**](/documentation/boletos/instrucoes/rateio_de_credito)。
:::
---
# 列出临时汇款文件
URL: /zh-Hans/documentation/boletos/cnab/listar_arquivos_temporarios
临时 CNAB 文件列表将返回符合请求中发送的 查询参数 的所有钱包临时 CNAB 文件。
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file
MÉTODO GET
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
### Query parameters
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|---------|---------------------------------------|--------------------------|
| `temporary_cnab_file_status` | string | 临时 CNAB 文件状态 | **[Enumeradores temporary_cnab_file_status](#enumeradores-temporary_cnab_file_status)** |
| `page` | integer | 页码 | - |
| `page_size` | integer | 每页大小 | - |
### Enumeradores temporary_cnab_file_status
| 枚举值 | 描述 |
|------------------------------|--------------------------------------------------------------|
| uploaded | 上传成功，但文件尚未开始处理 |
| processing | 文件正在读取中 |
| read | 文件已读取并接受 |
| rejected | 文件已读取并因语法错误被拒绝 |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"temporary_cnab_file_key": "a6db5f8b-1ed7-4d13-9cbf-f3c4275e3ca3",
"temporary_cnab_file_name": "240903573.REM",
"temporary_cnab_file_status": "processing",
"occurrence_quantity": null,
"created_at": "2024-09-07T15:44:01Z"
},
{
"temporary_cnab_file_key": "2351c4ae-9a01-4675-86e4-099a30dafa42",
"temporary_cnab_file_name": "240904603.REM",
"temporary_cnab_file_status": "rejected",
"occurrence_quantity": 0,
"created_at": "2024-09-06T12:35:50Z"
},
{
"temporary_cnab_file_key": "fa4f094d-8475-4828-9105-99756914e14f",
"temporary_cnab_file_name": "240827463_t.REM",
"temporary_cnab_file_status": "read",
"occurrence_quantity": 10424,
"created_at": "2024-08-28T15:09:30Z"
},
{
"temporary_cnab_file_key": "e99cea6d-0d1c-4ec3-a2c6-bc603aede7c6",
"temporary_cnab_file_name": "240827443_t.REM",
"temporary_cnab_file_status": "read",
"occurrence_quantity": 542,
"created_at": "2024-08-27T20:07:11Z"
},
{
"temporary_cnab_file_key": "2351c4ae-9a01-4675-86e4-099a30dafa42",
"temporary_cnab_file_name": "240812604.REM",
"temporary_cnab_file_status": "rejected",
"occurrence_quantity": 0,
"created_at": "2024-08-12T12:52:13Z"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|-------------------------|---------------------------------------------|
| `data` * | object array | 临时 CNAB 文件列表 | **[Objeto temporary_cnab_file](#objeto-temporary_cnab_file)** |
| `pagination` * | object | 分页信息 | **[Objeto pagination](#objeto-pagination)** |
### Objeto temporary_cnab_file
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------------|---------|--------------------------------------------------------|--------------------------------------------------|
| `temporary_cnab_file_key` * | uuidv4 | 临时 CNAB 文件唯一标识键，uuid v4 格式 | 36 |
| `temporary_cnab_file_name` * | uuidv4 | 文件名 | 100 |
| `temporary_cnab_file_status` * | string | 临时 CNAB 文件状态 | **[Enumeradores temporary_cnab_file_status](#enumeradores-temporary_cnab_file_status)** |
| `occurrence_quantity` * | integer | 文件中的记录数量 | - |
| `created_at` * | string | 文件在数据库中创建的时间戳，ISO Zulu 格式 | 20 |
### Objeto pagination
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|----------------|--------------------------------------------------------------|
| `current_page` * | integer | 当前页码 | - |
| `rows_per_page` * | integer | 每页记录数 | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 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. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
---
# 列出临时记录
URL: /zh-Hans/documentation/boletos/cnab/listar_ocorrencias_temporarias
临时记录列表将返回给定 CNAB 文件的所有临时记录。
:::info
当 CNAB 文件因语法错误被拒绝时，将不再为其创建临时记录，因为所有记录都将因文件被拒绝而遭拒。因此，文件被拒绝时，与该文件相关的临时记录数量可能少于文件中发送的记录数量。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file / TEMPORARY_CNAB_FILE_KEY /occurrences
MÉTODO GET
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
### Query parameters
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|----------------------------|--------------------------|
| `occurrence_status` | string | 临时记录状态 | **[Enumeradores occurrence_status](#enumeradores-temporary_cnab_file_status)** |
| `occurrence_type` | string | 临时记录类型 | **[Enumeradores occurrence_type](#enumeradores-temporary_cnab_file_type)** |
| `page` | integer | 页码 | - |
| `page_size` | integer | 每页大小 | - |
### Enumeradores occurrence_status
| 枚举值 | 描述 |
|------------------------------|------------------------------------------|
| pending | 记录尚未处理 |
| processed | 记录处理成功 |
| rejected | 记录因语义错误被处理并拒绝 |
### Enumeradores occurrence_type
| 枚举值 | 描述 |
|------------------------------------------|------------------------------------------|
| registration | 票据登记 |
| write_off | 票据核销 |
| rebate | 票据价值减免 |
| cancel_rebate | 取消减免 |
| extension | 付款日期延期 |
| protest_request | 抗议申请 |
| bankruptcy_protest_request | 破产抗议申请 |
| protest_cancel_and_write_off_request | 取消抗议申请并核销票据 |
| protest_cancel_request | 取消抗议申请 |
| bank_slip_edit | 编辑票据其他数据 |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"occurrence_key": "191f2220-1465-47d7-8c81-67d8f59f5af2",
"occurrence_status": "rejected",
"occurrence_type": "registration",
"occurrence_our_number": 12455,
"error_data": {
"code": "BKS000069",
"title": "Bad Request",
"description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
"translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
"extra_fields": {
"account_digit": "4",
"account_branch": "0001",
"account_number": "1927400"
}
}
},
{
"occurrence_key": "adc0ce54-9e69-45ec-9220-fbfe0e3ba103",
"occurrence_status": "rejected",
"occurrence_type": "registration",
"occurrence_our_number": 12453,
"error_data": {
"code": "BKS000069",
"title": "Bad Request",
"description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
"translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
"extra_fields": {
"account_digit": "4",
"account_branch": "0001",
"account_number": "1927400"
}
}
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|-------------------------|---------------------------------------------|
| `data` * | object array | 临时记录列表 | **[Objeto temporary_occurrence](#objeto-temporary_occurrence)** |
| `pagination` * | object | 分页信息 | **[Objeto pagination](#objeto-pagination)** |
### Objeto temporary_cnab_file
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|--------------------------------------------------------|--------------------------------------------------|
| `occurrence_key` * | uuidv4 | 临时记录唯一标识键，uuid v4 格式 | 36 |
| `occurrence_status` * | string | 临时记录状态 | **[Enumeradores temporary_occurrence_status](#enumeradores-temporary_occurrence_status)** |
| `occurrence_type` * | string | 临时记录类型 | **[Enumeradores occurrence_type](#enumeradores-occurrence_type)** |
| `occurrence_our_number` * | integer | 文件中的记录数量 | - |
| `error_data` | object | 文件中发现的错误对象（JSON 格式），与 API 返回格式相同 | **[Objeto error_data](#objeto-error_data)** |
### Objeto pagination
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|----------------|--------------------------------------------------------------|
| `current_page` * | integer | 当前页码 | - |
| `rows_per_page` * | integer | 每页记录数 | - |
### Objeto error_data
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|---------|----------------------------|--------------------------------------------------|
| `code` * | string | 错误代码 | 9 |
| `title` * | string | 错误标题 | 100 |
| `description` * | string | 错误描述（英文） | 100 |
| `translation` * | integer | 错误描述翻译 | 100 |
| `extra_fields` | object | 关于错误的附加信息 | - |
:::danger 重要
`extra_fields` 对象中返回的字段用于提供关于错误的附加信息，可能有所不同。因此，不应以严格限定的方式进行映射。
:::
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 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. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 404 | BKS000054 | Not Found | Remittance not found with key: `{temporary_cnab_file_key}` | Remessa não encontrada com a chave: `{temporary_cnab_file_key}` |
---
# 上传汇款文件（CNAB）
URL: /zh-Hans/documentation/boletos/cnab/upload_de_arquivo_remessa
:::caution 注意！
调用必须按照[**上传文档**](/documentation/upload_de_documentos)部分所述的标准进行认证。
:::
汇款文件（CNAB）提供了在单个文件中发送多条票据登记指令以及其他类型指令（延期、减免、核销等）的可能性，这些指令可针对不同的票据。发送上述指令（延期、减免等）用于已有票据时，票据通过钱包代码（`requester_profile_code`）和我方号码（`our_number`）进行识别。
:::info
上传 CNAB 文件后，若请求成功（响应代码 `202`），将创建一个临时 CNAB 文件（`TemporaryCNABFile`）。可以使用[**临时 CNAB 文件查询**](/documentation/boletos/cnab/consulta_por_chave)和[**其记录**](/documentation/boletos/cnab/listar_ocorrencias_temporarias)端点来查看文件处理状态以及可能的错误。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /cnab_file
MÉTODO POST
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
## Request Body Params
以下数据应作为 form-data 在请求 body 中发送：
| 字段 | 类型 | 描述 | 字符数 |
|---------|------|---------------------------------------|--------|
| `file` *| file | 符合 QI Tech 规定标准的 CNAB 文件 | - |
## Response
STATUS 202
Response Body
```json
{
"temporary_cnab_file_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
"temporary_cnab_file_status": "accepted"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------------|---------|---------------------------------------------------------|----------------------------|
| `temporary_cnab_file_key` * | uuidv4 | CNAB 文件唯一标识键，uuid v4 格式 | 36 |
| `temporary_cnab_file_status` * | string | CNAB 文件状态 | **[Enumeradores temporary_cnab_file_status](#enumeradores-cnab_file_status)** |
### Enumeradores temporary_cnab_file_status
| 枚举值 | 描述 |
|------------|------------------------------------------------------------|
| uploaded | 上传成功，但文件尚未开始处理 |
| processing | 文件正在读取中 |
| read | 文件已读取并接受 |
| rejected | 文件已读取并被拒绝（文件的所有记录均被拒绝） |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 409 | BKS000053 | Conflict | CNAB file already received: '``' | Arquivo CNAB já recebido: '``' |
---
# 通过密钥查询 Boleto
URL: /zh-Hans/documentation/boletos/consulta/consulta_por_chave
通过密钥查询 Boleto 可返回该 Boleto 的详细信息，例如与该 Boleto 相关的所有指令。
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY
MÉTODO GET
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|-----------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` | uuidv4 | Boleto 唯一标识密钥，格式为 uuid v4 | 36 |
## Response
STATUS 200
Response Body
```json
{
"bank_slip_key": "4c2fa514-a44d-40f2-8d57-c0caf1b9165a",
"request_control_key": "0dcb3182-4d7e-4526-8f92-c15cdbc51bad",
"our_number": 26652176735,
"document_number": "DOC4561237",
"amount": "5000.00",
"rebate_amount": "0.00",
"expiration": "2024-07-12",
"barcode": "32994978900005000000001546128483498231955340",
"digitable_line": "32990001524612848349582319553408497890000500000",
"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.0,
"days_to_fine": 10
},
"interest_data": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10.0,
"days_to_interest": 2
},
"discounts_data": [
{
"discount_type": "absolute",
"discount_amount": 50.0,
"discount_number": 1,
"discount_limit_date": "2024-07-12"
}
],
"payer_data": {
"name": "Global Tech",
"address": {
"city": "Innovation City",
"state": "SP",
"number": "202",
"street": "101 High St.",
"complement": "Building A",
"postal_code": "57099999",
"neighborhood": "Tech Park"
},
"person_type": "legal",
"document_number": "12345678000195"
},
"guarantor_data": {
"name": "Jane Doe",
"address": {
"city": "Peaceful Town",
"state": "RJ",
"number": "303",
"street": "202 Elm St.",
"complement": "House 1",
"postal_code": "57099999",
"neighborhood": "Quiet Neighborhood"
},
"person_type": "natural",
"document_number": "23456789012"
},
"qr_code_data": {
"qr_code_key": "58bd3558-f214-4e83-9c88-1ac4c93db214",
"pix_key": "f9b05a58-9dcf-49cb-bc7f-99c5b3f1fdcb",
"receiver_conciliation_id": "a3861b53f5414b0ba6c9f800d7374474",
"url": "00020126890014br.gov.bcb.pix2567qrcode-h.dev.qitech.app/bacen/cobv/a3861b53f5414b0ba6c9f800d73744745204000053039865802BR5922BeatrizCoutodeCarvalho6012SAOJOSEDORIO61081501410062070503***6304ED95",
"image": ""
},
"payment_notice_data": {
"payment_method": "account_debit",
"payment_origin": "internet",
"payment_notice_date": "2024-07-01"
},
"payment_data": {
"paid_amount": 850.0,
"paid_rebate_amount": 200.0,
"paid_discount_amount": 0.0,
"paid_fine_amount": 0.0,
"paid_interest_amount": 50.0,
"payment_method": "account_debit",
"payment_origin": "internet",
"payment_credit_date": "2024-07-02",
"payment_date": "2024-07-01",
"payment_bank": {
"code": "341",
"ispb": 60701190,
"name": "ITAU UNIBANCO S.A."
},
"payment_branch": "0216"
},
"bank_slip_status": "registered",
"occurrences": [
{
"request_control_key": "0dcb3182-4d7e-4526-8f92-c15cdbc51bad",
"occurrence_key": "ec67408c-a149-418a-b89b-b9c9d3b6c403",
"occurrence_type": "registration",
"occurrence_status": "confirmed",
"created_at": "2024-06-23T09:15:32Z"
},
{
"request_control_key": "9618c632-7f4d-490b-8817-2bb72ec1e84a",
"occurrence_key": "70d3e632-644d-499f-baac-f65f21fb8574",
"occurrence_type": "rebate",
"occurrence_status": "confirmed",
"created_at": "2024-06-26T12:36:04Z"
},
{
"request_control_key": "c2b2ba59-9c37-488d-823d-2c3bfc1e9108",
"occurrence_key": "dbdd513c-e918-4d17-b194-b5ae3d979988",
"occurrence_type": "cancel_rebate",
"occurrence_status": "confirmed",
"created_at": "2024-06-26T12:53:47Z"
}
]
}
```
### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------------|-------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| `bank_slip_key` * | uuidv4 | Boleto 唯一标识密钥，格式为 uuid v4 | 36 |
| `request_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4 | 36 |
| `our_number` * | integer | Boleto 在钱包中的唯一识别编号 | 11 |
| `bank_slip_status` * | string | Boleto 状态 | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)** |
| `protest_status` * | string | Boleto 在公证处的抗议状态 | **[protest_status 枚举值](#enumeradores-protest_status)** |
| `document_number` * | string | Boleto 识别编号 | 10 |
| `amount` * | float | Boleto 基准金额 | - |
| `expiration` * | string | 到期日 | 10 |
| `barcode` * | string | Boleto 条形码 | 44 |
| `digitable_line` * | string | Boleto 可打印行 | 47 |
| `bank_teller_instructions` | string | 额外注册说明，将显示在 Boleto PDF 中 | 320 |
| `rebate_amount` | float | Boleto 减免金额，将在基准金额之上应用 | - |
| `max_payment_days` * | integer | Boleto 到期后可供支付的最大自然日数（最多 365 天） | - |
| `write_off_data` | object | 核销配置 | **[write_off_data 对象](#objeto-write_off_settings)** |
| `protest_data` | object | 抗议配置 | **[protest_data 对象](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object | 破产抗议配置 | **[bankruptcy_protest_data 对象](#objeto-bankruptcy_protest_settings)** |
| `fine_data` | object | 罚款配置 | **[fine_data 对象](#objeto-fine_settings)** |
| `interest_data` | object | 利息配置 | **[interest_data 对象](#objeto-interest_settings)** |
| `discounts_data` | object array | 折扣配置 | **[discount 对象](#objeto-discounts_data)** |
| `payer_data` * | object | 付款方数据 | **[payer_data 对象](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` * | object | 担保人数据 | **[guarantor_data 对象](#objetos-payer_data-e-guarantor_data)** |
| `qr_code_data` | object | QR Code 数据 | **[qr_code_data 对象](#objeto-qr_code_data)** |
| `payment_notice_data` | object 或 array | 付款通知数据 | **[payment_notice_data 对象或数组](#objeto-ou-array-payment_notice_data)** |
| `payment_data` | object 或 array | 付款数据 | **[payment_data 对象或数组](#objeto-ou-array-payment_data)** |
| `occurrences` | object array | Boleto 相关指令 | **[bank_slip_occurrence 对象](#objeto-bank_slip_occurrence)** |
:::info 说明
`amount` 字段是 Boleto 的**基准金额**，即**不含**罚款（fine）、利息（interest）、减免（rebate）和折扣（discounts）。
:::
### bank_slip_status 枚举值
| 枚举值 | 描述 |
|-------------------------------|----------------------------------------------------|
| accepted | 已接受并发送至 Nuclea/CIP 进行分析 |
| rejected | 被 Nuclea/CIP 拒绝注册 |
| payment_notice | 付款通知（Boleto 已付但付款尚未清算） |
| notary_office_payment_notice | 公证处付款通知（Boleto 已付但付款尚未清算） |
| registered | Nuclea/CIP 已确认注册 |
| payment_blocked | 已锁定支付（处于抗议流程中） |
| paid | 已支付 |
| written_off | 已核销 |
### protest_status 枚举值
| 枚举值 | 描述 |
|-----------------------------|------------------------------|
| not_protested | Boleto 尚未启动抗议流程 |
| protest_requested | 已申请公证处抗议 |
| notary_office_entry | Boleto 在公证处，处于三日期间 |
| protest_cancel_requested | 已申请撤销抗议 |
| notary_office_exit | Boleto 已离开公证处 |
| protested | Boleto 已被抗议 |
| paid_at_notary_office | 在公证处支付 |
| judicially_suspended | 抗议被司法暂停 |
| protest_remove_requested | 已申请移除抗议 |
### write_off_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|---------------------------------------|--------|
| `days_to_write_off` * | integer | Boleto 到期后自动核销的天数 | - |
### protest_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|---------------------------------------|--------|
| `days_to_protest` * | integer | Boleto 到期后自动抗议的天数 | - |
### bankruptcy_protest_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|---------|---------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | Boleto 到期后自动破产抗议的天数 | - |
### fine_data 对象
**选项 1：绝对值罚款（`fine_type=absolute`）**
| 字段 | 类型 | 描述 | 字符数 |
|------------------|---------|-----------------------------------|------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_amount` * | float | 罚款绝对值 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
**选项 2：百分比罚款（`fine_type=percentage`）**
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|-----------------------------------|------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | 罚款百分比，1 至 100 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
### fine_type 枚举值
| 枚举值 | 描述 |
|----------|----------|
| absolute | 绝对值 |
| percentage | 百分比 |
### interest_data 对象
**选项 1：绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）**
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|---------|-------------------------------------------|-------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_amount` * | float | 每单位时间（工作日或自然日）收取的利息金额 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
**选项 2：百分比利息（`interest_type=calendar_days_monthly_percentage`）**
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|-----------------------------------------------|-------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | 每单位时间（工作日或自然日）收取的利息百分比 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
### interest_type 枚举值
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------|
| calendar_days_daily_amount | 按自然日计算的每日金额 |
| workdays_daily_amount | 按工作日计算的每日金额 |
| calendar_days_monthly_percentage | 按自然日计算的月利率百分比 |
### discount 对象
**选项 1：绝对值折扣（`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`）**
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|---------|-----------------------------|-----------------------------------------------------------------|
| `discount_amount` * | float | 每单位时间的绝对折扣金额 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 折扣类型（绝对值） | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣截止日期 | 10 |
**选项 2：百分比折扣（`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`）**
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|-----------------------------|-----------------------------------------------------------------|
| `discount_percentage` * | float | 每单位时间的折扣百分比 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 折扣类型（百分比） | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣截止日期 | 10 |
:::caution 注意！
一张 Boleto 最多可有三个折扣，且**所有折扣必须为同一类型**，即具有相同的 `discount_type`。折扣编号必须从 1 开始，按递增顺序编号，**最大到 3**。即，若请求中发送两个折扣，必须分别编号为 1 和 2。
:::
### discount_type 枚举值
| 枚举值 | 描述 |
|--------------------------------------------|----------------------------------------|
| absolute | 固定金额 |
| anticipation_calendar_days_daily_amount | 按自然日计算的提前还款每日折扣金额 |
| anticipation_workdays_daily_amount | 按工作日计算的提前还款每日折扣金额 |
| percentage | 固定百分比 |
| anticipation_calendar_days_daily_percentage | 按自然日计算的提前还款月折扣百分比 |
| anticipation_workdays_daily_percentage | 按工作日计算的提前还款年折扣百分比 |
### payer_data 和 guarantor_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|--------|------------------------|----------------------------------------------------------------|
| `name` * | string | 全名 | 100 |
| `document_number` * | string | 证件号码（CPF/CNPJ） | 11 或 14 |
| `person_type` * | string | 人员类型（自然人或法人）| **[person_type 枚举值](#enumeradores-person_type)** |
| `contact` | object | 联系信息 | **[contact 对象](#objeto-contact)** |
| `address` | object | 地址 | **[address 对象](#objeto-address)** |
### person_type 枚举值
| 枚举值 | 描述 |
|---------|--------|
| natural | 自然人 |
| legal | 法人 |
### contact 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------|--------|----------|---------------------------------------|
| `email` | string | 联系邮箱 | 320 |
| `phone` | object | 联系电话 | **[phone 对象](#objeto-phone)** |
### phone 对象
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|--------|----------------|--------|
| `international_dial_code` * | string | 国际区号（DDI） | 3 |
| `area_code` * | string | 地区区号（DDD） | 2 |
| `number` * | string | 电话号码 | 9 |
### address 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|--------|----------------------------------------------------|
| `street` * | string | 街道 | 500 |
| `number` * | string | 门牌号 | 6 |
| `complement` | string | 补充 | 500 |
| `neighborhood` * | string | 社区 | 100 |
| `postal_code` * | string | 邮编 | 8 |
| `city` * | string | 城市 | 100 |
| `state` * | string | 州（UF） | **[state 枚举值](#enumeradores-state)** |
### state 枚举值
| 枚举值 | 描述 |
|------|----------------------|
| 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 | 其他 |
### qr_code_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|----------------------------------|--------|
| `qr_code_key` | uuidv4 | QR Code 唯一标识密钥 | 36 |
| `pix_key` | uuidv4 | 与 QR Code 关联的 PIX 密钥 | 36 |
| `receiver_conciliation_id` | uuidv4 | QR Code 对账标识符 | 36 |
| `url` | string | QR Code 的 URL（Pix 复制粘贴） | - |
| `image` | string | QR Code URL 的 base64 编码图片 | - |
### payment_notice_data 对象或数组
:::caution 注意！
对于未配置部分支付的 Boleto，`payment_notice_data` 字段将以**对象**形式返回。对于配置了部分支付的 Boleto，将以**对象数组**形式返回，因为可能存在多笔付款。
此外，如果 Boleto 通过 **QR Code** 支付，该字段不会返回，因为清算在付款当日完成。
:::
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|--------|------------|-------------------------------------------------------------------------|
| `payment_method` | string | 支付方式 | **[payment_method 枚举值](#enumeradores-payment_method)** |
| `payment_origin` | string | 支付来源 | **[payment_origin 枚举值](#enumeradores-payment_origin)** |
| `payment_notice_date` | string | 付款通知日期 | 10 |
### payment_data 对象或数组
:::caution 注意！
对于未配置部分支付的 Boleto，`payment_data` 字段将以**对象**形式返回。对于配置了部分支付的 Boleto，将以**对象数组**形式返回，因为可能存在多笔付款。
:::
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|------------|-------------------------------------------------------------------------|
| `paid_amount` | float | 付款金额 | - |
| `paid_rebate_amount` | float | 已付减免金额 | - |
| `paid_discount_amount` | float | 已付折扣金额 | - |
| `paid_fine_amount` | float | 已付罚款金额 | - |
| `paid_interest_amount` | float | 已付利息金额 | - |
| `payment_method` | string | 支付方式 | **[payment_method 枚举值](#enumeradores-payment_method)** |
| `payment_origin` | string | 支付来源 | **[payment_origin 枚举值](#enumeradores-payment_origin)** |
| `payment_credit_date` | string | 付款入账日期 | 10 |
| `payment_bank` | object | Boleto 付款所在的银行。仅在 Boleto 付款后返回 | **[payment_bank 对象](#objeto-payment_bank)** |
| `payment_branch` | string | Boleto 付款所在的分行（agência）。仅在 Boleto 付款后返回 | - |
:::info 信息
字段 `payment_bank` 和 `payment_branch` 仅在 Boleto 已付款（即存在已确认的付款记录）时返回。在 Boleto 付款之前，响应中不会包含这些字段。
:::
### payment_bank 对象
| 字段 | 类型 | 描述 | 字符数 |
|--------|---------|---------------------|--------|
| `code` | string | 银行清算代码（3 位数） | 3 |
| `ispb` | integer | 银行 ISPB | 8 |
| `name` | string | 银行名称 | - |
### payment_method 枚举值
| 枚举值 | 描述 |
|--------------|------------|
| cash | 现金 |
| account_debit | 账户扣款 |
| credit_card | 信用卡 |
| check | 支票 |
### payment_origin 枚举值
| 枚举值 | 描述 |
|-----------------------|----------------------------|
| phisical_cashier | 银行网点 - 传统柜台 |
| taa | 自动取款机 |
| internet | 互联网（网上/办公室银行） |
| corban | 银行代理 |
| call_center | 电话客服中心 |
| eletronic_file | 电子文件 |
| dda | DDA |
| digital_correspondent | 数字银行代理 |
| qr_code | Pix QR Code 支付 |
### bank_slip_occurrence 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|--------|-----------------------------------------------------|---------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4 | 36 |
| `occurrence_key` * | uuidv4 | Boleto 唯一标识密钥，格式为 uuid v4 | 36 |
| `occurrence_type` * | string | 事件类型 | **[occurrence_type 枚举值](#enumeradores-occurrence_type)** |
| `occurrence_status` * | string | 事件状态 | **[occurrence_status 枚举值](#enumeradores-occurrence_status)** |
| `created_at` * | string | 事件创建日期，ISO 格式（UTC - "YYYY-MM-DDTHH:MM:SSZ"） | 20 |
### occurrence_type 枚举值
| 枚举值 | 描述 |
|-------------------|-------------------|
| registration | 注册事件 |
| write_off | 核销申请事件 |
| rebate | 添加减免事件 |
| cancel_rebate | 取消减免事件 |
| discount | 修改折扣事件 |
| fine | 修改罚款事件 |
| interest | 修改利息事件 |
| extension | 延期事件 |
| bank_slip_edit | 修改 Boleto 其他数据事件 |
| payment_notice | 付款通知事件 |
| payment | 付款清算事件 |
| protest_request | 抗议申请事件 |
### occurrence_status 枚举值
| 枚举值 | 描述 |
|----------|----------------------------|
| pending | 已发送至 Nuclea/CIP 待分析 |
| rejected | 已拒绝 |
| confirmed | 已确认 |
## 错误响应
STATUS 4xx
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`translation` |
|------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
---
# Boleto 列表查询
URL: /zh-Hans/documentation/boletos/consulta/listar_boletos
Boleto 列表将返回符合请求中发送的查询参数的所有钱包 Boleto。
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slips
MÉTODO GET
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一识别密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4 | 36 |
### 查询参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|---------|----------------------------------------|---------------------------------------------------------------------------|
| `request_control_key` | uuidv4 | 请求唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_status` | string | Boleto 状态 | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)** |
| `page` | integer | 页码 | - |
| `page_size` | integer | 每页大小 | - |
| `from_date` | string | 起始登记日期（格式"YYYY-MM-DD"） | 10 |
| `to_date` | string | 终止登记日期（格式"YYYY-MM-DD"） | 10 |
### bank_slip_status 枚举值
| 枚举值 | 描述 |
|------------------------------|-----------------------------------------------|
| accepted | 已接受并发送至 Nuclea/CIP 待分析 |
| rejected | 被 Nuclea/CIP 拒绝登记 |
| payment_notice | 支付通知（已付款但尚未清算） |
| notary_office_payment_notice | 公证处支付通知（已付款但尚未清算） |
| registered | 已由 Nuclea/CIP 确认登记 |
| payment_blocked | 已被锁定支付（在抗议流程中） |
| paid | 已付款 |
| written_off | 已注销 |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"bank_slip_key": "b58ce415-5428-45c4-8e33-b2df0d3ab6e8",
"request_control_key": "53529224-330d-44b5-9f4d-59d55bc3cb8c",
"our_number": 24384760943,
"document_number": "DOC4561237",
"amount": "8000.00",
"rebate_amount": "200.00",
"expiration": "2024-07-13",
"barcode": "32994978900005000000001594438621284040114400",
"digitable_line": "32990001529443862128940401144007497890000500000",
"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.0,
"days_to_fine": 10
},
"interest_data": {
"interest_type": "workdays_daily_amount",
"interest_amount": 5.0,
"days_to_interest": 10
},
"discounts_data": [
{
"discount_type": "anticipation_workdays_daily_percentage",
"discount_number": 1,
"discount_limit_date": "2024-07-13",
"discount_percentage": 10
}
],
"payer_data": {
"name": "Country Tech",
"address": {
"city": "Innovation City",
"state": "RS",
"number": "202",
"street": "101 High St.",
"complement": "Building A",
"postal_code": "57099999",
"neighborhood": "Tech Park"
},
"person_type": "legal",
"document_number": "12345678000195"
},
"guarantor_data": {
"name": "Jamie Doe",
"address": {
"city": "Peaceful Town",
"state": "MG",
"number": "303",
"street": "202 Elm St.",
"complement": "House 1",
"postal_code": "57099999",
"neighborhood": "Quiet Neighborhood"
},
"person_type": "natural",
"document_number": "98765432100"
},
"bank_slip_status": "paid",
"payment_data": {
"paid_amount": 8000.0,
"payment_credit_date": "2024-07-15",
"payment_date": "2024-07-14"
}
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------------|--------------|---------------------------------------------------|
| `data` * | object array | Boleto 列表 | **[bank_slip 对象](#objeto-bank_slip)** |
| `pagination` * | object | 分页信息 | **[pagination 对象](#objeto-pagination)** |
### bank_slip 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|------------------------------------------------|---------------------------------------------------------------------------|
| `bank_slip_key` * | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
| `request_control_key` * | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4 | 36 |
| `our_number` * | integer | Boleto 在钱包中的唯一识别号 | 11 |
| `bank_slip_status` * | string | Boleto 状态 | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)** |
| `protest_status` * | string | Boleto 公证处抗议状态 | **[protest_status 枚举值](#enumeradores-protest_status)** |
| `document_number` * | string | Boleto 识别号码 | 10 |
| `amount` * | float | Boleto 基础金额 | - |
| `expiration` * | string | 到期日期 | 10 |
| `barcode` * | string | Boleto 条形码 | 44 |
| `digitable_line` * | string | Boleto 可输入行 | 47 |
| `bank_teller_instructions` | string | 额外登记说明，将显示在 Boleto PDF 中 | 320 |
| `rebate_amount` | float | Boleto 折扣金额，将在基础金额上应用 | - |
| `max_payment_days` * | integer | 到期后可供付款的最大自然日数（最多 365 天） | - |
| `write_off_data` | object | 注销配置 | **[write_off_data 对象](#objeto-write_off_settings)** |
| `protest_data` | object | 抗议配置 | **[protest_data 对象](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object | 破产抗议配置 | **[bankruptcy_protest_data 对象](#objeto-bankruptcy_protest_settings)** |
| `fine_data` | object | 罚款配置 | **[fine_data 对象](#objeto-fine_settings)** |
| `interest_data` | object | 利息配置 | **[interest_data 对象](#objeto-interest_settings)** |
| `discounts_data` | object array | 折扣 | **[discount 对象](#objeto-discounts_data)** |
| `payer_data` * | object | 付款人数据 | **[payer_data 对象](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` * | object | 保证人数据 | **[guarantor_data 对象](#objetos-payer_data-e-guarantor_data)** |
### pagination 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|---------|----------|--------|
| `current_page` * | integer | 当前页码 | - |
| `rows_per_page` * | integer | 每页条数 | - |
### protest_status 枚举值
| 枚举值 | 描述 |
|---------------------------|------------------------------|
| not_protested | 未启动抗议流程的 Boleto |
| protest_requested | 已申请公证处抗议 |
| notary_office_entry | Boleto 在公证处三日期内 |
| protest_cancel_requested | 已申请撤销抗议 |
| notary_office_exit | Boleto 已离开公证处 |
| protested | 已被抗议的 Boleto |
| paid_at_notary_office | 已在公证处付款 |
| judicially_suspended | 抗议被司法中止 |
| protest_remove_requested | 已申请移除抗议 |
### write_off_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|---------|-------------------------------------|--------|
| `days_to_write_off` * | integer | 到期后自动注销 Boleto 所需天数 | - |
### protest_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|--------------------------------------|--------|
| `days_to_protest` * | integer | 到期后自动抗议 Boleto 所需天数 | - |
### bankruptcy_protest_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|---------|--------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | 到期后自动破产抗议 Boleto 所需天数 | - |
### fine_data 对象
选项 1：绝对值罚款（`fine_type=absolute`）
| 字段 | 类型 | 描述 | 字符数 |
|------------------|---------|---------------------------------------------|----------------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_amount` * | float | 罚款绝对值 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款所需天数 | - |
选项 2：百分比罚款（`fine_type=percentage`）
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|---------|----------------------------------------|----------------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | 罚款百分比，1 到 100 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款所需天数 | - |
### fine_type 枚举值
| 枚举值 | 描述 |
|-----------|------------|
| absolute | 绝对值 |
| percentage | 百分比 |
### interest_data 对象
选项 1：绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|---------|----------------------------------------------------|----------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_amount` * | float | 按时间单位（工作日或自然日）收取的利息值 | - |
| `days_to_interest` * | integer | 到期后开始收取利息所需天数 | - |
选项 2：百分比利息（`interest_type=calendar_days_monthly_percentage`）
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|---------|------------------------------------------------|----------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | 按时间单位（工作日或自然日）收取的利息百分比 | - |
| `days_to_interest` * | integer | 到期后开始收取利息所需天数 | - |
### interest_type 枚举值
| 枚举值 | 描述 |
|---------------------------------|--------------------------------|
| calendar_days_daily_amount | 按自然日计的每日金额 |
| workdays_daily_amount | 按工作日计的每日金额 |
| calendar_days_monthly_percentage | 按自然日计的月利率 |
### discount 对象
选项 1：绝对值折扣（`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`）
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|---------|----------------------------------------|--------------------------------------------------------------------|
| `discount_amount` * | float | 按时间单位计的绝对折扣值 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 绝对值折扣配置 | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣应用截止日期 | 10 |
选项 2：百分比折扣（`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`）
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|----------------------------------------|--------------------------------------------------------------------|
| `discount_percentage` * | float | 按时间单位计的百分比折扣值 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 百分比折扣配置 | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣应用截止日期 | 10 |
:::caution 注意！
一张 Boleto 最多可有三个折扣，且**折扣必须为同一类型**，即必须具有相同的 `discount_type`。折扣必须按升序编号，从 **1 开始**。即，若请求中发送两个折扣，则必须编号为 1 和 2。
:::
### discount_type 枚举值
| 枚举值 | 描述 |
|--------------------------------------------|----------------------------------------|
| absolute | 固定值 |
| anticipation_calendar_days_daily_amount | 按自然日计的每日提前折扣值 |
| anticipation_workdays_daily_amount | 按工作日计的每日提前折扣值 |
| percentage | 固定百分比 |
| anticipation_calendar_days_daily_percentage | 按自然日计的月提前折扣百分比 |
| anticipation_workdays_daily_percentage | 按工作日计的年提前折扣百分比 |
### payer_data 和 guarantor_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|--------|-----------------------------|----------------------------------------------------------------|
| `name` * | string | 全名 | 100 |
| `document_number` * | string | 证件号码（CPF/CNPJ） | 11 或 14 |
| `person_type` * | string | 人员类型（个人或法人） | **[person_type 枚举值](#enumeradores-person_type)** |
| `contact` | object | 联系信息 | **[contact 对象](#objeto-contact)** |
| `address` | object | 地址 | **[address 对象](#objeto-address)** |
### person_type 枚举值
| 枚举值 | 描述 |
|---------|--------|
| natural | 自然人 |
| legal | 法人 |
### contact 对象
| 字段 | 类型 | 描述 | 字符数 |
|--------|--------|--------------|---------------------------------------------|
| `email` | string | 联系邮箱 | 320 |
| `phone` | object | 联系电话 | **[phone 对象](#objeto-phone)** |
### phone 对象
| 字段 | 类型 | 描述 | 字符数 |
|------------------------------|--------|--------------------|--------|
| `international_dial_code` * | string | 国际区号（DDI） | 3 |
| `area_code` * | string | 区号（DDD） | 2 |
| `number` * | string | 电话号码 | 9 |
### address 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|------------|-----------------------------------------------------|
| `street` * | string | 街道 | 500 |
| `number` * | string | 门牌号 | 6 |
| `complement` | string | 补充信息 | 500 |
| `neighborhood` * | string | 社区 | 100 |
| `postal_code` * | string | 邮政编码 | 8 |
| `city` * | string | 城市 | 100 |
| `state` * | string | 州（UF） | **[state 枚举值](#enumeradores-state)** |
### state 枚举值
| 枚举值 | 描述 |
|-------|-----------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | 联邦区 |
| 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 | 例外 |
## 错误响应
STATUS 4xx
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`translation` |
|------------------------|--------------------|--------------------|------------------------------|---------------------------|
| 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. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
---
# Excel 格式日常仓位报告
URL: /zh-Hans/documentation/boletos/consultar_v1/posicao_diaria_excel
## Request
ENDPOINT /bank_slip/duplicates_balance_excel
MÉTODO GET
:::caution 注意
此请求的响应体将是一个以 base64 编码的 Excel 文件。
:::
### Query params
| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `beneficiary_key` | string | 受益人标识键（若无 requester_profile_code 则必填） | uuid 键 |
| `requester_profile_code` | string | 钱包代码（若无 beneficiary_key 则必填） | 10 |
| `expiration_date` | date | 最大到期日（格式 YYYY-MM-DD） | 10 |
## Response
STATUS 200
Response Body
```json
此请求的响应体将是一个以 base64 编码的 Excel 文件。
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# JSON 格式日常仓位报告
URL: /zh-Hans/documentation/boletos/consultar_v1/posicao_diaria_json
## Request
ENDPOINT /bank_slip/duplicates_balance
MÉTODO GET
### Query params
| 字段 | 类型 | 描述 | 字符数 |
|---|---|---|---|
| `beneficiary_key` | string | 受益人标识键（若无 requester_profile_code 则必填） | 10 |
| `requester_profile_code` | string | 钱包代码（若无 beneficiary_key 则必填） | 10 |
| `expiration_date` | date | 最大到期日（格式 YYYY-MM-DD） | 10 |
## Response
STATUS 200
Response Body
```json
{
"expire_after_90_days": 0,
"expire_between_31_and_60_days": 0,
"expire_between_61_and_90_days": 0,
"expire_in_30_days": 0,
"expired": 3,
"expired_in_notary_office": 0,
"expired_not_in_notary_office": 0,
"paid": 0,
"paid_after_due_date": 2,
"paid_before_due_date": 0,
"paid_on_due_date": 0,
"to_expire": 0,
"unpaid": 0
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# 申请票据补发
URL: /zh-Hans/documentation/boletos/consultar_v1/segunda_via_de_boleto
## Request
ENDPOINT /bank_slip/2-way/ BANK_SLIP_KEY
MÉTODO POST
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-----------------------------------------------------|--------|
| `bank_slip_key` | uuidv4 | 票据唯一标识键，格式为 uuid v4 | 36 |
## Response
STATUS 200
Response Body
```json
{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [
{
"barcode": "32998827300000003000001010000000000200670490",
"created_at": "2020-05-19T18:46:41",
"digitable_line": "32990001031000000000902006704908882730000000300",
"url": "https://linkparadownload.com/arquivo.pdf"
}
],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"bank_teller_instructions": "Boleto Teste",
"beneficiary_account_branch": "0001",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "67049",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"discount_limit_date": null,
"discount_value": null,
"document_number": "Parcela 1",
"expenses": [],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"nfe_key": null,
"nfe_url": null,
"occurrences": [...],
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_address": "Rua Carlos tampaio, 204",
"payer_document": "41651732825",
"payer_name": "Beatriz Couto",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"rebate_amount": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15"
}
```
STATUS 400
Response Body
```json
{
{"title": "Bad Request", "description": "Invalid request body.", "translation": "Corpo da requisição inválido.", "extra_fields": {}, "code": "LEG000069"}
}
```
---
# 单张 Boleto 发行（即时）
URL: /zh-Hans/documentation/boletos/emissao/emissao_boleto_unico_instantanea
:::danger 重要
要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::
对于即时注册单张 Boleto，创建请求的响应（同步响应）将直接返回已注册（或被拒绝）的 Boleto。Nuclea/CIP 对 Boleto 注册的确认/拒绝时间已包含在此端点的响应时间内。
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/instant
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|-----------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"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,
},
"financial_instrument_type": "digital_commercial_invoice",
"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": {"country_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": {"country_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": {"country_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_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4 | 36 |
| `our_number` | integer | Boleto 在钱包中的唯一识别编号，可由客户提供，若未提供则由 QI Tech 自动生成 | 11 |
| `document_number` | string | Boleto 识别编号，可为电子发票编号 | 10 |
| `participant_control_number` | string | 参与方控制号码 | 25 |
| `amount` * | float | Boleto 基准金额 | - |
| `expiration` * | string | 到期日 | 10 |
| `bank_teller_instructions` | string | 给付款方的备注。最多接受 320 个字符，分布在最多 7 行中。每行最多 90 个字符，若超过则自动换行 | 320 |
| `rebate_amount` | float | Boleto 减免金额，将在基准金额之上应用 | - |
| `max_payment_days` | integer | Boleto 到期后可供支付的最大自然日数（最多 365 天） | - |
| `financial_instrument_type` | string | Boleto 类型 | **[financial_instrument_type 枚举值](#enumeradores-financial_instrument_type)** |
| `partial_payment_data` | object | 部分支付配置 | **[partial_payment_data 对象](#objeto-partial_payment_data)** |
| `write_off_data` | object | 核销配置 | **[write_off_data 对象](#objeto-write_off_settings)** |
| `protest_data` | object | 抗议配置 | **[protest_data 对象](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object | 破产抗议配置 | **[bankruptcy_protest_data 对象](#objeto-bankruptcy_protest_settings)** |
| `fine_data` | object | 罚款配置 | **[fine_data 对象](#objeto-fine_settings)** |
| `interest_data` | object | 利息配置 | **[interest_data 对象](#objeto-interest_settings)** |
| `discounts_data` | object array | 折扣配置 | **[discount 对象](#objeto-discounts_data)** |
| `payer_data` * | object | 付款方数据 | **[payer_data 对象](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` | object | 担保人数据 | **[guarantor_data 对象](#objetos-payer_data-e-guarantor_data)** |
| `pix_key` | uuidv4 | 随机类型 Pix 密钥 | 36 |
:::info BolePix
若在请求中发送可选参数 `pix_key`，将生成 bolePix。bolePix 是一种付款与 Pix QR Code 绑定的 Boleto。付款方既可通过 Boleto 的可打印行付款，也可扫描关联的 Pix QR Code 付款。若通过 QR Code 付款，资金即时到账，而相关的银行回执和 Webhook 将与普通 Boleto 一样生成。
**重要提示：** 要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::
:::tip 钱包默认配置
若请求中未发送 `max_payment_days`、`write_off_data`、`protest_data`、`bankruptcy_protest_data`、`fine_data`、`interest_data` 和 `pix_key` 字段，且钱包中存在默认配置（即 `requester_profile` 的 `configuration_data` 中分别有 `max_payment_days`、`write_off_settings`、`protest_settings`、`bankruptcy_protest_settings`、`fine_settings`、`interest_settings` 和 `qr_code_settings`），则发行时将使用这些默认配置。
:::
:::caution 限制和约束
- **部分支付 Boleto：** 不允许通过 Pix QR Code 付款。因此，不允许在注册时发送 `pix_key`，也不允许为钱包设置 bolePix 生成的**默认配置**。
- **信用卡 Boleto：** 不需要也不允许发送减免、折扣、罚款和利息信息。这是因为市场惯例中，许多金融机构不接受包含这些信息的信用卡 Boleto 付款。钱包也不能将这些配置设为默认值。因此，此类 Boleto 即使在到期后也可部分支付，当前账单不产生利息、罚款、折扣或减免。若要应用这些值，需要在下一账单中包含，可通过 Boleto 的[金额编辑事件](/documentation/boletos/instrucoes/valor)或发行包含这些值的新 Boleto 来实现。此类 Boleto 可发送 `amount = 0`。
**重要提示：** `credit_card` 类型的 Boleto 必须支持部分支付，因此需要提供 `partial_payment_data` 信息或在钱包中设置此默认配置。若未发送 `financial_instrument_type` 字段，默认值为 `digital_commercial_invoice`。
:::
:::tip 钱包建议
- **标准 Boleto 钱包：** 保持罚款、利息和抗议的默认配置
- **部分支付 Boleto 钱包：** 无 Pix 配置，并设置部分支付规则
- **信用卡 Boleto 钱包：** 无罚款、利息、折扣或减免配置
创建专用钱包可确保每种类型 Boleto 的默认配置适当，并避免业务规则冲突。
:::
:::info 状态机
部分支付 Boleto 的状态机有所不同。详情请参阅**[简介](/documentation/boletos/introducao)**，其中包含如何按照市场最佳实践对 Boleto 应用利息和罚款的说明。
:::
### financial_instrument_type 枚举值
| 枚举值 | 描述 |
|------------------------------------|----------------------------------|
| digital_commercial_invoice | DMI 商业发票指定复本 |
| credit_card | 信用卡 |
| check | 支票 |
| digital_commercial | DM 商业复本 |
| digital_service_invoice | 服务复本 |
| digital_service_invoice_indication | DSI 服务复本指定 |
| digital_rural_invoice | DR 农村复本 |
| bill_of_exchange | LC 汇票 |
| commercial_credit_note | NCC 商业信贷票据 |
| export_credit_note | NCE 出口信贷票据 |
| industrial_credit_note | NCI 工业信贷票据 |
| rural_credit_note | NCR 农村信贷票据 |
| promissory_note | NP 本票 |
| rural_promissory_note | NPR 农村本票 |
| mercantile_triplicate | TM 商业三联单 |
| service_triplicate | TS 服务三联单 |
| insurance_note | NS 保险票据 |
| receipt | RC 收据 |
| printed_bank_slip | FAT 票据 |
| debit_note | ND 借记票据 |
| insurance_policy | AP 保险单 |
| school_monthly_fee | ME 学费月付款 |
| consortium_installment | PC 联合体分期付款 |
| invoice | NF 发票 |
| debt_document | DD 债务文件 |
| rural_product_certificate | 农村产品证书 |
| warrant | 权证 |
| state_active_debt | 州活跃债务 |
| municipal_active_debt | 市活跃债务 |
| federal_active_debt | 联邦活跃债务 |
| condominium_charges | 公寓费用 |
| proposal_bank_slip | 提案 Boleto |
| deposit_and_contribution_bank_slip | 存款和认购 Boleto |
| others | 其他 |
### partial_payment_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------------|---------|---------------------------|--------------------------------------------------------------------------------|
| `partial_payment_minimum_type` * | string | 部分支付最小金额类型 | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage` | float | 允许的最小部分支付百分比 | - |
| `partial_payment_minimum_amount` | float | 允许的最小部分支付金额 | - |
| `partial_payment_maximum_type` | string | 部分支付最大金额类型 | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage` | float | 允许的最大部分支付百分比 | - |
| `partial_payment_maximum_amount` | float | 允许的最大部分支付金额 | - |
| `partial_payment_quantity` * | integer | 允许的部分支付次数 | - |
:::caution 注意！
根据 `partial_payment_minimum_type` 和 `partial_payment_maximum_type` 字段发送的值，需要相应发送 `partial_payment_minimum_amount` 或 `partial_payment_minimum_percentage`，以及 `partial_payment_maximum_amount` 或 `partial_payment_maximum_percentage`。
:::
### partial_payment_type 枚举值
| 枚举值 | 描述 |
|----------|----------|
| absolute | 绝对金额 |
| percentage | 百分比 |
### write_off_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_write_off` * | integer | Boleto 到期后自动核销的天数 | - |
### protest_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_protest` * | integer | Boleto 到期后自动抗议的天数 | - |
### bankruptcy_protest_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|---------|-----------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | Boleto 到期后自动破产抗议的天数 | - |
### fine_data 对象
**选项 1：绝对值罚款（`fine_type=absolute`）**
| 字段 | 类型 | 描述 | 字符数 |
|------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_amount` * | float | 罚款绝对值 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
**选项 2：百分比罚款（`fine_type=percentage`）**
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | 罚款百分比，1 至 100 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
### fine_type 枚举值
| 枚举值 | 描述 |
|----------|----------|
| absolute | 绝对值 |
| percentage | 百分比 |
### interest_data 对象
**选项 1：绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）**
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|---------|---------------------------------------------|-------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_amount` * | float | 每单位时间（工作日或自然日）收取的利息金额 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
**选项 2：百分比利息（`interest_type=calendar_days_monthly_percentage`）**
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|------------------------------------------------|-------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | 每单位时间（工作日或自然日）收取的利息百分比 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
### interest_type 枚举值
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------|
| calendar_days_daily_amount | 按自然日计算的每日金额 |
| workdays_daily_amount | 按工作日计算的每日金额 |
| calendar_days_monthly_percentage | 按自然日计算的月利率百分比 |
### discount 对象
**选项 1：绝对值折扣**
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_amount` * | float | 每单位时间的绝对折扣金额 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 折扣类型（绝对值） | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣截止日期 | 10 |
**选项 2：百分比折扣**
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_percentage` * | float | 每单位时间的折扣百分比 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 折扣类型（百分比） | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣截止日期 | 10 |
:::caution 注意！
一张 Boleto 最多可有三个折扣，且**所有折扣必须为同一类型**，即具有相同的 `discount_type`。折扣编号必须从 1 开始，按递增顺序编号，**最大到 3**。
:::
### discount_type 枚举值
| 枚举值 | 描述 |
|--------------------------------------------|----------------------------------------|
| absolute | 固定金额 |
| anticipation_calendar_days_daily_amount | 按自然日计算的提前还款每日折扣金额 |
| anticipation_workdays_daily_amount | 按工作日计算的提前还款每日折扣金额 |
| percentage | 固定百分比 |
| anticipation_calendar_days_daily_percentage | 按自然日计算的提前还款月折扣百分比 |
| anticipation_workdays_daily_percentage | 按工作日计算的提前还款年折扣百分比 |
### payer_data 和 guarantor_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|--------|------------------------|----------------------------------------------------------------|
| `name` * | string | 全名 | 100 |
| `document_number` * | string | 证件号码（CPF/CNPJ） | 11 或 14 |
| `person_type` * | string | 人员类型 | **[person_type 枚举值](#enumeradores-person_type)** |
| `contact` | object | 联系信息 | **[contact 对象](#objeto-contact)** |
| `address` | object | 地址 | **[address 对象](#objeto-address)** |
### person_type 枚举值
| 枚举值 | 描述 |
|---------|--------|
| natural | 自然人 |
| legal | 法人 |
### contact 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------|--------|----------|---------------------------------------|
| `email` | string | 联系邮箱 | 320 |
| `phone` | object | 联系电话 | **[phone 对象](#objeto-phone)** |
### phone 对象
| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|----------------|--------|
| `country_code` * | string | 国际区号（DDI） | 3 |
| `area_code` * | string | 地区区号（DDD） | 2 |
| `number` * | string | 电话号码 | 9 |
### address 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|--------|----------------------------------------------------|
| `street` * | string | 街道 | 500 |
| `number` * | string | 门牌号 | 6 |
| `complement` | string | 补充 | 500 |
| `neighborhood` * | string | 社区 | 100 |
| `postal_code` * | string | 邮编 | 8 |
| `city` * | string | 城市 | 100 |
| `state` * | string | 州（UF） | **[state 枚举值](#enumeradores-state)** |
### state 枚举值
| 枚举值 | 描述 |
|------|----------------------|
| 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 | 其他 |
### notification 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|---------|--------------------------------------------|-----------|
| `document_number` * | string | 接收通知者的证件号码（CPF/CNPJ） | 11 或 14 |
| `name` * | string | 接收通知者姓名 | 100 |
| `email` | string | 通知发送邮箱 | 320 |
| `phone` | object | 通知发送联系电话 | **[phone 对象](#objeto-phone)** |
| `send_2_way` * | boolean | 发送副本 | - |
| `send_before_due_date` * | boolean | 在到期日前向付款方发送通知 | - |
| `send_after_due_date` * | boolean | Boleto 到期时向付款方发送通知 | - |
| `send_on_protest` * | boolean | 进入抗议流程时发送通知 | - |
## Response
STATUS 201
Response Body: 已注册 Boleto
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"bank_slip_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"bank_slip_status": "registered",
"our_number": 92580722204,
"barcode": "32998995900000892812147469258072220406456140",
"digitable_line": "32992147466925807222704064561402899590000089281",
"qr_code_data": {
"qr_code_key": "bc5cb30c-8f98-4273-b405-3546da1d8d7a",
"pix_key": "06797774-e050-419e-a91a-c64c919b52c7",
"receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
"url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/58fd5103a8e64bbbab2fd49b0bd580145204000053039865802BR5925GONNFUNDODEINVESTIMENTOEM6012RiodeJaneiro6107226401262070503***6304EA0D",
"image": ""
}
}
```
STATUS 202
Response Body: 待注册 Boleto
```json
{
"request_control_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
"bank_slip_key": "e8599844-5cad-40b4-8716-cb4770d415b4",
"bank_slip_status": "accepted"
}
```
:::info 说明
若返回 **HTTP Status 202** 且 `bank_slip_status` 值为 `accepted`，则不应重试发行。
此发行将异步处理。需要通过查询 Boleto 来验证状态，或等待接收[Webhook 页面](/documentation/boletos/v2/webhooks/boleto)中描述的确认 Webhook。
:::
### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|---------|----------------------------------------------------|----------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Boleto 唯一标识密钥，格式为 uuid v4 | 36 |
| `bank_slip_status` * | string | Boleto 状态 | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)** |
| `our_number` * | integer | Boleto 在钱包中的唯一识别编号 | 11 |
| `barcode` * | string | Boleto 条形码 | 44 |
| `digitable_line` * | string | Boleto 可打印行 | 47 |
| `qr_code_data` | object | QR Code 数据 | **[qr_code_data 对象](#objeto-qr_code_data)** |
| `created_at` * | string | 事件创建日期，ISO 格式（UTC - "YYYY-MM-DDTHH:MM:SSZ"） | 20 |
### bank_slip_status 枚举值
| 枚举值 | 描述 |
|----------|---------------------------|
| accepted | Boleto 已接受但尚未注册 |
| registered | Boleto 已注册 |
### qr_code_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|----------------------------------|--------|
| `qr_code_key` | uuidv4 | QR Code 唯一标识密钥 | 36 |
| `pix_key` | uuidv4 | 与 QR Code 关联的 PIX 密钥 | 36 |
| `receiver_conciliation_id` | uuidv4 | QR Code 对账标识符 | 36 |
| `url` | string | QR Code 的 URL（Pix 复制粘贴） | - |
| `image` | string | QR Code URL 的 base64 编码图片 | - |
## 错误响应
STATUS 4xx
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`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 can not be equal or greater than the bank slip amount. | O valor do rebate não pode ser igual ou maior do 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. |
| 400 | BKS000125 | Bad Request | Partial payment data is required for this bank slip species type. | Os dados de pagamento parcial são obrigatórios para o tipo de boleto fornecido. |
| 400 | BKS000128 | Bad Request | QR code payment is not allowed for partial payment. | Pagamento via QR code não é permitido para pagamento parcial. |
| 400 | BKS000131 | Bad Request | Rebate amount is not allowed for this bank slip species type. | O valor de abatimento não é permitido para o tipo de boleto fornecido. |
| 400 | BKS000132 | Bad Request | Discount data is not allowed for this bank slip species type. | Os dados de desconto não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000133 | Bad Request | Fine data is not allowed for this bank slip species type. | Os dados de multa não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000134 | Bad Request | Interest data is not allowed for this bank slip species type. | Os dados de juros não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000136 | Bad Request | Only credit card financial instrument type can have zero amount. | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero. |
---
# 单张 Boleto 发行（标准）
URL: /zh-Hans/documentation/boletos/emissao/emissao_boleto_unico_padrao
:::danger 重要
要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::
在标准 Boleto 注册流程中，若请求成功，响应将返回状态为 `accepted` 的 Boleto（Boleto 已被 QI Tech 接受）。Nuclea/CIP 确认或拒绝后，Boleto 将转为 `registered` 或 `rejected` 状态。
:::caution 注意！
由于这是异步注册，当 Boleto 状态从 `accepted` 变更为 `registered` 或 `rejected` 时，申请方将通过 [**Webhook**](/documentation/boletos/v2/webhooks/boleto) 收到通知。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|-----------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"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,
},
"financial_instrument_type": "digital_commercial_invoice",
"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": {"country_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": {"country_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": "4d25d8fc-0074-42bb-b0a4-dd12b1cd0e98",
"notification": {
"document_number": "12345678000195",
"name": "Global Tech",
"email": "finance@globaltech.com",
"phone": {"country_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
},
"split_payment_data": {
"beneficiary_settlement_percentage": 70,
"split_payment_rules": [
{
"percentage": 20,
"document_number": "12345678901",
"account_owner_name": "John Smith",
"account_number": "1234567",
"account_digit": "8"
},
{
"percentage": 10,
"document_number": "10987654321",
"account_owner_name": "Mary Johnson",
"account_number": "7654321",
"account_digit": "0"
}
]
}
}
```
### 请求体
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4 | 36 |
| `our_number` | integer | Boleto 在钱包中的唯一识别编号，可由客户提供，若未提供则由 QI Tech 自动生成 | 11 |
| `document_number` | string | Boleto 识别编号，可为电子发票编号 | 10 |
| `participant_control_number` | string | 参与方控制号码 | 25 |
| `amount` * | float | Boleto 基准金额 | - |
| `expiration` * | string | 到期日 | 10 |
| `bank_teller_instructions` | string | 给付款方的备注。最多接受 320 个字符，分布在最多 7 行中。每行最多 90 个字符，若超过则自动换行 | 320 |
| `rebate_amount` | float | Boleto 减免金额，将在基准金额之上应用 | - |
| `max_payment_days` | integer | Boleto 到期后可供支付的最大自然日数（最多 365 天） | - |
| `financial_instrument_type` | string | Boleto 类型 | **[financial_instrument_type 枚举值](#enumeradores-financial_instrument_type)** |
| `partial_payment_data` | object | 部分支付配置 | **[partial_payment_data 对象](#objeto-partial_payment_data)** |
| `write_off_data` | object | 核销配置 | **[write_off_data 对象](#objeto-write_off_settings)** |
| `protest_data` | object | 抗议配置 | **[protest_data 对象](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object | 破产抗议配置 | **[bankruptcy_protest_data 对象](#objeto-bankruptcy_protest_settings)** |
| `fine_data` | object | 罚款配置 | **[fine_data 对象](#objeto-fine_settings)** |
| `interest_data` | object | 利息配置 | **[interest_data 对象](#objeto-interest_settings)** |
| `discounts_data` | object array | 折扣配置 | **[discount 对象](#objeto-discounts_data)** |
| `payer_data` * | object | 付款方数据 | **[payer_data 对象](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` | object | 担保人数据 | **[guarantor_data 对象](#objetos-payer_data-e-guarantor_data)** |
| `pix_key` | uuidv4 | 随机类型 Pix 密钥 | 36 |
| `notification` | object | 付款方通知配置 | **[notification 对象](#objeto-notification)** |
| `split_payment_data` | object | Boleto 的信用分账（分账支付）配置 | **[split_payment_data 对象](#objeto-split_payment_data)** |
:::info BolePix
若在请求中发送可选参数 `pix_key`，将生成 bolePix。bolePix 是一种付款与 Pix QR Code 绑定的 Boleto。付款方既可通过 Boleto 的可打印行付款，也可扫描关联的 Pix QR Code 付款。若通过 QR Code 付款，资金即时到账，而相关的银行回执和 Webhook 将与普通 Boleto 一样生成。
**重要提示：** 要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::
:::tip 钱包默认配置
若请求中未发送 `max_payment_days`、`write_off_data`、`protest_data`、`bankruptcy_protest_data`、`fine_data`、`interest_data` 和 `pix_key` 字段，且钱包中存在默认配置，则发行时将使用这些默认配置。
:::
:::caution 限制和约束
- **部分支付 Boleto：** 不允许通过 Pix QR Code 付款。因此，不允许在注册时发送 `pix_key`，也不允许为钱包设置 bolePix 生成的**默认配置**。
- **信用卡 Boleto：** 不需要也不允许发送减免、折扣、罚款和利息信息。此类 Boleto 即使在到期后也可部分支付，当前账单不产生利息、罚款、折扣或减免。可发送 `amount = 0`。
**重要提示：** `credit_card` 类型的 Boleto 必须支持部分支付，若未发送 `financial_instrument_type` 字段，默认值为 `digital_commercial_invoice`。
:::
:::tip 钱包建议
- **标准 Boleto 钱包：** 保持罚款、利息和抗议的默认配置
- **部分支付 Boleto 钱包：** 无 Pix 配置，并设置部分支付规则
- **信用卡 Boleto 钱包：** 无罚款、利息、折扣或减免配置
创建专用钱包可确保每种类型 Boleto 的默认配置适当，并避免业务规则冲突。
:::
:::info 状态机
部分支付 Boleto 的状态机有所不同。详情请参阅**[简介](/documentation/boletos/introducao)**。
:::
### financial_instrument_type 枚举值
| 枚举值 | 描述 |
|------------------------------------|----------------------------------|
| digital_commercial_invoice | DMI 商业发票指定复本 |
| credit_card | 信用卡 |
| check | 支票 |
| digital_commercial | DM 商业复本 |
| digital_service_invoice | 服务复本 |
| digital_service_invoice_indication | DSI 服务复本指定 |
| digital_rural_invoice | DR 农村复本 |
| bill_of_exchange | LC 汇票 |
| commercial_credit_note | NCC 商业信贷票据 |
| export_credit_note | NCE 出口信贷票据 |
| industrial_credit_note | NCI 工业信贷票据 |
| rural_credit_note | NCR 农村信贷票据 |
| promissory_note | NP 本票 |
| rural_promissory_note | NPR 农村本票 |
| mercantile_triplicate | TM 商业三联单 |
| service_triplicate | TS 服务三联单 |
| insurance_note | NS 保险票据 |
| receipt | RC 收据 |
| printed_bank_slip | FAT 票据 |
| debit_note | ND 借记票据 |
| insurance_policy | AP 保险单 |
| school_monthly_fee | ME 学费月付款 |
| consortium_installment | PC 联合体分期付款 |
| invoice | NF 发票 |
| debt_document | DD 债务文件 |
| rural_product_certificate | 农村产品证书 |
| warrant | 权证 |
| state_active_debt | 州活跃债务 |
| municipal_active_debt | 市活跃债务 |
| federal_active_debt | 联邦活跃债务 |
| condominium_charges | 公寓费用 |
| proposal_bank_slip | 提案 Boleto |
| deposit_and_contribution_bank_slip | 存款和认购 Boleto |
| others | 其他 |
### split_payment_data 对象
用于配置 Boleto 的**信用分账**（分账支付），将结算金额在 Boleto 受益人和最多 10 个额外账户之间分配。目标账户必须为开通状态并已在 QI Tech 注册，且各项百分比之和（受益人 + 规则）必须正好等于 100。
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------------------|--------------|------------------------------------------------------------------------------------------------|------------|
| `beneficiary_settlement_percentage` * | float | 分配给 Boleto 受益人的结算金额百分比，取值范围 0 至 100 | - |
| `beneficiary_max_amount` | float | 受益人在结算时可获得的最大金额。当付款金额超过此限额时，超出部分将全部分配给 `split_payment_rules` 数组中的第一条规则。取值大于 0 且不大于 Boleto 金额 | - |
| `split_payment_rules` * | object array | 分账规则列表。最少 1 条，最多 10 条 | **[split_payment_rule 对象](#objeto-split_payment_rule)** |
#### split_payment_rule 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|----------|-------------------------------------------------------------------------------------|------------|
| `percentage` * | float | 分配给该账户的结算金额百分比，取值范围 0 至 100。当此规则专门用于接收 `beneficiary_max_amount` 之上的超出部分时，请使用 `0` | - |
| `document_number` * | string | 目标账户持有人的 CPF/CNPJ | 11 或 14 |
| `account_owner_name` * | string | 目标账户持有人姓名 | 100 |
| `account_number` * | string | 目标账户号 | 20 |
| `account_digit` * | string | 目标账户校验位 | 2 |
:::caution 注意！
- `beneficiary_settlement_percentage` 与 `split_payment_rules` 中各项百分比之和必须正好等于 **100**。
- `document_number` 在各规则之间必须唯一，且不得与受益人相同。
- 分账适用于 Boleto 的所有结算流程（SILOC、STR、公证处和 Pix QR Code）。
- 提供 `beneficiary_max_amount` 时，必须大于 0 且不大于 Boleto 金额。当任一规则的 `percentage = 0` 时，此字段必填。
- 每张 Boleto 仅允许**一条**规则的 `percentage = 0`（即超出部分的接收方）。
- 发行后，只要 Boleto 处于 `registered` 状态且尚未支付，可通过[**信用分账更新接口**](/documentation/boletos/instrucoes/rateio_de_credito)更新规则。
:::
:::tip 用例：将利息/滞纳金导向单独账户
若希望受益人始终收到 Boleto 面值，并由不同账户接收逾期付款产生的利息/滞纳金，请配置 `beneficiary_settlement_percentage = 100` + `beneficiary_max_amount = ` + 一条 `percentage = 0` 的规则，指向超出部分的接收账户。完整说明请参见 [**信用分账更新**](/documentation/boletos/instrucoes/rateio_de_credito#用例将逾期利息和滞纳金导向单独账户)。
:::
### partial_payment_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------------|---------|---------------------------|--------------------------------------------------------------------------------|
| `partial_payment_minimum_type` * | string | 部分支付最小金额类型 | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage` | float | 允许的最小部分支付百分比 | - |
| `partial_payment_minimum_amount` | float | 允许的最小部分支付金额 | - |
| `partial_payment_maximum_type` | string | 部分支付最大金额类型 | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage` | float | 允许的最大部分支付百分比 | - |
| `partial_payment_maximum_amount` | float | 允许的最大部分支付金额 | - |
| `partial_payment_quantity` * | integer | 允许的部分支付次数 | - |
:::caution 注意！
根据 `partial_payment_minimum_type` 和 `partial_payment_maximum_type` 字段发送的值，需要相应发送对应的金额或百分比字段。
:::
### partial_payment_type 枚举值
| 枚举值 | 描述 |
|----------|----------|
| absolute | 绝对金额 |
| percentage | 百分比 |
### write_off_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_write_off` * | integer | Boleto 到期后自动核销的天数 | - |
### protest_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_protest` * | integer | Boleto 到期后自动抗议的天数 | - |
### bankruptcy_protest_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|---------|-----------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | Boleto 到期后自动破产抗议的天数 | - |
### fine_data 对象
**选项 1：绝对值罚款（`fine_type=absolute`）**
| 字段 | 类型 | 描述 | 字符数 |
|------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_amount` * | float | 罚款绝对值 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
**选项 2：百分比罚款（`fine_type=percentage`）**
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | 罚款百分比，1 至 100 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
### fine_type 枚举值
| 枚举值 | 描述 |
|----------|----------|
| absolute | 绝对值 |
| percentage | 百分比 |
### interest_data 对象
**选项 1：绝对值利息**
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|---------|---------------------------------------------|-------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_amount` * | float | 每单位时间（工作日或自然日）收取的利息金额 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
**选项 2：百分比利息**
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|------------------------------------------------|-------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | 每单位时间（工作日或自然日）收取的利息百分比 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
### interest_type 枚举值
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------|
| calendar_days_daily_amount | 按自然日计算的每日金额 |
| workdays_daily_amount | 按工作日计算的每日金额 |
| calendar_days_monthly_percentage | 按自然日计算的月利率百分比 |
### discount 对象
**选项 1：绝对值折扣**
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_amount` * | float | 每单位时间的绝对折扣金额 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 折扣类型（绝对值） | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣截止日期 | 10 |
**选项 2：百分比折扣**
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_percentage` * | float | 每单位时间的折扣百分比 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 折扣类型（百分比） | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣截止日期 | 10 |
:::caution 注意！
一张 Boleto 最多可有三个折扣，且**所有折扣必须为同一类型**，折扣编号必须从 1 开始按递增顺序编号。
:::
### discount_type 枚举值
| 枚举值 | 描述 |
|--------------------------------------------|----------------------------------------|
| absolute | 固定金额 |
| anticipation_calendar_days_daily_amount | 按自然日计算的提前还款每日折扣金额 |
| anticipation_workdays_daily_amount | 按工作日计算的提前还款每日折扣金额 |
| percentage | 固定百分比 |
| anticipation_calendar_days_daily_percentage | 按自然日计算的提前还款月折扣百分比 |
| anticipation_workdays_daily_percentage | 按工作日计算的提前还款年折扣百分比 |
### payer_data 和 guarantor_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|--------|------------------------|----------------------------------------------------------------|
| `name` * | string | 全名 | 100 |
| `document_number` * | string | 证件号码（CPF/CNPJ） | 11 或 14 |
| `person_type` * | string | 人员类型 | **[person_type 枚举值](#enumeradores-person_type)** |
| `contact` | object | 联系信息 | **[contact 对象](#objeto-contact)** |
| `address` | object | 地址 | **[address 对象](#objeto-address)** |
### person_type 枚举值
| 枚举值 | 描述 |
|---------|--------|
| natural | 自然人 |
| legal | 法人 |
### contact 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------|--------|----------|---------------------------------------|
| `email` | string | 联系邮箱 | 320 |
| `phone` | object | 联系电话 | **[phone 对象](#objeto-phone)** |
### phone 对象
| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|----------------|--------|
| `country_code` * | string | 国际区号（DDI） | 3 |
| `area_code` * | string | 地区区号（DDD） | 2 |
| `number` * | string | 电话号码 | 9 |
### address 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|--------|----------------------------------------------------|
| `street` * | string | 街道 | 500 |
| `number` * | string | 门牌号 | 6 |
| `complement` | string | 补充 | 500 |
| `neighborhood` * | string | 社区 | 100 |
| `postal_code` * | string | 邮编 | 8 |
| `city` * | string | 城市 | 100 |
| `state` * | string | 州（UF） | **[state 枚举值](#enumeradores-state)** |
### state 枚举值
| 枚举值 | 描述 |
|------|----------------------|
| 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 | 其他 |
### notification 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|---------|--------------------------------------------|-----------|
| `document_number` * | string | 接收通知者的证件号码（CPF/CNPJ） | 11 或 14 |
| `name` * | string | 接收通知者姓名 | 100 |
| `email` | string | 通知发送邮箱 | 320 |
| `phone` | object | 通知发送联系电话 | **[phone 对象](#objeto-phone)** |
| `send_2_way` * | boolean | 发送副本 | - |
| `send_before_due_date` * | boolean | 在到期日前向付款方发送通知 | - |
| `send_after_due_date` * | boolean | Boleto 到期时向付款方发送通知 | - |
| `send_on_protest` * | boolean | 进入抗议流程时发送通知 | - |
## Response
STATUS 202
Response Body
```json
{
"request_control_key": "0d496b4d-01f6-48cd-8ec9-9ead1e43f156",
"bank_slip_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"bank_slip_status": "accepted",
"our_number": 67215548222,
"barcode": "32995995900000892811606496721554822228569790",
"digitable_line": "32991606429672155482022285697904599590000089281",
"qr_code_data": {
"qr_code_key": "a92b180a-4aa5-47c2-8a71-4e7bbb074410",
"pix_key": "4d25d8fc-0074-42bb-b0a4-dd12b1cd0e98",
"receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
"url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/58fd5103a8e64bbbab2fd49b0bd580145204000053039865802BR5925GONNFUNDODEINVESTIMENTOEM6012RiodeJaneiro6107226401262070503***6304EA0D",
"image": ""
}
}
```
### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|---------|----------------------------------------------------|----------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Boleto 唯一标识密钥，格式为 uuid v4 | 36 |
| `bank_slip_status` * | string | Boleto 状态 | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)** |
| `our_number` * | integer | Boleto 在钱包中的唯一识别编号 | 11 |
| `barcode` * | string | Boleto 条形码 | 44 |
| `digitable_line` * | string | Boleto 可打印行 | 47 |
| `qr_code_data` | object | QR Code 数据 | **[qr_code_data 对象](#objeto-qr_code_data)** |
| `created_at` * | string | 事件创建日期，ISO 格式（UTC - "YYYY-MM-DDTHH:MM:SSZ"） | 20 |
### bank_slip_status 枚举值
| 枚举值 | 描述 |
|----------|---------------------------|
| accepted | Boleto 已接受但尚未注册 |
### qr_code_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|----------------------------------|--------|
| `qr_code_key` | uuidv4 | QR Code 唯一标识密钥 | 36 |
| `pix_key` | uuidv4 | 与 QR Code 关联的 PIX 密钥 | 36 |
| `receiver_conciliation_id` | uuidv4 | QR Code 对账标识符 | 36 |
| `url` | string | QR Code 的 URL（Pix 复制粘贴） | - |
| `image` | string | QR Code URL 的 base64 编码图片 | - |
## 错误响应
STATUS 4xx
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`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 | 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 can not be equal or greater than the bank slip amount. | O valor do rebate não pode ser igual ou maior do 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. |
| 400 | BKS000125 | Bad Request | Partial payment data is required for this bank slip species type. | Os dados de pagamento parcial são obrigatórios para o tipo de boleto fornecido. |
| 400 | BKS000128 | Bad Request | QR code payment is not allowed for partial payment. | Pagamento via QR code não é permitido para pagamento parcial. |
| 400 | BKS000131 | Bad Request | Rebate amount is not allowed for this bank slip species type. | O valor de abatimento não é permitido para o tipo de boleto fornecido. |
| 400 | BKS000132 | Bad Request | Discount data is not allowed for this bank slip species type. | Os dados de desconto não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000133 | Bad Request | Fine data is not allowed for this bank slip species type. | Os dados de multa não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000134 | Bad Request | Interest data is not allowed for this bank slip species type. | Os dados de juros não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000136 | Bad Request | Only credit card financial instrument type can have zero amount. | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero. |
---
# 批量 Boleto 发行
URL: /zh-Hans/documentation/boletos/emissao/emissao_em_lote
:::danger 重要
要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::
批量 Boleto 发行仅以异步方式进行。若某张 Boleto 在验证所提供信息时失败，则同一请求中的所有 Boleto 均不会被注册。
:::caution 注意！
由于这是异步注册，当每张 Boleto 状态从 `accepted` 变更为 `registered` 或 `rejected` 时，申请方将通过 [**Webhook**](/documentation/boletos/v2/webhooks/boleto) 收到通知。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/batch
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|-----------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"bank_slips": [
{
"request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
"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,
},
"financial_instrument_type": "digital_commercial_invoice",
"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": "2025-01-01",
}
],
"payer_data": {
"name": "Global Tech",
"contact": {
"email": "finance@globaltech.com",
"phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
},
"address": {
"street": "101 High St.",
"neighborhood": "Tech Park",
"number": "202",
"postal_code": "49069234",
"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": {"country_code": "055", "area_code": "11", "number": "999999999"},
},
"address": {
"street": "202 Elm St.",
"neighborhood": "Quiet Neighborhood",
"number": "303",
"postal_code": "35700854",
"city": "Peaceful Town",
"state": "RJ",
"complement": "House 1",
},
"document_number": "23456789012",
"person_type": "natural",
},
"pix_key": "78252991-d26d-4d6b-8c50-be3233ffabf7",
"notification": {
"document_number": "12345678000195",
"name": "Global Tech",
"email": "finance@globaltech.com",
"phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
"send_2_way": true,
"send_before_due_date": true,
"send_after_due_date": true,
"send_on_protest": true
}
},
{
"request_control_key": "b3a428fd-58ee-4d6f-8872-633874ebf5e2",
"our_number": 987654321,
"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
},
"financial_instrument_type": "digital_commercial_invoice",
"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": "2025-01-01"
}
],
"payer_data": {
"name": "Global Tech",
"contact": {
"email": "finance@globaltech.com",
"phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
},
"address": {
"street": "101 High St.",
"neighborhood": "Tech Park",
"number": "202",
"postal_code": "79071231",
"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": {"country_code": "055", "area_code": "11", "number": "999999999"},
},
"address": {
"street": "202 Elm St.",
"neighborhood": "Quiet Neighborhood",
"number": "303",
"postal_code": "65066380",
"city": "Peaceful Town",
"state": "RJ",
"complement": "House 1"
},
"document_number": "23456789012",
"person_type": "natural"
}
}
]
}
```
### 请求体参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------------------------------------------------------------|------------------------|--------|
| `bank_slips` * | **[bank_slip 对象](#objeto-bank_slip)** 数组 | 待注册的 Boleto 列表 | - |
### bank_slip 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|--------------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4 | 36 |
| `our_number` | integer | Boleto 在钱包中的唯一识别编号，可由客户提供，若未提供则由 QI Tech 自动生成 | 11 |
| `document_number` | string | Boleto 识别编号 | 10 |
| `participant_control_number` | string | 参与方控制号码 | 25 |
| `amount` * | float | Boleto 基准金额 | - |
| `expiration` * | string | 到期日 | 10 |
| `bank_teller_instructions` | string | 注册附加说明，将显示在 Boleto PDF 中。最多接受 320 个字符，分布在最多 7 行中 | 320 |
| `rebate_amount` | float | Boleto 减免金额，将在基准金额之上应用 | - |
| `max_payment_days` | integer | Boleto 到期后可供支付的最大自然日数（最多 365 天） | - |
| `financial_instrument_type` | string | Boleto 类型 | **[financial_instrument_type 枚举值](#enumeradores-financial_instrument_type)** |
| `partial_payment_data` | object | 部分支付配置 | **[partial_payment_data 对象](#objeto-partial_payment_data)** |
| `write_off_data` | object | 核销配置 | **[write_off_data 对象](#objeto-write_off_settings)** |
| `protest_data` | object | 抗议配置 | **[protest_data 对象](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object | 破产抗议配置 | **[bankruptcy_protest_data 对象](#objeto-bankruptcy_protest_settings)** |
| `fine_data` | object | 罚款配置 | **[fine_data 对象](#objeto-fine_settings)** |
| `interest_data` | object | 利息配置 | **[interest_data 对象](#objeto-interest_settings)** |
| `discounts_data` | object array | 折扣配置 | **[discount 对象](#objeto-discounts_data)** |
| `payer_data` * | object | 付款方数据 | **[payer_data 对象](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` | object | 担保人数据 | **[guarantor_data 对象](#objetos-payer_data-e-guarantor_data)** |
| `pix_key` | uuidv4 | 随机类型 Pix 密钥 | 36 |
:::info BolePix
若在请求中发送可选参数 `pix_key`，将生成 bolePix。**重要提示：** 要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。
:::
:::tip 钱包默认配置
若请求中未发送 `max_payment_days`、`write_off_data`、`protest_data`、`bankruptcy_protest_data`、`fine_data`、`interest_data` 和 `pix_key` 字段，且钱包中存在默认配置，则发行时将使用这些默认配置。
:::
:::caution 限制和约束
- **部分支付 Boleto：** 不允许通过 Pix QR Code 付款。
- **信用卡 Boleto：** 不需要也不允许发送减免、折扣、罚款和利息信息。此类 Boleto 必须支持部分支付。若未发送 `financial_instrument_type` 字段，默认值为 `digital_commercial_invoice`。
:::
:::tip 钱包建议
- **标准 Boleto 钱包：** 保持罚款、利息和抗议的默认配置
- **部分支付 Boleto 钱包：** 无 Pix 配置，并设置部分支付规则
- **信用卡 Boleto 钱包：** 无罚款、利息、折扣或减免配置
:::
:::info 状态机
部分支付 Boleto 的状态机有所不同。详情请参阅**[简介](/documentation/boletos/introducao)**。
:::
### financial_instrument_type 枚举值
| 枚举值 | 描述 |
|------------------------------------|----------------------------------|
| digital_commercial_invoice | DMI 商业发票指定复本 |
| credit_card | 信用卡 |
| check | 支票 |
| digital_commercial | DM 商业复本 |
| digital_service_invoice | 服务复本 |
| digital_service_invoice_indication | DSI 服务复本指定 |
| digital_rural_invoice | DR 农村复本 |
| bill_of_exchange | LC 汇票 |
| commercial_credit_note | NCC 商业信贷票据 |
| export_credit_note | NCE 出口信贷票据 |
| industrial_credit_note | NCI 工业信贷票据 |
| rural_credit_note | NCR 农村信贷票据 |
| promissory_note | NP 本票 |
| rural_promissory_note | NPR 农村本票 |
| mercantile_triplicate | TM 商业三联单 |
| service_triplicate | TS 服务三联单 |
| insurance_note | NS 保险票据 |
| receipt | RC 收据 |
| printed_bank_slip | FAT 票据 |
| debit_note | ND 借记票据 |
| insurance_policy | AP 保险单 |
| school_monthly_fee | ME 学费月付款 |
| consortium_installment | PC 联合体分期付款 |
| invoice | NF 发票 |
| debt_document | DD 债务文件 |
| rural_product_certificate | 农村产品证书 |
| warrant | 权证 |
| state_active_debt | 州活跃债务 |
| municipal_active_debt | 市活跃债务 |
| federal_active_debt | 联邦活跃债务 |
| condominium_charges | 公寓费用 |
| proposal_bank_slip | 提案 Boleto |
| deposit_and_contribution_bank_slip | 存款和认购 Boleto |
| others | 其他 |
### partial_payment_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------------|---------|---------------------------|--------------------------------------------------------------------------------|
| `partial_payment_minimum_type` * | string | 部分支付最小金额类型 | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage` | float | 允许的最小部分支付百分比 | - |
| `partial_payment_minimum_amount` | float | 允许的最小部分支付金额 | - |
| `partial_payment_maximum_type` | string | 部分支付最大金额类型 | **[partial_payment_type 枚举值](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage` | float | 允许的最大部分支付百分比 | - |
| `partial_payment_maximum_amount` | float | 允许的最大部分支付金额 | - |
| `partial_payment_quantity` * | integer | 允许的部分支付次数 | - |
### partial_payment_type 枚举值
| 枚举值 | 描述 |
|----------|----------|
| absolute | 绝对金额 |
| percentage | 百分比 |
### write_off_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_write_off` * | integer | Boleto 到期后自动核销的天数 | - |
### protest_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|----------------------------------|--------|
| `days_to_protest` * | integer | Boleto 到期后自动抗议的天数 | - |
### bankruptcy_protest_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------|---------|-----------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | Boleto 到期后自动破产抗议的天数 | - |
### fine_data 对象
**选项 1：绝对值罚款（`fine_type=absolute`）**
| 字段 | 类型 | 描述 | 字符数 |
|------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_amount` * | float | 罚款绝对值 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
**选项 2：百分比罚款（`fine_type=percentage`）**
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|--------------------------|------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | 罚款百分比，1 至 100 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款的天数 | - |
### fine_type 枚举值
| 枚举值 | 描述 |
|----------|----------|
| absolute | 绝对值 |
| percentage | 百分比 |
### interest_data 对象
**选项 1：绝对值利息**
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|---------|---------------------------------------------|-------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_amount` * | float | 每单位时间（工作日或自然日）收取的利息金额 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
**选项 2：百分比利息**
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|------------------------------------------------|-------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | 每单位时间（工作日或自然日）收取的利息百分比 | - |
| `days_to_interest` * | integer | 到期后开始收取利息的天数 | - |
### interest_type 枚举值
| 枚举值 | 描述 |
|-----------------------------------|------------------------------------------|
| calendar_days_daily_amount | 按自然日计算的每日金额 |
| workdays_daily_amount | 按工作日计算的每日金额 |
| calendar_days_monthly_percentage | 按自然日计算的月利率百分比 |
### discount 对象
**选项 1：绝对值折扣**
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_amount` * | float | 每单位时间的绝对折扣金额 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 折扣类型（绝对值） | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣截止日期 | 10 |
**选项 2：百分比折扣**
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|-------------------------|----------------------------------------------------------------|
| `discount_percentage` * | float | 每单位时间的折扣百分比 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 折扣类型（百分比） | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣截止日期 | 10 |
:::caution 注意！
一张 Boleto 最多可有三个折扣，且**所有折扣必须为同一类型**，折扣编号必须从 1 开始按递增顺序编号。
:::
### discount_type 枚举值
| 枚举值 | 描述 |
|--------------------------------------------|----------------------------------------|
| absolute | 固定金额 |
| anticipation_calendar_days_daily_amount | 按自然日计算的提前还款每日折扣金额 |
| anticipation_workdays_daily_amount | 按工作日计算的提前还款每日折扣金额 |
| percentage | 固定百分比 |
| anticipation_calendar_days_daily_percentage | 按自然日计算的提前还款月折扣百分比 |
| anticipation_workdays_daily_percentage | 按工作日计算的提前还款年折扣百分比 |
### payer_data 和 guarantor_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|--------|------------------------|----------------------------------------------------------------|
| `name` * | string | 全名 | 100 |
| `document_number` * | string | 证件号码（CPF/CNPJ） | 11 或 14 |
| `person_type` * | string | 人员类型 | **[person_type 枚举值](#enumeradores-person_type)** |
| `contact` | object | 联系信息 | **[contact 对象](#objeto-contact)** |
| `address` | object | 地址 | **[address 对象](#objeto-address)** |
### person_type 枚举值
| 枚举值 | 描述 |
|---------|--------|
| natural | 自然人 |
| legal | 法人 |
### contact 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------|--------|----------|---------------------------------------|
| `email` | string | 联系邮箱 | 320 |
| `phone` | object | 联系电话 | **[phone 对象](#objeto-phone)** |
### phone 对象
| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------|----------------|--------|
| `country_code` * | string | 国际区号（DDI） | 3 |
| `area_code` * | string | 地区区号（DDD） | 2 |
| `number` * | string | 电话号码 | 9 |
### address 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|--------|----------------------------------------------------|
| `street` * | string | 街道 | 500 |
| `number` * | string | 门牌号 | 6 |
| `complement` | string | 补充 | 500 |
| `neighborhood` * | string | 社区 | 100 |
| `postal_code` * | string | 邮编 | 8 |
| `city` * | string | 城市 | 100 |
| `state` * | string | 州（UF） | **[state 枚举值](#enumeradores-state)** |
### state 枚举值
| 枚举值 | 描述 |
|------|----------------------|
| 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 | 其他 |
### notification 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|---------|--------------------------------------------|-----------|
| `document_number` * | string | 接收通知者的证件号码（CPF/CNPJ） | 11 或 14 |
| `name` * | string | 接收通知者姓名 | 100 |
| `email` | string | 通知发送邮箱 | 320 |
| `phone` | object | 通知发送联系电话 | **[phone 对象](#objeto-phone)** |
| `send_2_way` * | boolean | 发送副本 | - |
| `send_before_due_date` * | boolean | 在到期日前向付款方发送通知 | - |
| `send_after_due_date` * | boolean | Boleto 到期时向付款方发送通知 | - |
| `send_on_protest` * | boolean | 进入抗议流程时发送通知 | - |
## Response
STATUS 202
Response Body
```json
{
"bank_slips": [
{
"request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
"bank_slip_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"bank_slip_status": "accepted",
"our_number": 123456789,
"barcode": "32998995900000892812147469258072220406456140",
"digitable_line": "32992147466925807222704064561402899590000089281"
},
{
"request_control_key": "b3a428fd-58ee-4d6f-8872-633874ebf5e2",
"bank_slip_key": "4056f1f1-a6ea-4162-8bac-b1ce2546a9bf",
"bank_slip_status": "accepted",
"our_number": 987654321,
"barcode": "",
"digitable_line": ""
}
]
}
```
STATUS 4xx
### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|---------------------------------------------------------------------|-------------------------|--------|
| `bank_slips` | **[bank_slip_response 对象](#objeto-bank_slip_response)** 数组 | Boleto 列表 | - |
### bank_slip_response 对象
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|---------|----------------------------------------------------|----------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户请求唯一标识密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Boleto 唯一标识密钥，格式为 uuid v4 | 36 |
| `bank_slip_status` * | string | Boleto 状态 | **[bank_slip_status 枚举值](#enumeradores-bank_slip_status)** |
| `our_number` * | integer | Boleto 在钱包中的唯一识别编号 | 11 |
| `barcode` * | string | Boleto 条形码 | 44 |
| `digitable_line` * | string | Boleto 可打印行 | 47 |
| `qr_code_data` | object | QR Code 数据 | **[qr_code_data 对象](#objeto-qr_code_data)** |
| `created_at` * | string | 事件创建日期，ISO 格式（UTC - "YYYY-MM-DDTHH:MM:SSZ"） | 20 |
### bank_slip_status 枚举值
| 枚举值 | 描述 |
|----------|---------------------------|
| accepted | Boleto 已接受但尚未注册 |
### qr_code_data 对象
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|----------------------------------|--------|
| `qr_code_key` | uuidv4 | QR Code 唯一标识密钥 | 36 |
| `pix_key` | uuidv4 | 与 QR Code 关联的 PIX 密钥 | 36 |
| `receiver_conciliation_id` | uuidv4 | QR Code 对账标识符 | 36 |
| `url` | string | QR Code 的 URL（Pix 复制粘贴） | - |
| `image` | string | QR Code URL 的 base64 编码图片 | - |
## 错误响应
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`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 | 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 can not be equal or greater than the bank slip amount. | O valor do rebate não pode ser igual ou maior do 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. |
| 400 | BKS000125 | Bad Request | Partial payment data is required for this bank slip species type. | Os dados de pagamento parcial são obrigatórios para o tipo de boleto fornecido. |
| 400 | BKS000128 | Bad Request | QR code payment is not allowed for partial payment. | Pagamento via QR code não é permitido para pagamento parcial. |
| 400 | BKS000131 | Bad Request | Rebate amount is not allowed for this bank slip species type. | O valor de abatimento não é permitido para o tipo de boleto fornecido. |
| 400 | BKS000132 | Bad Request | Discount data is not allowed for this bank slip species type. | Os dados de desconto não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000133 | Bad Request | Fine data is not allowed for this bank slip species type. | Os dados de multa não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000134 | Bad Request | Interest data is not allowed for this bank slip species type. | Os dados de juros não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000136 | Bad Request | Only credit card financial instrument type can have zero amount. | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero. |
---
# 取消折让
URL: /zh-Hans/documentation/boletos/instrucoes/abatimento/cancelar_abatimento
取消折让意味着取消 Boleto 的现有折让。若有意移除折让或创建新折让，则需进行取消操作。
:::caution 注意！
若存在待确认的折让取消申请，或不存在活跃的折让，则无法申请取消折让。
**注意：** 在 Boleto 登记时发送的折让金额（`rebate_amount`）（若大于 R$0,00）视为活跃折让。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /cancel_rebate
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一识别密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"request_control_key": "86864aec-a6c8-462e-8460-b05ef5a1eb62"
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|------------------------------------------------|--------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4 | 36 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "539cefc8-382e-4fef-80e1-978a3a178a5c",
"bank_slip_key": "d402e91a-32ac-4428-8357-d71824b113b5"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
### 错误响应
STATUS 4xx
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`translation` |
|------------------------|--------------------|--------------------|------------------------------|---------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000031 | Bad Request | Bank slip must have an active rebate. | O boleto deve possuir um rebate ativo. |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000034 | Bad Request | There is already a pending cancel rebate occurrence for this bank slip. | Já existe uma ocorrência de cancelamento de rebate pendente para este boleto. |
---
# 创建折让
URL: /zh-Hans/documentation/boletos/instrucoes/abatimento/criar_abatimento
为 Boleto 创建折让意味着从票据基础金额中扣除部分金额，以减少最终付款金额。
:::caution 注意！
若存在待确认的折让申请或已有活跃的折让，则不允许创建新的折让。若有活跃折让且需要修改，必须先发送取消折让的请求。待确认后，方可创建另一个折让。
**注意：** 在 Boleto 登记时发送的折让金额（`rebate_amount`）不算作**待处理**的折让申请，但算作活跃的折让申请。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /rebate
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一识别密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"request_control_key": "d66b807a-25fa-4e21-b198-9beb221a29ce",
"rebate_amount": 150.00
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|------------------------------------------------|--------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4 | 36 |
| `rebate_amount` * | float | 折让绝对金额 | - |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "7f01165b-fdd0-4f59-b231-42170ea90131",
"bank_slip_key": "dad779c1-5e1c-422e-9f36-c704916a87cf"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
### 错误响应
STATUS 4xx
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`translation` |
|------------------------|--------------------|--------------------|------------------------------|---------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 409 | BKS000030 | Conflict | There is already a pending rebate occurrence for this bank slip. | Já existe uma ocorrência de rebate pendente para este boleto. |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000033 | Conflict | This bank slip already has an active rebate. You must send a 'cancel_rebate' occurrence before trying to create another one. | Este boleto já possui um rebate ativo. Você deve mandar uma ocorrência do tipo 'cancel_rebate' antes de tentar criar outro. |
| 400 | BKS000045 | Bad Request | Rebate amount can not be equal or greater than the bank slip amount. | O valor do rebate não pode ser igual ou maior do que o valor do boleto. |
---
# 注销
URL: /zh-Hans/documentation/boletos/instrucoes/baixa
当 Boleto 被注销时，将无法再用于付款，即 Boleto "已取消"。
:::caution 注意！
若存在待确认的注销申请，则不允许创建新的申请。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /write_off
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一识别密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|------------------------------------------------|--------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4 | 36 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
### 错误响应
STATUS 4xx
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`translation` |
|------------------------|--------------------|--------------------|------------------------------|---------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000049 | Conflict | There is already a pending write off occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. | Já existe uma ocorrência de baixa pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
---
# 折扣
URL: /zh-Hans/documentation/boletos/instrucoes/desconto
折扣指令用于应用具有多种计算规则的折扣。若相关 Boleto 已存在折扣，且折扣指令被接受，则原有折扣将被覆盖。
:::caution 注意！
若存在待确认的折扣添加申请，则不允许创建新的申请。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /discount
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一识别密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"request_control_key": "2e2f0053-a988-40c7-ad17-41c4c4da861e",
"discounts_data": [
{
"discount_type": "anticipation_workdays_daily_percentage",
"discount_percentage": 2,
"discount_number": 1,
"discount_limit_date": "2024-12-01"
},
{
"discount_type": "anticipation_workdays_daily_percentage",
"discount_percentage": 1,
"discount_number": 2,
"discount_limit_date": "2025-01-02"
}
]
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------------|------------------------------------------------|----------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4 | 36 |
| `discounts_data` | object array | 折扣 | **[discount 对象](#objeto-discounts_data)** |
### discount 对象
选项 1：绝对值折扣（`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`）
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------|---------|----------------------------------------|--------------------------------------------------------------------|
| `discount_amount` * | float | 按时间单位计的绝对折扣值 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 绝对值折扣配置 | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣应用截止日期 | 10 |
选项 2：百分比折扣（`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`）
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|----------------------------------------|--------------------------------------------------------------------|
| `discount_percentage` * | float | 按时间单位计的百分比折扣值 | - |
| `discount_number` * | integer | 折扣编号 | - |
| `discount_type` * | string | 百分比折扣配置 | **[discount_type 枚举值](#enumeradores-discount_type)** |
| `discount_limit_date` * | string | 折扣应用截止日期 | 10 |
:::caution 注意！
一张 Boleto 最多可有三个折扣，且**折扣必须为同一类型**，即必须具有相同的 `discount_type`。折扣必须按升序编号，从 **1 开始**。即，若请求中发送两个折扣，则必须编号为 1 和 2。
:::
### discount_type 枚举值
| 枚举值 | 描述 |
|--------------------------------------------|----------------------------------------|
| absolute | 固定值 |
| anticipation_calendar_days_daily_amount | 按自然日计的每日提前折扣值 |
| anticipation_workdays_daily_amount | 按工作日计的每日提前折扣值 |
| percentage | 固定百分比 |
| anticipation_calendar_days_daily_percentage | 按自然日计的月提前折扣百分比 |
| anticipation_workdays_daily_percentage | 按工作日计的年提前折扣百分比 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "aaf64135-6bd8-4d49-be6f-e8f884b20ee7",
"bank_slip_key": "470cfcae-159b-4de4-ad22-2d3b2dd717f7"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
### 错误响应
STATUS 4xx
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`translation` |
|------------------------|--------------------|--------------------|------------------------------|---------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 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 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 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 | BKS000046 | Bad Request | Invalid discount type. All types in the discount list must be the same. | Tipo de desconto inválido. Todos os tipos da lista de descontos devem ser iguais. |
| 409 | BKS000048 | Conflict | There is already a pending discount occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. | Já existe uma ocorrência de desconto pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
---
# 编辑
URL: /zh-Hans/documentation/boletos/instrucoes/edicao
编辑指令用于在票据发行后修改其可配置的数据，例如自动核销设置、抗议设置、破产抗议设置和付款人数据。该指令允许在单次请求中更新票据的多个方面。
:::caution 注意！
票据必须处于 `registered` 状态才能进行编辑。请求中除 `request_control_key` 外，至少必须提供一个数据字段（`write_off_data`、`protest_data`、`bankruptcy_protest_data` 或 `payer_data`）。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /bank_slip_edit
MÉTODO POST
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
Request Body
```json
{
"request_control_key": "c4dd443a-6e2f-4261-8f28-adfa4c0d4c5b",
"write_off_data": {"days_to_write_off": 365},
"protest_data": {"days_to_protest": 7},
"bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
"payer_data": {
"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",
},
},
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `write_off_data` | object | 自动核销设置（null 表示移除） | **[Objeto write_off_data](#objeto-write_off_data)** |
| `protest_data` | object | 抗议设置（null 表示移除） | **[Objeto protest_data](#objeto-protest_data)** |
| `bankruptcy_protest_data` | object | 破产抗议设置（null 表示移除） | **[Objeto bankruptcy_protest_data](#objeto-bankruptcy_protest_data)** |
| `payer_data` | object | 付款人数据（`address` 为 null 或 `contact` 为 null 表示移除对应字段） | **[Objeto payer_data](#objeto-payer_data)** |
:::info 说明
请求中至少必须提供一个数据字段（`write_off_data`、`protest_data`、`bankruptcy_protest_data` 或 `payer_data`）。
:::
### Objeto write_off_data
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_write_off` * | integer | 到期后自动核销票据的天数 | - |
### Objeto protest_data
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|---------------------------------------------|--------|
| `days_to_protest` * | integer | 到期后自动抗议票据的天数 | - |
### Objeto bankruptcy_protest_data
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------------|---------|---------------------------------------------------|--------|
| `days_to_bankruptcy_protest` * | integer | 到期后自动启动破产抗议流程的天数 | - |
### Objeto payer_data
| 字段 | 类型 | 描述 | 字符数 |
|-----------|--------|--------------|-------------------------------------------------------|
| `contact` | object | 联系信息 | **[Objeto contact](#objeto-contact)** |
| `address` | object | 地址 | **[Objeto address](#objeto-address)** |
### Objeto contact
| 字段 | 类型 | 描述 | 字符数 |
|---------|--------|--------------|----------------------------------------|
| `email` | string | 联系电子邮件 | 320 |
| `phone` | object | 联系电话 | **[Objeto phone](#objeto-phone)** |
### Objeto phone
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------------|--------|-------------------------|--------|
| `international_dial_code` * | string | 国际区号（DDI） | 3 |
| `area_code` * | string | 地区区号（DDD） | 2 |
| `number` * | string | 补充号码 | 9 |
### Objeto address
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|------------|--------|
| `street` * | string | 街道 | 500 |
| `number` * | string | 门牌号 | 6 |
| `complement` | string | 补充信息 | 500 |
| `neighborhood` * | string | 社区/街区 | 100 |
| `postal_code` * | string | 邮政编码 | 8 |
| `city` * | string | 城市 | 100 |
| `state` * | string | 州（UF） | **[Enumerador state](#enumeradores-state)** |
### Enumeradores state
| 枚举值 | 描述 |
|--------|-----------------------|
| 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 200
Response Body
```json
{
"occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
"bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` * | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
---
# 延期
URL: /zh-Hans/documentation/boletos/instrucoes/extensao
延期申请用于延长票据的到期日期。
:::caution 注意！
若存在待确认的延期申请，则不允许创建新的申请。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /extension
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一识别密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"request_control_key": "2e2f0053-a988-40c7-ad17-41c4c4da861e",
"new_expiration_date": "2025-01-01"
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|------------------------------------------------|--------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4 | 36 |
| `new_expiration_date` * | string | 新到期日期，格式为 "YYYY-MM-DD" | 10 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "6f2eb385-898f-4fa3-96df-80a76a30ad01",
"bank_slip_key": "0d462dda-7412-444f-ace9-375e4ab43c2f"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
### 错误响应
STATUS 4xx
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`translation` |
|------------------------|--------------------|--------------------|------------------------------|---------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 400 | BKS000041 | Bad Request | The new expiration date must be greater than the current expiration date. | A nova data de expiração deve ser posterior à data de expiração atual. |
| 409 | BKS000042 | Conflict | There is already a pending extension occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. | Já existe uma ocorrência de extensão pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
---
# 利息
URL: /zh-Hans/documentation/boletos/instrucoes/juros
利息指令用于配置在截止日期后付款时应收取的利息。若相关 Boleto 已存在利息配置，且利息指令被接受，则原有配置将被覆盖。
:::caution 注意！
若存在待确认的利息指令，则不允许发送新的指令。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /interest
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一识别密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"request_control_key": "c4dd443a-6e2f-4261-8f28-adfa4c0d4c5b",
"interest_data": {
"interest_type": "calendar_days_daily_amount",
"interest_amount": 50.00,
"days_to_interest": 5
}
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|------------------------------------------------|----------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4 | 36 |
| `interest_data` | object | 利息配置 | **[interest_data 对象](#objeto-interest_data)** |
### interest_data 对象
选项 1：绝对值利息（`interest_type=calendar_days_daily_amount` 或 `interest_type=workdays_daily_amount`）
| 字段 | 类型 | 描述 | 字符数 |
|----------------------|---------|----------------------------------------------------|----------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_amount` * | float | 按时间单位（工作日或自然日）收取的利息值 | - |
| `days_to_interest` * | integer | 到期后开始收取利息所需天数 | - |
选项 2：百分比利息（`interest_type=calendar_days_monthly_percentage`）
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|---------|------------------------------------------------|----------------------------------------------------------------|
| `interest_type` * | string | 利息类型 | **[interest_type 枚举值](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | 按时间单位（工作日或自然日）收取的利息百分比 | - |
| `days_to_interest` * | integer | 到期后开始收取利息所需天数 | - |
### interest_type 枚举值
| 枚举值 | 描述 |
|---------------------------------|--------------------------------|
| calendar_days_daily_amount | 按自然日计的每日金额 |
| workdays_daily_amount | 按工作日计的每日金额 |
| calendar_days_monthly_percentage | 按自然日计的月利率 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
"bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
### 错误响应
STATUS 4xx
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`translation` |
|------------------------|--------------------|--------------------|------------------------------|---------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000051 | Conflict | There is already a pending interest occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. | Já existe uma ocorrência de juros pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
---
# 查询指令批次
URL: /zh-Hans/documentation/boletos/instrucoes/lote/consultar_lote_de_instrucoes
返回先前创建批次的详情，包括所生成事件的列表、每个事件的状态以及对应 Boleto 的基本信息。
## Request
ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches/ BATCH_KEY /results
MÉTODO GET
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一识别密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4 | 36 |
| `batch_key` | uuidv4 | 批次密钥（由创建 POST 返回） | 36 |
## Response
STATUS 200
Response Body
```json
{
"batch_key": "f2d3e1b9-4a5c-46e7-8f12-9a8b7c6d5e4f",
"requester_profile_key": "8217da98-3e26-4ca5-8b86-698bfa50b0df",
"occurrence_type": "extension",
"occurrence_quantity": 2,
"accepted_quantity": 2,
"created_at": "2026-06-09T17:08:33Z",
"items": [
{
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5",
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
"occurrence_type": "extension",
"payer_name": "Global Tech",
"payer_document": "12345678000195",
"amount": 5000.00,
"our_number": "123456789",
"requester_occurrence_status": "accepted",
"registration_institution_occurrence_status": "submitted",
"created_at": "2026-06-09T17:08:33Z"
}
]
}
```
### Response Body Params
| 字段 | 类型 | 描述 |
|----------------------------|---------|-------------------------------------------------------------------------------|
| `batch_key` * | uuidv4 | 批次密钥 |
| `requester_profile_key` * | uuidv4 | 持有该批次的钱包密钥 |
| `occurrence_type` * | string | 批次的指令类型 |
| `occurrence_quantity` * | integer | 批次中发送的总项目数 |
| `accepted_quantity` * | integer | 批次中被接受的项目数 |
| `created_at` * | string | 批次的 UTC 创建时间（ISO 8601，含 `Z` 后缀） |
| `items` * | array | 批次生成的事件列表。详见 **[item 对象](#item-对象)** |
### item 对象
| 字段 | 类型 | 描述 |
|------------------------------------------------|---------|----------------------------------------------------------------------------|
| `bank_slip_key` * | uuidv4 | 事件对应的 Boleto 密钥 |
| `occurrence_key` * | uuidv4 | 创建事件的唯一密钥 |
| `request_control_key` * | string | 客户为该项目提供的控制密钥 |
| `occurrence_type` * | string | 指令类型 |
| `payer_name` | string | Boleto 付款人名称 |
| `payer_document` | string | 付款人证件号 |
| `amount` | float | Boleto 基础金额 |
| `our_number` | string | Boleto 的 "our number" |
| `requester_occurrence_status` | string | 请求方视角的事件状态（例如 `accepted`、`rejected`） |
| `registration_institution_occurrence_status` | string | 注册机构侧的事件处理状态（例如 `submitted`、`confirmed`） |
| `created_at` * | string | 事件的 UTC 创建时间（ISO 8601，含 `Z` 后缀） |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "标题",
"description": "description in English",
"translation": "descrição em português",
"code": "代码",
"extra_fields": {}
}
```
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英）
`description` | 描述（葡）
`translation` |
|------------------------|--------------------|--------------------|----------------------------------------|------------------------------------------|
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
:::caution 注意！
当 `batch_key` 不存在或不属于所提供的 `requester_profile_key` 时，API 同样返回 `BKS000013`（"Carteira não encontrada"）。请确认 `batch_key` 是否在所查询的钱包下创建。
:::
---
# 创建指令批次
URL: /zh-Hans/documentation/boletos/instrucoes/lote/criar_lote_de_instrucoes
通过单次请求，对多个不同的 Boleto 提交同一类型的指令（注销、折扣、展期、抗议等）。QI Tech 会对整个批次进行校验，要么所有项均被接受，要么全部不予处理。
- 若**任一**项未通过语义校验，则该批次**所有**项均不会被处理。错误响应会逐项说明拒绝原因。
- 若所有项均通过校验，相应的事件将异步创建并逐一处理。每当事件状态变更时，系统将通过 [**webhook**](/documentation/boletos/v2/webhooks/boleto) 通知请求方。
:::info 幂等性
批次级的 `request_control_key` 保证幂等性：重复使用同一密钥再次发送，将返回已创建的批次，不会重复创建。
每个项目也拥有自己的 `request_control_key`，并在项目级别保持幂等性。若再次使用已使用过的 `request_control_key` 提交项目，整个批次将被拒绝。
:::
:::caution 注意！
本操作仅适用于注册在 **QI SCD** 注册机构下的钱包。
:::
## Request
ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一识别密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"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
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------------------------------------|-----------------------------------------------------------------------|--------|
| `request_control_key` * | string | 客户定义的批次唯一密钥，用于保证批次的幂等性 | 1–64 |
| `occurrence_type` * | string | 应用于所有项目的指令类型。详见 **[occurrence_type 枚举](#occurrence_type-枚举)** | - |
| `items` * | **[item 对象](#item-对象)** 数组 | 指令列表（最少 1 项，最多 10000 项） | - |
### occurrence_type 枚举
| 枚举值 | 描述 |
|---------------------------|-----------------------------------------------------------------|
| `extension` | 到期日延期 —— 每项需提供 `new_due_date` |
| `rebate` | 应用折扣 —— 每项需提供 `rebate_amount` |
| `cancel_rebate` | 取消已应用的折扣 |
| `write_off` | 注销 Boleto |
| `protest_request` | 抗议申请 |
| `protest_cancel_request` | 撤回待处理的抗议申请 |
| `protest_remove_request` | 删除（取消）已登记的抗议 |
### item 对象
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|----------------------------------------------------------------------------|--------|
| `bank_slip_key` * | uuidv4 | 指令将应用的 Boleto 密钥 | 36 |
| `request_control_key` * | string | 客户定义的项目唯一密钥，用于保证项目级幂等性 | 1–64 |
| `new_due_date` | string | 新的到期日（`YYYY-MM-DD`）。当 `occurrence_type=extension` 时必填 | 10 |
| `rebate_amount` | float | 折扣金额。当 `occurrence_type=rebate` 时必填 | - |
## Response
STATUS 201
Response Body
```json
{
"batch_key": "f2d3e1b9-4a5c-46e7-8f12-9a8b7c6d5e4f",
"occurrence_quantity": 2,
"accepted_quantity": 2,
"semantic_errors": []
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|---------|------------------------------------------------------------------------------|--------|
| `batch_key` * | uuidv4 | 批次唯一密钥，用于查询批次详情 | 36 |
| `occurrence_quantity` * | integer | 批次中发送的总项目数 | - |
| `accepted_quantity` * | integer | 批次中被接受的项目数 | - |
| `semantic_errors` * | array | 成功时为空数组。语义校验失败时请参阅 **[Error Response](#error-response)** | - |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "标题",
"description": "description in English",
"translation": "descrição em português",
"code": "代码",
"extra_fields": {}
}
```
语义校验失败时（`BLP000112`），响应中的 `reasons` 字段会列出每个被拒绝的项目：
Response Body: 语义校验失败
```json
{
"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"
}
]
}
]
}
```
### `reasons[]` 对象字段
| 字段 | 类型 | 描述 |
|------------------------------|---------|-----------------------------------------------------------------------|
| `occurrence_sequence` * | string | 项目在请求 `items` 数组中的位置（从 `"0"` 开始） |
| `bank_slip_key` * | uuidv4 | 被拒项目对应的 Boleto 密钥 |
| `request_control_key` * | string | 客户为该项目提供的控制密钥 |
| `errors` * | array | 拒绝原因列表（同一项目可能存在多个原因） |
| `errors[].reason_code` * | string | 拒绝原因代码（Febraban 标准） |
| `errors[].translation_pt_br` | string | 原因的葡萄牙语描述 |
| `errors[].translation_en_us` | string | 原因的英语描述 |
| `errors[].created_at` | string | 原因在目录中的登记日期 |
### 错误代码
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英）
`description` | 描述（葡）
`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: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 422 | BLP000112 | Unprocessable Entity | Rejected Remittance | Remessa Rejeitada |
---
# 列出指令批次
URL: /zh-Hans/documentation/boletos/instrucoes/lote/listar_lotes_de_instrucoes
按分页方式列出某钱包下创建的指令批次，可按指令类型和日期范围进行筛选。
## Request
ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches
MÉTODO GET
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一识别密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4 | 36 |
### Query Parameters
| 字段 | 类型 | 描述 |
|-------------------|---------|---------------------------------------------------------------------------------------|
| `page` | integer | 查询页码（默认 `1`） |
| `page_size` | integer | 每页批次数量（默认 `20`，最大 `100`） |
| `occurrence_type` | string | 按指令类型筛选。可使用与创建 POST 相同的枚举 |
| `from_date` | string | 起始日期（含），格式 `YYYY-MM-DD`，对批次的 `created_at` 进行筛选 |
| `to_date` | string | 结束日期（含），格式 `YYYY-MM-DD`，对批次的 `created_at` 进行筛选 |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"batch_key": "f2d3e1b9-4a5c-46e7-8f12-9a8b7c6d5e4f",
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f",
"requester_profile_key": "8217da98-3e26-4ca5-8b86-698bfa50b0df",
"occurrence_type": "extension",
"occurrence_quantity": 14,
"accepted_quantity": 14,
"created_at": "2026-06-09T17:08:33Z"
}
],
"pagination": {
"page": 1,
"page_size": 20,
"total": 1
}
}
```
### Response Body Params
| 字段 | 类型 | 描述 |
|-----------------------------------|---------|-----------------------------------------------------------------------|
| `data` * | array | 当前页的批次列表 |
| `data[].batch_key` * | uuidv4 | 批次密钥 |
| `data[].request_control_key` * | string | 创建批次时客户提供的控制密钥 |
| `data[].requester_profile_key` * | uuidv4 | 持有该批次的钱包密钥 |
| `data[].occurrence_type` * | string | 批次的指令类型 |
| `data[].occurrence_quantity` * | integer | 批次中发送的总项目数 |
| `data[].accepted_quantity` * | integer | 批次中被接受的项目数 |
| `data[].created_at` * | string | 批次的 UTC 创建时间（ISO 8601，含 `Z` 后缀） |
| `pagination` * | object | 分页元数据 |
| `pagination.page` * | integer | 当前页 |
| `pagination.page_size` * | integer | 每页大小 |
| `pagination.total` * | integer | 符合筛选条件的批次总数 |
### Error Response
STATUS 4xx
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英）
`description` | 描述（葡）
`translation` |
|------------------------|--------------------|--------------------|------------------------------|------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
---
# 罚款
URL: /zh-Hans/documentation/boletos/instrucoes/multa
罚款指令用于配置在截止日期后付款时应收取的罚款。若相关 Boleto 已存在罚款配置，且罚款指令被接受，则原有配置将被覆盖。
:::caution 注意！
若存在待确认的罚款指令，则不允许发送新的指令。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /fine
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|--------|----------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一识别密钥，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"request_control_key": "c4dd443a-6e2f-4261-8f28-adfa4c0d4c5b",
"fine_data": {
"fine_type": "absolute",
"fine_amount": 50.00,
"days_to_fine": 5
}
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------------|--------|------------------------------------------------|----------------------------------------------------------------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一识别密钥，格式为 uuid v4 | 36 |
| `interest_data` | object | 罚款配置 | **[fine_data 对象](#objeto-fine_data)** |
### fine_data 对象
选项 1：绝对值罚款（`fine_type=absolute`）
| 字段 | 类型 | 描述 | 字符数 |
|------------------|---------|---------------------------------------------|----------------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_amount` * | float | 罚款绝对值 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款所需天数 | - |
选项 2：百分比罚款（`fine_type=percentage`）
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|---------|----------------------------------------|----------------------------------------------------------------|
| `fine_type` * | string | 罚款类型 | **[fine_type 枚举值](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | 罚款百分比，1 到 100 | - |
| `days_to_fine` * | integer | 到期后开始收取罚款所需天数 | - |
### fine_type 枚举值
| 枚举值 | 描述 |
|-----------|------------|
| absolute | 绝对值 |
| percentage | 百分比 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "aaf64135-6bd8-4d49-be6f-e8f884b20ee7",
"bank_slip_key": "470cfcae-159b-4de4-ad22-2d3b2dd717f7"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 事件（指令）唯一识别密钥，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Boleto 唯一识别密钥，格式为 uuid v4 | 36 |
### 错误响应
STATUS 4xx
Response Body: 错误
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`translation` |
|------------------------|--------------------|--------------------|------------------------------|---------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000050 | Conflict | There is already a pending fine occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. | Já existe uma ocorrência de multa pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
---
# 部分付款
URL: /zh-Hans/documentation/boletos/instrucoes/pagamento_parcial
部分付款指令允许修改票据的部分付款配置，前提是票据已登记且启用了部分付款功能。若票据已有部分付款配置，接受新指令后，原有配置将被覆盖。
:::caution 注意！
若存在待确认的部分付款指令，则不允许发送新的指令。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /partial_payment
MÉTODO POST
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
Request Body
```json
{
"request_control_key": "01234567-89ab-cdef-0123-456789abcdef",
"partial_payment_data": {
"partial_payment_minimum_type": "absolute",
"partial_payment_minimum_amount": 50.00,
"partial_payment_maximum_type": "absolute",
"partial_payment_maximum_amount": 1000.00,
"partial_payment_quantity": 3
}
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `partial_payment_data` * | object | 部分付款配置 | **[Objeto partial_payment_data](#objeto-partial_payment_data)** |
### Objeto partial_payment_data
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------------|---------|-----------------------------------------------|--------|
| `partial_payment_minimum_type` * | string | 部分付款最小金额类型 | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage` | float | 部分付款允许的最小百分比 | - |
| `partial_payment_minimum_amount` | float | 部分付款允许的最小金额 | - |
| `partial_payment_maximum_type` | string | 部分付款最大金额类型 | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage` | float | 部分付款允许的最大百分比 | - |
| `partial_payment_maximum_amount` | float | 部分付款允许的最大金额 | - |
| `partial_payment_quantity` * | integer | 允许的部分付款次数 | - |
:::caution 注意！
根据 `partial_payment_minimum_type` 和 `partial_payment_maximum_type` 字段的值，需要相应发送 `partial_payment_minimum_amount` 或 `partial_payment_minimum_percentage`，以及 `partial_payment_maximum_amount` 或 `partial_payment_maximum_percentage`。
:::
### Enumeradores partial_payment_type
| 枚举值 | 描述 |
|-------------|----------|
| absolute | 绝对值 |
| percentage | 百分比 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
"bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` * | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000126 | Conflict | There is already a pending partial payment occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. | Já existe uma ocorrência de pagamento parcial pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
| 400 | BKS000127 | Bad Request | Partial payment data is not set for this bank slip. | Os dados de pagamento parcial não estão configurados para este boleto. |
---
# 查询抗议工具文件
URL: /zh-Hans/documentation/boletos/instrucoes/protesto/consulta_instrumento_de_protesto
抗议工具文件是公证处在抗议执行过程中发出的官方文件，用于证明催收程序已执行。该文件在抗议完成后发出，前提是债务人在被通知后未支付债务。
:::caution 注意！
只有在票据**被实际抗议**（`protest_status` 值为 `protested`）之后，才能查询抗议工具文件。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_instrument
MÉTODO GET
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
## Response
STATUS 200
Response Body
```json
{
"bank_slip_key": "bc34e9b1-42e4-4f17-bfc0-c88f29d5230e",
"file_url": "https://storage.googleapis.com/live-bank-slip-api/protest_instrument/bc34e9b1-42e4-4f17-bfc0-c88f29d5230e.pdf"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|---------|-----------------------------------------------------|--------|
| `bank_slip_key` * | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
| `file_url` * | string | 包含抗议工具文件（PDF）的文件 URL | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000081 | Bad Request | The protest instrument will be available only after bank slip's protest confirmation. | O instrumento de protesto só estará disponível após a confirmação do protesto do título. |
| 500 | BKS000105 | Internal Server Error | Could not fetch protest instrument for the given 'bank_slip_key' at this moment. Please, try again later. | Não foi possível recuperar o instrumento de protesto para a chave ('bank_slip_key') fornecida. Por favor, tente novamente mais tarde. |
| 404 | BKS000106 | Not Found | No protest found for the given bank slip. | Nenhum protesto foi encontrado para o boleto fornecido. |
---
# 通过键查询抗议
URL: /zh-Hans/documentation/boletos/instrucoes/protesto/consulta_por_chave
通过键查询抗议，可返回有关该抗议的详细信息。
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /protest/ BANK_SLIP_KEY
MÉTODO GET
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
## Response
STATUS 200
Response Body
```json
{
"protest_key": "bc34e9b1-42e4-4f17-bfc0-c88f29d5230e",
"request_control_key": "59515878-50e9-466b-b40d-1aac3939c3fd",
"protest_status": "protested",
"bank_slip_key": "7d3d262b-9b55-44cd-8355-2f00d5b1d142",
"requester_profile_code": "329-09-0001-1467576",
"protest_type": "protest",
"protocol_number": "0000672016",
"protocol_date": "2012-12-16",
"notary_office": {
"city": "VITORIA",
"uf": "ES"
}
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------|--------------------------------------------------|
| `protest_key` * | uuidv4 | 抗议唯一标识键，uuid v4 格式 | 36 |
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `protest_status` * | string | 抗议状态 | **[Enumeradores protest_status](#enumeradores-protest_status)** |
| `bank_slip_key` * | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_code` * | string | 钱包唯一识别码 | 10 |
| `protest_type` * | string | 抗议类型 | **[Enumeradores protest_type](#enumeradores-protest_type)** |
| `protocol_number` | string | 协议号码 | 10 |
| `protocol_date` | string | 协议日期（格式"YYYY-MM-DD"） | 10 |
| `notary_office` | object | 公证处数据 | **[Objeto notary_office](#objeto-notary_office)** |
### Enumeradores protest_status
| 枚举值 | 描述 |
|------------------------------|----------------------------------------------------------|
| accepted | 已接受，但尚未发送至公证处 |
| submitted | 已发送至公证处 |
| cancellation_requested | 已申请中止抗议 |
| cancelled | 发送已取消，或抗议已中止 |
| rejected | 抗议申请被拒绝 |
| at_notary_office | 在公证处，处于三日期间 |
| paid_at_notary_office | 票据已在公证处支付 |
| protested | 票据已被抗议并核销 |
| removal_requested | 票据已被抗议，已申请取消 |
| removed | 抗议已取消 |
### Enumeradores protest_type
| 枚举值 | 描述 |
|----------------------|--------------|
| protest | 普通抗议 |
| bankruptcy_protest | 破产抗议 |
### Objeto notary_office
| 字段 | 类型 | 描述 | 字符数 |
|-----------|--------|----------------------|--------|
| `city` * | string | 公证处所在城市 | - |
| `uf` * | string | 公证处所在州（UF） | 2 |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 404 | BKS000106 | Not Found | No protest found for the given bank slip. | Nenhum protesto foi encontrado para o boleto fornecido. |
---
# 撤回（中止）抗议
URL: /zh-Hans/documentation/boletos/instrucoes/protesto/desistencia_de_protesto
可以通过发送 `protest_cancel_request` 指令来撤回抗议申请。
:::caution 注意！
`protest_cancel_request` 记录本身不会核销票据。若公证处的退出由 `protest_cancel_request` 类型的记录触发，则会创建一条 `notary_office_exit` 记录，该记录会发送至 CIP/Nuclea 以解除票据的支付冻结。确认后，票据可再次通过可输入行进行支付。若希望在撤回抗议后同时核销票据，建议发送[**撤回抗议并核销票据**](/documentation/boletos/instrucoes/protesto/desistencia_de_protesto_e_baixa_do_boleto)指令。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_cancel_request
MÉTODO POST
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
Request Body
```json
{
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` * | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000019 | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 400 | BKS000076 | Bad Request | Bank slip must have an ongoing protest request. | O boleto deve ter um pedido de protesto em vigência. |
| 400 | BKS000077 | Bad Request | Invalid bank slip protest status to cancel protest request. | Status de protesto do boleto inválido para desistir do pedido de protesto. |
---
# 撤回（中止）抗议并核销票据
URL: /zh-Hans/documentation/boletos/instrucoes/protesto/desistencia_de_protesto_e_baixa_do_boleto
撤回抗议申请的另一种方式是发送 `protest_cancel_and_write_off_request` 指令。
:::caution 注意！
`protest_cancel_and_write_off_request` 指令还会在 CIP/Nuclea 中核销票据。确认后，将自动创建 `write_off` 记录并发送至 Nuclea。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_cancel_and_write_off_request
MÉTODO POST
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
Request Body
```json
{
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` * | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000019 | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 400 | BKS000076 | Bad Request | Bank slip must have an ongoing protest request. | O boleto deve ter um pedido de protesto em vigência. |
| 400 | BKS000077 | Bad Request | Invalid bank slip protest status to cancel protest request. | Status de protesto do boleto inválido para desistir do pedido de protesto. |
---
# 简介
URL: /zh-Hans/documentation/boletos/instrucoes/protesto/introducao
## 公证处抗议
公证处抗议申请可在票据到期日之后提出，用于要求付款人在公证处偿还票款。若付款人未履行，将在其名下进行公开的违约登记，并将其姓名列入 Serasa 等信用保护机构。
## 抗议流程
### 抗议申请
票据的抗议流程始于一次**抗议申请**：类型为 `protest_request` 的指令。一旦 CIP/Nuclea 接受了抗议申请（`protest_request` 指令得到确认），票据将被冻结支付，这意味着付款人只能在公证处进行支付。同时，还会创建一条 `notary_office_entry` 记录，用于将抗议申请发送至公证处。抗议申请的汇款每天上午 9 点发送至公证处，因此，若在该时间之后收到抗议申请指令，则将在次日发送至公证处。
在随后的几天内，公证处需确认票据已进入公证处（`notary_office_entry` 记录得到确认），随后进入三日期间。三日期间是付款人在公证处支付票款的 3 个工作日期限，若未能支付，票据将被抗议。若票据在公证处支付，则会为该票据创建 `notary_office_payment_notice` 类型的记录，并在次日完成清算。在后一种情况下，还会自动生成 `payment_write_off` 指令，以便在 CIP/Nuclea 核销票据。
若三日期间结束，票据未被支付且未申请撤回抗议，票据将被抗议。此时，将生成 `protest_write_off` 指令，在 CIP/Nuclea 中核销票据，票据的生命周期随之结束。
### 撤回（中止）抗议申请
若付款人与背书人之间的纠纷在票据被实际抗议之前（即三日期间最后一天之前）直接解决，可以发送 `protest_cancel_request` 指令撤回抗议申请；或发送 `protest_cancel_and_write_off_request` 指令，同时撤回抗议申请并在 CIP/Nuclea 中核销票据。值得注意的是，`protest_cancel_request` 记录本身不会核销票据。若公证处的退出由 `protest_cancel_request` 类型的记录触发，则会创建一条 `notary_office_exit` 记录，该记录会发送至 CIP/Nuclea 以解除票据的支付冻结。确认后，票据可再次通过可输入行进行支付。另一方面，若公证处的退出由 `protest_cancel_and_write_off_request` 类型的记录触发，则会自动创建 `write_off` 记录，在 CIP/Nuclea 中核销票据。
### 撤销（取消）抗议申请
若票据已被抗议后，付款人与背书人之间的纠纷才得以解决，可以发送 `protest_remove_request` 类型的指令，该指令会撤销公开的违约登记以及与该票据相关的一切损害付款人名誉的记录。若记录得到确认（被公证处接受），抗议将被撤销，且由于票据已在 CIP/Nuclea 中核销，不会再为该票据创建任何其他指令。
---
# 列出抗议
URL: /zh-Hans/documentation/boletos/instrucoes/protesto/listar_protestos
抗议列表将返回符合请求中发送的 查询参数 的所有钱包票据公证处抗议记录。
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /protests
MÉTODO GET
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
### Query parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|--------------------------------------------------------|--------------------------|
| `protest_key` | uuidv4 | 抗议唯一标识键，uuid v4 格式 | 36 |
| `request_control_key` | uuidv4 | 请求唯一标识键，uuid v4 格式 | 36 |
| `protest_status` | string | 抗议状态 | **[Enumeradores protest_status](#enumeradores-protest_status)** |
| `bank_slip_key` | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
| `protocol_number` | string | 协议号码 | 36 |
| `protocol_date` | string | 协议日期（格式"YYYY-MM-DD"） | 10 |
| `page_size` | integer | 每页大小 | - |
| `from_date` | string | 起始日期（格式"YYYY-MM-DD"） | 10 |
| `to_date` | string | 结束日期（格式"YYYY-MM-DD"） | 10 |
### Enumeradores protest_status
| 枚举值 | 描述 |
|------------------------------|----------------------------------------------------------|
| accepted | 已接受，但尚未发送至公证处 |
| submitted | 已发送至公证处 |
| cancellation_requested | 已申请中止抗议 |
| cancelled | 发送已取消，或抗议已中止 |
| rejected | 抗议申请被拒绝 |
| at_notary_office | 在公证处，处于三日期间 |
| paid_at_notary_office | 票据已在公证处支付 |
| protested | 票据已被抗议并核销 |
| removal_requested | 票据已被抗议，已申请取消 |
| removed | 抗议已取消 |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"protest_key": "ad44278d-7cf1-4ac7-9545-410649a47dde",
"request_control_key": "7e40ebab-f00c-4dbf-88be-ff34434ab358",
"protest_status": "protested",
"bank_slip_key": "7bf086ac-f520-4498-abd4-5a7d2173fd1c",
"requester_profile_code": "329-09-0001-1467576",
"protest_type": "protest",
"protocol_number": "0000000004",
"protocol_date": "2024-11-27",
"notary_office": {
"city": "SAO PAULO",
"uf": "SP"
}
},
{
"protest_key": "0087f425-5e54-4b4c-ab17-a57bc80f223a",
"request_control_key": "c413cedc-78ac-4deb-ace8-d94d4e98197c",
"protest_status": "at_notary_office",
"bank_slip_key": "e345c0b3-012b-4a4b-9d6b-6981f40b1a7c",
"requester_profile_code": "329-09-0001-1467576",
"protest_type": "protest",
"protocol_number": "0000000016",
"protocol_date": "2024-12-10",
"notary_office": {
"city": "RIO DE JANEIRO",
"uf": "RJ"
}
},
{
"protest_key": "bc34e9b1-42e4-4f17-bfc0-c88f29d5230e",
"request_control_key": "59515878-50e9-466b-b40d-1aac3939c3fd",
"protest_status": "accepted",
"bank_slip_key": "7d3d262b-9b55-44cd-8355-2f00d5b1d142",
"requester_profile_code": "329-09-0001-1467576",
"protest_type": "protest"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|--------------------|--------------------------------------------|
| `data` * | object array | 抗议列表 | **[Objeto protest](#objeto-protest)** |
| `pagination` * | object | 分页信息 | **[Objeto pagination](#objeto-pagination)**|
### Objeto protest
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------|--------------------------------------------------|
| `protest_key` * | uuidv4 | 抗议唯一标识键，uuid v4 格式 | 36 |
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `protest_status` * | string | 抗议状态 | **[Enumeradores protest_status](#enumeradores-protest_status)** |
| `bank_slip_key` * | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_code` * | string | 钱包唯一识别码 | 10 |
| `protest_type` * | string | 抗议类型 | **[Enumeradores protest_type](#enumeradores-protest_type)** |
| `protocol_number` | string | 协议号码 | 10 |
| `protocol_date` | string | 协议日期（格式"YYYY-MM-DD"） | 10 |
| `notary_office` | object | 公证处数据 | **[Objeto notary_office](#objeto-notary_office)** |
### Objeto pagination
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------|--------------------------------------------------------------|
| `current_page` * | integer | 当前页码 | - |
| `rows_per_page` * | integer | 每页记录数 | - |
### Enumeradores protest_type
| 枚举值 | 描述 |
|----------------------|--------------|
| protest | 普通抗议 |
| bankruptcy_protest | 破产抗议 |
### Enumeradores protest_status
| 枚举值 | 描述 |
|------------------------------|----------------------------------------------------------|
| accepted | 已接受，但尚未发送至公证处 |
| submitted | 已发送至公证处 |
| cancellation_requested | 已申请中止抗议 |
| cancelled | 发送已取消，或抗议已中止 |
| rejected | 抗议申请被拒绝 |
| at_notary_office | 在公证处，处于三日期间 |
| paid_at_notary_office | 票据已在公证处支付 |
| protested | 票据已被抗议并核销 |
| removal_requested | 票据已被抗议，已申请取消 |
| removed | 抗议已取消 |
### Objeto notary_office
| 字段 | 类型 | 描述 | 字符数 |
|-----------|--------|----------------------|--------|
| `city` * | string | 公证处所在城市 | - |
| `uf` * | string | 公证处所在州（UF） | 2 |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 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. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
---
# 抗议申请
URL: /zh-Hans/documentation/boletos/instrucoes/protesto/pedido_de_protesto
公证处抗议申请可在票据到期日之后提出，用于要求付款人在公证处偿还票款。若付款人未履行，将在其名下进行公开的违约登记，并将其姓名列入 Serasa 等信用保护机构。
:::caution 注意！
发送抗议申请时，票据中必须包含付款人的地址。 若地址不存在，可发送票据编辑指令进行补充。此外，若票据已处于抗议流程中，则不允许发送新的抗议申请。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_request
MÉTODO POST
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
Request Body
```json
{
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f",
"protest_type": "protest"
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `protest_type` * | string | 抗议类型（普通或破产） | **[Enumeradores protest_type](#enumeradores-protest_type)** |
### Enumeradores protest_type
| 枚举值 | 描述 |
|----------------------|--------------|
| protest | 普通抗议 |
| bankruptcy_protest | 破产抗议 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` * | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000019 | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000028 | Not Found | Notary office attended region not found for postal code: `` | Região de cartório não encontrada para o CEP: `` |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000075 | Conflict | An open protest request already exists for the given 'bank_slip_key'. | Já existe um pedido de protesto em aberto para a 'bank_slip_key' fornecida. |
| 400 | BKS000080 | Bad Request | A protest request can only be sent after bank slip's business expiration date. | Um pedido de protesto só pode ser enviado após o dia útil de expiração do boleto. |
---
# 撤销抗议
URL: /zh-Hans/documentation/boletos/instrucoes/protesto/sustacao_de_protesto
如果付款人和出票人担保人之间的纠纷在票据已被抗议后得以解决，可以发送 `protest_remove_request` 类型的指令，该指令将删除公开的拖欠记录以及与该票据相关的任何损害付款人信誉的记录。
:::caution 注意！
如果该事件被确认（公证处接受），抗议将被撤销，并且不会为该票据创建更多指令，因为该票据已在 CIP/Nuclea 注销。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_remove_request
MÉTODO POST
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | 账户的唯一标识键，格式为 uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | 钱包的唯一标识键，格式为 uuid v4 | 36 |
| `bank_slip_key` | uuidv4 | 票据的唯一标识键，格式为 uuid v4 | 36 |
Request Body
```json
{
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，格式为 uuid v4 | 36 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | 事件（指令）的唯一标识键，格式为 uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | 票据的唯一标识键，格式为 uuid v4 | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 描述 (eng)
`description` | 描述 (pt-br)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000019 | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 400 | BKS000076 | Bad Request | Bank slip must have an ongoing protest request. | O boleto deve ter um pedido de protesto em vigência. |
| 400 | BKS000078 | Bad Request | Bank slip's protest_status must be 'protested' to send a protest remove request. | Status de protesto (protest_status) do boleto deve ser 'protested' para enviar um pedido de remoção de protesto. |
---
# 信用分账更新
URL: /zh-Hans/documentation/boletos/instrucoes/rateio_de_credito
此接口用于更新已发行 Boleto 的**信用分账**（分账支付）规则。新规则将完全替换原有规则，并适用于该 Boleto 的下一次结算。
:::caution 注意！
- Boleto 必须处于 `registered` 状态且尚未支付。
- `beneficiary_settlement_percentage` 与 `split_payment_rules` 中各项百分比之和必须正好等于 **100**。
- 请求体将**完全替换**现有的所有分账规则（非增量更新）。
- 分账适用于 Boleto 的所有结算流程（SILOC、STR、公证处和 Pix QR Code），包括已生成 QR Code 的 Boleto——此时 QR Code 中的规则也会自动同步更新。
- 分账规则中的账户必须为开通状态并已在 QI Tech 注册（QI Tech 将根据所提供的 `document_number`、`account_number` 和 `account_digit` 进行查询）。
:::
## Request
ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /split_payment
方法 PUT
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|--------------------------------------------|------------|
| `account_key` | uuidv4 | Boleto 所在账户的唯一标识密钥 | 36 |
| `requester_profile_key` | uuidv4 | 钱包的唯一标识密钥 | 36 |
| `bank_slip_key` | uuidv4 | Boleto 的唯一标识密钥 | 36 |
请求体
```json
{
"beneficiary_settlement_percentage": 70,
"split_payment_rules": [
{
"percentage": 20,
"document_number": "12345678901",
"account_owner_name": "John Smith",
"account_number": "1234567",
"account_digit": "8"
},
{
"percentage": 10,
"document_number": "10987654321",
"account_owner_name": "Mary Johnson",
"account_number": "7654321",
"account_digit": "0"
}
]
}
```
### 请求体参数
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------------------|--------------|------------------------------------------------------------------------------------------------|------------|
| `beneficiary_settlement_percentage` * | float | 分配给 Boleto 受益人的结算金额百分比，取值范围 0 至 100 | - |
| `beneficiary_max_amount` | float | 受益人在结算时可获得的最大金额。当付款金额超过此限额时，超出部分将全部分配给 `split_payment_rules` 数组中的第一条规则。取值大于 0 且不大于 Boleto 金额 | - |
| `split_payment_rules` * | object array | 分账规则列表。最少 1 条，最多 10 条 | **[split_payment_rule 对象](#objeto-split_payment_rule)** |
### split_payment_rule 对象
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|----------|-------------------------------------------------------------------------------------|------------|
| `percentage` * | float | 分配给该账户的结算金额百分比，取值范围 0 至 100。当此规则专门用于接收 `beneficiary_max_amount` 之上的超出部分时，请使用 `0` | - |
| `document_number` * | string | 目标账户持有人的 CPF/CNPJ | 11 或 14 |
| `account_owner_name` * | string | 目标账户持有人姓名 | 100 |
| `account_number` * | string | 目标账户号 | 20 |
| `account_digit` * | string | 目标账户校验位 | 2 |
## 用例：将逾期利息和滞纳金导向单独账户
> **如何配置分账，使超出 Boleto 面值的利息和滞纳金被导向与受益人不同的账户？**
此场景常见于代第三方（学校、物业、市场平台等）发行 Boleto 的平台：Boleto 持有人始终应收取面值，而平台则在逾期付款时获得额外的利息/滞纳金。
通过 `beneficiary_max_amount` 与一条 `percentage = 0` 的分账规则配合实现：
```json
{
"beneficiary_settlement_percentage": 100,
"beneficiary_max_amount": 1000.00,
"split_payment_rules": [
{
"percentage": 0,
"document_number": "12345678000199",
"account_owner_name": "收款平台",
"account_number": "1234567",
"account_digit": "8"
}
]
}
```
**计算方式**（以 R$ 1.000,00 的 Boleto 为例）：
| 场景 | 已付金额 | 受益人收到 | 平台收到 |
|---|---|---|---|
| 按时付款 | R$ 1.000,00 | R$ 1.000,00 | R$ 0,00（不生成结算） |
| 逾期付款（含 R$ 100,00 利息/滞纳金） | R$ 1.100,00 | R$ 1.000,00 | R$ 100,00 |
| 部分逾期付款 | R$ 950,00 | R$ 950,00 | R$ 0,00 |
规则：受益人**最多**收到 `beneficiary_max_amount`；超过该限额的金额将全部分配给 `split_payment_rules` 中的**第一条**规则。
:::caution 注意！
- `beneficiary_max_amount` 必须大于 0 且不大于 Boleto 金额（`amount`）。
- 当任一规则的 `percentage = 0` 时，必须填写 `beneficiary_max_amount`。
- 每张 Boleto 仅允许 `split_payment_rules` 中**一条**规则的 `percentage = 0`（即超出部分的接收方）。
:::
## Response
状态码 204
响应体
```json
{}
```
## 错误响应
状态码 4xx
响应体：错误
```json
{
"title": "标题",
"description": "description in English",
"translation": "descrição em portugues",
"code": "代码",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 英文描述
`description` | 葡语描述
`translation` |
|--------------------------|--------------------|---------------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 422 | BKS000157 | Unprocessable Entity | Could not find an account matching the provided split payment account data. | Não foi possível encontrar uma conta com os dados informados na regra de split payment. |
| 400 | BKS000158 | Bad Request | The beneficiary_max_amount must be greater than 0 and not greater than the bank slip amount. | O beneficiary_max_amount deve ser maior que 0 e não pode ser maior que o valor do boleto. |
| 400 | BKS000159 | Bad Request | Split payment rules with percentage equal to 0 require beneficiary_max_amount to be set. | Regras de split payment com percentual igual a 0 exigem o campo beneficiary_max_amount preenchido. |
| 400 | BKS000160 | Bad Request | Only one split payment rule with percentage equal to 0 is allowed. | É permitido apenas uma regra de split payment com percentual igual a 0. |
---
# 金额
URL: /zh-Hans/documentation/boletos/instrucoes/valor
金额指令允许修改已登记票据的金额。若票据存在待确认的金额指令，则不允许发送新的指令。
:::caution 注意！
若存在待确认的金额指令，则不允许发送新的指令。
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /amount
MÉTODO POST
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键，uuid v4 格式 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
Request Body
```json
{
"request_control_key": "01234567-89ab-cdef-0123-456789abcdef",
"amount": 150.50
}
```
### Request Body Params
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|------------------------------------------------------------------------------|--------|
| `request_control_key` * | uuidv4 | 客户使用的请求唯一标识键，uuid v4 格式 | 36 |
| `amount` * | number | 票据新金额（必须与当前金额不同） | - |
:::caution 注意！
金额必须与票据当前金额不同，且最多保留 2 位小数。
:::
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
"bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|--------|-----------------------------------------------------|--------|
| `occurrence_key` * | uuidv4 | 记录（指令）唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_key` * | uuidv4 | 票据唯一标识键，uuid v4 格式 | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000135 | Conflict | An amount occurrence already exists for this bank slip. | Já existe uma ocorrência de valor para este boleto. |
| 400 | BKS000136 | Bad Request | Only credit card financial instrument type can have zero amount. | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero. |
| 400 | BKS000137 | Bad Request | Amount must be different from bank slip amount. | O valor deve ser diferente do valor do boleto. |
---
# 简介
URL: /zh-Hans/documentation/boletos/introducao
## 银行票据（Boleto bancário）
银行票据通常与收款业务相关。其特点是可输入的数字行**不**以数字 8 开头。银行票据在银行同业清算所（CIP/Núclea）进行登记，可在巴西中央银行授权的金融机构和支付机构进行支付。
## 收款钱包（Carteira de cobrança）
首先需要说明的是，在本文档中，收款钱包称为 `requester_profile`。收款钱包必然关联到一个账户，并带有特定的默认配置（如利息、罚款、抗议等），用于银行票据的登记。一旦在创建或编辑收款钱包时设置了这些默认配置，每当用户登记票据时，若未发送某项配置，将使用该参数的默认配置。
:::info 示例
创建收款钱包时，用户为钱包设置了罚款配置：若付款人延迟付款 5 天或以上，将收取 R$10.00 的罚款。登记票据时，该配置可被覆盖；例如，可以选择收取 R$15.00 的罚款，甚至不收取任何罚款。但是，如果在登记票据时没有覆盖该配置，则采用钱包的默认配置（付款人延迟超过 5 天时收取 R$10.00 罚款）。
:::
可以为同一账户创建多个收款钱包，账户开设时会自动创建一个初始钱包（无任何默认配置）。创建多个收款钱包的可能性允许用户创建具有不同默认配置的钱包；而默认配置则简化了具有相同配置的多张票据的登记，因为在登记票据时无需每次都发送罚款、利息等配置。
## 票据状态机
票据在其生命周期中可能经历以下状态：
| 枚举值 | 翻译 | 描述 |
|-------------------------------|------------------------|--------------------------------------------------------------------------|
| accepted | 已接受 | 票据已接受，等待 CIP/Núclea 确认 |
| rejected | 已拒绝 | 票据登记请求未被接受 |
| registered | 已登记 | 票据已在 CIP/Núclea 登记 |
| payment_blocked | 已冻结支付 | 票据因进入抗议流程而在 CIP/Núclea 被冻结支付 |
| written_off | 已核销 | 票据已核销（不再可支付） |
| payment_notice | 支付通知 | 票据已支付并核销，但尚未完成财务清算 |
| paid | 已支付 | 票据已支付、核销并完成财务清算 |
### 状态转换
- `accepted` -> `rejected`：票据登记未被 CIP/Núclea 接受；
- `accepted` -> `registered`：票据登记被 CIP/Núclea 接受；
- `registered` -> `written_off`：票据未经支付被核销；
- `registered` -> `payment_notice`：票据已支付并核销，但尚未完成财务清算；
- `payment_notice` -> `paid`：支付后，票据完成财务清算；
- `registered` -> `payment_blocked`：票据支付被冻结，因抗议流程开始；
- `payment_blocked` -> `notary_office_payment_notice`：票据在公证处支付并核销，但尚未完成财务清算；
- `notary_office_payment_notice` -> `paid`：在公证处支付后，票据完成财务清算；
- `payment_blocked` -> `written_off`：票据已被抗议。
:::caution 注意
对于配置了部分付款的票据，状态转换方式有所不同。收到付款后，若另一家银行发送的是银行间部分核销，配置了部分付款的票据仍保持 `registered` 状态。您会正常收到 [payment notice](/documentation/boletos/webhooks/boleto) 和 [payment](/documentation/boletos/webhooks/boleto) 的 webhook 通知，但票据保持 `registered` 状态。只有当付款银行通过 CIP/Núclea 发送银行间全额核销时，票据才会转为 `payment_notice` 状态，随后转为 `paid` 状态。若希望在任何时候核销票据，或总金额已支付但另一家机构未发送银行间全额核销，您可以发送[核销指令](/documentation/boletos/instrucoes/baixa)。
对于**信用卡**类型（`credit_card`）的票据，请注意这些票据不会收到银行间全额核销。因此，客户始终有责任手动核销票据，否则票据将在最大支付日期（根据 `max_payment_days` 配置）后 D+7 自动核销。
:::
## 票据登记
### 通过 API
标准登记流程
若系统通过[**标准登记流程**](/documentation/boletos/emissao/emissao_boleto_unico_padrao)收到票据登记请求，且该请求被接受（即发送的信息无任何不一致），将返回状态为 `accepted` 的票据，但这并不意味着该票据会被实际登记。在将票据发送至 CIP/Núclea 并收到响应后，票据将转为 `rejected` 或 `accepted` 状态。
批量登记流程
批量发行票据以异步方式进行，若任何票据在验证中失败，则所有票据均不会被登记。当票据状态发生变化时，申请人将通过 [**webhook**](/documentation/boletos/v2/webhooks/boleto) 收到通知。更多详情请查阅[**完整文档**](/documentation/boletos/emissao/emissao_em_lote)。
即时登记流程
票据登记还有另一种选择：[**即时登记流程**](/documentation/boletos/emissao/emissao_boleto_unico_instantanea)。在该流程中，票据登记以同步方式处理，API 响应直接返回票据是否被接受或拒绝；即响应返回的票据已具有 `accepted` 或 `rejected` 状态。Núclea/CIP 关于票据登记的确认/拒绝时间包含在该端点的响应时间内。
### 通过汇款文件
通过文件请求登记票据与通过 API 登记的最终结果完全相同。区别在于，通过文件登记时，需要将文件处理时间计入票据登记的总时间。因此，通常比通过 API 登记耗时更长。
另一方面，通过文件登记时，可以一次性登记大量票据。
---
# 列出清算组
URL: /zh-Hans/documentation/boletos/liquidacao/listar_grupos_de_liquidacao
:::info 信息
在我们的系统中，清算组是协调交易与已清算票据的一种方式。该流程（清算）描述了将已支付票据的金额转移至应收款账户的过程。简而言之，每当 QI 收到票据已被其他银行支付（或对于已抗议的票据，由公证处支付）的信息时，就会为该特定票据创建一条清算记录。随后，会创建**清算组**，这些清算组表示按类型分组的清算批次。
此后，会为该清算组执行向客户账户的付款交易。该交易的 **transaction_key** 随后将保存用于对账，通过此方式您可以查看在某次特定交易中已清算的所有票据。例如，若您有五张各 R$ 5.00 的票据，其中一张通过公证处支付，一张通过 QR Code PIX 支付，另外三张由其他银行通过可输入行或条形码支付，则会为这些票据创建五条清算记录。随后，这些清算记录将被分为三个清算组：一个 R$ 15.00 的清算组包含三张通过可输入行或条形码支付的票据（对其执行一笔交易）；一个 R$ 5.00 的清算组包含通过 QR Code PIX 支付的票据；最后一个 R$ 5.00 的清算组包含通过公证处支付的票据。
:::
清算组列表将返回符合请求中发送的 查询参数 的所有账户清算组。
## Request
ENDPOINT /account/ ACCOUNT_KEY /bank_slip_settlement_groups
MÉTODO GET
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|--------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键 | 36 |
### Query parameters
| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------|---------|-------------------------------------------|--------------------------|
| `bank_slip_settlement_group_key` | uuidv4 | 清算组唯一标识键，uuid v4 格式 | 36 |
| `transaction_key` | uuidv4 | 清算组交易唯一标识键，uuid v4 格式 | 36 |
| `bank_slip_settlement_group_status`| string | 清算组状态 | **[Enumeradores bank_slip_settlement_group_status](#enumeradores-bank_slip_settlement_group_status)** |
| `date_from` | string | 起始日期，格式"YYYY-MM-DD" | |
| `date_to` | string | 结束日期，格式"YYYY-MM-DD" | |
| `page` | integer | 页码 | - |
| `page_size` | integer | 每页大小 | - |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"bank_slip_settlement_group_key": "5ba0b0cf-ac4a-4c91-819d-d6c46d70e3ab",
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"transaction_key": "6704d927-9e0d-411d-8c44-c377c0c56637",
"amount": 1069.24,
"bank_slip_settlement_group_type": "notary_office",
"bank_slip_settlement_group_status": "settled",
"bank_slip_settlement_quantity": 1
},
{
"bank_slip_settlement_group_key": "feda6069-c0cf-4148-b881-a475737330ab",
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"transaction_key": "00d557de-78ca-4871-b254-2852499660e2",
"amount": 2400.0,
"bank_slip_settlement_group_type": "siloc",
"bank_slip_settlement_group_status": "settled",
"bank_slip_settlement_quantity": 303
},
{
"bank_slip_settlement_group_key": "5493030c-ba1c-44de-9e85-5aaee0afe46d",
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"transaction_key": "b42c4d0a-8060-41d7-bd00-17889cc76485",
"amount": 250.0,
"bank_slip_settlement_group_type": "siloc",
"bank_slip_settlement_group_status": "settled",
"bank_slip_settlement_quantity": 50
},
{
"bank_slip_settlement_group_key": "f33c087d-cbae-47a9-bd5a-e6a8ecc04ed2",
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"transaction_key": "6ee57aea-b589-4dff-9555-200c34380154",
"amount": 4024800.0,
"bank_slip_settlement_group_type": "str",
"bank_slip_settlement_group_status": "settled",
"bank_slip_settlement_quantity": 16
},
{
"bank_slip_settlement_group_key": "27b9b2b7-549e-406e-9f41-c71e0cb08b00",
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"transaction_key": "36aa7a00-6741-41d5-99e9-ce620fed5823",
"amount": 300.0,
"bank_slip_settlement_group_type": "split_payment",
"bank_slip_settlement_group_status": "settled",
"bank_slip_settlement_quantity": 1,
"settlement_date": "2026-04-23"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|--------------------|----------------------------------------------------------------------------------------------------|
| `data` | object array | 票据 | **[Objeto bank_slip_settlement_group](#objeto-bank_slip_settlement_group)** |
| `pagination` | object | 分页信息 | **[Objeto pagination](#objeto-pagination)** |
### Objeto bank_slip_settlement_group
| 字段 | 类型 | 描述 | 字符数 |
|----------------------------------------|---------|-----------------------------|--------------------------------------------------|
| `bank_slip_settlement_group_key` | uuidv4 | 清算组唯一标识键，uuid v4 格式 | 36 |
| `account_key` | uuidv4 | 账户唯一标识键 | 36 |
| `transaction_key` | uuidv4 | 清算组交易唯一标识键，uuid v4 格式 | 36 |
| `amount` | float | 已清算总金额 | - |
| `bank_slip_settlement_group_type` | string | 清算组类型 | **[Enumeradores bank_slip_settlement_group_type](#enumeradores-bank_slip_settlement_group_type)** |
| `bank_slip_settlement_group_status` | string | 清算组状态 | **[Enumeradores bank_slip_settlement_group_status](#enumeradores-bank_slip_settlement_group_status)** |
| `bank_slip_settlement_quantity` | integer | 清算组中的清算数量 | - |
### Objeto pagination
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|------------|--------|
| `current_page` | integer | 当前页码 | - |
| `rows_per_page` | integer | 每页记录数 | - |
### Enumeradores bank_slip_settlement_group_type
| 枚举值 | 描述 |
|----------------|-------------------------------------------------------------------|
| siloc | 用于票据支付（票据金额小于 R$ 250.000） |
| qr_code | 用于通过 QR Code 支付的票据 |
| str | 用于大额票据支付（票据金额大于 R$ 250.000） |
| notary_office | 用于通过公证处支付的票据 |
| split_payment | 来自票据[**信用分账**](/documentation/boletos/instrucoes/rateio_de_credito)的接收方账户清算组 |
:::tip 含信用分账的 Boleto
当 Boleto 配置了[**信用分账**](/documentation/boletos/instrucoes/rateio_de_credito)时，每次支付会按接收方生成一个清算组：
- **Boleto 受益人账户**的清算组保持原始结算流程的类型（`siloc`、`qr_code`、`str` 或 `notary_office`）。
- **分账接收方账户**的清算组以 `split_payment` 类型创建。
每个相关账户（受益人和接收方）都可以使用各自的 `account_key` 调用此接口列出自己的清算组——这样接收方可以精确对账每张 Boleto 收到的金额。
:::
### Enumeradores bank_slip_settlement_group_status
| 枚举值 | 描述 |
|-----------|----------------------------------------|
| pending | 清算组已创建，但交易尚未执行 |
| settled | 清算组已创建，且交易已执行 |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 400 | BKS000095 | Bad Request | Invalid bank slip settlement group status. | Status de grupo de liquidação de boleto inválido. |
---
# 列出清算记录
URL: /zh-Hans/documentation/boletos/liquidacao/listar_liquidacoes
:::info 信息
在我们的系统中，**清算记录**描述了将已支付票据的金额转移至应收款账户的过程。简而言之，每当 QI 收到票据已被其他银行支付（或对于已抗议的票据，由公证处支付）的信息时，就会为该特定票据创建一条清算记录。随后，会创建清算组，清算记录始终与清算组关联，清算组代表按类型分组的清算批次。
此后，会为该清算组执行向客户账户的付款交易。该交易的 **transaction_key** 随后将保存用于对账，通过此方式您可以查看在某次特定交易中已清算的所有票据。例如，若您有五张各 R$ 5.00 的票据，其中一张通过公证处支付，一张通过 QR Code PIX 支付，另外三张由其他银行通过可输入行或条形码支付，则会为这些票据创建五条清算记录。随后，这些清算记录将被分为三个清算组：一个 R$ 15.00 的清算组包含三张通过可输入行或条形码支付的票据（对其执行一笔交易）；一个 R$ 5.00 的清算组包含通过 QR Code PIX 支付的票据；最后一个 R$ 5.00 的清算组包含通过公证处支付的票据。
:::
清算记录列表将返回请求中指定清算组的所有清算记录。
## Request
ENDPOINT /account/ ACCOUNT_KEY /bank_slip_settlement_group/ BANK_SLIP_SETTLEMENT_GROUP_KEY /bank_slip_settlements
MÉTODO GET
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------|--------|-------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键 | 36 |
| `bank_slip_settlement_group_key` | uuidv4 | 清算组唯一标识键 | |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"settlement_key": "388eac3a-4138-421c-86af-f6fe3d1a9419",
"amount": 4800.0,
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"bank_slip_key": "d39e243b-8532-4006-9ffd-17607d5d1620",
"barcode": "32991981000275000002269450000000043200779790"
},
{
"settlement_key": "c3d7c62e-73fa-473f-b5a2-82e9b8a7f9bb",
"amount": 1.0,
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"bank_slip_key": "3088ffdd-dec0-4fa3-8643-995d6809a2e6",
"barcode": "32999980300000001000001370000000000100828480"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|--------------------|---------------------------------------------------------------------------------------------|
| `data` | object array | 票据 | **[Objeto bank_slip_settlement](#objeto-bank_slip_settlement_group)** |
| `pagination` | object | 分页信息 | **[Objeto pagination](#objeto-pagination)** |
### Objeto bank_slip_settlement
| 字段 | 类型 | 描述 | 字符数 |
|--------------------|---------|------------------------------------|--------|
| `settlement_key` | uuidv4 | 清算记录唯一标识键 | 36 |
| `account_key` | uuidv4 | 账户唯一标识键 | 36 |
| `amount` | float | 已清算金额 | - |
| `bank_slip_key` | uuidv4 | 票据唯一标识键，uuid v4 格式 | |
| `barcode` | string | 票据条形码 | |
### Objeto pagination
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|------------|--------|
| `current_page` | integer | 当前页码 | - |
| `rows_per_page` | integer | 每页记录数 | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000093 | Bad Request | Settlement group not found for the given key. | Grupo de liquidação não encontrado para a chave fornecida. |
---
# 清算场景模拟
URL: /zh-Hans/documentation/boletos/liquidacao/simulacao_de_cenarios_de_liquidacao
本页面描述如何模拟外部代理执行的操作，以测试票据清算流程。这些模拟对于集成验证和测试非常有用。
:::info 信息
这些请求没有响应体（response body）。它们模拟外部操作，仅返回 HTTP 状态码。
:::
## 1 - 模拟付款通知
模拟票据的付款通知，将票据状态更改为 `payment_notice`。
ENDPOINT /mock/bank_slip/payment_notice
MÉTODO POST
Request Body
```json
{
"bank_slip_key": "0d00b0e2-af11-472f-11f0-11f3330bae33",
"paid_amount": 12.0,
"payment_method": "cash",
"payment_type": "full_interbank"
}
```
### Objeto Request Body
| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------|---------|---------------------------------------------------|------------|
| **bank_slip_key*** | string | 票据唯一键 | 36 |
| **paid_amount** | float | 付款金额。若未提供，则使用票据原始金额 | - |
| **payment_method** | string | 使用的付款方式 | - |
| **payment_type** | string | 跨行付款类型 | - |
### Enumeradores payment_method
| 枚举值 | 描述 |
|-----------------|----------|
| `cash` | 现金 |
| `account_debit` | 账户借记 |
| `credit_card` | 信用卡 |
| `check` | 支票 |
### Enumeradores payment_type
| 枚举值 | 描述 |
|---------------------|----------------------|
| `full_interbank` | 跨行全额支付 |
| `partial_interbank` | 跨行部分支付 |
:::tip 行为说明
- 若未提供 `paid_amount`，将使用票据原始金额
- 若未提供 `payment_type`，则视为全额支付（`full_interbank`）
- 模拟将创建一条付款通知记录
- 模拟后，票据将移至 `payment_notice` 状态
- **重要**：对于 `partial_interbank`，票据状态不会改变。此选项用于模拟部分付款票据的场景，详见[简介](/documentation/boletos/introducao)
:::
## 2 - 模拟票据清算
模拟票据的付款和财务清算，将票据状态更改为 `paid`。
ENDPOINT /mock/bank_slip/settlement
MÉTODO POST
Request Body
```json
{
"bank_slip_key": "0d00b0e2-af11-472f-11f0-11f3330bae33",
"paid_amount": 12.0,
"payment_method": "cash"
}
```
### Objeto Request Body
| 字段 | 类型 | 描述 | 最大字符数 |
|-----------------------|---------|-----------------------------------------------------|------------|
| **bank_slip_key*** | string | 票据唯一键 | 36 |
| **paid_amount** | float | 清算付款金额。若未提供，则使用票据原始金额 | - |
| **payment_method** | string | 使用的付款方式 | - |
### Enumeradores payment_method
| 枚举值 | 描述 |
|-----------------|----------|
| `cash` | 现金 |
| `account_debit` | 账户借记 |
| `credit_card` | 信用卡 |
| `check` | 支票 |
:::tip 行为说明
- 若未提供 `paid_amount`，将使用票据原始金额
- 模拟默认使用代码 65（支付）创建一条付款记录
- 模拟后，票据将移至 `paid` 状态
:::
---
# 列出返回文件
URL: /zh-Hans/documentation/boletos/retorno/listar_arquivos_retorno
:::info
响应中提供的 URL 中的文件遵循 QI Tech 400 位返回文件布局标准。
以下是手册下载链接：[催收布局 - QI Tech 版本 2.1](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)
:::
返回文件用于对账。文件中，每行交易记录（类型 1）对应前一天 CIP/Nuclea 确认或拒绝的一条指令（无论是发行、延期、减免等类型）。
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /discharge_files
MÉTODO GET
### Path parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------|--------|
| `account_key` | uuidv4 | 账户唯一标识键 | 36 |
| `requester_profile_key` | uuidv4 | 钱包唯一标识键，uuid v4 格式 | 36 |
### Query parameters
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|-----------------------------------|--------|
| `discharge_file_key` | uuidv4 | 返回文件唯一标识键，uuid v4 格式 | 36 |
| `page` | integer | 页码 | - |
| `page_size` | integer | 每页大小 | - |
| `from_date` | string | 起始日期（格式"YYYY-MM-DD"） | 10 |
| `to_date` | string | 结束日期（格式"YYYY-MM-DD"） | 10 |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"discharge_file_key": "f1a8fe59-29cd-49e5-8d18-55194869b45c",
"discharge_file_name": "CB15102401.RET",
"discharge_file_url": "https://storage.googleapis.com/local-bank-slip-api/2024/61a746ca-05bf-429d-99c3-3fba0f9fbea7/329-20-7336-3073959/discharge/CB15102401.RET",
"reference_date": "2024-10-15"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| 字段 | 类型 | 描述 | 字符数 |
|------------------|--------------|--------------------|--------------------------------------------------------------------------- |
| `data` | object array | 返回文件 | **[Objeto discharge_file](#objeto-discharge_file)** |
| `pagination` | object | 分页信息 | **[Objeto pagination](#objeto-pagination)** |
### Objeto discharge_file
| 字段 | 类型 | 描述 | 字符数 |
|------------------------|---------|---------------------------------------|--------|
| `discharge_file_key` | uuidv4 | 返回文件唯一标识键，uuid v4 格式 | 36 |
| `discharge_file_name` | string | 返回文件名称 | - |
| `discharge_file_url` | string | 返回文件 URL | - |
| `reference_date` | string | 返回文件参考日期，格式 YYYY-MM-DD | 10 |
### Objeto pagination
| 字段 | 类型 | 描述 | 字符数 |
|---------------------|---------|------------|--------|
| `current_page` | integer | 当前页码 | - |
| `rows_per_page` | integer | 每页记录数 | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 状态码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 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 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 400 | BKS000052 | Bad Request | Invalid account status. | Status da conta inválido. |
---
# Boleto Webhooks
URL: /zh-Hans/documentation/boletos/webhooks/boleto
:::danger 注意！
QI Tech 的 Webhook 不应进行严格映射。
我们 API 返回的 Webhook 载荷中可能会新增额外字段。
:::
:::info 重新发送 Webhook
您可以按照文档中的详细说明查询和重新发送 Webhook：[重新发送 Webhook](/documentation/notificacoes/reenvio_de_notificacoes)。
:::
## 简介
在系统内 Boleto 的整个生命周期中，将发送包含以下 Boleto 状态（`bank_slip_status`）的 Webhook：
| 枚举值 | 描述 |
|------------------------------|---------------------------------------------------------------|
| registered | Boleto 已登记并可供付款 |
| rejected | Boleto 发行申请因验证错误被拒绝 |
| payment_notice | Boleto 支付通知（已付款但尚未清算） |
| notary_office_payment_notice | Boleto 公证处支付通知（已付款但尚未清算） |
| paid | Boleto 已付款并完成财务清算 |
| written_off | Boleto 已注销（不可再付款）且无财务清算 |
| payment_blocked | 因抗议流程而被锁定支付 |
以下类型（`occurrence_type`）的事件被确认时，将发送 Webhook：
| 枚举值 | 描述 |
|------------------------------|---------------------------------------------------------------|
| registration | Boleto 登记 |
| rebate | 票据基础金额折让 |
| cancel_rebate | 取消现有折让 |
| extension | 延长票据到期日期 |
| write_off | Boleto 注销 |
| protest_write_off | 因公证处抗议注销 Boleto |
| payment_write_off | 因付款注销 Boleto |
| discount | 折扣变更 |
| fine | 罚款变更 |
| interest | 利息变更 |
| protest_request | 公证处抗议申请 |
| bankruptcy_protest_request | 公证处破产抗议申请 |
| notary_office_entry | 票据进入公证处事件 |
| protest_cancel_request | 撤销当前抗议申请 |
| protest_remove_request | 票据抗议暂停 |
| notary_office_exit | 票据离开公证处事件 |
| payment_notice | Boleto 支付通知（已付款但尚未清算） |
| notary_office_payment_notice | Boleto 公证处支付通知（已付款但尚未清算） |
| payment | 通知 Boleto 已付款并注销 |
:::info 信息
我们 Webhook 的响应超时时间为 10 秒。
:::
## 示例
----
### 登记
Webhook Body: 事件已接受
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
"bank_slip_status": "registered",
"occurrence_key": "9077cc0b-5bbd-4432-888e-6bf6384c250a",
"occurrence_type": "registration",
"occurrence_status": "confirmed"
}
}
```
Webhook Body: 事件被拒绝
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "ae783ed7-b892-4e48-8480-b045e3b492f5",
"bank_slip_status": "rejected",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "registration",
"occurrence_status": "rejected"
}
}
```
### 折让/取消折让
Webhook Body: 折让
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
"bank_slip_status": "registered",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "rebate",
"occurrence_status": "confirmed"
}
}
```
Webhook Body: 取消折让
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
"bank_slip_status": "registered",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "cancel_rebate",
"occurrence_status": "confirmed"
}
}
```
### 延期
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
"bank_slip_status": "registered",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "extension",
"occurrence_status": "confirmed"
}
}
```
### 折扣
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "a8df1c2e-77ff-49ea-9e7a-8fd536a6e357",
"bank_slip_status": "registered",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "discount",
"occurrence_status": "confirmed"
}
}
```
### 利息
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "69f3f345-07c5-4c80-a8dd-51054afdad01",
"bank_slip_status": "registered",
"occurrence_key": "8550e47a-7554-455c-bdd8-cf0c048a277c",
"occurrence_type": "interest",
"occurrence_status": "confirmed"
}
}
```
### 罚款
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "97e6edab-b793-4eb6-a1a7-0a27e1d5c73e",
"bank_slip_status": "registered",
"occurrence_key": "47b06bdb-c006-47a7-81f2-7aac7fff823b",
"occurrence_type": "fine",
"occurrence_status": "confirmed"
}
}
```
### 注销
`occurrence_reason` 字段为可选字段，当银行提供注销原因时才会出现。它包含金融机构提供的原因代码和原因名称。
Webhook Body: 无原因
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "45c21054-57fd-4d28-8d5a-0cdc5cb29670",
"bank_slip_status": "written_off",
"occurrence_key": "0b92bd47-fae5-46c0-8c40-e5aebc9ecd28",
"occurrence_type": "write_off",
"occurrence_status": "confirmed"
}
}
```
Webhook Body: 含原因
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2026-05-04T21:12:07.877Z",
"data": {
"bank_slip_key": "25add0b0-cb2d-4be4-8f22-4305a4dd9793",
"bank_slip_status": "written_off",
"occurrence_key": "ca71f446-be05-47cc-b470-234e4806344c",
"occurrence_type": "write_off",
"occurrence_status": "confirmed",
"occurrence_reason": {
"bank_reason_code": "16",
"bank_reason_name": "Título Baixado pelo Banco por decurso de Prazo"
}
}
}
```
### 因抗议注销
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-25T18:05:01.395Z",
"data": {
"bank_slip_key": "7182639f-dea5-46c6-99c6-af0d94d772cb",
"bank_slip_status": "written_off",
"occurrence_key": "93380917-beee-4f3e-af01-6c24e140d53d",
"occurrence_type": "protest_write_off",
"occurrence_status": "confirmed"
}
}
```
### 因付款注销
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-18T18:02:15.152Z",
"data": {
"bank_slip_key": "40d6a1bc-cfed-4444-a901-e02ecc169ce5",
"bank_slip_status": "written_off",
"occurrence_key": "78221daa-945f-485b-b39c-97ef0e251afe",
"occurrence_type": "payment_write_off",
"occurrence_status": "confirmed"
}
}
```
### 抗议申请
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-16T20:54:13.013Z",
"data": {
"bank_slip_key": "f03c5fec-b31c-402a-b832-80da8a493653",
"bank_slip_status": "payment_blocked",
"occurrence_key": "304958f6-cdf2-4fb1-b8f3-5482030bf0eb",
"occurrence_type": "protest_request",
"occurrence_status": "confirmed"
}
}
```
### 破产抗议申请
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-16T20:54:13.013Z",
"data": {
"bank_slip_key": "21aeefb4-4fa1-4e32-b2bb-32a7486128f0",
"bank_slip_status": "payment_blocked",
"occurrence_key": "11a7e9e8-4667-471b-bc3f-2f65f77e22e9",
"occurrence_type": "bankruptcy_protest_request",
"occurrence_status": "confirmed"
}
}
```
### 进入公证处
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-17T18:00:48.341Z",
"data": {
"bank_slip_key": "5bc4c1d4-d51b-4b0b-b308-81850d04e523",
"bank_slip_status": "payment_blocked",
"occurrence_key": "159e6e3f-fce5-4362-829e-1595fc14d66c",
"occurrence_type": "notary_office_entry",
"occurrence_status": "confirmed"
}
}
```
### 取消抗议
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-23T18:00:52.374Z",
"data": {
"bank_slip_key": "96d2a896-f2da-484c-8d40-20fabbde15ee",
"bank_slip_status": "registered",
"occurrence_key": "2505fedf-0061-478b-b45e-8420b755ebbb",
"occurrence_type": "protest_cancel_request",
"occurrence_status": "confirmed"
}
}
```
### 暂停抗议
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-30T18:01:00.452Z",
"data": {
"bank_slip_key": "878d462e-be4e-40bd-b797-b831fef87f48",
"bank_slip_status": "written_off",
"occurrence_key": "cb08785d-0a4d-41f4-a64c-bafe730b175b",
"occurrence_type": "protest_remove_request",
"occurrence_status": "confirmed"
}
}
```
### 离开公证处
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-11-01T18:01:01.949Z",
"data": {
"bank_slip_key": "79d07a3d-3953-4195-a2e2-bbbf10635f27",
"bank_slip_status": "registered",
"occurrence_key": "c703b04c-7334-40fe-bf8d-b43bd991dbab",
"occurrence_type": "notary_office_exit",
"occurrence_status": "confirmed"
}
}
```
### 支付通知
**第一个 Webhook：Boleto 已付款，但尚未清算**
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.payment_notice",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"bank_slip_status": "payment_notice",
"occurrence_key": "d0341ad7-aa87-4dad-929b-38c8c9218f23",
"occurrence_type": "payment_notice",
"occurrence_status": "confirmed"
}
}
```
### 公证处支付通知
**第一个 Webhook：Boleto 已在公证处付款，但尚未清算**
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.notary_office_payment_notice",
"webhook_datetime": "2024-10-16T18:00:43.621Z",
"data": {
"bank_slip_key": "05f2b81b-b241-4e72-9b2c-7312257a0284",
"bank_slip_status": "notary_office_payment_notice",
"occurrence_key": "3ecab7b1-c991-4d91-8d71-08a34eec1d7d",
"occurrence_type": "notary_office_payment_notice",
"occurrence_status": "confirmed"
}
}
```
### 付款
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.payment",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"bank_slip_status": "paid",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "payment",
"occurrence_status": "confirmed",
"paid_amount": 850.0,
"paid_rebate_amount": 200.0,
"paid_discount_amount": 0.0,
"paid_fine_amount": 0.0,
"paid_interest_amount": 50.0,
"payment_method": "account_debit",
"payment_origin": "qr_code",
"payment_credit_date": "2024-07-02",
"payment_bank": {
"code": "341",
"ispb": 60701190,
"name": "ITAU UNIBANCO S.A."
},
"payment_branch": "0216"
}
}
```
:::info 信息
`payment_bank` 和 `payment_branch` 字段表示 Boleto 付款所在的银行和分行。它们仅在付款结算时收到该信息后才会填充；如果未识别出付款银行，`payment_bank` 将返回 `null`。
:::
### payment_origin 枚举值
| 枚举值 | 描述 |
|----------------|----------------------------|
| cash | 现金 |
| account_debit | 账户扣款 |
| credit_card | 信用卡 |
| check | 支票 |
### payment_origin 枚举值
| 枚举值 | 描述 |
|--------------------|-------------------------------|
| phisical_cashier | 传统网点 |
| taa | 自动取款机终端 |
| internet | 网络银行（home/office banking） |
| corban | 银行代理 |
| call_center | 客服中心 |
| eletronic_file | 电子文件 |
| dda | DDA |
| digital_correspondent | 数字代理 |
| qr_code | Pix QR Code 支付 |
---
# 票据钱包 Webhooks
URL: /zh-Hans/documentation/boletos/webhooks/carteira
:::danger 注意！
QI Tech 的 webhooks 不应以严格限定的方式进行映射。
我们 API 返回的 webhook payload 中可能会添加新字段。
:::
:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::
## 简介
在我们系统内创建钱包（`requester_profile`）后，将发送包含以下状态的 webhooks：
| 枚举值 | 描述 |
|------------|------------------------------------|
| opened | 票据钱包已开启，可登记票据 |
:::info 信息
我们 webhooks 的响应超时时间为 10 秒。
:::
## 示例
----
### 开启确认
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.requester_profile",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"requester_profile_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
"request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
"requester_profile_code": "329-04-2338-2625918",
"requester_profile_status": "opened"
}
}
```
---
# 清算 Webhooks
URL: /zh-Hans/documentation/boletos/webhooks/liquidacao
:::danger 注意！
QI Tech 的 webhooks 不应以严格限定的方式进行映射。
我们 API 返回的 webhook payload 中可能会添加新字段。
:::
:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::
## 简介
在我们的系统中，清算组是协调交易与已清算票据的一种方式。该流程（清算）描述了将已支付票据的金额转移至应收款账户的过程。简而言之，每当 QI 收到票据已被其他银行支付（或对于已抗议的票据，由公证处支付）的信息时，就会为该特定票据创建一条清算记录。随后，会创建**清算组**，这些清算组代表按类型分组的清算批次。
此后，会为该清算组执行向客户账户的付款交易。该交易的 **transaction_key** 随后将保存用于对账，通过此方式您可以查看在某次特定交易中已清算的所有票据。例如，若您有五张各 R$ 5.00 的票据，其中一张通过公证处支付，一张通过 QR Code PIX 支付，另外三张由其他银行通过可输入行或条形码支付，则会为这些票据创建五条清算记录。随后，这些清算记录将被分为三个清算组：一个 R$ 15.00 的清算组包含三张通过可输入行或条形码支付的票据（对其执行一笔交易）；一个 R$ 5.00 的清算组包含通过 QR Code PIX 支付的票据；最后一个 R$ 5.00 的清算组包含通过公证处支付的票据。
:::info 信息
我们 webhooks 的响应超时时间为 10 秒。
:::
## 示例
----
### 清算组
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.bank_slip_settlement_group",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_settlement_group_key": "87e6687b-d02b-45dc-b5b8-b51e16ec0a03",
"amount": 1,
"bank_slip_settlement_group_type": "siloc",
"bank_slip_settlement_group_status": "settled",
"transaction_key": "fc60a57e-c6ac-4e39-a3cf-2dc3c491dac6"
}
}
```
### Enumeradores bank_slip_settlement_group_type
| 枚举值 | 描述 |
|----------------|-------------------------------------------------------------------|
| siloc | 用于票据支付（票据金额小于 R$ 250.000） |
| qr_code | 用于通过 QR Code 支付的票据 |
| str | 用于大额票据支付（票据金额大于 R$ 250.000） |
| notary_office | 用于通过公证处支付的票据 |
### Enumeradores bank_slip_settlement_group_status
| 枚举值 | 描述 |
|-----------|----------------------------------------|
| pending | 清算组已创建，但交易尚未执行 |
| settled | 清算组已创建，且交易已执行 |
---
# 返回文件 Webhooks
URL: /zh-Hans/documentation/boletos/webhooks/retorno
返回文件用于对账。文件中，每行交易记录（类型 1）对应前一天 CIP/Nuclea 确认或拒绝的一条指令（无论是发行、延期、减免等类型）。
:::danger 注意！
QI Tech 的 webhooks 不应以严格限定的方式进行映射。
我们 API 返回的 webhook payload 中可能会添加新字段。
:::
:::info Webhook 重发
您可以按照文档中的详细说明查询和重发 webhooks：[重发 Webhooks](/documentation/notificacoes/reenvio_de_notificacoes)。
:::
:::info 信息
我们 webhooks 的响应超时时间为 10 秒。
:::
## 示例
----
### 返回文件
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.discharge_file",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"discharge_file_key": "f1a8fe59-29cd-49e5-8d18-55194869b45c",
"reference_date": "2024-10-15",
"requester_profile_key": "fc60a57e-c6ac-4e39-a3cf-2dc3c491dac6",
"discharge_file_url": "https://storage.googleapis.com/local-bank-slip-api/2024/61a746ca-05bf-429d-99c3-3fba0f9fbea7/329-20-7336-3073959/discharge/CB15102401.RET",
"cnab_bank": "qi_scd",
"cnab_layout": "400",
}
}
```
:::info 支持的银行
目前，返回文件 webhook 支持以下银行：
- Bradesco（bradesco）
- Itaú（itau）
- QI SCD（qi_scd）
- Santander（santander）
:::
:::info 支持的布局
目前，返回文件 webhook 支持以下 CNAB 布局：
- CNAB 400（400）
:::
---
# 开启票据 tombamento 批次
URL: /zh-Hans/documentation/troca_de_titularidade/abrir_lote
此端点将创建一个票据 tombamento 批次。
批次创建时不包含任何票据，票据需通过[票据纳入](/incluir_boletos)端点添加。
## 请求
ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/stream
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。 | 36 |
| `REQUESTER-PROFILE-KEY` | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36 |
Request Body - 托收钱包 UUID 键
```json
{
"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
"new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24"
}
```
Request Body - 托收钱包代码
```json
{
"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
"new_requester_profile_code": "329-09-0001-1234567",
"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24"
}
```
:::info 票据托收钱包代码
托收钱包代码是遵循以下模式的字符串：
[ 银行编号 ] + [ 钱包代码 ] + [ 账户支行号 ] + [ 7位不含校验位的账户号 ]
在 QI Tech，银行编号、钱包代码和支行号始终分别为 `329`、`09` 和 `0001`。
因此，账户号 5308318-3 的托收钱包代码为：`329-09-0001-5308318`。
:::
## Body 参数
| 字段 | 类型 | 描述 | 字符数 |
|---|------|-----------| --|
|`request_control_key`| uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。 |36|
|`new_requester_profile_key`| uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 |36|
|`new_requester_profile_code`| string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。 |19|
|`new_pix_key` | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。 | 255 |
## 响应
STATUS 202
Response Body
```json
{
"bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
"bank_slip_ownership_exchange_batch_status": "open",
"new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
"new_requester_profile_code": "329-09-0001-8703524",
"new_requester_profile_owner_name": "Fulano de Tal",
"new_requester_profile_owner_document_number": "70896538000101",
"new_requester_profile_account_number": "8703524",
"new_requester_profile_account_digit": "1",
"new_requester_profile_account_branch": "0001",
"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 0,
"total_amount": 0
}
```
## 响应参数
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key` | uuidv4 | tombamento 批次的唯一识别键。 | 36 |
| `request_control_key` | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。 | 36 |
| `bank_slip_ownership_exchange_batch_status` | enum | tombamento 批次的状态。 | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key` | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36 |
| `new_requester_profile_code` | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。 | 19 |
| `new_requester_profile_owner_name` | string | 目标账户持有人及目标托收钱包受益人的姓名。 | 255 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。 | 255 |
| `new_requester_profile_account_number` | string | tombamento 目标账户号。 | 7 |
| `new_requester_profile_account_digit` | string | tombamento 目标账户校验位。 | 1 |
| `new_requester_profile_account_branch` | string | tombamento 目标账户支行号。 | 4 |
| `new_pix_key` | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。 | 255 |
| `total_bank_slip_count` | float | tombamento 批次中的票据总数。 | - |
| `total_amount` | float | tombamento 批次中票据面值总和。 | - |
### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述 |
|------------|--------------------------------------------------------------------------------------------------------|
| open | 批次已创建，仍开放以纳入/删除票据。 |
| sent | 票据选择已完成，tombamento 批次待批准。批准方需完成批准操作。 |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| approved | 批次中的票据已完成 tombamento 转移给目标方。 |
| cancelled | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |
---
# 批准票据 tombamento 批次
URL: /zh-Hans/documentation/troca_de_titularidade/aprovar_lote
通过 ```/send``` 发送 tombamento 批次后，需要完成 tombamento 的批准。
批准必须由目标账户和 requester 完成，他们将成为 tombamento 后票据的新负责人。如果 tombamento 在同一 requester 的账户间进行，只需更改 account-key。
## 请求
ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /approve
MÉTODO PATCH
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | 目标账户的唯一识别键，即票据将被发送到的账户。 | 36 |
| `REQUESTER-PROFILE-KEY` | uuidv4 | 目标钱包的唯一识别键，即票据将被转移到的钱包。 | 36 |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | tombamento 批次的唯一识别键。 | 36 |
Request Body
```json
{}
```
## 响应
STATUS 200
Response Body
```json
{
"bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
"bank_slip_ownership_exchange_batch_status": "processing",
"new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
"new_requester_profile_code": "329-09-0001-8703524",
"new_requester_profile_owner_name": "Fulano de Tal",
"new_requester_profile_owner_document_number": "70896538000101",
"new_requester_profile_account_number": "8703524",
"new_requester_profile_account_digit": "1",
"new_requester_profile_account_branch": "0001",
"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 3,
"total_amount": 750.00
}
```
## 响应参数
| 字段 | 类型 | 描述 | 字符数 |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key` | uuidv4 | tombamento 批次的唯一识别键。 | 36 |
| `request_control_key` | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。 | 36 |
| `bank_slip_ownership_exchange_batch_status` | enum | tombamento 批次的状态。 | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key` | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36 |
| `new_requester_profile_code` | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。 | 19 |
| `new_requester_profile_owner_name` | string | 目标账户持有人及目标托收钱包受益人的姓名。 | 255 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。 | 255 |
| `new_requester_profile_account_number` | string | tombamento 目标账户号。 | 7 |
| `new_requester_profile_account_digit` | string | tombamento 目标账户校验位。 | 1 |
| `new_requester_profile_account_branch` | string | tombamento 目标账户支行号。 | 4 |
| `new_pix_key` | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。 | 255 |
| `total_bank_slip_count` | float | tombamento 批次中的票据总数。 | - |
| `total_amount` | float | tombamento 批次中票据面值总和。 | - |
### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述 |
|------------|--------------------------------------------------------------------------------------------------------|
| open | 批次已创建，仍开放以纳入/删除票据。 |
| closed | 批次已关闭，批次中票据的 tombamento 已完成。 |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| pending_approval | 票据选择已完成，tombamento 批次待批准。批准方可以从批次中删除票据。 |
| canceled | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |
---
# 取消票据 tombamento 批次
URL: /zh-Hans/documentation/troca_de_titularidade/cancelar_lote
## 请求
ENDPOINT /bank_slip/account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /cancel
MÉTODO PATCH
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。 | 36 |
| `REQUESTER-PROFILE-KEY` | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36 |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | tombamento 批次的唯一识别键。| 36 |
Request Body
```json
{}
```
## 响应
STATUS 200
Response Body
```json
{
"bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
"bank_slip_ownership_exchange_batch_status": "canceled",
"new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
"new_requester_profile_code": "329-09-0001-8703524",
"new_requester_profile_owner_name": "Fulano de Tal",
"new_requester_profile_owner_document_number": "70896538000101",
"new_requester_profile_account_number": "8703524",
"new_requester_profile_account_digit": "1",
"new_requester_profile_account_branch": "0001",
"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 3,
"total_amount": 750.00
}
```
## 响应参数
| 字段 | 类型 | 描述 | 字符数 |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key` | uuidv4 | tombamento 批次的唯一识别键。 | 36 |
| `request_control_key` | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。 | 36 |
| `bank_slip_ownership_exchange_batch_status` | enum | tombamento 批次的状态。 | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key` | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36 |
| `new_requester_profile_code` | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。 | 19 |
| `new_requester_profile_owner_name` | string | 目标账户持有人及目标托收钱包受益人的姓名。 | 255 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。 | 255 |
| `new_requester_profile_account_number` | string | tombamento 目标账户号。 | 7 |
| `new_requester_profile_account_digit` | string | tombamento 目标账户校验位。 | 1 |
| `new_requester_profile_account_branch` | string | tombamento 目标账户支行号。 | 4 |
| `new_pix_key` | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。 | 255 |
| `total_bank_slip_count` | float | tombamento 批次中的票据总数。 | - |
| `total_amount` | float | tombamento 批次中票据面值总和。 | - |
### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述 |
|------------|--------------------------------------------------------------------------------------------------------|
| open | 批次已创建，仍开放以纳入/删除票据。 |
| closed | 批次已关闭，批次中票据的 tombamento 已完成。 |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| pending_approval | 票据选择已完成，tombamento 批次待批准。批准方可以从批次中删除票据。 |
| canceled | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |
---
# 将票据加入 tombamento 批次
URL: /zh-Hans/documentation/troca_de_titularidade/incluir_boletos
此端点用于将票据加入票据 tombamento 批次。
## 请求
ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /append
MÉTODO PATCH
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。 | 36 |
| `REQUESTER-PROFILE-KEY` | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36 |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | tombamento 批次的唯一识别键。| 36 |
Request Body
```json
{
"bank_slips": [
"b21c5b5a-a71f-4672-9254-022401cd15f6",
"8197e3d0-1500-439f-9f9d-d243115542fa",
"8293b817-bed9-418a-8c1e-ec8ef5a31468"
]
}
```
:::caution 注意！
payload 中 `bank_slips` 对象的票据列表，每次请求限制为 10,000 个票据。
:::
## 响应
STATUS 200
Response Body
```json
{
"bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
"bank_slip_ownership_exchange_batch_status": "open",
"new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
"new_requester_profile_code": "329-09-0001-8703524",
"new_requester_profile_owner_name": "Fulano de Tal",
"new_requester_profile_owner_document_number": "70896538000101",
"new_requester_profile_account_number": "8703524",
"new_requester_profile_account_digit": "1",
"new_requester_profile_account_branch": "0001",
"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 3,
"total_amount": 750.00
}
```
## 响应参数
| 字段 | 类型 | 描述 | 字符数 |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key` | uuidv4 | tombamento 批次的唯一识别键。 | 36 |
| `request_control_key` | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。 | 36 |
| `bank_slip_ownership_exchange_batch_status` | enum | tombamento 批次的状态。 | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key` | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36 |
| `new_requester_profile_code` | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。 | 19 |
| `new_requester_profile_owner_name` | string | 目标账户持有人及目标托收钱包受益人的姓名。 | 255 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。 | 255 |
| `new_requester_profile_account_number` | string | tombamento 目标账户号。 | 7 |
| `new_requester_profile_account_digit` | string | tombamento 目标账户校验位。 | 1 |
| `new_requester_profile_account_branch` | string | tombamento 目标账户支行号。 | 4 |
| `new_pix_key` | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。 | 255 |
| `total_bank_slip_count` | float | tombamento 批次中的票据总数。 | - |
| `total_amount` | float | tombamento 批次中票据面值总和。 | - |
### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述 |
|------------|--------------------------------------------------------------------------------------------------------|
| open | 批次已创建，仍开放以纳入/删除票据。 |
| sent | 票据选择已完成，tombamento 批次待批准。批准方需完成批准操作。 |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| approved | 批次中的票据已完成 tombamento 转移给目标方。 |
| cancelled | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |
---
# 简介
URL: /zh-Hans/documentation/troca_de_titularidade/introducao
银行票据的持有人变更**（tombamento）**是指对已登记票据的托收钱包及关联结算账户进行更改的过程。
在持有人变更中，始终存在**一个原始账户和托收钱包，以及一个目标账户和托收钱包。**
- **原始账户和钱包**是票据最初登记的账户和钱包。
- **目标账户和钱包**是票据将被转移（tombado）到的账户和钱包。
**什么会被更改？**
- 托收钱包
- 结算账户
**什么不会被更改？**
- 托收受益人数据
- 付款可输入行
- 付款 Pix QR Code（BolePix 情况下）
## 使用场景
### 担保合成
一个钱包的托收票据可用于合成信贷操作的担保。
在此场景下，目标账户持有人将其简单托收钱包中的票据转移（tombamento）到与操作担保账户关联的托收钱包。
### 信贷权益转让
在票据与预付信贷权益关联的情况下，预付完成后，可将票据转移到预付权益新债权人的钱包。
:::caution 注意！
票据持有人变更 API **不办理**信托转让或信贷权益预付的正式化手续。
它仅反映与已变更托收票据挂钩的资产财务流应发生的情况。
:::
## 流程说明
票据 tombamento 是将已登记票据的持有权从一个钱包转移到另一个钱包的过程。
该流程由四个主要步骤组成，必须按顺序通过 API 调用执行。
以下描述每个步骤的功能。
**1. 开批**
第一步是创建一个 tombamento 批次，该批次将汇总所有将被转移的票据。
批次创建后，以初始状态 `opened` 返回。
此步骤需要填写原始账户、目标钱包和新关联 Pix 密钥的键。
**2. 将票据加入批次**
批次开启后，可以添加将纳入持有人变更的票据。
此阶段批次状态保持为 `opened`，表示批次仍在准备中，可以接收新票据。
**3. 发送票据**
添加所有目标票据后，需要将批次发送进行处理。
发送时，批次状态更新为 `sent`，并触发 webhook 通知状态变更。
此发送标志着 tombamento 操作流程的开始。
**4. 批准 tombamento**
最后，批次的批准由目标账户完成，确认票据持有权的转移。
批准后，批次状态变更为 `processing`，表示 tombamento 正在进行中。
流程成功完成后，系统发送带有 `approved` 状态的最终 webhook，确认持有人变更已完成。
以下链接展示了完整流程的组织图，包括各步骤的关联端点及相应状态变更：
---
# 列出 tombamento 批次中的票据
URL: /zh-Hans/documentation/troca_de_titularidade/listar_boletos_lote
使用此端点列出所查询 tombamento 批次中所有纳入的票据。
## 请求
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip_ownership_exchange_batch/ BANK_SLIP_OWNERSHIP_EXCHANGE_BATCH_KEY /bank_slips
MÉTODO GET
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `account_key` | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。 | 36 |
| `requester_profile_key` | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36 |
| `bank_slip_ownership_exchange_batch_key` | uuidv4 | tombamento 批次的唯一识别键。| 36 |
### 查询参数
| 字段 | 描述 |
|----------------------|--------------------------------------------|
| `page_number` | 当前查询的页码 |
| `page_size` | 每页结果数量 |
## 响应
STATUS 200
Response Body
```json
{
"data": [
{
"bank_slip_key": "b58ce415-5428-45c4-8e33-b2df0d3ab6e8",
"request_control_key": "53529224-330d-44b5-9f4d-59d55bc3cb8c",
"our_number": 24384760943,
"document_number": "DOC4561237",
"amount": "8000.00",
"rebate_amount": "200.00",
"expiration": "2024-07-13",
"barcode": "32994978900005000000001594438621284040114400",
"digitable_line": "32990001529443862128940401144007497890000500000",
"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,
"days_to_fine": 10
},
"interest_data": {
"interest_type": "workdays_daily_amount",
"interest_amount": 5,
"days_to_interest": 10
},
"discounts_data": [
{
"discount_type": "anticipation_workdays_daily_percentage",
"discount_number": 1,
"discount_limit_date": "2024-07-13",
"discount_percentage": 10
}
],
"payer_data": {
"name": "Country Tech",
"address": {
"city": "Innovation City",
"state": "RS",
"number": "202",
"street": "101 High St.",
"complement": "Building A",
"postal_code": "57099999",
"neighborhood": "Tech Park"
},
"person_type": "legal",
"document_number": "12345678000195"
},
"guarantor_data": {
"name": "Jamie Doe",
"address": {
"city": "Peaceful Town",
"state": "MG",
"number": "303",
"street": "202 Elm St.",
"complement": "House 1",
"postal_code": "57099999",
"neighborhood": "Quiet Neighborhood"
},
"person_type": "natural",
"document_number": "98765432100"
},
"bank_slip_status": "accepted"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
## 响应参数
[票据列表对象](../boletos/consulta/listar_boletos#response-body-params)
---
# 列出票据 tombamento 批次 - 目标方
URL: /zh-Hans/documentation/troca_de_titularidade/listar_lotes_destino
使用此端点从目标账户列出票据 tombamento 批次——即票据被转移到的账户。
## 请求
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip_ownership_exchange_batches/incoming
MÉTODO GET
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|-------------------------------------------------------------------------------------------------------|------------|
| `account_key` | uuidv4 | 目标账户的唯一识别键，即票据将被转移到的账户。 | 36 |
| `requester_profile_key` | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移到的托收钱包。 | 36 |
### 查询参数
| 字段 | 描述 |
|----------------------|--------------------------------------------|
| `page_number` | 当前查询的页码 |
| `page_size` | 每页结果数量 |
## 响应
STATUS 200
Response Body
```json
{
"data": [
{
"bank_slip_exchange_batch_key": "186e73f1-456f-4265-8cb0-b32722041580",
"request_control_key": "fa7fa38c-0356-4345-98ef-21a089d9a39a",
"bank_slip_ownership_exchange_batch_status": "processing",
"old_requester_profile_key": "01a30518-0b2e-4dd1-a105-8f8bf31868a2",
"old_requester_profile_code": "329-09-0001-5963550",
"old_requester_profile_owner_document_number": "02602536000102",
"old_requester_profile_owner_name": "Coca Cola",
"old_requester_profile_account_number": "5963550",
"old_requester_profile_account_digit": "7",
"old_requester_profile_account_branch": "0001",
"old_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 200,
"total_amount": 38145.58
},
{
"bank_slip_exchange_batch_key": "8a5bbded-72ff-4642-8830-f2a5a73eb62c",
"request_control_key": "d3725802-7e56-4196-8182-2747ea18e96a",
"bank_slip_ownership_exchange_batch_status": "open",
"old_requester_profile_key": "316052e8-a017-4fb9-9939-9ce0390fa053",
"old_requester_profile_code": "329-09-0001-4743630",
"old_requester_profile_owner_document_number": "40500359000142",
"old_requester_profile_owner_name": "QI SCD",
"old_requester_profile_account_number": "4743630",
"old_requester_profile_account_digit": "1",
"old_requester_profile_account_branch": "0001",
"old_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 450,
"total_amount": 548682.19
},
{
"bank_slip_exchange_batch_key": "6f749806-8768-44ab-b7de-1f0d94d0a61a",
"request_control_key": "1c1551f2-c6e7-42d5-b78d-1f7662128a33",
"bank_slip_ownership_exchange_batch_status": "closed",
"old_requester_profile_key": "8bfdd50f-97fd-4f29-bc53-b542a914f2d6",
"old_requester_profile_code": "329-09-0001-7390371",
"old_requester_profile_owner_document_number": "56000040000198",
"old_requester_profile_name": "Meta",
"old_requester_profile_account_number": "7390371",
"old_requester_profile_account_digit": "7",
"old_requester_profile_account_branch": "0001",
"old_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 40,
"total_amount": 67245.96
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
## 响应参数
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key` | uuidv4 | tombamento 批次的唯一识别键。 | 36 |
| `request_control_key` | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。 | 36 |
| `bank_slip_ownership_exchange_batch_status` | enum | tombamento 批次的状态。 | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `old_requester_profile_key` | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36 |
| `old_requester_profile_code` | string | 目标托收钱包代码，即票据将被转移到的托收钱包。 | 19 |
| `old_requester_profile_owner_name` | string | 目标账户持有人及目标托收钱包受益人的姓名。 | 255 |
| `old_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。 | 255 |
| `old_requester_profile_account_number` | string | tombamento 目标账户号。 | 7 |
| `old_requester_profile_account_digit` | string | tombamento 目标账户校验位。 | 1 |
| `old_requester_profile_account_branch` | string | tombamento 目标账户支行号。 | 4 |
| `old_pix_key` | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。 | 255 |
| `total_bank_slip_count` | float | tombamento 批次中的票据总数。 | - |
| `total_amount` | float | tombamento 批次中票据面值总和。 | - |
### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述 |
|------------|--------------------------------------------------------------------------------------------------------|
| open | 批次已创建，仍开放以纳入/删除票据。 |
| sent | 票据选择已完成，tombamento 批次待批准。批准方需完成批准操作。 |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| approved | 批次中的票据已完成 tombamento 转移给目标方。 |
| cancelled | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |
---
# 列出票据 tombamento 批次 - 来源方
URL: /zh-Hans/documentation/troca_de_titularidade/listar_lotes_origem
使用此端点从 tombamento 来源账户列出票据 tombamento 批次——即票据最初登记的账户。
## 请求
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip_ownership_exchange_batches/outgoing
MÉTODO GET
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|---------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。 | 36 |
| `REQUESTER-PROFILE-KEY` | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36 |
### 查询参数
| 字段 | 描述 |
|----------------------|--------------------------------------------|
| `page_number` | 当前查询的页码 |
| `page_size` | 每页结果数量 |
## 响应
STATUS 200
Response Body
```json
{
"data": [
{
"bank_slip_exchange_batch_key": "186e73f1-456f-4265-8cb0-b32722041580",
"request_control_key": "fa7fa38c-0356-4345-98ef-21a089d9a39a",
"bank_slip_ownership_exchange_batch_status": "processing",
"new_requester_profile_key": "01a30518-0b2e-4dd1-a105-8f8bf31868a2",
"new_requester_profile_code": "329-09-0001-5963550",
"new_requester_profile_owner_document_number": "02602536000102",
"new_requester_profile_owner_name": "Coca Cola",
"new_requester_profile_account_number": "5963550",
"new_requester_profile_account_digit": "7",
"new_requester_profile_account_branch": "0001",
"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 200,
"total_amount": 38145.58
},
{
"bank_slip_exchange_batch_key": "8a5bbded-72ff-4642-8830-f2a5a73eb62c",
"request_control_key": "d3725802-7e56-4196-8182-2747ea18e96a",
"bank_slip_ownership_exchange_batch_status": "open",
"new_requester_profile_key": "316052e8-a017-4fb9-9939-9ce0390fa053",
"new_requester_profile_code": "329-09-0001-4743630",
"new_requester_profile_owner_document_number": "40500359000142",
"new_requester_profile_owner_name": "QI SCD",
"new_requester_profile_account_number": "4743630",
"new_requester_profile_account_digit": "1",
"new_requester_profile_account_branch": "0001",
"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 450,
"total_amount": 548682.19
},
{
"bank_slip_exchange_batch_key": "6f749806-8768-44ab-b7de-1f0d94d0a61a",
"request_control_key": "1c1551f2-c6e7-42d5-b78d-1f7662128a33",
"bank_slip_ownership_exchange_batch_status": "closed",
"new_requester_profile_key": "8bfdd50f-97fd-4f29-bc53-b542a914f2d6",
"new_requester_profile_code": "329-09-0001-7390371",
"new_requester_profile_owner_document_number": "56000040000198",
"new_requester_profile_name": "Meta",
"new_requester_profile_account_number": "7390371",
"new_requester_profile_account_digit": "7",
"new_requester_profile_account_branch": "0001",
"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 40,
"total_amount": 67245.96
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
## 响应参数
| 字段 | 类型 | 描述 | 字符数 |
|-----------------------------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key` | uuidv4 | tombamento 批次的唯一识别键。 | 36 |
| `request_control_key` | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。 | 36 |
| `bank_slip_ownership_exchange_batch_status` | enum | tombamento 批次的状态。 | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key` | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36 |
| `new_requester_profile_code` | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。 | 19 |
| `new_requester_profile_owner_name` | string | 目标账户持有人及目标托收钱包受益人的姓名。 | 255 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。 | 255 |
| `new_requester_profile_account_number` | string | tombamento 目标账户号。 | 7 |
| `new_requester_profile_account_digit` | string | tombamento 目标账户校验位。 | 1 |
| `new_requester_profile_account_branch` | string | tombamento 目标账户支行号。 | 4 |
| `new_pix_key` | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。 | 255 |
| `total_bank_slip_count` | float | tombamento 批次中的票据总数。 | - |
| `total_amount` | float | tombamento 批次中票据面值总和。 | - |
### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述 |
|------------|--------------------------------------------------------------------------------------------------------|
| open | 批次已创建，仍开放以纳入/删除票据。 |
| sent | 票据选择已完成，tombamento 批次待批准。批准方需完成批准操作。 |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| approved | 批次中的票据已完成 tombamento 转移给目标方。 |
| cancelled | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |
---
# 从 tombamento 批次中移除票据
URL: /zh-Hans/documentation/troca_de_titularidade/remover_boletos
此端点用于从状态为 `open` 的票据 tombamento 批次中移除票据。
## 请求
ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /remove
MÉTODO PATCH
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。 | 36 |
| `REQUESTER-PROFILE-KEY` | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36 |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | tombamento 批次的唯一识别键。| 36 |
Request Body
```json
{
"bank_slips": [
"b21c5b5a-a71f-4672-9254-022401cd15f6",
"8197e3d0-1500-439f-9f9d-d243115542fa",
"8293b817-bed9-418a-8c1e-ec8ef5a31468"
]
}
```
:::caution 注意！
payload 中 `bank_slips` 对象的票据列表，每次请求限制为 10,000 个票据。
:::
## 响应
STATUS 200
Response Body
```json
{
"bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
"bank_slip_ownership_exchange_batch_status": "open",
"new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
"new_requester_profile_code": "329-09-0001-8703524",
"new_requester_profile_owner_name": "Fulano de Tal",
"new_requester_profile_owner_document_number": "70896538000101",
"new_requester_profile_account_number": "8703524",
"new_requester_profile_account_digit": "1",
"new_requester_profile_account_branch": "0001",
"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 0,
"total_amount": 0
}
```
## 响应参数
| 字段 | 类型 | 描述 | 字符数 |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key` | uuidv4 | tombamento 批次的唯一识别键。 | 36 |
| `request_control_key` | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。 | 36 |
| `bank_slip_ownership_exchange_batch_status` | enum | tombamento 批次的状态。 | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key` | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36 |
| `new_requester_profile_code` | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。 | 19 |
| `new_requester_profile_owner_name` | string | 目标账户持有人及目标托收钱包受益人的姓名。 | 255 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。 | 255 |
| `new_requester_profile_account_number` | string | tombamento 目标账户号。 | 7 |
| `new_requester_profile_account_digit` | string | tombamento 目标账户校验位。 | 1 |
| `new_requester_profile_account_branch` | string | tombamento 目标账户支行号。 | 4 |
| `new_pix_key` | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。 | 255 |
| `total_bank_slip_count` | float | tombamento 批次中的票据总数。 | - |
| `total_amount` | float | tombamento 批次中票据面值总和。 | - |
### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述 |
|------------|--------------------------------------------------------------------------------------------------------|
| open | 批次已创建，仍开放以纳入/删除票据。 |
| sent | 票据选择已完成，tombamento 批次待批准。批准方需完成批准操作。 |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| approved | 批次中的票据已完成 tombamento 转移给目标方。 |
| cancelled | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |
---
# 发送票据 tombamento 批次
URL: /zh-Hans/documentation/troca_de_titularidade/validar_lote_e_enviar
此端点用于关闭批次并启动持有权变更的处理。发起请求时，批次将被验证，状态更改为 sent，双方将收到与 tombamento 相关的 webhook。
:::danger 注意！
只有在票据插入完成且来源和目标各方之间的正式化手续已完成时，才应调用此端点。
:::
## 请求
ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /send
MÉTODO PATCH
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | 原始账户的唯一识别键，即票据最初登记的账户。 | 36 |
| `REQUESTER-PROFILE-KEY` | uuidv4 | 原始托收钱包的唯一识别键，即票据最初登记的托收钱包。 | 36 |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | tombamento 批次的唯一识别键。 | 36 |
Request Body
```json
{}
```
## 响应
STATUS 200
Response Body
```json
{
"bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
"bank_slip_ownership_exchange_batch_status": "processing",
"new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
"new_requester_profile_code": "329-09-0001-8703524",
"new_requester_profile_owner_name": "Fulano de Tal",
"new_requester_profile_owner_document_number": "70896538000101",
"new_requester_profile_account_number": "8703524",
"new_requester_profile_account_digit": "1",
"new_requester_profile_account_branch": "0001",
"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
"total_bank_slip_count": 3,
"total_amount": 750.00
}
```
## 响应参数
| 字段 | 类型 | 描述 | 字符数 |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key` | uuidv4 | tombamento 批次的唯一识别键。 | 36 |
| `request_control_key` | uuidv4 | 此端点请求的唯一识别键。用于避免 API 调用重复。 | 36 |
| `bank_slip_ownership_exchange_batch_status` | enum | tombamento 批次的状态。 | [枚举器 `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key` | uuidv4 | 目标托收钱包的唯一识别键，即票据将被转移（tombados）到的托收钱包。可通过[账户托收钱包查询端点](../boletos/carteira/listar_carteiras)获取此键。 | 36 |
| `new_requester_profile_code` | string | 目标托收钱包代码，即票据将被转移（tombados）到的托收钱包。 | 19 |
| `new_requester_profile_owner_name` | string | 目标账户持有人及目标托收钱包受益人的姓名。 | 255 |
| `new_requester_profile_owner_document_number` | string | 目标账户持有人及目标托收钱包受益人的证件号（CPF/CNPJ）。 | 255 |
| `new_requester_profile_account_number` | string | tombamento 目标账户号。 | 7 |
| `new_requester_profile_account_digit` | string | tombamento 目标账户校验位。 | 1 |
| `new_requester_profile_account_branch` | string | tombamento 目标账户支行号。 | 4 |
| `new_pix_key` | string | tombamento 目标账户的 Pix 密钥（BolePix 情况下使用）。 | 255 |
| `total_bank_slip_count` | float | tombamento 批次中的票据总数。 | - |
| `total_amount` | float | tombamento 批次中票据面值总和。 | - |
### 枚举器 bank_slip_ownership_exchange_batch_status
| 枚举器 | 描述 |
|------------|--------------------------------------------------------------------------------------------------------|
| open | 批次已创建，仍开放以纳入/删除票据。 |
| closed | 批次已关闭，批次中票据的 tombamento 已完成。 |
| processing | 票据选择已完成，批次中票据的 tombamento 正在处理中。 |
| pending_approval | 票据选择已完成，tombamento 批次待批准。批准方可以从批次中删除票据。 |
| canceled | tombamento 批次已取消。 |
| rejected | tombamento 批次已拒绝。 |