# QI Tech — Investment-as-a-Service › Primeiros Passos

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

Índice:
- Recebimento de Webhooks (/documentation/iaas/introducao/autenticacao_webhooks)
- Introdução (/documentation/iaas/introducao/inicio)
- Integração pelo portal (/documentation/iaas/introducao/integracao_via_portal)
- Pacote de Endpoints (/documentation/iaas/introducao/pacote_endpoints)
- Endpoints de teste (/documentation/iaas/introducao/teste_de_autenticacao/endpoints_de_teste)
- Teste de autenticação (/documentation/iaas/introducao/teste_de_autenticacao/)
- Troca de Chaves (/documentation/iaas/introducao/troca_de_chaves)

---

# Recebimento de Webhooks

URL: /documentation/iaas/introducao/autenticacao_webhooks

A assinatura dos Webhooks utiliza-se de uma estratégia de criptografia com chaves simétricas, ou seja, tanto a QI CTVM quanto o Parceiro integrador compartilham de uma mesma chave. Ao realizarmos uma configuração de Webhooks, iremos gerar uma Signature Key e disponibiliza-lá. Toda requisição originada no sistema da QI, irá carregar um header SIGNATURE que será um JWT assinado com essa chave. O encoding é realizado com o algoritmo HS256.

Abaixo temos um exemplo em python de como realizar o decoding da assinatura:
```python
from jose import jwt

signature_key = "CHAVE UNICA DISPONIBILIZADA PELO TIME QI"

signature_token = headers["SIGNATURE"]

decoded_token = jwt.decode(signature_token, key=signature_key, algorithms=["HS256"])
print(decoded_token)
```

## O que a assinatura carrega

O JWT decodificado traz quatro campos:

| Campo | Descrição |
|-------|-----------|
| `timestamp` | Data e hora da assinatura, em UTC, no formato `AAAA-MM-DDTHH:MM:SS`. |
| `method` | Método HTTP da requisição — sempre `POST`. |
| `uri` | A URL de destino configurada para o seu webhook. |
| `payload_md5` | Hash MD5 do corpo da requisição. |

:::tip Use o `payload_md5` para validar integridade
Calcular o MD5 do corpo recebido e comparar com `payload_md5` confirma que o payload não foi alterado em trânsito. Como o hash é calculado sobre o corpo serializado, compare os bytes recebidos — não o resultado de um *re-encode* do JSON depois de parsear.
:::

Além do `SIGNATURE`, as requisições levam o header **`AGENT-KEY`**, com o identificador do agente (classe de fundo, investidor ou gestor) a que a notificação se refere. Ele é útil para rotear a notificação quando a sua integração atende mais de um fundo pela mesma URL.

## Tentativas de entrega

Consideramos a entrega bem-sucedida quando a sua aplicação responde com um status de sucesso. Em caso de falha — resposta de erro ou erro de rede — a notificação volta para a fila e é retentada.

São feitas **até 5 tentativas** por notificação. Esgotadas as tentativas, ela é marcada como falha e não é mais retentada automaticamente.

:::info Notificação que não chegou
Uma notificação que falhou nas 5 tentativas pode ser reenviada pela QI CTVM — entre em contato com o time de integração informando o período e o tipo de evento. O reenvio não é uma operação disponível na sua integração.
:::

:::warning Trate o recebimento como idempotente
Uma tentativa pode ter chegado à sua aplicação e a resposta ter se perdido, o que faz a notificação ser retentada. Sua aplicação precisa tolerar receber a mesma notificação mais de uma vez — use as chaves do payload para reconhecer o que já foi processado.
:::

## Validação de origem

Sugerimos que, além de comparar a assinatura, o parceiro integrador valide o nosso IP, dado que todas as nossas requisições são originadas de um mesmo IP, conforme o ambiente:

|Ambiente|IP            |
|--------|--------------|
|Produção|54.205.166.229|
|Sandbox |52.72.221.4   |

:::danger Atenção!
Os webhooks da QI CTVM não devem ser mapeados de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

---

# Introdução

URL: /documentation/iaas/introducao/inicio

A QI CTVM é uma instituição financeira que presta os serviços de Administração e Custódia de Fundos de Investimento. Nós temos uma série de serviços, utilizando REST APIs que viabilizam uma nova experiência em toda a operação, visando facilidades, automações e uma total transparência para os envolvidos.

Essa documentação tem como objetivo descrever os fluxos, endpoints e estruturas de dados necessárias para operar quaisquer Fundos de Investimentos.

Obs.: Em caso de dúvidas em qualquer etapa do processo favor entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) detalhando seu problema/dúvida que te auxiliaremos.

## Perfis de Acesso

No nosso sistema nós reconhecemos o usuário pelo perfil que ele assume dentro da estrutura da QI CTVM. Possuímos 5 principais perfis:
1. Gestores;
2. Originadores;
3. Cedentes;
4. Investidores;
5. Distribuidores;

Cada um desses perfis possui um Endpoint específico para a sua integração, com as devidas rotas disponibilizadas;

Para criarmos um Perfil de Acesso para utilização das nossas APIs é necessário que se entre em contato com nosso time através do e-mail [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br).

Gestoras e consultorias solicitam apenas o **nome, e-mail e CPF** do usuário master responsável e, a partir daí, criam a integração e cadastram a chave pública pelo próprio portal — sem enviar chaves por e-mail. Veja [Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal).

## Ambientes (Hosts)

A QI CTVM possui dois ambientes, SANDBOX e PRODUÇÃO. Ambos os ambientes possuem código e comportamento completamente idênticos, porém, o ambiente de SANDBOX apresenta valores monetários totalmente fictícios, e o ambiente de Produção realiza transações financeiras válidas.

O ambiente Sandbox foi criado para os desenvolvedores realizarem suas integrações, e quando estiverem prontos para entrada em produção, atualizarem apenas as variáveis de ambiente com os parâmetros de Produção.

| Perfil         | Ambiente | Host                                           |
|----------------|----------|------------------------------------------------|
| Gestores       | Sandbox  | https://manager-api.sandbox.qidtvm.com.br/     |
| Originadores   | Sandbox  | https://originator-api.sandbox.qidtvm.com.br/  |
| Cedentes       | Sandbox  | https://assignor-api.sandbox.qidtvm.com.br/    |
| Investidores   | Sandbox  | https://investor-api.sandbox.qidtvm.com.br/    |
| Distribuidores | sandbox  | https://distributor-api.sandbox.qidtvm.com.br/ |
| Consultores    | sandbox  | https://consultant-api.sandbox.qidtvm.com.br/  |
| Gestores       | Produção | https://manager-api.qidtvm.com.br/             |
| Cedentes       | Produção | https://assignor-api.qidtvm.com.br/            |
| Originadores   | Produção | https://originator-api.qidtvm.com.br/          |
| Investidores   | Produção | https://investor-api.qidtvm.com.br/            |
| Distribuidores | Produção | https://distributor-api.qidtvm.com.br/         |
| Consultores    | Produção | https://consultant-api.qidtvm.com.br/          |
| Público        | Produção | https://api.qidtvm.com.br/                     |

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

---

# Integração pelo portal

URL: /documentation/iaas/introducao/integracao_via_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.

:::tip Este é o caminho padrão
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](#quando-o-envio-por-e-mail-ainda-e-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](mailto: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.

:::danger Não envie chaves por e-mail
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:

1. Acesse **Gestão de Acesso > Usuários** e clique em **Criar usuário**.
2. Informe **Nome**, **Sobrenome**, **E-mail** e **CPF**.
3. 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`)

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](/documentation/iaas/introducao/teste_de_autenticacao). |
| **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.

1. Escolha o **Algoritmo da chave**.
2. Clique em **Gerar par de chaves**. O download da chave privada começa automaticamente.
3. 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.
4. 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](/documentation/iaas/introducao/troca_de_chaves) — envie apenas a chave pública:

- **Arraste o arquivo** para a área indicada, ou clique para selecioná-lo (`.pem`, `.pub`, `.key`, `.crt` ou `.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

:::info Apenas para gestoras
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](/documentation/iaas/introducao/autenticacao_webhooks).

:::caution Webhooks são configurados por agente
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`.

:::danger A troca é imediata
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.

:::danger Aviso Importante!
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](/documentation/iaas/introducao/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.

---

# Pacote de Endpoints

URL: /documentation/iaas/introducao/pacote_endpoints

Para facilitar a experiência de integração com o ecossistema da QI Tech , disponibilizamos um pacote completo contendo todos os endpoints possíveis, já organizado em uma estrutura de pastas.

Nosso objetivo é tornar o processo de integração mais ágil, claro e padronizado — reduzindo o esforço inicial e garantindo que você tenha acesso imediato a todos os recursos necessários durante a implementação.

Esse pacote centraliza:

- A lista completa dos endpoints disponíveis para cada produto;

- Estrutura organizada por temas, seguindo a documentação;

Um ponto único de referência, evitando consultas fragmentadas ou perda de informações importantes.

Ao disponibilizarmos essa pasta, buscamos garantir que parceiros integradores tenham um caminho mais simples, rápido e estruturado para iniciar suas implementações com a QI Tech, reforçando nosso compromisso com clareza, segurança e eficiência técnica.

### [📦 Baixar pacote Python completo](/downloads/integracao_python_iaas.zip)

---

# Endpoints de teste

URL: /documentation/iaas/introducao/teste_de_autenticacao/endpoints_de_teste

## Método GET

### Request

ENDPOINT /authentication_test
MÉTODO GET

### Response

STATUS 200

Response Body

```json
{
  "success": "Congrats!"
}
```

## Metodo POST

### Request

ENDPOINT /authentication_test
MÉTODO POST

Request Body

```json
{
  "name": "QI Tech"
}
```

### Response

STATUS 200

Response Body

```json
{
  "name": "QI Tech",
  "success": "Congrats!"
}

```

---

# Teste de autenticação

URL: /documentation/iaas/introducao/teste_de_autenticacao/

### 1. Introdução

Nessa seção iremos explicar como deve funcionar a requisição para que possa ser aceita pelo nosso sistema. Em primeiro Lugar deve-se colocar no header API-CLIENT-KEY a Api Key fornecida pelo time da QI CTVM. Depois deve-se criar um Header de AUTHORIZATION assinando com a Chave Privada do parceiro integrador; 

Abaixo iremos ensinar o passo a passo utilizando de Python para exemplificar o processo de criação da AUTHORIZATION.

### 2. Importar bibliotecas
Neste exemplo em python estamos usando 5 bibliotecas para poder realizar o processo de autenticação.

```python
from datetime import datetime
import json
from jose import jwt
from hashlib import md5
import requests
```

### 3. Inserir a chave privada e a chave de integração
```python title="Dados da criptografia"
api_key = "\<API KEY FORNECIDA PELA QI\>"

client_private_key = '''-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEH7OuewosJfz4zKF+Gm0ogJxhb8G6LSMDVQQbFYz335mHCx9/Pr6Yk+
yYwsVozeXhlry3/vnUn1zCasU+4O+yseZ6AHBgUrgQQAI6GBiQOBhgAEAa46fN/2
8vI64shRhu9erMA6JLl3zHFX8gFHQrbb0g4IDfjXCKMCILiwdtL8QecstsgepTa7
yo1pTXOVNDbmLX2TAK38xb2Gv6OC+PA+5drF2wWajWbVLpR2R7mYEzr5HNIAJYHb
5C1jvM2ItK2R22HAbYfH25nsvGhkCGbrRNWQVF9g
-----END EC PRIVATE KEY-----'''

```

### 4. Definir variáveis
Definir as variáveis método, endpoint e conteúdo particular a cada requisição (neste exemplo, utilizaremos o método "POST" para o endpoint "/authentication_test")
```python title="Dados da requisição"
base_url = "https://assignor-api.qidtvm.com.br"
today_str = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S")
method = "POST"
endpoint = "/authentication_test"
body = {"name": "QI Tech"}
```

:::caution **Atenção**
O campo `uri` da assinatura deve ser **idêntico** ao caminho enviado na requisição. Se o endpoint receber parâmetros na *query string*, eles também fazem parte da URI assinada — veja [Requisições com query string](#query-string).
:::

### 5. Construir Dicionário Base de Assinatura
```python title="Dicionário base"

dict_to_sign = {"timestamp": today_str, "method": method, "uri": endpoint}

```

#### 5.1. Se necessário, adicionar o conteúdo
Para as requisições que tenham _body_, deve-se adicionar o md5 do bytes desse conteúdo. Como todas as requisições no nosso sistema são através de JSON, pode-se usar o seguinte:

```python title="Dicionário base"
body_bytes = json.dumps(body).encode()

md5_instance = md5()
md5_instance.update(body_bytes)
md5_body = md5_instance.hexdigest()

dict_to_sign["payload_md5"] = md5_body
```

### 6. Realizar criptografia do header
Realizar criptografia utilizando biblioteca JWT (neste exemplo de código, utilizamos jsonwebtoken como jwt em javascript)

```python
jwt_headers = {"alg": "ES512", "typ": "JWT"}
encoded_header_token = jwt.encode(
    claims=dict_to_sign,
    key=client_private_key,
    algorithm="ES512",
    headers=jwt_headers,
)
```

### 7. Montando o header final

```python
headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token}
```

```python title="Definindo url final"
url = f"{base_url}{endpoint}"
```

### Realizando requisição

```python
resp = requests.post(url=url, headers=headers, json=body)
print(resp.json())
```

## Requisições com query string {#query-string}

Endpoints paginados ou com filtros recebem parâmetros na *query string* — por exemplo `?page=0&limit=20`. Nesses casos, a *query string* **faz parte da URI assinada**.

O campo `uri` deve ser igual ao caminho enviado na requisição: mesmos parâmetros, na mesma ordem e com a mesma codificação. Se a URI assinada e a URI enviada não forem iguais, a requisição é recusada com status `401`:

```json title="Resposta"
{
  "title": "Invalid endpoint",
  "description": "Invalid endpoint.",
  "translation": "O endpoint e invalido",
  "code": "MIT000015"
}
```

### Exemplo

```python title="GET com paginação"
base_url = "https://manager-api.qidtvm.com.br"
path = "/quota/fund_class/{fund_class_key}/investor_positions"
query_string = "page=0&limit=20"

# a query string faz parte da uri assinada
uri = f"{path}?{query_string}"

method = "GET"
today_str = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S")

dict_to_sign = {"timestamp": today_str, "method": method, "uri": uri}

jwt_headers = {"alg": "ES512", "typ": "JWT"}
encoded_header_token = jwt.encode(
    claims=dict_to_sign,
    key=client_private_key,
    algorithm="ES512",
    headers=jwt_headers,
)

headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token}

resp = requests.get(url=f"{base_url}{uri}", headers=headers)
print(resp.json())
```

### Recomendações

- Monte a *query string* e envie a URL completa. Evite usar o argumento `params` do `requests` junto com uma URI já assinada: o cliente HTTP pode reordenar ou recodificar os parâmetros e invalidar a assinatura.
- Requisições `GET` normalmente não têm corpo. Nesse caso, não envie *body* nem o campo `payload_md5`.
- Valores com caracteres especiais (pontuação de documentos, datas, espaços) devem ser assinados já no formato final em que serão enviados na URL.

---

# Troca de Chaves

URL: /documentation/iaas/introducao/troca_de_chaves

## 1. Requisição Assinada

Todas as requisições em nossas APIs devem usar o protocolo **HTTPs**, utilizando **TLS 1.2 ou 1.3**, contendo dois Headers:

1. API-CLIENT-KEY: Uma chave disponibilizada pelo nosso time de Integração que identifica uma integração específica;
2. AUTHORIZATION: Uma assinatura da requisição que deve ser realizada conforme explicado nesse manual;

Como padrão a QI CTVM utiliza-se do padrão de chaves assimétricas, onde existem duas chaves diferentes, uma para assinatura, denominada chave privada , e uma para leitura, denominada de chave pública . Com a chave privada, o parceiro integrador deverá realizar a assinatura utilizando-se do padrão JWT.
O parceiro integrador é responsável por gerar o par e fornecer à QI CTVM a chave pública para que possamos validar as suas requisições.

:::caution **Atenção**
 A chave privada é de uso exclusivo do parceiro integrador, e deve ser armazenada com segurança. A QI CTVM nunca irá pedir, em hipótese alguma, que voce a compartilhe conosco.
:::

## 2. Como entregar a chave pública

:::tip Gestoras e consultorias: cadastre pelo portal
Se você é uma **gestora** ou uma **consultoria**, o caminho recomendado é cadastrar a chave pública você mesmo, pela tela do Portal do Gestor ou do Portal do Consultor. Veja o guia completo em **[Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal)**.

Pelo portal você cria a integração, cadastra a chave pública e recebe a API Key na própria tela — nenhuma chave trafega por e-mail. O cadastro é imediato, o fingerprint da chave fica visível para conferência e a troca pode ser feita a qualquer momento, sem abrir chamado. É o procedimento padrão tanto em sandbox quanto em produção.

Para começar, envie ao time de integração o **nome, e-mail e CPF** do usuário master responsável pela homologação — e **apenas isso**. A chave pública não deve ser anexada a essa solicitação.
:::

Os demais perfis de acesso — **cedentes, originadores, investidores e distribuidores** — continuam enviando a chave pública gerada ao time de integração da QI Tech, em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), e aguardando a configuração da integração.

## 3. Gerando o par

Você pode gerar o par de chaves pelo próprio portal, no momento do cadastro — a chave privada é gerada no seu navegador e baixada apenas para você (veja [Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal)) — ou gerá-lo localmente pelo terminal.

Para gerar uma chave privada em um computador UNIX faça:

```bash
$ ssh-keygen -t ecdsa -b 521 -m PEM -f private.key
```

E a partir desta chave privada gere sua chave pública.

```bash
$ openssl ec -in private.key -pubout -outform PEM -out public.key.pub
```

A chave pública é o arquivo `public.key.pub`. É esse — e somente esse — arquivo que deve ser cadastrado no portal ou enviado ao time de integração.

# Vídeo explicativo