# QI Tech — Banking-as-a-Service › 预付卡管理
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
17 página(s).
Índice:
- 授权请求（可选） (/zh-Hans/documentation/cards/autorizacao/)
- 模拟授权 (/zh-Hans/documentation/cards/autorizacao/simular_autorizacao)
- 创建实体卡 (/zh-Hans/documentation/cards/create/gerar_cartao_fisico)
- 创建虚拟卡 (/zh-Hans/documentation/cards/create/gerar_cartao_virtual)
- 简介 (/zh-Hans/documentation/cards/introducao)
- 通过授权密钥查询授权 (/zh-Hans/documentation/cards/search/buscar_autorizacao)
- 查询授权列表 (/zh-Hans/documentation/cards/search/buscar_autorizacoes)
- 通过密钥查询卡片 (/zh-Hans/documentation/cards/search/buscar_cartao_by_key)
- 查询 PCI 数据 (/zh-Hans/documentation/cards/search/buscar_dados_pci)
- 通过卡片密钥查询配送信息 (/zh-Hans/documentation/cards/search/buscar_entrega_by_key)
- 查询 PCI 密码 (/zh-Hans/documentation/cards/search/buscar_senha)
- 列出卡片 (/zh-Hans/documentation/cards/search/listar_cartoes)
- 激活实体卡 (/zh-Hans/documentation/cards/status/ativar_cartao)
- 更新状态 (/zh-Hans/documentation/cards/status/update_status_cartao)
- 非接触式（Contactless）配置 (/zh-Hans/documentation/cards/update/contactless_cartao)
- 修改实体卡密码 (/zh-Hans/documentation/cards/update/password_cartao)
- 更新配送地址 (/zh-Hans/documentation/cards/update/update_delivery_address)
---
# 授权请求（可选）
URL: /zh-Hans/documentation/cards/autorizacao/
---
程序配置完成、持卡人已添加并拥有一张有效卡片后，该卡片即可在世界各地的多个销售点进行消费。每当在某个受理终端发起交易时，系统将创建一个 `Authorization`（授权）来授权该操作。系统将向客户系统发送 `Authorization Request`（授权请求），由客户根据请求中包含的信息决定是否批准该授权。
`Authorization` 实体包含已授权和已捕获金额的当前状态，可取以下状态值：
| 状态 | 描述 |
|---|---|
| pending | 授权请求已获批准，尚无捕获或取消事件被处理 |
| unauthorized | 授权请求未获批准 |
| completed | 对该授权至少已成功捕获一个金额（可等于、小于或大于所有授权请求中批准的总金额）|
| reversed | 授权已被完全冲正，或已过期而未捕获 |
授权字段详情请参阅[查询授权](/documentation/cards/search/buscar_autorizacao/)
发送给客户的 `Authorization Request` 将包含[认证头信息](/documentation/primeiros_passos/teste_de_autenticacao/webhook_v2/index.html)，其结构如下：
### 授权请求
ENDPOINT (client_url)/authorization_request
METODO POST
Request Body
```json
{
"authorization_key": "c91ce179-517c-48f9-9c28-18368457b67f",
"authorization_request_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"card": {
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"type": "virtual",
"card_name": "ecommerce sample",
"printed_name": "Aurora Catarina",
"status": "active",
"brand": "visa",
"bin": "123456",
"last_four_digits": "5695"
},
"terminal_id": "123456",
"terminal_country_code": "BRA",
"terminal_type": "2",
"terminal_pin_entry_capability": true,
"terminal_magnetic_stripe_capability": true,
"terminal_contactless_capability": false,
"terminal_chip_capability": true,
"merchant_acquirer_code": "250",
"merchant_code": "123456",
"merchant_name": "VASP LINHAS AEREAS",
"merchant_street": "RUA CMDTE X, 127",
"merchant_city": "SAO PAULO, SP",
"merchant_region": "BRA",
"merchant_postal_code": "04570-140",
"merchant_mcc": "3036",
"authorization_code": "473890",
"nsu": "123456",
"acquirer_reference_number": "12312423",
"merchant_currency_code": "BRL",
"merchant_amount": 10.59,
"billing_currency_code": "BRL",
"billing_amount": 10.59,
"processing_datetime": "2023-01-10T13:45:52.000Z",
"number_of_installments": 1,
"authorization_type": "authorization",
"pan_entry_mode": "chip",
"pin_sent": true,
"autorization": {Objeto Autorização}
}
```
#### Authorization Request
| 字段 | 类型 | 描述 |
|---|---| ---|
| `authorization_request_key` | string | 授权请求的唯一标识符 |
| `authorization_key` | string | 与本请求关联的授权实体的唯一标识符 |
| `card` | object |**[Card 对象](#objeto-card)** |
| `terminal_id` | string | 收单机构在授权消息中发送的终端标识符 |
| `terminal_country_code` | string | 终端所在国家代码，依据 ISO 3166-1 alpha-3 在授权消息中发送 |
| `terminal_type` | string | 授权消息中收到的终端类型 |
| `terminal_pin_entry_capability` | boolean | 终端是否支持输入卡密码？ |
| `terminal_magnetic_stripe_capability` | boolean | 终端是否能读取磁条？ |
| `terminal_contactless_capability` | boolean | 终端是否能发起非接触式交易？ |
| `terminal_chip_capability` | boolean | 终端是否能使用 EMV 芯片发起交易？ |
| `merchant_acquirer_code` | string | 授权消息中收单机构的标识符 |
| `merchant_code` | string | 授权消息中商户在收单机构的标识符 |
| `merchant_name` | string | 授权消息中的商户名称 |
| `merchant_street` | string | 商户地址的街道 |
| `merchant_city` | string | 商户地址的城市 |
| `merchant_region` | string | 商户地址的地区 |
| `merchant_postal_code` | string | 商户地址的邮政编码（CEP）|
| `merchant_mcc` | string | 商户类别代码 - 识别商户类型 - [最新列表可在此处查阅](https://usa.visa.com/content/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf) |
| `authorization_code` | string | 6 位授权码 |
| `nsu` | string | 定义一次授权的唯一顺序号 |
| `acquirer_reference_number` | string | 收单机构的唯一授权标识符 |
| `merchant_currency_code` | string | 交易使用的货币 - ISO 4217-alpha |
| `merchant_amount` | decimal | 交易发生货币下的交易金额 |
| `billing_currency_code` | string | 持卡人账单货币 - ISO 4217-alpha |
| `billing_amount` | decimal | 持卡人账单货币下的交易金额 |
| `processing_datetime` | timestamp utc | 授权请求的处理时间 |
| `number_of_installments` | int | 本次请求授权的分期数 |
| `authorization_request_type` | enum | **[授权请求类型枚举](#tipos-de-autorizacao)** |
| `pan_entry_mode` | enum | **[PAN 输入模式](#modos-de-entrada-do-pan)** - 芯片、手动输入、磁条、降级、非接触式 |
| `pin_sent` | boolean | 终端是否输入了密码？ |
| `authorization` | object | 授权对象，详见 [GET 授权](/documentation/cards/search/buscar_autorizacao/)，仅在授权类型为增量时存在。 |
#### Card 对象
| 字段 | 类型 | 描述 |
|---| ---| ---|
| `card_key` | string | 卡片识别密钥 |
| `account_key` | string | 持卡人账户标识符 |
| `type` | string | 卡片类型 |
| `card_name` | string | 卡片字母数字标识符 |
| `printed_name` | string | 印在卡片上的姓名 |
| `status` | string | 卡片当前状态 |
| `brand` | string | 卡片所属卡组织 |
| `bin` | string | 卡片 BIN |
| `last_four_digits` | string | 卡号后四位 |
#### 授权请求类型
| 枚举值 | 描述 |
|---|---|
| **authorization** | 普通授权请求 |
| **incremental_authorization** | 对已有授权的增量授权请求 |
| **partial_reversal_authorization** | 对之前交易进行部分冲正的授权，仅出现在事件中，不由客户明确授权 |
| **reversal_authorization** | 对之前交易进行冲正的授权，仅出现在事件中，不由客户明确授权 |
#### PAN 输入模式
枚举值 | ISO 8583 | 描述
---------- | -------- | -----------
unknown | 00 | 未知的 PAN 输入模式。
typed | 01 | 手动输入（键入）PAN。
bar_code | 03 | 通过条形码读取器输入 PAN
ocr | 04 | 通过 OCR（光学字符识别）输入 PAN
chip | 05 | 通过集成电路卡（芯片）输入 PAN
track_1 | 06 | 通过卡片磁条 Track 1 输入 PAN
contactless | 07 | 通过非接触式 EMV 输入 PAN
fallback_typed | 79 | 尝试使用设备读卡器或磁条时无法处理交易（可能是设备或卡片问题），随后手动键入 PAN。某些情况下收单机构未获授权使用芯片或磁条并发送此代码。
fallback_magnetic_stripe | 80 | 尝试使用设备读卡器时无法处理交易（可能是设备或卡片问题），随后改用卡片磁条。
ecommerce | 81 | 电商/非当面交易
magnetic_stripe | 90 | 磁条交易（卡片无芯片或设备无读卡器/未获授权）
### 对授权请求的批准或拒绝响应
对授权请求的响应必须始终使用 HTTP Status 201，审批意见在 *approve* 字段中说明。若审批为否定，需选择一个拒绝原因枚举值，并可发送文字描述来详述拒绝原因。
ENDPOINT (client_url)/authorization_request
MÉTODO POST
HTTP STATUS 201
Response Body
```json
"authorization_request_response": "unauthorized",
"denial_reason": "fraud_suspicion",
"denial_reason_details": "Customer tried to perform a transaction 10 times the average transaction value."
```
| 字段 | 类型 | 描述 |
|---|---| ---|
| `authorization_request_response` | enum | *authorized* 或 *unauthorized* |
| `denial_reason` | enum | **[拒绝原因枚举](#razoes-de-negacao)** — 仅在 `authorization_request_response` 为 *unauthorized* 时必填 |
| `denial_reason_details` | string | 拒绝原因的文字描述 |
#### 拒绝原因
| 枚举值 | 描述 |
|---|---|
| insufficient_funds | 余额不足 |
| invalid_pin | PIN 无效 |
| card_blocked | 卡片已被封锁 |
| card_expired | 卡片已过期 |
| card_not_active | 卡片未激活 |
| fraud_suspicion | 疑似欺诈 |
| transaction_not_allowed | 不允许此交易 |
| invalid_amount | 金额无效 |
| generic_error | 通用错误 |
---
# 模拟授权
URL: /zh-Hans/documentation/cards/autorizacao/simular_autorizacao
### Request
ENDPOINT /mock/card/authorization
MÉTODO POST
Request Body
```json
{
"card_key": "ff3c4484-7a52-457e-b989-d9dcb87dfcd6",
"merchant_name": "Supermarket XYZ",
"merchant_city": "São Paulo",
"merchant_region": "BR",
"merchant_postal_code": "01001000",
"merchant_mcc": "5411",
"amount": 150.75,
"authorization_type": "purchase"
}
```
### Response
```json
{
"is_approved": true,
"response_code": "00",
"limit_amount": null
}
```
### 请求体字段说明
下表列出了上述请求中所有变量的描述。
| 字段 | 类型 | 描述 | 最大字符数 | 示例 |
|-----------------------|--------|----------------------------------------------------|--------------|----------------------|
| **card_key** | string | 卡片唯一密钥（必填）| 36 | "ff3c4484-7a52-457e-b989-d9dcb87dfcd6" |
| **authorization_type**| string | 授权类型（必填）| **[枚举值](#authorization-type-enumeradores)** |
| **merchant_name** | string | 商户名称 | 40 | "Supermarket XYZ" |
| **merchant_city** | string | 商户城市 | 40 | "São Paulo" |
| **merchant_region** | string | 商户所在国家 | 2 | "BR" |
| **merchant_postal_code** | string | 商户邮政编码 | 8 | "01001000" |
| **merchant_mcc** | string | 商户类别代码（MCC）| **[枚举值](#merchant-mcc-enumeradores)** |
| **amount** | number | 交易金额 | - | 150.75 |
### merchant_mcc 枚举值
| 枚举值 | 描述 |
|------------|--------------------------------------------|
| 5812 | Eating Places, Restaurants |
| 5499 | Miscellaneous Food Stores |
| 5814 | Fast Food Restaurants |
| 5411 | Grocery Stores, Supermarkets |
| 4121 | Taxicabs and Limousines |
| 4111 | Local and Suburban Transit |
| 4215 | Courier Services, Air or Ground |
| 5912 | Drug Stores and Pharmacies |
| 5815 | Digital Goods: Applications (Excludes Games)|
| 8999 | Professional Services (Not Elsewhere Classified)|
| 5462 | Bakeries |
| 5541 | Service Stations (with or without Ancillary Services)|
| 7523 | Parking Lots, Parking Meters and Garages |
| 5300 | Wholesale Clubs |
| 4899 | Cable, Satellite and Other Pay Television and Radio Services|
| 5311 | Department Stores |
| 5813 | Bars, Cocktail Lounges, Discotheques, Nightclubs and Taverns (Drinking Places)|
| 7372 | Computer Programming, Data Processing and Integrated Systems Design Services|
| 5099 | Durable Goods (Not Elsewhere Classified) |
| 5943 | Stationery Stores, Office and School Supply Stores|
| 7299 | Miscellaneous Personal Services (Not Elsewhere Classified)|
| 5199 | Nondurable Goods (Not Elsewhere Classified)|
| 7230 | Beauty and Barber Shops |
| 5999 | Miscellaneous and Specialty Retail Stores |
| 5651 | Family Clothing Stores |
### authorization_type 枚举值
| 枚举值 | 描述 |
|-------------|----------------------------|
| purchase | Purchase |
| reversal | Reversal |
| withdrawal | Withdrawal |
---
# 创建实体卡
URL: /zh-Hans/documentation/cards/create/gerar_cartao_fisico
## Request
ENDPOINT /prepaid/card
MÉTODO POST
Request Body
```json
{
"account_key": "5294ed8d-08fc-4397-b15f-6d9aa07b0041",
"program_key": "7d405c31-ec9a-46c1-8ac8-54bab209bf41",
"type": "plastic",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"contactless_enabled": true,
"delivery_address": {
"address": "Rua Cel. Domingos Diniz",
"number": 124,
"neighborhood": "Centro",
"zip_code": "35797000",
"city": "Presidente Juscelino",
"state": "MG",
"complement": "Quadra 08 Lote 259",
"reference": "Supermercado Presidente",
"address_type": "residential"
}
}
```
:::info
实体卡寄送所用的地址将与在 QI Tech 开立支付账户时填写的地址相同。
:::
### 请求体参数
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| `account_key` * | string | QI Tech 支付账户的识别密钥。| uuid |
| `program_key` * | string | 用于发行卡片的程序识别密钥。| uuid |
| `type` * | string | 要发行的卡片类型（PLASTIC）。| **[枚举值](#enumeradores-card_type)** |
| `card_name` * | string | 卡片别名，用于识别该卡片。| 15 |
| `printed_name` * | string | 印在卡片上的姓名（不允许使用数字和特殊字符）。| 26 |
| `contactless_enabled` * | boolean | 启用或禁用卡片的非接触式功能。| - |
| `delivery_address` | Object | 卡片配送地址。| **[Address 对象](#address)** |
### card_type 枚举值
| 枚举值 | 说明 |
|------------|----------------|
| plastic | 实体卡 |
| virtual | 虚拟卡 |
### Address
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|---------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| address* | string | 配送地址 | 100 |
| neighborhood*| string | 配送地址的街区/社区 | 100 |
| zip_code* | string | 配送地址的邮政编码 | 8 |
| city* | string | 配送地址的城市 | 100 |
| state* | string | 配送地址的州 | 2 |
| number | number | 配送地址的门牌号 | |
| complement | string | 配送地址的补充信息 | 100 |
| reference | string | 配送地址的参考地标 | 100 |
| address_type* | string | 配送类型 | **[枚举值](#enumeradores-address_type)** |
:::caution 注意！
`number` 字段为可选项。无门牌号的地址可以不填写此字段。
:::
### address_type 枚举值
| 枚举值 | 说明 |
|------------|----------------------|
| residential| 住宅地址 |
| commercial | 商业地址 |
| other | 其他地址 |
## Response
STATUS 201
Response Body
```json
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"created_at": "2023-06-20T19:28:16Z",
"status":"created"
}
```
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "The type of person is invalid for this program, please try another.",
"translation": "Invalid Person",
"code": "CARD000007"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000005| 404 | It was not possible to fetch the Program for the program_key \{program_key\}.|
| CARD000006| 404 | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000007| 400 | The type of person is invalid for this program, please try another.|
| CARD000008| 400 | The Card Holder with the status \{status\} is invalid for the operation.|
| CARD000009| 400 | We're sorry, but the card could not be generated. Please try again later.|
| CARD000010| 404 | It was not possible to fetch the Person for the person_key \{owner_person_key\}.|
| CARD000033| 403 | Create plastic card is not allowed for program_key \{program_key\}.|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card",
"event_datetime": "2023-07-24T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"program_key": "bf74df61-557a-45cb-914f-41e127a6e18c",
"status": "created",
"type": "plastic"
}
}
```
---
# 创建虚拟卡
URL: /zh-Hans/documentation/cards/create/gerar_cartao_virtual
## Request
ENDPOINT /prepaid/card
MÉTODO POST
Request Body
```json
{
"account_key": "5294ed8d-08fc-4397-b15f-6d9aa07b0041",
"program_key":"7d405c31-ec9a-46c1-8ac8-54bab209bf41",
"type": "virtual",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"cvv_rotation_interval_hours": 72
}
```
### 请求体参数
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------|--------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| `account_key` * | string | QI Tech 支付账户的识别密钥。| uuid |
| `program_key` * | string | 用于发行卡片的程序识别密钥。| uuid |
| `type` * | string | 要发行的卡片类型（VIRTUAL）。| **[枚举值](#enumeradores-card_type)** |
| `card_name` * | string | 卡片别名，用于识别该卡片。| uuid |
| `printed_name` * | string | 印在卡片上的姓名（不允许使用数字和特殊字符）。| uuid |
| `cvv_rotation_interval_hours` * | int | CVV 号码更新的时间间隔（小时）。| Number |
### card_type 枚举值
| 枚举值 | 说明 |
|------------|----------------|
| plastic | 实体卡 |
| virtual | 虚拟卡 |
## Response
STATUS 201
Response Body
```json
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"created_at": "2023-02-20T19:28:16Z",
"status":"created"
}
```
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "The type of person is invalid for this program, please try another.",
"translation": "Invalid Person",
"code": "CARD000007"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000005| 404 | It was not possible to fetch the Program for the program_key \{program_key\}.|
| CARD000006| 404 | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000007| 400 | The type of person is invalid for this program, please try another.|
| CARD000008| 400 | The Card Holder with the status \{status\} is invalid for the operation.|
| CARD000009| 400 | We're sorry, but the card could not be generated. Please try again later.|
| CARD000010| 404 | It was not possible to fetch the Person for the person_key \{owner_person_key\}.|
| CARD000032| 403 | Create virtual card is not allowed for program_key \{program_key\}.|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card",
"event_datetime": "2023-07-24T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"program_key": "bf74df61-557a-45cb-914f-41e127a6e18c",
"status": "created",
"type": "virtual"
}
}
```
---
# 简介
URL: /zh-Hans/documentation/cards/introducao
预付卡发行 API 允许 QI Tech 合作伙伴的客户申请和发行预付卡，包括实体卡和虚拟卡。
在 QI Tech，我们为合作伙伴提供成为子发行商的机会。通过我们的 API，合作伙伴可以为其自身客户提供发行实体预付卡和虚拟预付卡的能力，从而提供完整的银行服务解决方案。
为了更好地理解我们的系统，我们将简要介绍预付卡生态系统的运作方式。请注意，与其他 API 一样，服务的开通需与我们的团队协调，且**[调用需经过身份验证](/documentation/primeiros_passos/teste_de_autenticacao)**。
### 预付卡
预付卡与 QI Tech 内的支付账户绑定。
通过该卡执行的所有交易均将从支付账户的现有余额中扣除。
若账户余额不足，交易将被拒绝。
### 支付账户
QI Tech 是巴西中央银行授权运营预付支付账户的金融机构。预付卡始终与预付支付账户绑定。
因此，无论是实体卡还是虚拟卡，创建预付卡前都必须先开立支付账户。请参阅**[此处](/documentation/contas/abertura_de_conta/abertura_de_conta_pf)**的开户 API。
### 程序（Program）
合作伙伴要发行预付卡，必须在其与 QI 的集成中关联并配置相应的程序。
程序即发行符合 VISA 卡组织规定所需的配置和规则。
以下是关于程序的一些重要信息：
* **程序类型** — 指卡的使用模式。本文档所述为预付模式。
* **卡组织** — 我们使用 VISA 卡组织发行卡片。
* **卡面设计** — 指将印在实体卡上以及虚拟卡图形界面中显示的设计。
:::caution 注意
如需在集成中配置新程序，请联系 QI Tech 的商务团队和实施团队。
:::
### 虚拟卡
QI Tech 的卡 API 提供生成虚拟卡的功能，可用于线上交易。该解决方案为持卡人提供安全性和便利性。
使用虚拟卡时，持卡人无需在网络交易中提供实体卡的详细信息。他们可以生成一张专用于特定交易的唯一虚拟卡，拥有独立的卡号和信息。这有助于降低欺诈风险，提升线上交易的可信度。
### 实体卡
QI Tech 的卡 API 提供创建实体卡的选项，为持卡人提供可用于线下交易的实体塑料卡。
申请实体卡后，持卡人将收到一张个性化的塑料卡。
实体卡为持卡人提供了一种传统且被广泛接受的支付方式，确保线下交易的便利性和实用性。此外，实体卡还可能具备额外功能，例如支持非接触式（contactless）支付技术以加速交易。
QI Tech 预付卡 API 让持卡人能够根据个人需求和偏好，灵活选择使用虚拟卡进行线上交易或使用实体卡进行线下交易。
---
# 通过授权密钥查询授权
URL: /zh-Hans/documentation/cards/search/buscar_autorizacao
## Request
ENDPOINT /prepaid/card/(card_key)/authorization/(authorization_key)
MÉTODO GET
## Response
STATUS 200
Response Body
```json
{
"authorization_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"merchant_currency_code": "BRL",
"original_merchant_amount": 25.32,
"billing_currency_code": "BRL",
"original_billing_amount": 25.32,
"merchant_amount": 25.32,
"iof_amount": 0,
"billing_amount": 25.32,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"captured_amount": 25.32,
"authorization_status": "completed",
"card": {
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"type": "virtual",
"card_name": "ecommerce sample",
"printed_name": "Aurora Catarina",
"status": "active",
"brand": "visa",
"bin": "123456",
"last_four_digits": "5695"
},
"balance_transactions": [
{
"balance_transaction_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"balance_transaction_type": "debit",
"account_transaction_key": "595e08f0-da4e-40f7-8db4-f9a25c820000",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"merchant_currency_code": "BRL",
"merchant_amount": 25.32,
"billing_currency_code": "BRL",
"billing_amount": 25.32,
"processing_datetime": "2023-01-10T13:45:52.000Z",
"balance_transaction_status": "transacted",
"transacted_amount": 25.32,
}
],
"authorization_requests": [
{
"authorization_request_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"authorization_code": "473890",
"nsu": "123456",
"acquirer_reference_number": "12312423",
"merchant_currency_code": "BRL",
"merchant_amount": 25.32,
"billing_currency_code": "BRL",
"billing_amount": 25.32,
"processing_datetime": "2023-01-10T13:45:52.000Z",
"number_of_installments": 1,
"authorization_type": "authorization",
"authorization_request_response": "authorized"
}
],
"authorization_events": [
{
"merchant_currency_code": "BRL",
"merchant_amount": 25.32,
"billing_currency_code": "BRL",
"billing_amount": 25.32,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"authorization_event_type": "authorization"
}
]
}
```
### 授权对象
| 字段 | 类型 | 描述 |
|---|---| ---|
| authorization_key | string | 授权的唯一标识符 |
| merchant_currency_code | string | 交易使用的货币 - ISO 4217-alpha |
| original_merchant_amount | decimal | 交易发生货币下的原始交易金额 |
| billing_currency_code | string | 持卡人账单货币 - ISO 4217-alpha |
| original_billing_amount | decimal | 持卡人账单货币下的原始交易金额 |
| merchant_amount | decimal | 所有授权请求中交易货币金额的汇总 |
| iof_amount | decimal | 当交易货币与持卡人账单货币不同时，汇兑所缴纳的 IOF 金额汇总 |
| billing_amount | decimal | 所有授权请求中持卡人账单货币金额的汇总 |
| processing_datetime | datetime UTC | 授权对象的创建时间，通常为第一次授权请求的时间 |
| captured_amount | decimal | 所有授权请求已捕获的总金额 |
| authorization_status | enumerator | **[授权状态枚举](#status-da-autorizacao)** |
| card | object |**[Card 对象](#objeto-card)** |
| balance_transactions | list of objects |**[Balance Transaction 对象](#objeto-balance-transaction)** |
| authorization_requests | list of objects |**[授权请求对象](#objeto-rquisicao-de-autorizacao)** |
| authorization_events | list of objects | **[授权事件对象](#objeto-evento-autorizacao)** |
### Card 对象
| 字段 | 类型 | 描述 |
|---| ---| ---|
| card_key | string | 卡片识别密钥 |
| account_key | string | 持卡人账户标识符 |
| type | string | 卡片类型 |
| card_name | string | 卡片字母数字标识符 |
| printed_name | string | 印在卡片上的姓名 |
| cvv_rotation_interval_hours | int | CVV 轮换间隔 |
| status | string | 卡片当前状态 |
| brand | string | 卡片所属卡组织 |
| bin | string | 卡片 BIN |
| last_four_digits | string | 卡号后四位 |
### Balance Transaction 对象
`Balance Transaction` 对象表示持卡人 QI Conta 上需要执行的任何资金变动。可以是因授权获批而产生的*借记*交易，也可以是授权取消等场景下的*贷记*交易。
| 字段 | 类型 | 描述 |
|---| ---| ---|
| balance_transaction_key | string | 交易的唯一标识符 |
| balance_transaction_type | enumerator | 贷记时为 *credit*，借记时为 *debit* |
| account_key | string | 与所用卡片关联的 QI Conta 标识符 |
| merchant_currency_code | string | 交易使用的货币 - ISO 4217-alpha |
| merchant_amount | decimal | 交易货币下的等值收费金额 |
| billing_currency_code | string | 持卡人账单货币 - ISO 4217-alpha |
| billing_amount | decimal | 持卡人账单货币下的交易金额 |
| processing_datetime | datetime | 交易的处理和创建日期。由于 QI Conta 中的实际交易可能不会发生，此值作为收费或贷记生成时的参考时间 |
| balance_transaction_status | enumerator | 描述交易是否已在持卡人 QI Conta 上执行，可能为待处理（`pending_transaction_execution`）、部分交易（`partially_transacted`）或已交易（`transacted`）|
| transacted_amount | decimal | 已在 QI Conta 上执行的借记或贷记的持卡人货币总金额 |
### 授权请求对象
详见[授权请求](/documentation/cards/autorizacao/)
### 授权事件对象
`Authorization Event` 对象表示授权上发生的事件。更详细的说明请参阅[手册](/documentation/manual_pre_pago/casos_uso/)。
| 字段 | 类型 | 描述 |
|---| ---| ---|
| merchant_currency_code | string | 交易使用的货币 - ISO 4217-alpha |
| merchant_amount | decimal | 交易货币下的等值收费金额 |
| billing_currency_code | string | 持卡人账单货币 - ISO 4217-alpha |
| billing_amount | decimal | 持卡人账单货币下的事件金额 |
| processing_datetime | datetime | 事件的处理日期 |
| authorization_event_type | enumerator | **[授权事件类型](#tipos-evento-autorizacao)** |
### 授权状态
| 状态 | 描述 |
|---|---|
| pending | 授权请求已获批准，尚无捕获或取消事件被处理 |
| unauthorized | 授权请求未获批准 |
| completed | 对该授权至少已成功捕获一个金额（可等于、小于或大于所有授权请求中批准的总金额）|
| reversed | 授权已被完全冲正，或已过期而未捕获 |
### 授权事件类型
| 类型 | 描述 |
|---|---|
| authorization | 通知一次授权请求已被响应 |
| incremental_authorization | 通知一次增量授权请求已被响应 |
| authorization_reversal | 通知一次授权取消已被处理 |
| partial_authorization_reversal | 通知一次部分授权取消已被处理 |
| authorization_expiration | 通知一次授权已过期 |
| capture | 通知一笔特定金额已为某授权完成捕获 |
| refund | 通知一次授权已被退款 |
| partial_refund | 通知一次授权已被部分退款 |
---
# 查询授权列表
URL: /zh-Hans/documentation/cards/search/buscar_autorizacoes
## Request
ENDPOINT /prepaid/card/(card_key)/authorizations
MÉTODO GET
PARÂMETROS from_date, to_date, size, page
## 查询参数
| 字段 | 类型 | 描述 |
|-----------------|--------|----------------------------------------------------------|
| `size` | int | 返回的记录数量，默认值为 10。|
| `page` | int | 查询的页码，默认值为 0。|
| `from_date` | string | 查询的开始日期（格式：YYYY-MM-DD）。|
| `to_date` | string | 查询的结束日期（格式：YYYY-MM-DD）。|
## Response
STATUS 200
Response Body
```json
{
"pagination": {
"current_page": 1,
"rows_per_page": 10,
"next_page": 2
},
"data": [
{
"authorization_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
"merchant_currency_code": "BRL",
"original_merchant_amount": 25.32,
"billing_currency_code": "BRL",
"original_billing_amount": 25.32,
"merchant_amount": 25.32,
"iof_amount": 0,
"billing_amount": 25.32,
"processing_datetime": "2023-07-24T12:00:00.000Z",
"captured_amount": 25.32,
"authorization_status": "completed"
}
]
}
```
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Not Found Card",
"code": "CARD000011"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000016| 400 | We're sorry, but the card could not be fetch. Please try again later.|
---
# 通过密钥查询卡片
URL: /zh-Hans/documentation/cards/search/buscar_cartao_by_key
## Request
ENDPOINT /prepaid/card/ CARD_KEY
MÉTODO GET
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |
## Response
STATUS 200
Response Body
```json
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
"type": "virtual",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"cvv_rotation_interval_hours": 72,
"created_at": "2023-02-20T19:28:16Z",
"updated_at": "2023-02-22T19:28:16Z",
"status": "active",
"brand": "visa",
"last_four_digits": "5695",
"status_events": [
{
"status": "created",
"created_at": "2023-02-20T19:28:16Z"
},
{
"status": "active",
"created_at": "2023-02-20T19:35:10Z"
}
]
}
```
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Not Found Card",
"code": "CARD000011"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000016| 400 | We're sorry, but the card could not be fetch. Please try again later.|
---
# 查询 PCI 数据
URL: /zh-Hans/documentation/cards/search/buscar_dados_pci
## Request
ENDPOINT /prepaid/card/ CARD_KEY /pci
MÉTODO GET
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |
## Response
STATUS 200
Response Body
```json
{
"printed_name": "Aurora Catarina",
"valid_until": "2023-02-20T10:04:12Z",
"expiration_date": "03/24",
"card_number": "4539347744299311",
"cvv": "713"
}
```
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Not Found Card",
"code": "CARD000011"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400 | It was not possible to fetch PCI for the card_key \{card_key\}.|
---
# 通过卡片密钥查询配送信息
URL: /zh-Hans/documentation/cards/search/buscar_entrega_by_key
## Request
ENDPOINT /card/ CARD_KEY /tracking
MÉTODO GET
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |
## Response
STATUS 200
Response Body
```json
{
"card_key": "92b4e2bd-4a6f-4c56-859e-17c729e1f0c8",
"tracking_code": "4F68A72B902317",
"status": "posted",
"recipient": "João Silva",
"address": {
"zip_code": "1234567",
"street": "Rua das Flores",
"number": 123,
"complement": "Bloco A",
"neighborhood": "Centro",
"city": "Cidade Exemplo",
"state": "SP"
},
"event": [
{
"created_at": "2024-02-27T08:30:00Z",
"old_status": "pending",
"new_status": "posted",
"description": "Pedido recebido e postado",
"place": "SAO PAULO"
}
]
}
```
### DeliveryStatus 枚举值
| 枚举值 | 说明 |
|--------------------|---------------------|
| pending | 待处理 |
| posted | 已寄出 |
| prepared | 已备货 |
| in_transfer | 转运中 |
| in_delivery_unit | 在配送网点 |
| on_route | 派送中 |
| attempt_failed | 尝试失败 |
| awaiting_withdrawal| 等待自提 |
| returning | 退回中 |
| delivered | 已送达 |
| returned | 已退回 |
| canceled | 已取消 |
| failed | 失败 |
| resend | 重新发送 |
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Tracking for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Not Found",
"code": "TRACK000011"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| TRACK000011| 404 | It was not possible to fetch the Tracking for the card_key \{card_key\}.|
| TRACK000016| 400 | We're sorry, but the tracking could not be fetch. Please try again later.|
---
# 查询 PCI 密码
URL: /zh-Hans/documentation/cards/search/buscar_senha
## Request
ENDPOINT /prepaid/card/ CARD_KEY /pci/password
MÉTODO GET
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |
## Response
STATUS 200
Response Body
```json
{
"pin": "1234"
}
```
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "It was not possible to fetch PCI for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
"translation": "Fetch PCI failed",
"code": "CARD000012"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400 | It was not possible to fetch PCI for the card_key \{card_key\}.|
---
# 列出卡片
URL: /zh-Hans/documentation/cards/search/listar_cartoes
## Request
ENDPOINT /prepaid/card
MÉTODO GET
PARÂMETROS account_key, size, page
## 查询参数
| 字段 | 类型 | 描述 | 字符数 |
|-----------------|--------|----------------------------------------------------------|------------|
| `account_key` * | string | QI Tech 支付账户的识别密钥。| uuid |
| `size` | int | 返回的记录数量，默认值为 10。| - |
| `page` | int | 查询的页码，默认值为 0。| - |
## Response
STATUS 200
Response Body
```json
{
"pagination": {
"current_page": 1,
"rows_per_page": 0,
"next_page": 2
},
"data": [
{
"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
"type": "virtual",
"card_name": "ecommerce",
"printed_name": "Aurora Catarina",
"cvv_rotation_interval_hours": 72,
"created_at": "2023-02-20T19:28:16Z",
"updated_at": "2023-02-22T19:28:16Z",
"status": "active",
"brand": "visa"
},
{
"card_key": "ee084f00-d72e-4263-87fb-3a3c11a418c6",
"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
"program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
"type": "virtual",
"card_name": "uber",
"printed_name": "Aurora Catarina",
"cvv_rotation_interval_hours": 72,
"created_at": "2023-02-10T11:28:16Z",
"updated_at": "2023-02-15T11:28:16Z",
"status": "canceled",
"brand": "visa"
}
]
}
```
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Not Found",
"description": "It was not possible to fetch the Account for the account_key 94f982c0-164c-45e3-8a0e-69f54ad7b155.",
"translation": "Not Found Account",
"code": "CARD000006"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| CARD000006| 404 | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000021| 400 | Account key can not be null when search for cards.|
| CARD000022| 400 | Invalid integer value for page or size querystring parameters.|
---
# 激活实体卡
URL: /zh-Hans/documentation/cards/status/ativar_cartao
每张实体卡都需要通过随卡一起发送给持卡人的激活码进行激活。
持卡人收到邮寄卡片后，需将激活码告知 QI 的合作伙伴，由合作伙伴通过此端点完成卡片激活。
:::caution 注意
出于安全原因，合作伙伴无法通过 API 查询激活码。
激活码仅在实体卡寄出时独家发送给持卡人。
在集成测试时，可在沙盒环境中通过查询卡片获取该激活码。
:::
## Request
ENDPOINT /prepaid/card/ CARD_KEY /activate
MÉTODO PATCH
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |
Request Body
```json
{
"code": "253615"
}
```
### 请求体参数
| 字段 | 类型 | 描述 | 字符数 |
|-----------|--------|-------------------------------|------------|
| `code` * | string | 卡片激活码。| 6 |
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Not Acceptable",
"description": "Invalid activation code [1254].",
"translation": "Unable to activate card",
"code": "CARD000020"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000017| 406 | The activation operation is not valid for the current card status [\{card_status\}].|
| CARD000018| 400 | We're sorry, but the card could not be activate. Please try again later.|
| CARD000020| 406 | Invalid activation code [\{code\}].|
| CARD000023| 406 | The card type is invalid for this operation. Only plastic cards are allowed.|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card",
"event_datetime": "2023-07-25T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
"type": "plastic",
"status": "active",
"old_status": "embossing"
}
}
```
---
# 更新状态
URL: /zh-Hans/documentation/cards/status/update_status_cartao
## Request
ENDPOINT /prepaid/card/ CARD_KEY
MÉTODO PATCH
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |
Request Body
```json
{
"status": "blocked"
}
```
### 请求体参数
| 字段 | 类型 | 描述 | 字符数 |
|-------------|--------|-------------------|-----------------------------------------------|
| `status` * | string | 卡片状态。| **[枚举值](#enumeradores-card_status)** |
### card_status 枚举值
| 枚举值 | 说明 | 类型 |
|------------|---------------------|-----------------|
| created | 已申请创建 | Initial |
| building | 创建中 | Initial |
| active | 可进行交易 | Active |
| embossing | 生产中 | Temporary block |
| blocked | 已封锁 | Temporary block |
| warning | 有可疑情况 | Temporary block |
| pending | 待处理 | Temporary block |
| lost | 已丢失 | Terminated |
| robbed | 被抢劫 | Terminated |
| fraud | 欺诈 | Terminated |
| canceled | 已取消 | Terminated |
| theft | 被盗 | Terminated |
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Not Acceptable",
"description": "The operation is not valid for the current status of the card [canceled]",
"translation": "Unable to transition",
"code": "CARD000014"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000013| 406 | Unable to transition from \{old_status\} to \{new_status\}.|
| CARD000014| 406 | The operation is not valid for the current status of the card [\{card_status\}].|
| CARD000015| 400 | We're sorry, but the card could not be update. Please try again later|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card",
"event_datetime": "2023-07-25T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
"type": "virtual",
"status": "active",
"old_status": "created"
}
}
```
---
# 非接触式（Contactless）配置
URL: /zh-Hans/documentation/cards/update/contactless_cartao
启用或禁用非接触式（contactless）支付功能，用于线下当面支付。
要启用或禁用卡片的非接触式支付功能，卡片状态必须为**有效**或**临时封锁**类型。（有关状态类型的详细信息，请参阅[此处](../../cards/status/update_status_cartao#enumeradores-card_status)）
## Request
ENDPOINT /prepaid/card/ CARD_KEY /contactless
MÉTODO PATCH
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |
Request Body
```json
{
"contactless_enabled": false
}
```
### 请求体参数
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|---------|-----------------------------------|------------|
| `contactless_enabled` * | Boolean | 指示是否已启用。| true/false |
## Response
STATUS SUCCESS 200
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "We're sorry, but the card could not be update contactless. Please try again later.",
"translation": "Unexpected error update contactless card",
"code": "CARD000026"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406 | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000026| 400 | We're sorry, but the card could not be update contactless. Please try again later.|
| CARD000025| 406 | The status \{status\} is invalid for the operation.|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card.updated.contactless
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card.updated.contactless",
"event_datetime": "2023-07-25T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
"contactless_enabled": true
}
}
```
---
# 修改实体卡密码
URL: /zh-Hans/documentation/cards/update/password_cartao
每张实体卡都有一个用于授权交易的密码，必要时可以更新。
要更新卡片密码，卡片状态必须为**Active（有效）**或**Temporary block（临时封锁）**类型。（有关状态的详细信息，请参阅[此处](../../cards/status/update_status_cartao#enumeradores-card_status)）
:::caution 注意
出于安全原因，更新密码时需谨慎，因为这可能影响卡片的授权。
请制定规则以提高密码授权的安全性，例如不使用生日日期、重复数字（如：3333）等。
:::
## Request
ENDPOINT /prepaid/card/ CARD_KEY /password
MÉTODO PATCH
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | 卡片识别密钥。| uuid |
Request Body
```json
{
"pin": "2143"
}
```
### 请求体参数
| 字段 | 类型 | 描述 | 字符数 |
|-----------|--------|-----------------------------------------------|------------|
| `pin` * | string | 用于授权交易的卡片密码。| 4 |
## Response
STATUS SUCCESS 200
### 错误
STATUS 4XX
Response Body
```json
{
"title": "Bad Request",
"description": "We're sorry, but the card could not be update password. Please try again later.",
"translation": "Unexpected error update password card",
"code": "CARD000024"
}
```
| Code | Status code | 描述 |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400 | Invalid Json schema.|
| CARD000011| 404 | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406 | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000024| 400 | We're sorry, but the card could not be update password. Please try again later.|
| CARD000025| 406 | The status \{status\} is invalid for the operation.|
### Webhook
WEBHOOK_TYPE baas.prepaid_card.card.updated.password
Webhook Body
```json
{
"webhook_type": "baas.prepaid_card.card.updated.password",
"event_datetime": "2023-07-25T12:00:00.000Z",
"data": {
"card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1"
}
}
```
---
# 更新配送地址
URL: /zh-Hans/documentation/cards/update/update_delivery_address
当发现地址有误或配送三次失败时，可通过更新配送地址来进行纠正。
## Request
ENDPOINT /account/ ACCOUNT_KEY /card/ CARD_KEY /address
MÉTODO POST
### 路径参数
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | 账户的唯一识别密钥，格式为 uuid v4 | 36 |
| `card_key` | uuidv4 | 卡片的唯一识别密钥，格式为 uuid v4 | 36 |
Request Body
```json
{
"postal_code": "5425020",
"street": "Rua Gilberto Sabino",
"number": 215,
"complement": "4 andar",
"neighborhood": "Pinheiros",
"city": "So Paulo",
"state": "SP",
"reference": "Terminal Pinheiros",
"address_type": "commercial",
"notes": ["obs1", "obs2"],
"phones": [
{"country_code": "55", "area_code": "19", "number": "983151110"},
{"country_code": "55", "area_code": "16", "number": "992334318"},
],
}
```
### 请求体
### address 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------|--------|----------------------------------------------------|------------|
| `street` * | string | 街道/路名 | 100 |
| `number` | string | 门牌号 | 10 |
| `neighborhood` * | string | 街区/社区 | 100 |
| `postal_code` * | string | 邮政编码 | 8 |
| `city` * | string | 城市 | 100 |
| `complement` | string | 补充信息 | 100 |
| `reference` | string | 参考地标 | 100 |
| `notes` | string array | 地址相关备注 | 100 |
| `phones` | object array | 联系电话 | **[phone 对象](#objeto-phone)** |
| `state` * | string | 州（UF）| **[state 枚举值](#enumeradores-state)** |
| `address_type` * | string | 地址类型 | **[address_type 枚举值](#enumeradores-address_type)** |
:::caution 注意！
`number` 字段为可选项。无门牌号的地址可以不填写此字段。
:::
:::caution 注意！
最多可发送 两个 联系电话和 四条 备注。若无联系电话和/或备注，则不应发送这些字段（`phones` 和 `notes`）。
:::
### phone 对象
| 字段 | 类型 | 描述 | 字符数 |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` * | string | 国际区号（DDI）| 2 |
| `area_code` * | string | 地区区号（DDD）| 2 |
| `number` * | string | 电话号码 | 9 |
### address_type 枚举值
| 枚举值 | 描述 |
|--------------------|--------------------------|
| residential | 住宅地址 |
| commercial | 商业地址 |
| other | 其他类型地址 |
### state 枚举值
| 枚举值 | 描述 |
|--------------------|-----------------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MG | Minas Gerais |
| MS | Mato Grosso do Sul |
| MT | Mato Grosso |
| PA | Pará |
| PB | Paraíba |
| PE | Pernambuco |
| PI | Piauí |
| PR | Paraná |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RO | Rondônia |
| RR | Roraima |
| RS | Rio Grande do Sul |
| SC | Santa Catarina |
| SE | Sergipe |
| SP | São Paulo |
| TO | Tocantins |
| EX | 例外 |
## Response
STATUS 200
Response Body
```json
{
"card_key": "1e3183f0-1bac-4e59-81e8-2d89db224040",
"tracking_code": "FD89B071241022",
"address": {
"city": "So Paulo",
"notes": [
"obs1",
"obs2"
],
"state": "SP",
"number": 215,
"phones": [
{
"number": "983151110",
"area_code": "19",
"country_code": "55"
},
{
"number": "992334318",
"area_code": "16",
"country_code": "55"
}
],
"street": "Rua Gilberto Sabino",
"reference": "Terminal Pinheiros",
"complement": "4 andar",
"postal_code": "5425020",
"address_type": "commercial",
"neighborhood": "Pinheiros"
}
}
```
### 响应体参数
| 字段 | 类型 | 描述 | 字符数 |
|-------------------------|--------|-------------------------------------------------------------------------------------------------|------------|
| `card_key` * | uuidv4 | 卡片的唯一识别密钥，格式为 uuid v4 | 36 |
| `tracking_code` * | string | 卡片配送的物流追踪码 | 14 |
| `address` | object | `address` 类型对象，与请求中发送的内容类似 | **[address 对象](#objeto-address)** |
## 错误响应
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP 代码
`status` | QI 代码
`code` | 标题
`title` | 描述（英文）
`description` | 描述（葡文）
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 403 | QIT000005 | Permission Validator Error | Selected agent and person_key are different | Agente selecionado e person_key são diferentes |
| 400 | TRACK000004 | Bad Request | Invalid status to change delivery address. | Status inválido para mudar o endereço de entrega. |
| 500 | TRACK000007 | Internal Server Error | Failed to update delivery address at delivery service provider. Please, try again later! | Falha ao atualizar endereço de entrega junto à provedora de serviços de delivery. Por favor, tente novamente mais tarde! |
| 404 | TRACK000012 | Not Found | Tracking not found for the given 'card_key'. | Rastreio não encontrado para a 'card_key' fornecida. |