跳到主要内容

使用双因素身份验证执行 TED 批量交易

QI Tech 提供通过单次 API 调用执行多笔 TED 交易的功能。在此系统中，交易以异步方式执行。如果初始调用返回 http status 4xx，则不会执行任何交易。请求后，集成合作伙伴将为每笔交易收到一个 Webhook，告知尝试的最终状态，可能为 rejected 或 sent。

在此类交易中，需要通过发送给账户中具有批准转账权限的人员的令牌来确认付款。

配置为使用双因素身份验证的集成合作伙伴的 TED 批量交易请求方式与执行 TED 批量交易中描述的方式类似。区别在于添加了 tfa_info 对象，以及成功请求的状态将始终为 pending_2fa_approval。

令牌发送至批准人的通知事件为 baas.token_validation.ted.batch。可以自定义发送的消息。

请求​

ENDPOINT
/account/ACCOUNT_KEY/ted_batch
方法
POST

通过邮件和短信进行身份验证​

Request Body: 通过短信或邮件进行 TFA 的批量转账
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "teds": [
    {
      "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
      "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": "ff9f2a48-918c-4911-9371-a496e37dccfc",
      "target_account": {
        "account_branch": "0001","account_number": "92797","account_digit": "2",
        "owner_document_number": "23599885000192","owner_name": "Titular da Conta",
        "ispb": "12345678","account_type": "checking_account"
      },
      "transaction_amount": 10.00
    }
  ]
}

通过设备进行身份验证​

除了现有的 sms 和 email 身份验证方式外，还可以使用预先注册的设备对交易进行身份验证。在这种情况下，需要从 Device Scan 中获取 session_id 并在 tfa_info 中发送。

Request Body: 通过设备进行 TFA 的批量转账
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "teds": [
    {
      "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
      "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": "ff9f2a48-918c-4911-9371-a496e37dccfc",
      "target_account": {
        "account_branch": "0001","account_number": "92797","account_digit": "2",
        "owner_document_number": "23599885000192","owner_name": "Titular da Conta",
        "ispb": "12345678","account_type": "checking_account"
      },
      "transaction_amount": 10.00
    }
  ]
}

Path Params​

字段类型描述字符数
account_keyuuidv4账户的唯一标识键。36

Body Params​

字段类型描述字符数
request_control_key *uuidv4客户使用的 uuid v4 格式的请求唯一标识键。36
teds *array与批次关联的 TED 对象列表。列表 Objeto ted
tfa_info *Object包含账户批准人文件号和联系方式的对象。Objeto tfa_info

Objeto tfa_info​

字段类型描述字符数
approver_document_number *string账户批准人的文件号。11
session_idstring设备会话唯一标识键，UUID v4 格式（设备 TFA 必填）。36
contact_type *string与账户批准人的联系方式，可为 sms、email 或 device

Objeto ted​

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

Objeto 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账户类型。Enumerador account_type
ispb *string基于金融机构 CNPJ（8 位数字）。8

Enumerador account_type​

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

响应​

STATUS
202
Response Body: 已请求批量转账
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "ted_batch_status": "pending_2fa_approval"
}

Enumerador ted_batch_status​

枚举值描述
approved批量转账已批准，交易正在执行中。
rejected批量转账已拒绝
pending_2fa_approval批量调度待双因素身份验证批准
cancelled批量转账已取消
STATUS
4xx
Response Body: 已拒绝转账
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "ted_batch_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "ted_batch_status": "rejected"
    }
  }
}
信息

此端点也可能返回 TED 批量交易 中列出的错误，以及以下错误。

HTTP 状态码
status		QI 代码
code		标题
title		描述（英文）
description		描述（葡文）
translation
400TED000079No approver permissionGiven document number does not belong to an approver for this accountNúmero de documento enviado não pertence a um aprovador da conta
400TED000080tfa_info is requiredClient must send object tfa_infoCliente deve enviar objeto tfa_info
400TED000081Error occurred while sending tokenAn unexpected error occurred while sending tokenUm erro inexperado ocorreu ao tentar enviar token