Integração pelo portal
Gestoras e consultorias criam a própria integração de API pelo portal: criam a integração, cadastram a chave pública e recebem ali mesmo a API Key. Nenhuma chave trafega por e-mail.
Cadastrar a chave pública pela tela é o procedimento recomendado para gestoras e consultorias, em sandbox e em produção. O envio da chave pública por e-mail é tratado como exceção — veja Quando o envio por e-mail ainda é usado.
Pelo portal a chave é cadastrada pelo próprio responsável, com confirmação explícita e fingerprint visível na tela. Isso elimina o repasse manual de arquivos entre caixas de e-mail, reduz o risco de a chave errada ser cadastrada e permite a troca da chave a qualquer momento, sem abrir chamado.
Visão geral do fluxo
| Etapa | Quem faz | Onde |
|---|---|---|
| 1. Cadastro do usuário master | Time de integração da QI Tech | A partir do contato por e-mail ou WhatsApp |
| 2. Acesso ao portal | Usuário master | Portal do Gestor ou Portal do Consultor |
| 3. Criação dos demais usuários e permissões | Usuário master | Portal, em Gestão de Acesso > Usuários |
| 4. Criação da integração | Usuário master ou usuário com permissão | Portal, em Gestão de Acesso > Integração API |
| 5. Cadastro da chave pública | Usuário com permissão | Portal, na tela da integração |
| 6. Liberação das permissões da integração | Time de integração da QI Tech | Aparece na própria tela quando concluída |
| 7. Configuração de webhooks (opcional) | Usuário com permissão | Portal, na tela da integração |
1. Solicitar o cadastro do usuário master
Entre em contato com o time de integração da QI Tech por e-mail (integracao.dtvm@qitech.com.br) ou WhatsApp informando, do responsável pela homologação:
- Nome completo
- E-mail corporativo
- CPF
Com esses dados criamos o usuário master da gestora ou da consultoria no ambiente solicitado. Esse usuário é o ponto de partida: é ele quem cria os demais usuários, concede permissões e cria as integrações de API.
A solicitação contém apenas nome, e-mail e CPF do responsável. Não envie a chave pública nessa mensagem — ela é cadastrada por você mesmo no portal, na etapa 5. E a chave privada nunca é enviada a ninguém, em nenhuma hipótese: a QI Tech jamais pedirá que você a compartilhe.
2. Acessar o portal
| Perfil | Ambiente | Portal |
|---|---|---|
| Gestora | Sandbox | https://portal-do-gestor.sandbox.fundos.qitech.com.br/ |
| Gestora | Produção | https://portal-do-gestor.fundos.qitech.com.br/ |
| Consultoria | Sandbox | https://portal-do-consultor.sandbox.fundos.qitech.com.br/ |
| Consultoria | Produção | https://portal-do-consultor.fundos.qitech.com.br/ |
O acesso é feito por login único (SSO) com o e-mail cadastrado na etapa anterior.
3. Criar os demais usuários e conceder permissões
Somente o usuário master (ou quem ele autorizar) enxerga a tela de integração. Para dar acesso a outras pessoas do time:
- Acesse Gestão de Acesso > Usuários e clique em Criar usuário.
- Informe Nome, Sobrenome, E-mail e CPF.
- Abra o usuário criado e conceda a permissão de integração:
- Gestora: Gerenciar Integração API (
manager.manage_integration) - Consultoria: Gerenciar integração com a API (
consultant.manage_integration)
- Gestora: Gerenciar Integração API (
Sem essa permissão o item Integração API não aparece no menu.
4. Criar a integração
Em Gestão de Acesso > Integração API, clique em Criar integração e informe um nome que identifique o uso (por exemplo, ETL noturno ou Backoffice).
Ao confirmar, a QI Tech gera as credenciais da integração e a tela de detalhe é aberta:
| Credencial | Para que serve |
|---|---|
| API Key | Vai no header API-CLIENT-KEY de todas as requisições. Veja Teste de autenticação. |
| Client Integration Key | Identificador da integração. Use para referenciá-la em contatos com o time de integração. |
Uma mesma gestora ou consultoria pode manter várias integrações ativas ao mesmo tempo, cada uma com sua própria chave pública — útil para separar sistemas ou ambientes internos.
A integração nasce com status Criada. Ela só passa a Ativa depois que a chave pública é cadastrada.
5. Cadastrar a chave pública
Na tela da integração, clique em Cadastrar chave pública. Há duas formas de fazer isso.
Opção A — Gerar o par de chaves no navegador
O portal gera o par direto no seu navegador e baixa a chave privada para a sua máquina. A chave privada nunca é enviada à QI Tech: só a chave pública é transmitida.
- Escolha o Algoritmo da chave.
- Clique em Gerar par de chaves. O download da chave privada começa automaticamente.
- Guarde a chave privada em local seguro — ela não é exibida novamente e não pode ser recuperada. Se necessário, use Baixar chave privada e Baixar chave pública antes de sair da tela.
- A chave pública já vem preenchida no formulário. Confirme para cadastrá-la.
Cada algoritmo determina o alg que você deve usar ao assinar o JWT das requisições:
| Algoritmo no portal | Assinatura do JWT |
|---|---|
| RSA 2048 (recomendado) | RS256 |
| RSA 4096 | RS256 |
| EC P-256 | ES256 |
| EC P-384 | ES384 |
| EC P-521 | ES512 |
Opção B — Enviar a sua própria chave pública
Se você já gerou o par fora do portal — veja Troca de chaves — envie apenas a chave pública:
- Arraste o arquivo para a área indicada, ou clique para selecioná-lo (
.pem,.pub,.key,.crtou.txt); ou - Cole o conteúdo do PEM no campo de texto.
O portal identifica o algoritmo da chave e informa, abaixo do campo, com qual alg você deve assinar suas requisições.
Requisitos e recusas
A chave precisa estar em PEM, no bloco -----BEGIN PUBLIC KEY-----. O portal recusa o cadastro nos casos abaixo:
| Situação | Motivo |
|---|---|
Conteúdo de chave privada (BEGIN ... PRIVATE KEY) | A chave privada nunca deve ser enviada |
Certificado (BEGIN CERTIFICATE) | Não é uma chave pública |
Chave no formato OpenSSH (ssh-rsa, ecdsa-sha2-...) | Converta para PEM |
| RSA com menos de 2048 bits | Abaixo do mínimo aceito |
| PEM ilegível | Conteúdo corrompido ou incompleto |
Para confirmar, digite CADASTRAR no campo de confirmação. O cadastro é imediato: a integração passa a usar essa chave assim que você confirma.
Concluído o cadastro, a tela exibe o Fingerprint (SHA-256) da chave e a data do cadastro. Use o fingerprint para conferir que a chave cadastrada é mesmo a sua.
6. Liberação das permissões da integração
Consultorias não passam por esta etapa: a autorização é feita pelas permissões de fundo da consultoria, e a integração já fica pronta para uso depois do cadastro da chave.
Para gestoras, o último passo é a liberação das permissões de Leitura e Escrita da integração, feita pelo time de integração da QI Tech. Não é preciso aguardar na tela — o status aparece em Permissões quando a liberação for concluída.
7. Configurar webhooks (opcional)
Ainda na tela da integração, o bloco Webhooks permite cadastrar a URL de destino das notificações. Os sistemas disponíveis são:
| Sistema | Eventos |
|---|---|
| Cadastro de cedentes | Análises, registro de cedentes e apontamentos |
| Contratos de cessão | Status de contratos de cessão e produtos |
| Recebíveis | Cessões e ativos da esteira de recebíveis |
| Liquidação | Lotes de pagamento e liquidações |
Você pode usar a mesma URL para todos os sistemas ou uma URL por sistema. Cada sistema gera uma chave de assinatura (HMAC) própria, usada para validar as entregas recebidas — veja Recebimento de Webhooks.
A configuração de webhooks vale para a gestora ou consultoria como um todo, não por integração. Se houver mais de uma integração de API, todas compartilham a mesma configuração.
Trocar a chave pública
A qualquer momento, na tela da integração, use Trocar chave e repita a etapa 5. Confirme digitando TROCAR.
A chave anterior é invalidada na hora. Requisições assinadas com ela passam a falhar assim que a nova chave é cadastrada. Faça a troca em uma janela em que você possa atualizar a chave privada usada pela sua aplicação.
Desativar e reativar a integração
Desativar integração (confirmando com DESATIVAR) faz com que toda chamada feita com aquela credencial passe a ser recusada. Nada é apagado: chave pública, permissões e webhooks continuam salvos e voltam a valer ao reativar.
Use a desativação como resposta imediata a uma suspeita de vazamento da chave privada; em seguida, gere um novo par e cadastre a nova chave pública antes de reativar.
Entrada em produção
O procedimento em produção é o mesmo. Envie por e-mail ao time de integração o nome, e-mail e CPF do usuário master da gestora ou da consultoria no ambiente de produção. A partir do acesso desse usuário master, a criação dos demais usuários, a concessão de permissões e a criação das integrações de API são feitas por você, pelo portal — sem novo contato com o time.
As credenciais de sandbox não valem em produção: cada ambiente tem suas próprias integrações, chaves e API Keys.
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
Quando o envio por e-mail ainda é usado
O cadastro pelo portal está disponível para gestoras e consultorias. Os demais perfis de acesso — cedentes, originadores, investidores e distribuidores — continuam enviando a chave pública ao time de integração, conforme descrito em Troca de chaves.
Se você é gestora ou consultoria e ainda não tem acesso ao portal, solicite o usuário master pela etapa 1 em vez de enviar a chave por e-mail.