通过门户集成
管理人和顾问通过门户自行创建 API 集成：创建集成、注册公钥，并在门户中直接获取 API Key。 任何密钥都不经过邮件传递。
无论是 Sandbox 还是生产环境，通过页面注册公钥都是管理人和顾问的推荐方式。通过邮件发送公钥属于例外情况——参见何时仍使用邮件发送。
通过门户，公钥由负责人本人注册，需要明确确认，且页面上会显示指纹（fingerprint）。这样就无需在邮箱之间手动转交文件，降低了注册错误密钥的风险，并且可以随时创建新的集成，无需提交工单。
流程概览
| 步骤 | 执行方 | 位置 |
|---|---|---|
| 1. 注册主用户（master） | QI Tech 集成团队 | 基于邮件或 WhatsApp 联系 |
| 2. 访问门户 | 主用户 | Portal do Gestor 或 Portal do Consultor |
| 3. 创建其他用户并分配权限 | 主用户 | 门户中的 Gestão de Acesso > Usuários |
| 4. 创建集成 | 主用户或有权限的用户 | 门户中的 Gestão de Acesso > Integração API |
| 5. 注册公钥 | 有权限的用户 | 门户中的集成页面 |
| 6. 开通集成权限 | QI Tech 集成团队 | 完成后直接显示在页面上 |
| 7. 配置 webhook（可选） | 有权限的用户 | 门户中的集成页面 |
1. 申请注册主用户
通过邮件（integracao.dtvm@qitech.com.br）或 WhatsApp 联系 QI Tech 集成团队，并提供对接负责人的以下信息：
- 全名
- 企业邮箱
- CPF
我们将根据这些信息，在所申请的环境中为管理人或顾问创建主用户（master）。该用户是一切的起点：由它创建其他用户、分配权限并创建 API 集成。
申请中只需包含负责人的姓名、邮箱和 CPF。请勿在该邮件中发送公钥——公钥由您在第 5 步自行在门户中注册。私钥在任何情况下都不得发送给任何人：QI Tech 绝不会要求您提供私钥。
2. 访问门户
使用上一步注册的邮箱通过单点登录（SSO）访问。
3. 创建其他用户并分配权限
只有主用户（或经其授权的用户）才能 看到集成页面。如需为团队其他成员开通访问：
- 进入 Gestão de Acesso > Usuários，点击 Criar usuário。
- 填写 Nome、Sobrenome、E-mail 和 CPF。
- 打开新建的用户，授予集成权限：
- 管理人：Gerenciar Integração API
- 顾问：Gerenciar integração com a API
没有该权限时，菜单中不会显示 Integração API。
4. 创建集成
在 Gestão de Acesso > Integração API 中点击 Criar integração，并填写一个能标识用途的名称（例如 ETL noturno 或 Backoffice）。
确认后，QI Tech 会生成集成凭证，并打开详情页面。凭证位于页面底部的 Credenciais 区块，可随时通过同一路径复制：
| 凭证 | 用途 |
|---|---|
| API Key | 放在所有请求的 API-CLIENT-KEY header 中。即认证测试中的 api_key。 |
| URL base da API（API Base URL） | 接收该集成调用的主机，已对应门户的角色和环境。即认证测试中的 base_url。 |
| Client Integration Key | 集成的标识。与集成团队沟通时用它指代该集成。 |
API key 只在该 URL 上有效：即您所属角色的主机（Portal do Gestor 为 manager-api，Portal do Consultor 为 consultant-api），且为创建集成时所在的环境。完整的主机列表参见环境（主机）。
同一个管理人或顾问可以同时保有多个有效集成，每个集成都有各自的 API key 和公钥——便于区分内部系统或环境。
集成创建后的状态为 Criada。只有注册公钥之后，才会变为 Ativa。
5. 注册公钥
在集成页面点击 Cadastrar chave pública。有两种方式。
方式 A — 在浏览器中生成密钥对
门户直接在您的浏览器中生成密钥对，并将私钥下载到您的电脑。私钥绝不会发送给 QI Tech：只有公钥会被传输。
- 选择 Algoritmo da chave。
- 点击 Gerar par de chaves，私钥会自动开始下载。
- 将私钥保存在安全 的位置——它不会再次显示，也无法找回。如有需要，离开页面前请使用 Baixar chave privada 和 Baixar chave pública。
- 公钥已自动填入表单。确认即可完成注册。
每种算法决定了您签名请求 JWT 时应使用的 alg：
| 门户中的算法 | JWT 签名 |
|---|---|
| RSA 2048（推荐） | RS256 |
| RSA 4096 | RS256 |
| EC P-256 | ES256 |
| EC P-384 | ES384 |
| EC P-521 | ES512 |
方式 B — 上传您自己的公钥
如果您已在门户之外生成了密钥对——参见密钥交换——只需上传公钥：
- 拖拽文件到指定区域，或点击选择文件（
.pem、.pub、.key、.crt或.txt）；或 - 将 PEM 内容粘贴到文本框中。
门户会识别密钥的算法，并在输入框下方提示您签名请求时应使用的 alg。
要求与拒绝情形
密钥必须为 PEM 格式，位于 -----BEGIN PUBLIC KEY----- 块中。以下情况门户会拒绝注册：
| 情形 | 原因 |
|---|---|
私钥内容（BEGIN ... PRIVATE KEY） | 私钥绝不应被上传 |
证书（BEGIN CERTIFICATE） | 不是公钥 |
OpenSSH 格式的密钥（ssh-rsa、ecdsa-sha2-...） | 请转换为 PEM |
| 少于 2048 位的 RSA | 低于可接受的最低要求 |
| 无法解析的 PEM | 内容损坏或不完整 |
确认时，请在确认框中输入 CADASTRAR。注册立即生效：确认后，集成即开始使用该密钥。
每个集成只能有一个公钥。如需更换密钥——无论是定期轮换，还是私钥丢失或泄露——请创建新的集成。参见替换集成的密钥。
注册完成后，页面会显示密钥的 Fingerprint (SHA-256) 和注册日期。可用指纹核对已注册的密钥确实是您的密钥。
6. 开通集成权限
顾问无需此步骤：授权通过顾问的基金权限完成，注册公钥后集成即可使用。
对管理人而言，最后一步是由 QI Tech 集成团队为集成开通读取和写入权限。无需在页面上等待——开通完成后，状态会显示在 Permissões 中。
7. 配置 webhook（可选）
同样在集成页面中，Webhooks 区块用于注册通知的目标 URL。可用的系统如下：
| 系统 | 事件 |
|---|---|
| 转让方注册 | 审查、转让方注册及审查意见 |
| 转让合同 | 转让合同和产品的状态 |
| 应收账款 | 应收账款流程中的转让和资产 |
| 清算 | 付款批次和清算 |
您可以为所有系统使用同一个 URL，也可以为每个系统分别设置 URL。每个系统会生成各自的签名密钥（HMAC），用于验证收到的投递——参见 Webhook 接收。
webhook 配置对整个管理人或顾问生效，而不是按集成区分。如果有多个 API 集成，它们共享同一套配置。
停用和重新启用集成
Desativar integração（输入 DESATIVAR 确认）后，使用该凭证发起的所有调用都会被拒绝。不会删除任何内容：公钥、权限和 webhook 都会保留，重新启用后恢复生效。
怀疑私钥泄露时，可将停用作为即时应对措施。由于密钥不可更换，请勿重新启用已泄露的集成：应以新集成替代。
替换集成的密钥
如需在不中断业务的情况下改用其他密钥：
- 创建新集成（第 4 步），并在其中注册新公钥（第 5 步）。
- 管理人需等待新集成的权限开通（第 6 步）。
- 在您的应 用中更新新的 API key 和新的私钥——两者需同时更换。
- 使用新凭证运行认证测试。
- 停用旧集成。
无需重新配置 webhook：配置对管理人或顾问整体生效，而不是按集成区分。
上线生产环境
生产环境的流程相同。通过邮件向集成团队发送管理人或顾问在生产环境中主用户的姓名、邮箱和 CPF。主用户获得访问权限后，其他用户的创建、权限分配和 API 集成的创建均由您在门户中自行完成——无需再次联系团队。
Sandbox 的凭证在生产环境中无效：每个环境都有各自的集成、密钥和 API Key。
不得在 QI Tech 的 Sandbox 环境中使用真实的自然人和/或法人数据。
何时仍使用邮件发送
通过门户注册适用于管理人和顾问。其他访问角色——转让方、发起人、投资者和分销商——仍需将公钥发送给集成团队，具体参见密钥交换。
如果您是管理人或顾问但尚未获得门户访问权限，请按第 1 步申请主用户，而不是通过邮件发送密钥。