Boleto 列表查询

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 枚举值
`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

{
  "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": "accepted"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 100
  }
}

Response Body Params

字段	类型	描述	字符数
`data` *	object array	Boleto 列表	bank_slip 对象
`pagination` *	object	分页信息	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 枚举值
`protest_status` *	string	Boleto 公证处抗议状态	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 对象
`protest_data`	object	抗议配置	protest_data 对象
`bankruptcy_protest_data`	object	破产抗议配置	bankruptcy_protest_data 对象
`fine_data`	object	罚款配置	fine_data 对象
`interest_data`	object	利息配置	interest_data 对象
`discounts_data`	object array	折扣	discount 对象
`payer_data` *	object	付款人数据	payer_data 对象
`guarantor_data` *	object	保证人数据	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 枚举值
`fine_amount` *	float	罚款绝对值	-
`days_to_fine` *	integer	到期后开始收取罚款所需天数	-

选项 2：百分比罚款（fine_type=percentage）

字段	类型	描述	字符数
`fine_type` *	string	罚款类型	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 枚举值
`interest_amount` *	float	按时间单位（工作日或自然日）收取的利息值	-
`days_to_interest` *	integer	到期后开始收取利息所需天数	-

选项 2：百分比利息（interest_type=calendar_days_monthly_percentage）

字段	类型	描述	字符数
`interest_type` *	string	利息类型	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 枚举值
`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 枚举值
`discount_limit_date` *	string	折扣应用截止日期	10

注意！

一张 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 枚举值
`contact`	object	联系信息	contact 对象
`address`	object	地址	address 对象

person_type 枚举值

枚举值	描述
natural	自然人
legal	法人

contact 对象

字段	类型	描述	字符数
`email`	string	联系邮箱	320
`phone`	object	联系电话	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 枚举值

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: 错误

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

Request​

路径参数​

查询参数​

bank_slip_status 枚举值​

Response​

Response Body Params​

bank_slip 对象​

pagination 对象​

protest_status 枚举值​

write_off_data 对象​

protest_data 对象​

bankruptcy_protest_data 对象​

fine_data 对象​

fine_type 枚举值​

interest_data 对象​

interest_type 枚举值​

discount 对象​

discount_type 枚举值​

payer_data 和 guarantor_data 对象​

person_type 枚举值​

contact 对象​

phone 对象​

address 对象​

state 枚举值​

错误响应​