Como obter os dados de acesso à API QTrust e como acionar o suporte quando algo não funciona.1. O que você precisa ter em mãos#
Para fazer a primeira chamada são necessários três dados:| Dado | Exemplo | Onde conseguir |
|---|
| Domínio do cliente | quicksoft (compondo https://{dominio-cliente}-ws.qtrust.com.br) | Consulte o administrador do sistema |
| Usuário | integracao | Criado pelo administrador do portal na sua empresa |
| Senha | — | Definida junto com o usuário |
Não há chave de API, client id, client secret nem token: a credencial é um usuário do portal QTrust.2. Como obter o usuário e a senha#
O usuário de integração é criado dentro do próprio portal QTrust, pelo administrador do sistema na sua empresa — o mesmo perfil que cadastra os demais usuários.1.
Criar um usuário dedicado à integração, separado dos usuários nominais das pessoas. Um usuário que não some quando alguém troca de área.
2.
Vincular o usuário à entidade correta — Consultoria ou Gestora, conforme o papel da sua empresa na operação. Esse vínculo é o que define a que endpoints o usuário terá acesso; veja a tabela em Modos de Autenticação. 3.
Conceder acesso ao fundo (ou aos fundos) que a integração vai movimentar.
4.
Liberar as telas correspondentes às operações que a integração fará. O caso mais comum de esquecimento: /v1/import-bank-return/ exige que o usuário tenha acesso à tela de Retorno Bancário na empresa/filial do fundo — sem isso a chamada responde 403.
5.
Verificar restrição de horário. Se o usuário tiver janela de acesso configurada, chamadas fora dela são recusadas com "Acesso fora do período permitido" — o que costuma quebrar rotinas noturnas.
💡 Vale conferir a credencial entrando no portal web com ela antes da primeira chamada. Se o login funciona, o problema na API é de permissão ou de requisição, não de senha.
3. Se sua empresa ainda não tem acesso#
Se você não sabe quem é o administrador do portal na sua empresa, ou sua empresa ainda não tem ambiente QTrust provisionado, escreva para suporte@qtrust.com.br informando:razão social e CNPJ da sua empresa;
papel na operação (Consultoria, Gestora, Custodiante, Cedente);
CNPJ do(s) fundo(s) envolvido(s);
quais integrações pretende usar (por exemplo: importação de remessa CNAB, retorno bancário, relatório de estoque, consulta de operações);
nome e e-mail do responsável técnico pela integração.
4. Boas práticas de credencial#
Usuário exclusivo por integração. Se você tem duas rotinas distintas, dois usuários — isolam falhas e facilitam a auditoria.
Senha em cofre de segredos ou variável de ambiente. Nunca no código-fonte, nunca versionada.
Nunca registre o header Authorization em log. Ele é Base64, não criptografia: qualquer pessoa com o log tem a senha.
Combine a troca de senha com o administrador. Não há token de longa duração para isolar a integração de uma mudança de senha: trocou a senha, a rotina para até você atualizar a configuração.
Não repita chamadas com credencial recusada. Tentativas seguidas podem bloquear o usuário pela política do portal.
5. Abrindo um chamado#
Para o atendimento não voltar pedindo informação, inclua:razão social e CNPJ da sua empresa;
domínio do cliente usado na URL (https://{dominio-cliente}-ws.qtrust.com.br);
ambiente (produção ou homologação);
usuário utilizado na chamada — nunca envie a senha.
método e caminho completo (por exemplo POST /soap/agendador/relatorioEstoque);
data e hora da tentativa, com fuso;
corpo enviado (ou o envelope SOAP), com dados sensíveis mascarados;
resposta recebida na íntegra: status HTTP e corpo;
o código do erro — Error.Code, error ou faultcode, conforme o endpoint;
se houver, os identificadores devolvidos: idMensagem, idAgendamento, executionId.
CNPJ do fundo e, quando fizer sentido, do cedente;
nome do arquivo envolvido, quando a chamada importa arquivo;
se é a primeira vez que a chamada falha ou se parou de funcionar de repente — e, nesse caso, desde quando.
⚠️ Não anexe senhas, o header Authorization completo, nem arquivos com dados pessoais além do necessário para reproduzir o problema.
6. Antes de abrir o chamado#
Boa parte dos casos se resolve com estas quatro verificações:1.
Status 401 com MissingCredentials — a credencial não chegou. Confira se o header Authorization está sendo enviado. Se você usa os headers username/password, confirme que o endpoint os aceita: /v1/import-bank-return/ não aceita.
2.
Status 401 ou 403 com AuthorizationError — a credencial chegou e é válida; o que falta é permissão. É cadastro no portal (entidade, fundo, tela), não senha.
3.
Status 200 mas nada aconteceu — nos endpoints SOAP, falha de negócio vem com 200. Leia tipoRetorno, statusCode ou idMensagem no corpo antes de concluir que deu certo.
4.
Status 400 com ValidationError — a mensagem costuma dizer exatamente qual campo está errado. Confira formato de data e de CNPJ.
Modificado em 2026-09-23 15:31:01
