# QI Tech — Risk Solutions › 账户监控 Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 7 página(s). Índice: - 账户创建 (/zh-Hans/documentation/caas/account_monitoring/account_registration) - authentication (/zh-Hans/documentation/caas/account_monitoring/authentication) - HTTP 状态码 (/zh-Hans/documentation/caas/account_monitoring/http_status) - 简介 (/zh-Hans/documentation/caas/account_monitoring/introduction) - 人员创建 (/zh-Hans/documentation/caas/account_monitoring/person_registration) - 标准 (/zh-Hans/documentation/caas/account_monitoring/standards) - Webhook (/zh-Hans/documentation/caas/account_monitoring/webhook) --- # 账户创建 URL: /zh-Hans/documentation/caas/account_monitoring/account_registration 账户监控产品分为个人账户和企业账户，其中个人账户只能包含自然人，而企业账户可以包含法人和自然人。要创建账户，只需将 _Account_ 类型的对象发送到以下端点之一： - 个人账户 `POST https://api.caas.qitech.app/account_monitoring/natural_person_account` > 示例 ```json { "account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4", "registration_date": "2019-12-20T15:23:12" } ``` - 企业账户 `POST https://api.caas.qitech.app/account_monitoring/legal_person_account` > 示例 ```json { "account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4", "registration_date": "2019-12-20T15:23:12" } ``` 注册的所有信息交换均使用以下对象定义。在某些情况下，为了便于实现并减少各方之间的数据流，部分信息可能会被省略。 名称 | 类型 | 描述 :----: | :----: | --------- account_id | string | 账户的唯一标识符。 **此编号对每个请求必须唯一** registration_date | string (ISO 8601) | 注册的日期和时间。 ## 账户停用和重新激活 要在账户监控产品中停用账户，需要在以下端点发送请求，并传入 new_account_status 字段值为 'deactivated'： - 个人账户 `PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}` > 示例 ```json { "new_account_status" : "deactivated" } ``` - 企业账户 `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}` > 示例 ```json { "new_account_status" : "deactivated" } ``` 这将停用账户并中止其监控。要重新激活账户并恢复其监控，只需在以下端点发送请求，此时传入 new_account_status 为 'active'： - 个人账户 `PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}` > 示例 ```json { "new_account_status" : "active" } ``` - 企业账户 `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}` > 示例 ```json { "new_account_status" : "active" } ``` 重新激活账户后，账户主题的监控间隔将重新开始。例如，如果所有主题均每 24 小时监控一次，则在账户重新激活时，更新将在重新激活后 24 小时执行。 --- # authentication URL: /zh-Hans/documentation/caas/account_monitoring/authentication ## 认证 > 要认证一次调用，请使用以下代码： ```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。 ::: --- # HTTP 状态码 URL: /zh-Hans/documentation/caas/account_monitoring/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/account_monitoring/introduction 欢迎使用 QI Tech 账户监控 API！您可以使用我们的 API 在各种监控主题上对账户和人员进行监控，监控间隔完全可根据客户的需求自定义。目前该产品具有以下监控主题： - 对于自然人； - OFAC 列表 - 美国外国资产控制办公室制裁名单（Office of Foreign Assets Control） - UNSC 列表 - 联合国安全理事会制裁名单（United Nations Security Council） - IBAMA 列表 - 巴西环境和可再生自然资源研究院环境处罚名单 - PEP 列表 - 政治公众人物名单 - 联邦税务局状态 - 巴西联邦税务局注册状况 - 对于法人； - OFAC 列表 - 美国外国资产控制办公室制裁名单（Office of Foreign Assets Control） - UNSC 列表 - 联合国安全理事会制裁名单（United Nations Security Council） - IBAMA 列表 - 巴西环境和可再生自然资源研究院环境处罚名单 - CEIS 列表 - 不诚信和被暂停企业注册 - CNEP 列表 - 国家受处罚企业注册 - 联邦税务局状态 - 巴西联邦税务局注册状况 请注意，间隔按监控主题和被监控人员类型定义，例如，OFAC 列表对自然人可每 10 天监控一次，对法人可每 30 天监控一次。 每个主题的监控间隔遵循 ISO 8601 标准，可以是以下任意间隔，或其组合： ### 天、周、月和年 | 表示法 | 含义 | |----------|------------| | `"P1D"` | 1 天 | | `"P7D"` | 7 天 | | `"P1W"` | 1 周 | | `"P1M"` | 1 个月 | | `"P1Y"` | 1 年 | --- ### 小时、分钟和秒 | 表示法 | 含义 | |-------------|----------------------------------| | `"PT1H"` | 1 小时 | | `"PT30M"` | 30 分钟 | | `"PT45S"` | 45 秒 | | `"PT2H30M"` | 2 小时 30 分钟 | | `"PT1H15M10S"` | 1 小时、15 分钟和 10 秒 | --- ### 自定义示例 | 表示法 | 含义 | |----------------|----------------------------------------| | `"P1DT12H"` | 1 天 12 小时 | | `"P2W3DT4H30M"` | 2 周、3 天、4 小时和 30 分钟 | 以下，您可以看到使用 curl 的 API 实现。这样，您就有了示例，可以根据自己喜欢的编程语言进行适当调整。 ## 遇到问题？ 我们不是躲在 API 后面的公司！请联系我们的 支持团队 ，我们将尽快回复。如果您需要快速回复，请随时致电我们！ ### 我们热爱反馈 即使您已经解决了问题，或者问题非常简单（甚至是您发现的一个错别字或不当的组织方式），也请给我们发电子邮件，这样我们可以让文档变得越来越实用，下一个人就不必经历您所经历的痛苦！ ## 环境 我们为客户提供两个环境。API 的基本 URL 为： * 生产环境 - `https://api.caas.qitech.app/account_monitoring/` * 沙盒环境 - `https://api.sandbox.caas.qitech.app/account_monitoring/` 在沙盒环境中，提交的分析不计费，并根据预先建立的规则进行响应。 ## 仅限 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/account_monitoring/person_registration 要为各自账户创建人员，必须保持 natural_person_account 和 legal_person_account 端点之间的隔离。 要为账户请求创建人员，只需将 Person 类型的对象发送到以下端点之一，遵循账户创建时的隔离： ### 个人账户 - 创建自然人 `POST https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person` > 示例 ```json { "id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245", "registration_date": "2024-11-04T13:37:00Z", "data": { "name": "John Doe", "document_number": "123.456.789-09", "birthdate": "2000-07-13" } } ``` ### 企业账户 - 创建自然人 `POST https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person` > 示例 ```json { "id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245", "registration_date": "2024-11-04T13:37:00Z", "data": { "name": "John Doe", "document_number": "123.456.789-09", "birthdate": "2000-07-13" } } ``` birthdate 字段仅对拥有联邦税务局状态监控的账户为必填项，查询未满 18 岁的人员时需要此字段。 - 创建法人 `POST https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person` > 示例 ```json { "id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245", "registration_date": "2024-11-04T13:37:00Z", "data": { "name": "Empresa das Tampas", "document_number": "12.482.243/0001-34" } } ``` ## 人员停用和重新激活 要停用人员，操作与账户的操作类似，使用以下端点： ### 个人账户 - 创建自然人 `PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person` > 示例 ```json { "new_person_status" : "deactivated" } ``` ### 企业账户 - 创建自然人 `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person` > 示例 ```json { "new_person_status" : "deactivated" } ``` - 创建法人 `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person` > 示例 ```json { "new_person_status" : "deactivated" } ``` 要重新激活之前停用的人员，操作与停用人员相同，但 new_person_status 传入 'active'，使用以下端点： ### 个人账户 - 创建自然人 `PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person` > 示例 ```json { "new_person_status" : "active" } ``` ### 企业账户 - 创建自然人 `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person` > 示例 ```json { "new_person_status" : "active" } ``` - 创建法人 `PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person` > 示例 ```json { "new_person_status" : "active" } ``` --- # 标准 URL: /zh-Hans/documentation/caas/account_monitoring/standards 为便于集成并保证信息完整性，整个 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 始终定义为字符串，并将针对以下掩码进行验证： `##.###.###/####-##` --- # Webhook URL: /zh-Hans/documentation/caas/account_monitoring/webhook Webhook Atualizações nos tópicos de monitoramento serão notificadas por meio do envio de webhooks. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma *signature_key* que será utilizada para assinar a requisição. Vale ressaltar que todos os envios de webhook serão feitos para um único endpoint. :::info **Atenção** Por questões de segurança, todas as requisições de Webhook serão somente realizadas em endpoints servidos por HTTPS. ::: ## Assinatura do Webhook ## Webhook de Atualização de Evento Request Body ```json { "person_type" : "natural_person", "account_type" : "natural_person_account", "person_id" : "22f5d028-0ce7-46f7-9b63-e7e38171b485", "account_id" : "e49ac344-f941-4668-9afb-a52ce4e5754a", "monitoring_topic" : "OFAC", "event" : "entered" } ``` Abaixo está o significado de cada campo: | Nome | Tipo | Descrição |:----------------:|:-----------------:|------------------------------------------------------------------------- | person_type | string | Tipo de pessoa (natural_person ou legal_person). | account_type | string | Tipo de conta (natural_person_account ou legal_person_account). | person_id | strin | Identificador único da pessoa, passado na requisição de criação. | account_id | string | Identificador único da conta, passado na requisição de criação. | monitoring_topic | string | Tópico monitorado em que ocorreu a mudança. | event | string | Tipo de evento ocorrido, como "entered" (entrada) ou "exited" (saída) para os tópicos de listas restritivas. A requisição de atualização do tópico de monitoramento possui o formato acima e notifica a mudança no status de um dos tópico de monitoramento dentro da conta. O método utilizado é um PUT e o endereço do endpoint pode conter também o id do evento, de acordo com a necessidade do cliente. É importante ressaltar que o corpo da requisição é enviado como texto codificado em UTF-8. ## Retentativas A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 7 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem: * 10 segundos * 40 segundos * 160 segundos * 640 segundos * 2560 segundos * 10240 segundos * 40960 segundos