# QI Tech — Risk Solutions › 电商反欺诈

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
6 página(s).

Índice:
- HTTP 状态码 (/zh-Hans/documentation/caas/card_order/http_status)
- 简介 (/zh-Hans/documentation/caas/card_order/introduction)
- 对象 (/zh-Hans/documentation/caas/card_order/objects)
- 订单 (/zh-Hans/documentation/caas/card_order/order)
- 标准 (/zh-Hans/documentation/caas/card_order/standards)
- Webhook (/zh-Hans/documentation/caas/card_order/webhook)

---

# HTTP 状态码

URL: /zh-Hans/documentation/caas/card_order/http_status

QI Tech 的所有 API 均遵循以下 HTTP 返回状态码标准，符合 RFC 7231 ：

HTTP 状态码 | 含义 | 描述
---------- | ------- | ---------------------------------
400 | Bad Request | 发送的请求存在格式错误。在大多数情况下，我们会在消息体中说明错误所在。
401 | Unauthorized | 认证出现问题，请检查 API Key 是否正确且在正确的 header 中，参见 认证 部分。
403 | Forbidden | 访问的端点为内部使用，此 API Key 无法访问。
404 | Not Found | 使用该密钥未找到所请求的数据。当请求无效端点时也会返回此状态。
405 | Method Not Allowed | 所使用的 HTTP 方法不适用于该端点。
406 | Not Acceptable | 请求体中发送的数据无效。通常表示发送的数据不是有效的 JSON。
409 | Conflict | 请求 ID 对应之前已处理过的 ID。当向服务器发送重复请求时返回此状态。
500 | Internal Server Error | 我们在处理此请求时遇到问题，一旦出现此错误，我们的专家将自动收到通知并立即开始分析和解决。
503 | Service Unavailable | 您遇到了计划内或计划外的服务器基础设施不可用情况。

---

# 简介

URL: /zh-Hans/documentation/caas/card_order/introduction

欢迎使用 QI Tech 卡片交易欺诈预防 API！您可以使用我们的 API 访问端点，以接收交易响应，向 QI Tech 发送交易以生成欺诈用户或欺诈卖家警报，以及更新交易状态。

:::info **注意**

请注意，此 API 面向接受无卡交易（可能遭受欺诈退款）的商户，即通过应用程序或网站销售并通过信用卡或借记卡接受付款的公司。
:::

以下，您可以看到使用 cUrl 的 API 实现。这样，您就有了示例，可以根据自己喜欢的编程语言进行适当调整。

## 遇到问题？

我们不是躲在 API 后面的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您需要快速回复，请随时致电我们！

### 我们热爱反馈

即使您已经解决了问题，或者问题非常简单（甚至是您发现的一个错别字或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！

## 环境

我们为客户提供两个环境。API 的基本 URL 为：

* 生产环境 - `https://api.caas.qitech.app/card_order/`
* 沙盒环境 - `https://api.sandbox.caas.qitech.app/card_order/`

:::danger 重要提示！
不得在 QI Tech 沙盒环境中使用真实的个人和/或法人数据。
:::

在沙盒环境中，提交的分析不计费，并根据预先建立的规则进行响应。

对于交易分析，以下规则适用于交易金额：

最小值 | 最大值 | 决策
------ | ------ | -------
0 | 1000 | 自动批准
1001 | 2000 | 转人工分析——随后批准
2001 | 3000 | 转人工分析——随后拒绝
3001 | 4000 | 自动拒绝
4001 | 5000 | 未分析
5001 | - | 待处理

## 仅限 HTTPS

出于安全原因，与 QI Tech API 的所有通信必须使用 HTTPS 协议。为避免因疏忽或其他原因发出 HTTP 调用，此服务器仅提供使用 TLS 1.2 通信的 443 端口。使用其他协议发出的调用将自动被拒绝。

## 认证

> 要认证一次调用，请使用以下代码：

```shell
# 在 shell 中，您只需在每个请求中添加适当的 header
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 请将 API Key 'EXAMPLE_API_KEY' 替换为您从我们支持团队获取的密钥。

我们使用 API Key 来允许访问我们的 API。它可能已经通过电子邮件发送给您。如果您尚未收到密钥，请发送电子邮件至 suporte.caas@qitech.com.br 。

我们的 API 期望在所有发送到服务器的请求中，以如下 header 的形式接收 API Key：

`Authorization: EXAMPLE_API_KEY`

:::info **注意**

您必须将 EXAMPLE_API_KEY 替换为从支持团队收到的 API Key。
:::

---

# 对象

URL: /zh-Hans/documentation/caas/card_order/objects

## *address* 对象

Request Body

```json
{
  "street": "Rua do Exemplo, 111",
  "neighborhood": "Bairro do Teste",
  "city": "Aparecida de Goiânia",
  "uf": "GO",
  "complement": "",
  "postal_code": "00000-000",
  "country": "BRA"
}
```

*address* 对象用于在整个 API 中表示地址，巴西境内地址的表示方式如下：

名称 | 类型 | 描述
---- | :----: | ---------
street | string | *（必填）* 地址的街道，包括公路名称，尽可能避免缩写。
number | string | 物业编号，如有字母则包含字母。
neighborhood | string | *（必填）* 区域，不缩写。 **例如：Santa Felicidade**
city | string | *（必填）* 城市全名，不缩写
uf | string | *（必填）* 联邦单位，两个大写字母。 **例如：SP**
complement | string | 用于定位物业的任何补充信息。 **例如：Apartamento 101, Conjunto 12**
postal_code | string | *（必填）* 该地点的邮政编码，含连字符。
country | string | *（必填）* 地址国家的 ISO 3166-1 alpha-3 代码。

对于国家不是巴西（"BRA"）的地址，postal_code 和联邦单位可以自由填写。

## *payment* 对象

Request Body

```json
{
  "total_amount": 10000,
  "shipping_amount": 500,
  "currency": "BRL",
  "is_recurrence": false,
  "transactions": [ . . . ]
}
```

支付由 *payment* 对象表示，具有以下字段：

名称 | 类型 | 描述
---- | :----: | ---------
total_amount | 整数 | *（必填）* 支付的总货币金额
shipping_amount | 整数 | 配送费用
currency | 枚举 | *（必填）* 根据 ISO 4217 的支付货币
is_recurrence | boolean | *（必填）* 如果这是周期性付款，在此标志中指示 true
transactions | Transaction 数组 | *（必填）* 为订单付款执行的交易列表（多卡支付）

## *transaction* 对象 - 信用卡

Request Body

```json
{
  "id": "124234",
  "amount": 10000,
  "bin": "123456",
  "last_4": "1234",
  "cardholder_name": "JOHN SAMPLE",
  "card_fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "expiration_date": "2020-11",
  "installments": 6,
  "processor": "stone",
  "payment_type": "credit"
}
```

交易由 *transaction* 对象表示，具有以下字段：

名称 | 类型 | 描述
---- | :----: | ---------
id | string | *（必填）* 客户系统中交易的标识符，每笔订单必须唯一
amount | integer | *（必填）* 表示支付金额的货币金额
bin | string | *（必填）* 支付使用的卡片 BIN
last4 | string | *（必填）* 支付使用的卡片后四位数字
cardholder_name | string | *（必填）* 持卡人姓名，如卡片上所写
card_fingerprint | string | *（必填）* 客户系统中的卡片标识符（"Token"）
expiration_date | string | 卡片到期日期（YYYY-DD）
installments | integer | *（必填）* 支付分期数
processor | 枚举 | *（必填）* 负责处理交易的收单机构或子收单机构
payment_type | 枚举 | *（必填）* 支付方式类型
status | 枚举 | 可选——发送给 QI Tech 时交易的最新状态——用于发送未授权的交易

processor 可用枚举值：
* cielo
* rede
* stone
* getnet
* adyen
* global_payments
* pagseguro

## *transaction* 对象 - PIX

Request Body

```json
{
  "id": "124234",
  "amount": 10000,
  "payment_type": "pix"
}
```

交易由 *transaction* 对象表示，具有以下字段：

名称 | 类型 | 描述
---- | :----: | ---------
id | string | *（必填）* 客户系统中交易的标识符，每笔订单必须唯一
amount | integer | *（必填）* 表示支付金额的货币金额
payment_type | 枚举 | *（必填）* 支付方式类型

## *dict_key* 对象

Request Body

```json
  {
    "key_type": "cpf",
    "key_value": "09991222669"
  }
```

**dict_key** 对象用于表示客户（无论是收款人还是付款人）在 DICT 中的绑定密钥数据。该对象的字段为：

名称 | 类型 | 描述
:----: | :----: | ---------
key_type        | string | 包含 DICT 中绑定密钥类型的枚举值。
key_value       | string | 包含在 DICT 中注册的绑定密钥。

*key_type* 字段的枚举值与 DICT API 中定义的相同：`cpf`、`cnpj`、`email`、`phone` 和 `evp`。

## *account* 对象

Request Body

```json
{
    "participant": "17315359",
    "branch": "0000",
    "account_number": "10442",
    "account_digit": "6",
    "account_type": "CACC"
}
```

表示账户数据的对象。

名称 | 类型 | 描述
:----:  | :----:  | ---------
participant                 | string | 账户所属机构的 ISPB
branch                      | string | 账户支行
account_number              | string | 不含校验位的账户号码
account_digit               | string | 账户校验位
account_type                | 枚举 | 来源账户类型，可能值："CACC"、"SLRY" 和 "SVGS"

## *phone* 对象

Request Body

```json
{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "999999999",
  "type": "mobile",
  "validated": false
}
```

phone 对象表示巴西境内或境外的电话号码及其分类。字段如下：

名称 | 类型 | 描述
---- | :----: | ---------
international_dial_code | string | *（必填）* 国际拨号代码，不含零或加号，仅数字
area_code | string | *（必填）* 区号，不含零，仅数字
number | string | *（必填）* 电话号码，不含连字符
type | 枚举 | *（必填）* 号码类型：手机、住宅、商务等。
validated | 布尔值 | 如果电话号码已验证（短信或电话），在此字段发送 true

电话类型的枚举值为：`residential`、`commercial`、`mobile`

## *seller* 对象

Request Body

```json
{
  "id": "COD",
  "name": "Restaurante do Aeroporto de Congonhas",
  "type": "legal_person",
  "document_number": "00.000.000/0001-00",
  "email": "seller@gmail.com",
  "registration_date": "2019-12-20T15:23:12-03:00",
  "url": "https://www.qitech.com.br",
  "phone": {
      "international_dial_code": "1",
      "area_code": "11",
      "number": "999999999",
      "type": "mobile"
  },
  "address": {
    "street": "Rua do Exemplo",
    "neighborhood": "Bairro do Teste",
    "city": "Aparecida de Goiânia",
    "number": "1000",
    "uf": "GO",
    "complement": "Térreo",
    "postal_code": "00000-000"
  }
}
```

*seller* 对象表示执行订单销售或交付的商店或卖家。需要发送的数据如下：

名称 | 类型 | 描述
---- | :----: | ---------
id | string | *（必填）* 客户系统中商店（或 MarketPlace 卖家）的标识码
name | string | *（必填）* 商店名称（或 MarketPlace 卖家名称）
type | 枚举 | 表示卖家是自然人还是法人的枚举值
document_number | string | *（必填）* 卖家的 CNPJ 或 CPF
url | string | 平台上卖家页面的地址
email | string | 卖家的电子邮件
registration_date | date | *（必填）* 卖家的注册日期
phone | *phone* | 卖家的电话
address | *address* | *（必填）* 如果是实体店，提供店铺地址

type 枚举值：

* `natural_person`
* `legal_person`

## *customer* 对象

Request Body

```json
{
  "id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
  "name": "Mary Sample",
  "gender": "female",
  "document_number": "000.000.000-00",
  "registration_date": "2019-12-20T15:23:12Z",
  "email": "test@sample.com",
  "birthdate": "1990-01-02",
  "address": { . . . },
  "phone": { . . . }
}
```

customer 对象表示使用自己的信用卡下单的人员数据。由以下字段组成：

名称 | 类型 | 描述
---- | :----: | ---------
id | string | *（必填）* 买家或用户的唯一标识符
name | string | *（必填）* 全名
gender | 枚举 | 客户的性别，根据枚举值列表。
document_number | string | *（必填）* CPF，格式正确
registration_date | date | 用户在客户系统中注册的日期
email | string | *（必填）* 用户的电子邮件
birthdate | date | 客户的出生日期
address | *address* | *（必填）* 买家/用户的住宅地址
phone | *phone* | *（必填）* 收集到的买家/用户电话

性别枚举值：

* `male`
* `female`

## *device* 对象

Request Body

```json
{
  "session_id": "595c46c1-b8c2-449d-8a86-6aeba2e5b0da",
  "platform": "android",
  "browser": "chrome",
  "ip": "243.178.100.37"
}
```

device 对象描述用于购物的设备数据。传递以下数据：

名称 | 类型 | 描述
---- | :----: | ---------
session_id | string | *（必填）* 会话标识符，也在 Device Scan 中传递
platform | 枚举 | 正在使用的操作系统枚举
browser | 枚举 | 正在使用的浏览器（或应用程序）枚举
ip | string | 购物的来源 IP，符合本文档的标准。**注意，以 10.*、172.16.* 和 192.168.* 开头的 IP 通常是内部 IP，因此不适用于欺诈预防**

平台枚举值：
* `android`
* `ios`
* `windows`
* `linux`

浏览器枚举值：
* `firefox`
* `chrome`
* `safari`
* `app`

---

# 订单

URL: /zh-Hans/documentation/caas/card_order/order

在向您的客户或卖家交付/发货产品或释放信用额度之前，您应将订单数据发送到我们的 API，以便我们向您返回关于欺诈的建议。发送的数据必须是最终数据，不会被更改，这一点非常重要。这对于保证以下两点至关重要：

* 反欺诈数据库中的数据一致性
* 真实的风险评估

分析过程包括在相应端点发送一个 Order，并等待响应。有四种可能的结果，通过 **analysis_status** 标志返回：

结果 | 描述
:---------: | ---------
自动批准 | 建议批准该订单
自动拒绝 | 建议拒绝该订单
转人工分析 | 我们的规则或模型对决策不够自信，决定将此订单转交人工分析
人工批准 | 人工分析后，分析师选择批准该订单
人工拒绝 | 人工分析后，分析师选择拒绝该订单
待处理 | 查询耗时超出预期，该订单已进入自动分析队列，将通过 Webhook 返回结果
未分析 | 查询以分析标志为 false 发送，或这是仅用于生成警报的分析，这意味着我们的系统不应在 Order 响应中返回建议

:::info **注意**
如果您的业务模式有需要，QI Tech 的引擎可以配置为不将任何订单转人工分析，也不转至待处理状态。这样，您的用户可以立即收到交易确认。
:::

### 状态动态

检索 Order 类型对象时，状态均可查看。除状态外，还会返回修改历史记录以供将来查询。这些修改被称为 events，包含新状态以及修改日期。

### 状态动态 - **payment_status**

订单的 **payment_status** 状态表示与该订单相关的支付情况，即交易是否被有效批准、是否被取消或是否收到欺诈退款。以下支付状态可用：

* open
* not_authorized
* authorized
* captured
* cancelled
* chargeback

:::info **注意**

向 QI Tech 发送支付状态至关重要，因为它被用作我们模型训练的基础。对于退款情况，正确发送 reason_code 非常重要，如下文所述。
:::

### 状态动态 - **analysis_status**

**analysis_status** 表示欺诈引擎决策的状态，其状态机非常简单：

* created
* automatically_approved
* automatically_reproved
* in_manual_analysis
* manually_approved
* manually_reproved
* pending
* not_analyzed

## 对象定义

Request Body

```json
{
	"id": "12345678",
	"is_one_dollar_auth": false,
	"seller": {
		"id": "COD",
		"name": "Restaurante do Aeroporto de Congonhas",
		"type": "legal_person",
		"document_number": "00.000.000/0001-00",
		"email": "seller@gmail.com",
		"registration_date": "2019-12-20T15:23:12-03:00",
		"url": "https://www.qitech.com.br",
		"phone": {
			"international_dial_code": "1",
			"area_code": "11",
			"number": "999999999",
			"type": "mobile",
			"validated": true
		},
		"address": {
			"street": "Rua do Exemplo",
			"neighborhood": "Bairro do Teste",
			"city": "Aparecida de Goiânia",
			"number": "1000",
			"uf": "GO",
			"complement": "Térreo",
			"postal_code": "00000-000",
			"country": "BRA"
		}
	},
	"payment": {
		"total_amount": 10000,
		"shipping_amount": 500,
		"currency": "BRL",
		"is_recurrence": false,
		"transactions": [{
			"id": "124234",
			"amount": 8000,
			"bin": "123456",
			"last_4": "1234",
			"cardholder_name": "JOHN SAMPLE",
			"card_fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
			"expiration_date": "2020-11",
			"installments": 6,
			"processor": "stone",
			"payment_type": "credit",
			"status": "not_authorized"
		}]
	},
	"shipping": {
		"name": "Mary Sample",
		"gender": "female",
		"document_number": "000.000.000-00",
		"birthdate": "1990-01-02",
		"email": "test@sample.com",
		"address": {
			"street": "Rua do Exemplo, 123",
			"neighborhood": "Bairro do Teste",
			"city": "Aparecida de Goiânia",
			"number": "1000",
			"uf": "GO",
			"complement": "",
			"postal_code": "00000-000",
			"country": "BRA"
		},
		"phone": {
			"international_dial_code": "1",
			"area_code": "11",
			"number": "999999999",
			"type": "mobile",
			"validated": true
		},
		"scheduled_date": "2020-01-10",
		"shipping_method": "regular"
	},
	"customer": {
		"id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
		"name": "Mary Sample",
		"gender": "female",
		"document_number": "000.000.000-00",
		"registration_date": "2019-12-20T15:23:12-03:00",
		"email": "test@sample.com",
		"birthdate": "1990-01-02",
		"address": {
			"street": "Rua do Exemplo, 123",
			"neighborhood": "Bairro do Teste",
			"city": "Aparecida de Goiânia",
			"number": "1000",
			"uf": "GO",
			"complement": "",
			"postal_code": "00000-000",
			"country": "BRA"
		},
		"phone": {
			"international_dial_code": "1",
			"area_code": "11",
			"number": "999999999",
			"type": "mobile",
			"validated": true
		}
	},
	"device": {
		"session_id": "595c46c1-b8c2-449d-8a86-6aeba2e5b0da",
		"platform": "android",
		"browser": "chrome",
		"ip": "243.178.100.37"
	},
	"products": [{
		"product_code": "latte-machiatto-30",
		"name": "Latte Machiatto 30cl",
		"description": "Latte Machiatto 30cl para levar, leite integral",
		"sku": "1234",
		"quantity": 2,
		"unit_cost": 5000
	}],
	"order_date": "2020-01-03T15:35:12.454-03:00"
}
```

一个订单的所有信息交换均使用以下对象定义。在某些情况下，为便于实现并减少各方之间的数据流，某些信息可能会被省略。

名称 | 类型 | 描述
:----: |:--------------------------------------:| ---------
id | string | 客户系统中的订单标识符。 **此值对于每个订单必须唯一**（必填）
is_one_dollar_auth | 布尔值 | 如果这是仅用于验证卡片的交易，使用此标志发送 true（必填）
seller | Seller 对象 | 完成销售的商店数据。在 MarketPlace 中，是卖家数据。在应用程序中，是取货店铺的数据（必填）
payment | Payment 对象 | 订单支付数据（必填）
customer | Customer 对象 | 客户/用户数据（必填）
shipping | Shipping 对象 | 订单配送数据——适用于实体配送产品的情况
device | Device 对象 | 下单所用设备/浏览器数据
products | Product 数组 | 购买的商品（必填）
order_date | 日期时间 | 下单日期和时间（必填）

## 发送订单

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "analysis_status": "automatically_approved"
  }
```

要对订单进行评估，只需将 Order 类型对象发送到以下端点：

`POST https://api.caas.qitech.app/card_order/order`

## 更新订单状态

Request Body

```json
{
  "transaction_status": "chargeback"
}
```

为确保规则和人工智能模型的持续优化，必须通知系统交易何时被授权、捕获、取消或收到退款。为此，需要使用 PUT 方法，并正常进行认证：

`PUT https://api.caas.qitech.app/card_order/order/12345678/transaction/124234`

*transaction_status* 的枚举值如下：`open`、`not_authorized`、`authorized`、`captured`、`cancelled`、`chargeback`

## 检索订单

要检索特定订单，只需发出 GET 请求。返回的结果是该订单的最新 JSON。如果该标识符未与任何对象关联，则返回 HTTP Status 404。

`GET https://api.caas.qitech.app/card_order/order/12345678`

```shell
curl "https://api.caas.qitech.app/card_order/order/12345678"
  -H "Authorization: EXAMPLE_API_KEY"
```

> 上述命令返回代表 CardOrder 对象的 JSON。

## 搜索 CardOrders

Response Body

```json
[
  {
    "id": "12345",
    ...
  },
  {
    "id": "12345",
    ...
  }
]
```

> 返回代表 CardOrder 对象列表的 JSON。

如需搜索 CardOrder，可以使用带查询参数的 GET 请求。返回的结果是代表 CardOrders 列表的 JSON。如果未找到符合发送参数的对象，则返回 HTTP Status 200，响应体中包含空列表。

`GET https://api.caas.qitech.app/card_order/order?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20`

以下参数可用于搜索 CardOrder 对象：

参数 | 默认值 | 描述
--------- | ----------- | --------------
initial_date | null | 根据 order_date 字段应返回的最早日期
final_date | null | 根据 order_date 字段应返回的最晚日期
page_number | 1 | 所需结果页码
page_rows | 50 | 一次查询返回的最大对象数

---

# 标准

URL: /zh-Hans/documentation/caas/card_order/standards

为便于集成并确保信息完整性，整个 API 遵循以下统一标准。

## 货币金额
> 示例：

```
10000
12345
98741
1223
1
0
```

API 假定所有发送的货币金额均为巴西雷亚尔。金额应以整数（分）形式发送。

## 含时区的日期和时间
> 部分示例：

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

按照 ISO 8601 表示。在这种情况下，时区紧跟在时间之后，必须表示该数据有效所在地的时区。例如，如果租赁计划在巴西利亚机场 09:30 开始，则发送的时间应表示为 09:30-03:00；如果租赁计划在马瑙斯 09:30 开始，则应表示为 09:30-04:00。

用于验证的掩码如下：

`YYYY-MM-ddThh:mm:ss±hh:mm`

## 不含时区的日期和时间
> 部分示例：

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

按照 ISO 8601 表示。与时区无关的数据应不含时区，始终使用 UTC，字母 Z 表示该数据为 UTC。因此，将验证以下格式：

`YYYY-MM-ddThh:mm:ssZ`

## 日期
> 部分示例

```
2019-10-15
2019-01-01
2017-03-20
```

对于仅接收日期的字段（例如出生日期），应只发送日期，不含任何时间，格式如下：

`YYYY-MM-dd`

## 文件/证件号

由于文件号码种类繁多，且许多包含非数字字符，因此所有文件号码均定义为字符串。将其定义为字符串的另一个好处是避免前导零消失。本页面中规定的文件格式具有明确的掩码，将进行验证。其他文件（如 RG）由于缺乏标准化，不进行验证。

## CPF

> 符合已定义掩码的有效 CPF 示例：

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> 不符合已定义掩码的无效 CPF 示例：

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

CPF 始终定义为字符串，将按掩码进行验证：

`###.###.###-##`

## CNPJ

> 符合已定义掩码的有效 CNPJ 示例：

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> 不符合已定义掩码的无效 CNPJ 示例：

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

CNPJ 始终定义为字符串，将按掩码进行验证：

`##.###.###/####-##`

## IP

> 符合已定义掩码的有效 IP 示例：

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> 无效 IP 示例：

```
201.81..86
358.81.161.86
201.81.161
```

IP 地址始终以 IPv4 格式发送，可以带也可以不带前导零，遵循以下掩码：

`###.###.###.###`

---

# Webhook

URL: /zh-Hans/documentation/caas/card_order/webhook

欺诈状态更新（针对转人工分析或响应为待处理的订单）以及卖家封锁，均通过 Webhook 进行通知。为此，需要通过[支持](mailto:suporte.caas@qitech.com.br)团队配置一个端点地址，我们将通过该地址通知更新，同时还需配置一个用于签署请求的 *signature_key*。

对于订单状态更新，客户也可以使用[轮询](https://en.wikipedia.org/wiki/Polling_(computer_science))技术。在这种情况下，不需要配置 webhook 端点，只需使用 Order 检索端点进行轮询即可。

:::info **注意**

出于安全原因，所有 Webhook 请求仅在 HTTPS 提供的端点上执行。
:::

## 签名

> Python 签名计算示例

```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (url + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

为确保接收到的 webhook 端点请求来自我们的服务器，类似于认证过程，在 *Signature* Header 中发送 HMAC 签名。

在服务器端计算出签名预期值后，需要将计算出的签名与发送的签名进行比较。如果签名匹配，则意味着请求来自我们的服务器并且是可信的。

## 订单更新 Webhook

Request Body

```json
    {
        "order_id": "123456",
        "fraud_status": "automatically_approved",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

更新订单分析状态的请求具有上述格式，并通知欺诈状态的变更。所用方法为 PUT，端点地址可以根据客户需要包含订单 ID。重要提示：请求体以 UTF-8 编码文本形式发送。

订单更新端点示例：

* https://apidocliente.com.br/order
* https://apidocliente.com.br/admin/order/1214

event_date 字段表示通知创建的日期和时间，如果之前的通知发送失败，该时间可能在过去。

## 卖家更新 Webhook

> 结算封锁请求示例

Request Body

```json
    {
        "document_number": "000.000.000-00",
        "settlement_status": "blocked",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

> 交易封锁请求示例

Request Body

```json
    {
        "document_number": "000.000.000-00",
        "transactional_status": "blocked",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

当需要封锁或解封卖家时，QI Tech 系统将发送上述格式的请求。使用的方法为 PUT，发送至可配置端点，客户可根据需要在端点地址中包含文件号码。

:::info **注意**

settlement_status 或 transactional_status 字段的存在决定了卖家封锁或解封的类型。
:::

卖家更新端点示例：

* https://apidocliente.com.br/seller
* https://apidocliente.com.br/admin/seller/000.000.000-00

可通知的结算状态如下：

枚举值 | 描述
---- | ---------:
blocked | 卖家的结算应被封锁
unblocked | 卖家的结算应被解除封锁

event_date 字段表示通知创建的日期和时间，如果之前的通知发送失败，该时间可能在过去。

## 重试

当收到 HTTP Status 200 响应时，通知被视为已送达。如果通知失败，将进行 7 次重试，时间间隔如下，直到收到 200 或重试结束：

* 10 秒
* 40 秒
* 160 秒
* 640 秒
* 2560 秒
* 10240 秒
* 40960 秒