门户集成
管理人（gestora）与顾问（consultoria）可自行通过门户创建 API 集成：创建集成、注册公钥，并直接在页面上获取 API Key。任何密钥都不会通过电子邮件传输。
对管理人和顾问而言，通过页面注册公钥是推荐的流程，Sandbox 与生产环境均适用。通过电子邮件发送公钥属于例外情况 —— 参见仍需通过电子邮件发送的情形。
在门户中，公钥由负责人本人注册，需要明确确认，且页面上会显示指纹。这样就免去了在各个邮箱之间手工传递文件，降低了注册错误密钥的风险，并且可随时更换密钥，无需另行提交工单。
流程总览
| 步骤 | 执行方 | 位置 |
|---|---|---|
| 1. 注册主用户 | QI Tech 集成团队 | 通过您的电子邮件或 WhatsApp 联系 |
| 2. 访问门户 | 主用户 | 管理人门户或顾问门户 |
| 3. 创建其他用户并授权 | 主用户 | 门户 Gestão de Acesso > Usuários（访问管理 > 用户） |
| 4. 创建集成 | 主用户或已授权用户 | 门户 Gestão de Acesso > Integração API（访问管理 > API 集成） |
| 5. 注册公钥 | 已授权用户 | 门户集成页面 |
| 6. 开通集成权限 | QI Tech 集成团队 | 完成后显示在同一页面 |
| 7. 配置 Webhook（可选） | 已授权用户 | 门户集成页面 |
1. 申请注册主用户
请通过电子邮件（integracao.dtvm@qitech.com.br）或 WhatsApp 联系 QI Tech 集成团队，提供验收（homologação）负责人的以下信息：
- 全名
- 企业电子邮箱
- CPF
我们将据此在您申请的环境中创建管理人或顾问的主用户。该用户是整个流程的起点：由其创建其他用户、授予权限并创建 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（
manager.manage_integration） - 顾问：Gerenciar integração com a API（
consultant.manage_integration）
- 管理人：Gerenciar Integração API（
未获得该权限时，菜单中不会显示 Integração API 项。
4. 创建集成
在 Gestão de Acesso > Integração API 中点击 Criar integração（创建集成），并填写一个能标识其用途的名称（例如 ETL noturno 或 Backoffice）。
确认后，QI Tech 会生成集成凭据并打开详情页面：
| 凭据 | 用途 |
|---|---|
| API Key | 放入每个请求的 API-CLIENT-KEY 请求头。参见认证测试。 |
| Client Integration 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 集成团队开通集成的 Leitura（读取）和 Escrita（写入）权限。无需在页面上等待 —— 开通完成后，状态会显示在 Permissões（权限）中。
7. 配置 Webhook（可选）
仍在集成页面，Webhooks 区块可用于登记接收通知的目标 URL。可用的系统如下：
| 系统 | 事件 |
|---|---|
| 转让方登记 | 转让方的分析、登记与备注 |
| 转让合同 | 转让合同与产品的状态 |
| 应收账款 | 应收账款流程中的转让与资产 |
| 清算 | 付款批次与清算 |
您可以为所有系统使用同一个 URL，也可以为每个系统单独设置 URL。 每个系统都会生成各自的 HMAC 签名密钥，用于校验所收到的推送 —— 参见接收 Webhook。
Webhook 配置作用于整个管理人或顾问，而非单个集成。若存在多个 API 集成，它们共用同一份配置。
更换公钥
您可以随时在集成页面点击 Trocar chave（更换密钥）并重复步骤 5。确认时请输入 TROCAR。
原密钥会立即失效。新密钥注册后，使用原密钥签名的请求将立即开始失败。请在能够同步更新应用所用私钥的时间窗口内执行更换。
停用与重新启用集成
Desativar integração（停用集成，需输入 DESATIVAR 确认）会使所有使用该凭据的调用被拒绝。数据不会被删除：公钥、权限和 Webhook 仍会保存，重新启用后即恢复生效。
如怀疑私钥泄露，可立即停用作为应急处理；随后生成新的密钥对并注册新公钥，再重新启用。
进入生产环境
生产环境的流程完全相同。请通过电子邮件向集成团队提供生产环境中管理人或顾问的主用户姓名、电子邮箱和 CPF。此后，创建其他用户、授予权限以及创建 API 集成均由您自行在门户中完成，无需再次联系集成团队。
Sandbox 的凭据在生产环境中无效：每个环境都有各自的集成、密钥和 API Key。
请勿在 QI Tech 的 Sandbox 环境中使用真实的自然人和/或法人数据。
仍需通过电子邮件发送的情形
门户注册功能面向管理人与顾问。其余访问角色 —— 转让方、发起方、投资者和分销商 —— 仍需按密钥交换中的说明，将公钥发送给集成团队。
如果您是管理人或顾问但尚未获得门户访问权限，请按步骤 1 申请主用户，而不要通过电子邮件发送密钥。