跳到主要内容

TED

执行 TED 转账​

在巴西国家金融系统中，TED 交易的接收并非即时完成。在 QI 系统中执行 TED 交易时，系统将立即返回响应，说明转账的错误、拒绝或接受情况。即使转账已被置于 sent 状态，接收金融机构也可能拒绝资金转入并将金额退回。在此情况下，将发送一个新的状态为 rejected 的 webhook，拒绝原因将在 refusal_reason 字段中返回。

对来源账户的扣款将立即执行。这并不意味着金额已被贷记至目标账户，因为上述 TED 交易原则仍然适用。若发出的交易被拒绝，交易金额将重新贷记至来源账户。

Request​

ENDPOINT
/account/ACCOUNT_KEY/ted
MÉTODO
POST
Request Body
{
  "target_account": {
    "account_branch": "0001",
    "account_number": "92796",
    "account_digit": "1",
    "owner_document_number": "23599885000192",
    "owner_name": "Titular da Conta",
    "ispb": "12345678",
    "account_type": "checking_account"
  },
  "transaction_amount": 8.86,
  "request_control_key": "048c8ee5-1c91-46a6-952e-7e5c27c21f20"
}

Body Params​

字段类型描述字符数
request_control_key *string客户使用的请求唯一标识密钥，格式为 uuid v4。36
target_account *object目标账户target_account 对象
transaction_amount *float转账金额10

target_account 对象​

字段类型描述字符数
account_branch *string支行。4
account_digit *string账户数字1
account_number *string账户号码。20
owner_document_number *string账户持有人的 CPF 或 CNPJ（仅数字）。14
owner_name *string账户持有人姓名。50
account_type*string账户类型。account_type 枚举
ispb *string以金融机构 CNPJ 为基础（8位数字）。8

account_type 枚举​

枚举值描述
checking_account活期账户
deposit_account存款账户
guaranteed_account担保账户
investment_account投资账户
payment_account支付账户
saving_account储蓄账户

Response​

STATUS
201
Response Body
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "sent",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "transaction_key": "8ea90347-330d-4b3a-8ebb-2ac217ad6eb3"
}
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
400QIT000001Bad RequestSchema ErrorErro de Schema
400TED000XXXrequest_control_key must be a valid uuid v4 stringrequest_control_key was not accepted for not being a valid uuid v4 stringrequest_control_key não foi aceito por não ser uma palavra uuid v4 válida
400TED000XXXInvalid Transaction AmountTransaction amount of {transaction_amount} is not valid. It must be a positive value with at maximum 2 decimal placesO valor de transação {transaction_amount} não é válido. Deve ser um valor positivo com no máximo duas casas decimais
404TED000XXXAccount not foundAccount not found for: {account_datum}Conta não encontrada para: {account_datum}
400TED000XXXAccount is ClosedAccount {account_key} is closed.Conta {account_key} está fechada.
400TED000XXXAccount is BlockedAccount {account_key} is blocked.Conta {account_key} está bloqueada.
403TED000XXXUser is not allowed to do this transactionUsuário não tem autorização para fazer essa transação
400TED000XXXTarget Account may not receive resourcesTarget account is currently unavailable o receive resorsesConta destino está impedida de receber recursos
400TED000XXXBad RequestInsufficient account balance for transfer and fee amount.Saldo de conta insuficiente para a transferência e a taxa.
400TED000XXXBad RequestBilling account closed or blockedConta de cobrança encerrada ou bloqueada
400TED000XXXBad RequestInsufficient billing account balance for fee.Saldo de conta de cobrança insuficiente para a taxa.
400TED000XXXBad RequestTransaction amount is over limit.O total da transferência é superior ao limite.
400TED000XXXBad RequestInsufficient account balance for transfer and fee amount.Saldo de conta insuficiente para a transferência e a taxa
400TED000XXXBad Requestrequest_control_key {request_control_key} already in userequest_control_key {request_control_key} já utilizada
400TED000XXXInvalid Target Account NumberTarget account number is invalidNúmero da conta de destino é inexistente ou inválido
400TED000XXXInvalid Target Account Document NumberTarget account document is invalidNúmero de documento enviado é inválido
400TED000XXXUnrelated Beneficiary Document NumberTarget account document is not the same as sentNúmero de documento da conta de destino diferente do enviado
400TED000XXXBlocked Target AccountTarget account is blocked.A conta de destino encontra-se bloqueada.
400TED000XXXClosed Target AccountTarget account is closed.A conta de destino encontra-se encerrada.
400TED000XXXRejected Payment OrderTransaction refused by targetTransação rejeitada por recebedor.

查询 TED 交易​

Request​

ENDPOINT
/account/ACCOUNT_KEY/ted/TED_KEY/TED_DIRECTION
MÉTODO
GET

Request Path Params​

字段类型描述字符数
ted_direction *string用于指示交易是入账还是出账的过滤器。ted_direction 枚举
account_key *uuidv4QI 账户的唯一标识密钥36
ted_key *uuidv4TED 转账的唯一标识密钥36

ted_direction 枚举​

枚举值描述
incoming入账
outgoing出账
注意

仅在以下情况下允许查看转账：对于 outgoing 类型的 ted_direction，请求方需对交易来源账户有权限；对于 incoming 类型的 ted_direction，请求方需对交易接收账户有权限。否则将返回未找到错误。

Response​

STATUS
200
Response Body: 被拒绝转账（outgoing）
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "rejected",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "target_account": {
    "account_branch": "0001",
    "account_digit": "6",
    "account_number": "78340",
    "ispb": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "QI Tech"
  },
  "refusal_reason": {
    "refusal_code": 1,
    "enumerator": "conta_destinatario_encerrada",
    "description": "Conta Destinatária do Crédito Encerrada"
  }
}
Response Body: 已发送转账（outgoing）
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "sent",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "target_account": {
    "account_branch": "0001",
    "account_digit": "6",
    "account_number": "78340",
    "ispb": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "QI Tech"
  },
  "refusal_reason": {}
}
Response Body: 已接收转账（incoming）
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "received",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "6",
    "account_number": "78340",
    "ispb": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "QI Tech"
  },
  "refusal_reason": {}
}
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
404TED000XXXOutgoing TED Not FoundTed key {ted_key} was not foundTransferência Ted de saída com chave {ted_key} não foi encontrada.
404TED000XXXIncoming TED Not FoundTed key {ted_key} was not foundTransferência Ted de entrada com chave {ted_key} não foi encontrada.

查询 TED 交易列表​

Request​

ENDPOINT
/account/ACCOUNT_KEY/teds
MÉTODO
GET

Path Params​

字段类型描述字符数
account_key *uuidv4QI 账户的唯一标识密钥36

Query Params​

字段类型描述字符数
ted_directionenumerator交易方向指示器（入账或出账）。若未发送，默认为 outgoingted_transfer_direction 枚举
request_control_keyuuidv4客户使用的请求唯一标识密钥。36
date_fromstring起始日期。格式为 "YYYY-MM-DD"
date_tostring结束日期。格式为 "YYYY-MM-DD"
pageinteger请求的页码，默认为 1
page_sizeinteger查询请求的页面大小，默认值和最大值均为 30最大值为 30

ted_transfer_direction 枚举​

枚举值描述
incoming入账 TED 转账
outgoing出账 TED 转账

Response​

STATUS
201
Response Body
{
  "data": [
    {
      "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
      "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
      "created_at": "2021-10-22T20:30:23.459Z",
      "ted_status": "sent",
      "transaction_amount": 126.97,
      "fee_amount": 0.0,
      "target_account": {
        "account_branch": "0001",
        "account_digit": "6",
        "account_number": "78340",
        "ispb": "12345678",
        "owner_document_number": "32402502000135",
        "owner_name": "QI Tech"
      },
      "refusal_reason": {}
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  }
}

TED 发送完成后的 Webhook​

Webhook 将通知 TED 交易是否被退回。

Webhook Request Body​

Webhook Body: TED 被拒绝
{
  "webhook_type": "baas.ted.outgoing_ted",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
    "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
    "created_at": "2021-10-22T20:30:23.459Z",
    "ted_status": "sent",
    "transaction_amount": 126.97,
    "fee_amount": 0.0,
    "target_account": {
      "account_branch": "0001",
      "account_digit": "6",
      "account_number": "78340",
      "ispb": "12345678",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech"
    },
    "refusal_reason": {
      "refusal_code": 1,
      "enumerator": "conta_destinatario_encerrada",
      "description": "Conta Destinatária do Crédito Encerrada"
    }
  }
}

Webhook Body Param​

字段类型描述最大字符数
webhook_typestring定义所报告事件类型的枚举值23
webhook_datetimestringWebhook 发送的日期和时间20
request_control_keystring客户使用的请求唯一标识密钥，格式为 uuid v436
ted_keystringTED 转账的唯一标识密钥36
created_atstring交易创建的日期和时间24
ted_statusstringTED 交易状态ted_status 枚举
transaction_amountnumber转账金额10
fee_amountnumber转账收取的费用35
target_accountObject目标账户 - 仅在 "manual" 类型交易中发送target_account 对象
refusal_reasonObject根据巴西中央银行标准的拒绝原因refusal_reason 对象

ted_status 枚举​

枚举值描述
sentTED 转账成功执行。
pendingTED 转账待处理。
rejectedTED 转账被拒绝。
returnedTED 转账被退回。

target_account 对象​

字段类型描述字符数
account_branch *string支行。4
account_digit *string账户数字1
account_number *string账户号码。20
owner_document_number *string账户持有人的 CPF 或 CNPJ（仅数字）。14
owner_name *string账户持有人姓名。50
account_type*string账户类型。account_type 枚举
ispb *string以金融机构 CNPJ 为基础（8位数字）。8

refusal_reason 对象​

字段类型描述字符数
bacen_code *string巴西中央银行拒绝代码3
enumerator *string巴西中央银行拒绝枚举值100
description *string巴西中央银行拒绝描述100

account_type 枚举​

枚举值描述
checking_account活期账户
deposit_account存款账户
guaranteed_account担保账户
investment_account投资账户
payment_account支付账户
saving_account储蓄账户

接收 TED 后的 Webhook​

Webhook 将通知 TED 交易的最终状态。

Webhook Request Body​

Request Body: TED 已接收
{
  "webhook_type": "baas.ted.incoming_ted",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
    "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
    "created_at": "2021-10-22T20:30:23.459Z",
    "ted_status": "received",
    "transaction_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "6",
      "account_number": "78340",
      "ispb": "12345678",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech"
    },
    "refusal_reason": {}
  }
}

Webhook Body Param​

字段类型描述最大字符数
webhook_typestring定义所报告事件类型的枚举值23
webhook_datetimestringWebhook 发送的日期和时间20
ted_keystringTED 转账的唯一标识密钥36
created_atstring交易创建的日期和时间100
ted_statusstringTED 交易状态ted_status 枚举
transaction_amountnumber转账金额10
fee_amountnumber转账收取的费用35
target_accountObject目标账户 - 仅在 "manual" 类型交易中发送target_account 对象
refusal_reasonObject根据巴西中央银行标准的拒绝原因refusal_reason 对象

ted_status 枚举​

枚举值描述
receivedTED 转账成功执行。
pendingTED 转账待处理。
rejectedTED 转账被拒绝。

target_account 对象​

字段类型描述字符数
account_branch *string支行。10
account_digit *string账户数字10
account_number *string账户号码。10
owner_document_number *string账户持有人的 CPF 或 CNPJ（仅数字）。14
owner_name *string账户持有人姓名。50
account_type*string账户类型。account_type 枚举
ispb *string以金融机构 CNPJ 为基础（8位数字）。8

refusal_reason 对象​

字段类型描述字符数
bacen_code *string巴西中央银行拒绝代码3
enumerator *string巴西中央银行拒绝枚举值100
description *string巴西中央银行拒绝描述100

account_type 枚举​

枚举值描述
checking_account活期账户
deposit_account存款账户
guaranteed_account担保账户
investment_account投资账户
payment_account支付账户
saving_account储蓄账户