跳到主要内容

操作的第三方拨付

此端点用于设置或替换一笔操作的第三方拨付指令，表示释放的金额将支付给第三方收款方（例如供应商），而不是支付到发行人的清算账户。

需申请开通的功能

第三方拨付默认不开通。集成前请先向 QI Tech 申请开通 — 未开通时，请求会以 COM000062 被拒绝。

整体替换与可变更窗口

该请求会替换整条指令 — 不支持字段级的部分更新。只有当操作处于 in_filling 状态时才能设置或变更该指令；不在该状态时，请求会以 COM000010 被拒绝。

操作的第三方拨付 (PUT)​

Request​

ENDPOINT
/commercial_paper/operation/OPERATION-KEY/third_party_disbursement
MÉTODO
PUT

Path Params​

字段类型描述最大字符数
OPERATION-KEY *string操作的唯一键（UUID v4）。36
Request Body — TED
{
    "payment_method": "ted",
    "target_account": {
        "account_branch": "0001",
        "account_number": "4464541",
        "account_digit": "3",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329",
        "account_type": "checking",
        "owner_document_number": "11.222.333/0001-81",
        "owner_name": "Fornecedor Exemplo LTDA"
    }
}
Request Body — Boleto
{
    "payment_method": "bank_slip",
    "digitable_line": "34191790010104351004791020150008291070100000000"
}

Request Body Params​

请求体不接受所列字段之外的任何字段（additionalProperties: false）。两条通道互斥，且该互斥性由 schema 保证：在 bank_slip 下发送 target_account、在 ted 下发送 digitable_line、遗漏所选通道的必填字段，或发送未知字段，都会返回 QIT000001。

字段类型描述最大字符数
payment_method *string拨付所使用的支付通道。payment_method 枚举值
target_accountobject收款方的银行账户。当 payment_method 为 ted 时必填；为 bank_slip 时禁止发送。target_account 对象
digitable_linestring收款方 boleto 的可键入行，仅数字（格式 ^[0-9]{47}$）。当 payment_method 为 bank_slip 时必填；为 ted 时禁止发送。47

payment_method 枚举值​

值描述
ted通过 TED 支付至 target_account 中填写的账户。
bank_slip支付 digitable_line 中填写的 boleto。

target_account 对象​

字段类型描述最大字符数
account_branch *string收款方银行账户的支行，仅数字（正好 4 位）。4
account_number *string收款方银行账户的号码，仅数字（1 至 20 位）。20
account_digit *string收款方银行账户的校验位，仅数字（正好 1 位）。1
financial_institution_ispb *string收款方金融机构的 ISPB 代码，仅数字（正好 8 位）。决定 TED 的路由。8
financial_institution_code_numberstring 或 null收款方金融机构的代码，仅数字（3 位）。可选，且不参与路由。3
account_type *string收款方的账户类型。account_type 枚举值
owner_document_number *string账户持有人的 CPF 或 CNPJ，需带格式（000.000.000-00 或 00.000.000/0000-00）。系统会校验其校验位。18
owner_name *string账户持有人的姓名（1 至 50 个字符）。50

account_type 枚举值​

值描述
checking活期账户。
savings储蓄账户。
salary工资账户。
payment支付账户。
TED — 请核对 ISPB

TED 的目标机构由 financial_institution_ispb 决定。ISPB 填错会把资金汇往错误的机构，即使 financial_institution_code_number 是正确的。

Boleto — 金额必须与释放金额一致

Boleto 的金额取自可键入行的最后 10 位数字，以分为单位，且必须等于操作的 financial.released_amount。任何差异都会以 COM000061 被拒绝。

由于计算得到的 released_amount 会因费用而与申请金额不同，实际可行的做法是：先创建操作，读取响应中的 released_amount，然后再附上正好为该金额的 boleto。请勿改写真实可键入行中的金额 — 这会使其校验位失效，boleto 将无法支付。

一张商业票据只支付一个收款方，且为全额支付：不支持付款拆分。

Response​

STATUS
200

响应返回操作的完整对象，其形式与按键值查询操作返回的一致。

Response Body
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
    "operation_type": "commercial_paper",
    "operation_status": "in_filling",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issuer_name": "Dynamic Enterprises",
    "issuer_document_number": "28.980.395/0001-55",
    "issuer_bank_account": {
        "account_type": "checking",
        "account_digit": "3",
        "account_branch": "0001",
        "account_number": "4464541",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329"
    },
    "financial": {
        ...
    }
}

Response Body Params​

字段类型描述
tenant_key *stringtenant 的唯一键。
operation_key *string操作的唯一键。
operation_status *string操作的状态。
issuer_key *string发行人的唯一键。
issuer_name *string发行人的名称。
issuer_document_number *string发行人的证件号码。
financial *object操作的财务数据。
信息

该指令在操作对象中以 third_party_disbursement 的形式出现，与提交时的形式一致。当操作没有第三方拨付时，该键会从响应中省略 — 不会返回 null。

错误​

以下错误代码同样记录在错误目录中。

错误代码HTTP描述
QIT000001400Schema 校验失败 — 例如 payment_method 缺失或不在枚举范围内、target_account 与 digitable_line 的组合无效、digitable_line 不符合 47 位数字的格式，或请求体中含有未知字段。
COM000010400操作不处于 in_filling 状态，无法更新。
COM000061400Boleto 金额与操作的 released_amount 不一致。
COM000062400未开通第三方拨付功能。
COM000063400收款方证件号码无效。
COM000007404未找到该操作。
COM000008403该操作不属于发起请求的 tenant。