通过密钥查询账单

通过密钥查询账单将返回特定账单的完整详情，包括所有账单项目。

Request

ENDPOINT

/wallet/WALLET_KEY/invoice/INVOICE_KEY

MÉTODO

GET

路径参数

字段	类型	描述	字符数
`wallet_key`	uuidv4	UUID v4 格式的钱包唯一密钥	36
`invoice_key`	uuidv4	UUID v4 格式的账单唯一密钥	36

Response

STATUS

200

Response Body：账单详情

{
  "invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "due_date": "2024-02-15",
  "closing_date": "2024-01-31",
  "invoice_status": "opened",
  "total_amount": 350.00,
  "paid_amount": 0.00,
  "invoice_items": [
    {
      "invoice_item_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "wallet_entry_key": null,
      "payment_instrument_entry_key": "g3ebe8d6-4c8a-1794-22d9-406c0f8g3dbe",
      "installment_number": 1,
      "invoice_description": "Compra no estabelecimento XYZ",
      "amount": 150.00,
      "used_limit": 150.00,
      "paid_amount": 0.00,
      "invoice_item_status": "concluded",
      "invoice_item_due_date": "2024-02-15",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "invoice_item_key": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
      "invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "wallet_entry_key": null,
      "payment_instrument_entry_key": "g3ebe8d6-4c8a-1794-22d9-406c0f8g3dbe",
      "installment_number": 2,
      "invoice_description": "Parcela 2 de 3 - Compra parcelada",
      "amount": 200.00,
      "used_limit": 200.00,
      "invoice_item_status": "concluded",
      "invoice_item_due_date": "2024-02-15",
      "created_at": "2024-01-16T14:45:00Z"
    }
  ],
  "invoice_payments": [
    {
      "invoice_payment_key": "c3d4e5f6-g7h8-9012-cdef-345678901234",
      "total_amount": 350.00,
      "paid_amount": 0.00,
      "invoice_payment_type": "bank_slip",
      "invoice_payment_status": "paid"
    }
  ],
  "invoice_payments_chargebacks": [
    {
      "invoice_item_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "chargeback_paid_amount": 50.00
    }
  ],
  "created_at": "2024-01-15T10:30:00Z"
}

响应体参数

字段	类型	描述	字符数
`invoice_key` *	uuidv4	uuid v4 格式的账单唯一识别密钥	36
`due_date` *	string	账单到期日（YYYY-MM-DD 格式）	10
`closing_date` *	string	账单结账日（YYYY-MM-DD 格式）	10
`invoice_status` *	string	账单状态	invoice_status 枚举值
`total_amount` *	number	账单总金额	-
`paid_amount` *	number	账单已付金额	-
`invoice_items` *	object array	账单项目	invoice_item 对象
`invoice_payments` *	object array	账单付款	invoice_payment 对象
`invoice_payments_chargebacks` *	object array	账单付款退款	invoice_payment_chargeback 对象
`created_at` *	string	创建日期（ISO 8601 UTC 格式）	-

invoice_item 对象

字段	类型	描述	字符数
`invoice_item_key` *	uuidv4	uuid v4 格式的账单项目唯一识别密钥	36
`invoice_key` *	uuidv4	uuid v4 格式的账单唯一识别密钥	36
`wallet_entry_key`	uuidv4	uuid v4 格式的钱包条目唯一识别密钥	36
`payment_instrument_entry_key`	uuidv4	uuid v4 格式的支付工具条目唯一识别密钥	36
`installment_number` *	integer	分期期数	-
`invoice_description` *	string	账单项目描述	-
`amount` *	float	项目金额	-
`used_limit` *	float	已用额度	-
`invoice_item_status` *	string	账单项目状态	invoice_item_status 枚举值
`invoice_item_due_date` *	string	项目到期日（YYYY-MM-DD 格式）	10
`created_at` *	string	创建日期（ISO 8601 UTC 格式）	-

invoice_payment 对象

字段	类型	描述	字符数
invoice_payment_key *	uuidv4	uuid v4 格式的账单付款唯一识别密钥	36
total_amount	number	付款总金额	-
paid_amount	number	已付金额	-
invoice_payment_type *	string	账单支付类型	invoice_payment_type 枚举值
invoice_payment_status *	string	账单付款状态	invoice_payment_status 枚举值

invoice_payment_chargeback 对象

字段	类型	描述	字符数
invoice_item_key *	uuidv4	与退款相关的账单项目 uuid v4 格式唯一识别密钥	36
chargeback_paid_amount	number	已使用的退款金额	-

invoice_status 枚举值

枚举值	描述
opened	账单已开
processing_closing	处理结账中
processing_expiration	处理到期中
closed	账单已结
processing_payment	等待付款
paid	账单已付

说明

processing_payment 状态仅适用于 payroll 类型的钱包，在已收到可能付款金额但仍有剩余金额需通过福利支付的场景下应用。

invoice_payment_type 枚举值

枚举值	描述
bank_slip	银行票据（Boleto bancário）
payroll_discount	通过 INSS 折扣支付

说明

payroll_discount 类型仅存在于 payroll 类型的钱包，代表通过福利扣除的金额。

invoice_payment_status 枚举值

枚举值	描述
processing_payment	等待付款
paid	已付款

说明

对于 payroll_discount 类型的付款：付款在账单结账时以 processing_payment 状态创建，并向 INSS 请求折扣。当折扣付款完成后，状态变为 paid。
对于 bank_slip 类型的付款：当我们收到票据付款通知时，付款以 processing_payment 状态创建。票据结算后，状态变为 paid。若未收到付款通知，付款可直接以 paid 状态创建。

invoice_item_status 枚举值

枚举值	描述
concluded	项目已完成
canceled	项目已取消

错误响应

STATUS

4xx

Response Body: Error

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

HTTP 代码 `status`	QI 代码 `code`	标题 `title`	描述（英文） `description`	描述（葡文） `translation`
404	CIN000007	Wallet not Found	Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found	Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado
404	CIN000080	Not Found	Invoice with key: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 was not found	Fatura com a chave: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 não foi encontrado

Request​

路径参数​

Response​

响应体参数​

invoice_item 对象​

invoice_payment 对象​

invoice_payment_chargeback 对象​

invoice_status 枚举值​

invoice_payment_type 枚举值​

invoice_payment_status 枚举值​

invoice_item_status 枚举值​

错误响应​