跳到主要内容

供应商银行账户

登记、列出和修改接收该供应商费用付款的账户。一个供应商可以有多个账户，但始终有且只有一个主账户（main_account: true）。第一个登记的账户即为主账户；如需更换主账户，请将另一个账户设为主账户。

账户不受审核锁定限制：在供应商处于任何状态时都可以登记和修改，且提交审核时不是必需的。

登记银行账户​

适用范围
角色主机所需权限
管理人manager-api写入
顾问consultant-api有效集成

各主机的 Base URL：环境（主机）。

ENDPOINT
/vendor_registry/vendor/{vendor_key}/bank_account
方法
POST

路径参数​

参数类型说明
vendor_keystring供应商的 key（UUID）。
Corpo da requisição — Pix por chave
{
    "transfer_type": "pix",
    "pix_key": "44555666000181",
    "main_account": true
}
Corpo da requisição — TED
{
    "transfer_type": "ted",
    "financial_institution_code": "341",
    "account_branch": "0001",
    "account_number": "123456",
    "account_digit": "7"
}

请求体属性​

字段类型必填说明
transfer_typestring是pix 或 ted。
pix_keystring条件必填Pix 密钥，1 至 77 个字符。仅在 transfer_type = pix 时使用，且不带账户信息。
financial_institution_codestring条件必填银行的 COMPE 代码，恰好 3 位数字（341），不能全为零。
account_branchstring条件必填支行号，恰好 4 位数字，不能全为零。
account_numberstring条件必填账号，1 至 20 位数字，不能全为零。
account_digitstring条件必填账号校验位，恰好 1 位数字。
main_accountboolean否将此账户设为主账户，原主账户随之降级。默认值：false。供应商的第一个账户始终是主账户。

有效组合：

  • pix 带 pix_key，不带账户信息。
  • pix 带全部四项账户信息，不带 pix_key（向账户进行 Pix 转账）。
  • ted 带全部四项账户信息。

提供账户信息时，API 会根据 financial_institution_code 识别银行，并在响应中返回 ISPB。

响应​

STATUS
201
Corpo da resposta
{
    "bank_account_key": "0f9e8d7c-6b5a-4f3e-2d1c-0b9a8f7e6d5c",
    "transfer_type": "ted",
    "main_account": false,
    "status": "active",
    "financial_institution_code": "341",
    "financial_institution_ispb": "60701190",
    "account_branch": "0001",
    "account_number": "123456",
    "account_digit": "7"
}

响应属性​

字段类型说明
bank_account_keystring账户的 key（UUID）。
transfer_typestringpix 或 ted。
main_accountboolean主账户。
statusstringactive 或 inactive。
pix_keystringPix 密钥。仅在提供时返回。
financial_institution_codestring银行的 COMPE 代码。仅在有账户信息时返回。
financial_institution_ispbstring银行的 ISPB，8 位数字。仅在有账户信息时返回。
account_branchstring支行号。仅在有账户信息时返回。
account_numberstring账号。仅在有账户信息时返回。
account_digitstring账号校验位。仅在有账户信息时返回。

没有值的字段不会以 null 返回：它们会从响应中省略。

修改银行账户​

将账户设为主账户或修改其状态。两个字段至少需要提供一个。

适用范围
角色主机所需权限
管理人manager-api写入
顾问consultant-api有效集成

各主机的 Base URL：环境（主机）。

ENDPOINT
/vendor_registry/vendor/{vendor_key}/bank_account/{bank_account_key}
方法
PUT
Corpo da requisição
{
    "main_account": true
}
字段类型必填说明
main_accountboolean否仅接受 true：将此账户设为主账户，当前主账户随之降级。false 返回 400（VRG000074）。
statusstring否inactive 停用账户；active 重新启用。

响应​

STATUS
200

返回更新后的账户，结构与登记相同。

列出银行账户​

适用范围
角色主机所需权限
管理人manager-api读取
顾问consultant-api有效集成

各主机的 Base URL：环境（主机）。

ENDPOINT
/vendor_registry/vendor/{vendor_key}/bank_account
方法
GET

查询参数​

参数类型必填说明
limitinteger否每页条数，0 至 1000。默认值：10。
pageinteger否页码，从 0 开始。默认值：0。

返回所有账户（包括启用和停用的），按从新到旧排序。

响应​

STATUS
200
Corpo da resposta
{
    "data": [
        {
            "bank_account_key": "0f9e8d7c-6b5a-4f3e-2d1c-0b9a8f7e6d5c",
            "transfer_type": "pix",
            "main_account": true,
            "status": "active",
            "pix_key": "44555666000181"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}

错误​

STATUS
400
code发生情形
VRG000059在 transfer_type = ted 时提交了 pix_key。
VRG000028pix_key 与账户信息一起提交。
VRG000048transfer_type = pix，但既没有 pix_key，也没有全部四项账户信息。
VRG000019transfer_type = ted，但没有全部四项账户信息。
VRG000021financial_institution_code 不对应任何银行。
VRG000074修改时提交了 main_account: false。
VRG000078您尝试将已停用的账户，或在同一调用中被停用的账户设为主账户。
VRG000075您尝试在存在其他启用账户时停用主账户。请先将另一个账户设为主账户。
Exemplo
{
  "title": "Pix Key Or Account Data Required",
  "description": "For a pix transfer, either pix_key or the full account data (financial_institution_code, account_branch, account_number, account_digit) must be provided.",
  "translation": "Para uma transferencia pix, e necessario informar a pix_key ou os dados completos da conta (financial_institution_code, account_branch, account_number, account_digit).",
  "code": "VRG000048"
}
STATUS
404
code发生情形
VRG000014该 vendor_key 不存在，或您看不到该供应商。
VRG000073该 bank_account_key 不属于此供应商。

认证、权限和主机相关的错误：参见 API 错误。

下一步​

签署人组，或进行**提交审核**。