Pular para o conteúdo principal

Integração via SFTP

O SFTP (Secure File Transfer Protocol) é o canal pelo qual a QI CTVM disponibiliza os relatórios dos fundos para download. Os modelos disponíveis, o layout coluna a coluna de cada arquivo e os exemplos para download estão na documentação de Relatórios DTVM.

Para a integração, recomendamos bibliotecas e clientes que implementem o protocolo, como o paramiko em Python, o sftp da linha de comando ou qualquer cliente SFTP padrão.

Liberação de acesso

Para solicitar o acesso, entre em contato com integracao.dtvm@qitech.com.br. A liberação é feita primeiro no ambiente de Homologação (Sandbox) e depois em Produção.

Como funciona a autenticação​

O acesso é autenticado por chave pública SSH — não há senha. Você gera o par de chaves, mantém a chave privada sob o seu controle e nos envia apenas a chave pública, que cadastramos no seu usuário do SFTP.

QuemO que fornece
VocêA chave pública (arquivo .pub), no formato OpenSSH
A QI CTVMHOSTNAME, PORT (22) e USERNAME, além do fingerprint do host
Nunca envie a sua chave privada

Nenhum time da QI Tech vai pedir a sua chave privada. Se alguém pedir — por e-mail, por chamado ou por qualquer outro canal —, não somos nós. O compartilhamento no 1Password descrito no passo 3 é apenas para a chave pública (sftp_qitech.pub).

Se a chave privada já foi enviada a alguém ou anexada em algum lugar, considere-a comprometida: gere um par novo e nos envie a nova chave pública.

1. Gerando o par de chaves​

Gere um par dedicado ao SFTP. Não reutilize a chave que assina os seus tokens JWT: são credenciais de sistemas diferentes, com ciclos de vida diferentes — rotacionar uma passaria a obrigar a rotação da outra, e um vazamento em um dos lados atingiria os dois.

Troque nome-da-empresa pelo nome da sua empresa — por exemplo, sftp-acme. Esse texto é apenas um comentário dentro da chave, e serve para nos ajudar a identificá-la.

mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f ~/.ssh/sftp_qitech
Copie o comando da aba correspondente

Cada aba escreve o caminho da pasta na forma que aquele programa entende, então os comandos não são intercambiáveis. Se você rodar o comando de uma aba em outro programa, aparece No such file or directory e nenhuma chave é criada — nesse caso, é só voltar e copiar o comando da aba certa.

No Windows, se você não sabe qual usar, use o PowerShell: é o que abre por padrão no Terminal do Windows.

O comando pergunta por uma passphrase e gera dois arquivos:

ArquivoO que é
sftp_qitechChave privada. Nunca envie e nunca compartilhe.
sftp_qitech.pubChave pública. É esta que você deve nos enviar.

Sobre a passphrase:

  • Integração automatizada (um serviço seu baixando os relatórios): deixe em branco, apertando Enter nas duas perguntas, e proteja a chave privada onde ela for armazenada, em um gerenciador de segredos com acesso restrito. Uma passphrase que precisa ficar disponível para o processo em tempo de execução não acrescenta proteção real.
  • Uso por uma pessoa: defina uma passphrase.

O ssh-keygen já cria a chave privada com permissão restrita ao seu usuário. Se você copiar o arquivo para outra máquina, restaure a permissão — clientes SSH recusam chaves privadas legíveis por outros usuários:

chmod 600 ~/.ssh/sftp_qitech

2. Conferindo o formato da chave pública​

O conteúdo do arquivo .pub é uma única linha, começando pelo tipo da chave e terminando no comentário:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE1wA3uBEFYG+Yi7zIw7/YUJJ4fBB0MUZsvUVaqyyv6M sftp-acme

Confira o arquivo antes de nos enviar:

ssh-keygen -lf ~/.ssh/sftp_qitech.pub

A resposta esperada é o fingerprint da chave, no formato 256 SHA256:... sftp-acme (ED25519). Se o comando responder is not a public key file, o arquivo está corrompido ou não é uma chave pública OpenSSH.

Se a sua chave está no formato PEM/X.509​

Uma chave que começa com -----BEGIN PUBLIC KEY----- está no formato PEM/X.509, o padrão do OpenSSL. Esse formato não pode ser cadastrado no SFTP: o servidor espera o formato OpenSSH, de uma única linha.

Se essa chave já é dedicada ao SFTP, você não precisa gerar outra — basta convertê-la:

  • Você ainda tem a chave privada correspondente. Vale para qualquer tipo de chave:

    ssh-keygen -y -f caminho/para/chave_privada

  • Você só tem a chave pública em PEM. Vale para chaves RSA:

    ssh-keygen -i -m PKCS8 -f caminho/para/chave_publica.pem

Os dois comandos imprimem a chave no formato OpenSSH na saída padrão. A conversão não preserva o comentário original; se quiser, acrescente sftp-nome-da-empresa ao final da linha.

3. Enviando a chave pública​

Envie a chave pública pelo 1Password, compartilhando o item com o time de integração. É por esse canal que recebemos as chaves: ele preserva o conteúdo exatamente como você o gerou e deixa a origem do envio verificável — quem conseguisse substituir a sua chave pública no caminho passaria a ter acesso ao seu diretório no SFTP.

  1. No 1Password, crie um item e cole nele o conteúdo do arquivo sftp_qitech.pub como texto puro, em uma única linha, sem quebras.
  2. Acrescente o fingerprint da chave — a saída do ssh-keygen -lf do passo anterior. Comparamos com o fingerprint da chave que recebemos e confirmamos que ela não foi alterada no caminho.
  3. Compartilhe o item com o time de integração e avise em integracao.dtvm@qitech.com.br que o compartilhamento foi feito.
Não anexe a chave em .docx nem em .pdf

A formatação automática desses programas substitui caracteres (um + por um travessão, aspas retas por tipográficas) e insere quebras de linha. Qualquer uma dessas alterações invalida a chave, e o erro só aparece na hora da conexão.

Com a chave pública cadastrada, confirmamos a liberação e enviamos o HOSTNAME, o USERNAME e o fingerprint do host.

4. Conectando ao SFTP​

Confira o host key na primeira conexão​

Na primeira conexão, o seu cliente vai perguntar se você confia no servidor. Não aceite sem conferir: compare o fingerprint apresentado com o que o time de integração enviou. É essa comparação que impede que outro servidor se passe pelo nosso.

ssh-keyscan -t ed25519 <hostname> > qitech_host_key
ssh-keygen -lf qitech_host_key          # compare com o fingerprint enviado pela QI CTVM
cat qitech_host_key >> ~/.ssh/known_hosts

Depois de conferido, o known_hosts passa a ser a referência do cliente e conexões com outro host key são recusadas automaticamente.

Credenciais da conexão​

CredencialOrigem
HOSTNAMEEndereço do servidor, informado pela QI CTVM
PORT22
USERNAMEUsuário, informado pela QI CTVM
Chave privadaO arquivo sftp_qitech que você gerou
Atenção

Essas credenciais dão acesso direto aos relatórios do seu fundo e não devem ser compartilhadas.

Exemplo de código​

import paramiko

HOSTNAME = "sftp.exemplo.com"                # informado pela QI CTVM
PORT = 22
USERNAME = "usuario"                         # informado pela QI CTVM
PRIVATE_KEY = "/caminho/para/sftp_qitech"    # a chave privada que você gerou
KNOWN_HOSTS = "/caminho/para/known_hosts"    # com o host key da QI CTVM já conferido

client = paramiko.SSHClient()
client.load_host_keys(KNOWN_HOSTS)

# Recusa a conexão se o host key não for o esperado.
# Não use AutoAddPolicy: ela aceita qualquer servidor sem verificação.
client.set_missing_host_key_policy(paramiko.RejectPolicy())

client.connect(
    hostname=HOSTNAME,
    port=PORT,
    username=USERNAME,
    key_filename=PRIVATE_KEY,  # o paramiko identifica o tipo da chave pelo arquivo
    look_for_keys=False,
    allow_agent=False,
    timeout=30,
)

try:
    with client.open_sftp() as sftp:
        # Lista os arquivos disponíveis
        for name in sftp.listdir("/"):
            print(name)

        # Faz o download de um arquivo
        sftp.get("caminho/remoto/arquivo.csv", "caminho/local/arquivo.csv")
finally:
    client.close()

5. Baixando os arquivos​

Os arquivos são nomeados a partir do nome resumido do fundo, do modelo do relatório e da data de referência no formato YYYY-MM-DD:

  • example_name_assets_wallet_composition_2026-07-29.csv

Os modelos disponíveis, o layout coluna a coluna de cada arquivo e os exemplos para download estão na documentação de Relatórios DTVM.

Informação

O SFTP de relatórios descrito nesta página é exclusivamente para download de arquivos; não é permitido realizar upload.

Rotação e revogação da chave​

Para trocar a chave, gere um par novo e nos envie a nova chave pública pelo 1Password, seguindo os passos 1 a 3. Cadastramos a nova chave e informamos quando a anterior for removida — assim a troca acontece sem janela de indisponibilidade.

Se houver suspeita de comprometimento da chave privada, avise o time de integração no mesmo contato: revogamos o acesso da chave antiga imediatamente, antes de cadastrar a nova.