# 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 6 página(s). Índice: - Recebimento de Webhooks (/documentation/iaas/introducao/autenticacao_webhooks) - Introdução (/documentation/iaas/introducao/inicio) - 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) ``` 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). ## 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. ::: --- # 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 = "\" 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"} ``` ### 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()) ``` --- # 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 ao time da 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. Gerando o par 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 gerada (arquivo public.key.pub) deve ser enviada para o time da QI Tech, e aguardar a integração ser configurada; # Vídeo explicativo