跳到主要内容

操作的第三方拨付

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

需申请开通的功能

第三方拨付默认不开通。集成前请先向 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 — Pix
{
    "payment_method": "pix",
    "pix_key": "52998224725",
    "pix_key_type": "cpf",
    "beneficiary": {
        "person_type": "natural",
        "name": "João da Silva",
        "document_number": "529.982.247-25",
        "street": "Rua das Flores",
        "number": "100",
        "postal_code": "01234-567",
        "city": "São Paulo",
        "state": "SP",
        "is_pep": false
    }
}

Request Body Params​

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

字段类型描述最大字符数
payment_method *string拨付所使用的支付通道。payment_method 枚举值
target_accountobject收款方的银行账户。当 payment_method 为 ted 时必填；在其他通道下禁止发送。target_account 对象
digitable_linestring收款方 boleto 的可键入行，仅数字（格式 ^[0-9]{47}$）。当 payment_method 为 bank_slip 时必填；在其他通道下禁止发送。47
pix_keystring收款方的 Pix 密钥；CPF 与 CNPJ 不带格式符号。当 payment_method 为 pix 时必填；在其他通道下禁止发送。77
pix_key_typestring所声明的 Pix 密钥类型。当 payment_method 为 pix 时必填；在其他通道下禁止发送。pix_key_type 枚举值
beneficiaryobject第三方收款人的资格信息。当 payment_method 为 pix 时必填；在 ted 与 bank_slip 下为可选。beneficiary 对象

payment_method 枚举值​

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

pix_key_type 枚举值​

值描述
cpfCPF，11 位数字，不带标点。
cnpjCNPJ，14 位数字，不带标点。
phone电话号码，格式为 +55 后接 10 或 11 位数字。
email电子邮箱地址，最多 77 个字符。
evp随机密钥（小写 UUID）。

密钥的格式由 schema 依据所声明的 pix_key_type 校验 — 格式不符时返回 QIT000001。对于 cpf 与 cnpj，随后还会校验校验位：格式正确但校验位错误时返回 COM000071。

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支付账户。

beneficiary 对象​

用于标识收款第三方。在 pix 通道下为必填 — 仅凭 Pix 密钥无法说明收款人是谁 — 在 ted 与 bank_slip 下为可选。该对象随指令一同流转，与操作一同被签署，并用于形成第三方付款的公司会议纪要。

仅 name 与 document_number 为必填。 其余字段均为可选，用于在会议纪要中补充收款方的资格信息。

字段类型描述是否必填
person_typestringnatural（自然人）或 legal（法人）。可选
name *string收款方名称。始终
document_number *stringCPF 或 CNPJ，带格式符号（000.000.000-00 或 00.000.000/0000-00）。始终
streetstring街道名称。可选
numberstring门牌号。可选
postal_codestring邮编，格式为 00000-000。可选
citystring城市。可选
statestring州（UF），两位大写字母。可选
is_pepboolean是否为政治公众人物（PEP）。可选
trading_namestring商号名称。可选
cnae_codestringCNAE，格式为 00.00-0-00。可选
company_typestring企业类型。可选
foundation_datestring成立日期（YYYY-MM-DD）。可选
neighborhoodstring街区。可选
complementstring地址补充信息。可选
document_identification_numberstring身份证件号码。可选
marital_statusstring婚姻状况。可选
property_systemstring夫妻财产制。可选
birthdatestring出生日期（YYYY-MM-DD）。可选
nationalitystring国籍。可选
mother_namestring母亲姓名。可选
father_namestring父亲姓名。可选
occupationstring职业。可选
发送得越多，会议纪要越完整

提供 person_type 时，会议纪要会包含收款方的资格信息；同时提供 street、number、postal_code、city 与 state（五项齐备）时，还会包含格式化后的地址。仅发送姓名与证件号码时，会议纪要只会列出收款方名称，不含资格信息与地址：不会报错，只是文档内容较为简略。

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收款方证件号码无效。
COM000071400cpf/cnpj 类型的 pix_key 校验位无效。
COM000007404未找到该操作。
COM000008403该操作不属于发起请求的 tenant。