Modos de Autenticação

A API QTrust não emite token de acesso. A credencial acompanha cada requisição, em um dos três modos abaixo.

A credencial é o usuário e a senha do portal QTrust do próprio cliente — os mesmos usados para entrar na aplicação web. Como obtê-los está em Credenciais e Suporte.

Modo 1 — `Authorization: Basic` (recomendado)

O padrão HTTP Basic: usuário e senha concatenados com dois-pontos e codificados em Base64.

Authorization: Basic base64(usuario:senha)

Para integracao / S3nh@Forte, o valor codificado de integracao:S3nh@Forte é aW50ZWdyYWNhbzpTM25oQEZvcnRl, resultando em:

Authorization: Basic aW50ZWdyYWNhbzpTM25oQEZvcnRl

Aceito por todos os endpoints REST e SOAP. É o único modo aceito por /v1/import-bank-return/.

Exemplos

cURL — não é preciso montar o Base64 na mão; o -u faz isso:

Python

Modo 2 — Headers `username` e `password`

Dois headers separados, com os valores em texto puro:

username: integracao
password: S3nh@Forte

Existe como fallback do Modo 1, para clientes SOAP antigos que não conseguem montar o header Authorization. O serviço só lê esses headers quando o Authorization está ausente ou não começa com Basic .

⚠️ /v1/import-bank-return/ não aceita este modo. Esse endpoint exige Authorization: Basic e responde 401 com MissingCredentials se você enviar apenas username/password.

Vale em: /consulta/operacao, /consulta/detalheOperacao, /operacoes/{id}/documentos e em todas as operações soap/*.

Exemplo

💡 Se o seu cliente consegue enviar o Authorization, use o Modo 1. O Modo 2 não traz vantagem alguma e não funciona em toda a API.

Modo 3 — Token de callback (somente certificadoras)

Os endpoints /v2/certifier-callback/* recebem chamadas da certificadora para o QTrust, e não seguem os modos acima.

Cada certificadora pode ter cadastrado no QTrust um par header/token:

quando ambos estão preenchidos, o callback precisa trazer aquele header exato com aquele valor exato — qualquer divergência responde 401;

quando qualquer um dos dois está em branco, o callback é aceito sem credencial.

Por isso não há nome de header a documentar aqui: ele é definido no cadastro da certificadora. Consulte o cadastro, ou peça a configuração ao suporte.

Regras de credencial que costumam pegar

Situação	Comportamento
Usuário em maiúsculas ou minúsculas	Indiferente — o nome de usuário é normalizado para maiúsculas antes da validação.
Senha em maiúsculas ou minúsculas	Faz diferença — a senha é sensível a maiúsculas e minúsculas.
Senha expirada	Autentica normalmente. A expiração bloqueia o portal web, não a API.
Usuário bloqueado	Recusado — `AuthenticationFailed`, "Usuário bloqueado."
Usuário inativo	Recusado — `AuthenticationFailed`, "Usuário inativo."
Fora do período de acesso permitido	Recusado — `AuthenticationFailed`, "Acesso fora do período permitido." O usuário pode ter janela de horário/dias configurada no portal.
Usuário ou senha inválidos	Recusado — `AuthenticationFailed`, "Usuário ou senha inválidos."

💡 Tentativas seguidas com senha errada podem bloquear o usuário pela política do portal. Ao receber AuthenticationFailed, pare o processo e corrija a credencial em vez de repetir a chamada.

Autenticação não é autorização

Passar pela credencial é só o primeiro passo. Depois disso o QTrust verifica a que entidade o usuário está vinculado e a que dados ele pode chegar.

Endpoint	Exige
`soap/importacaoArquivoCnab`	Usuário vinculado a Consultoria ou Gestora, e com acesso ao fundo informado no envelope
`soap/aprovacaoOperacaoConsultoria`, `soap/aprovacaoConsultoria`	Usuário vinculado a Consultoria
`soap/aprovacaoOperacaoGestor`	Usuário vinculado a Gestora
`/consulta/operacao`, `/consulta/detalheOperacao`	Usuário vinculado a Consultoria ou Gestora
`/operacoes/{id}/documentos`	Usuário com empresa vinculada
`soap/agendador/*`	Usuário autorizado no fundo consultado
`/v1/import-bank-return/`	Usuário com acesso à tela de Retorno Bancário na empresa/filial do fundo

A recusa vem com o código AuthorizationError. Repare no status HTTP:

/v1/import-bank-return/ devolve 403 Forbidden;

os demais endpoints devolvem 401 Unauthorized também para falta de permissão.

Ou seja, um 401 nem sempre significa credencial errada — leia a mensagem antes de concluir que a senha está inválida.

Códigos de erro de autenticação

Código	Status	Quando acontece
`MissingCredentials`	`401`	Nenhuma credencial informada, ou header `Authorization` malformado (Base64 inválido, sem `:`, usuário ou senha vazios)
`AuthenticationFailed`	`401`	Credencial informada mas recusada (senha errada, usuário bloqueado, inativo, fora do período)
`AuthorizationError`	`401` (`403` no retorno bancário)	Credencial válida, mas o usuário não tem permissão para a operação ou para o fundo

O formato do corpo muda conforme o endpoint — veja "Três formatos de erro diferentes" em Primeiros Passos.

Boas práticas

Um usuário exclusivo para a integração. Não reaproveite o usuário nominal de uma pessoa: quando ela sai da empresa ou troca a senha, a integração cai junto.

Não autentique duas vezes. Como não há token, não existe "login prévio": monte o header uma vez e reutilize na sessão HTTP.

Guarde a senha em cofre de segredos, variável de ambiente ou configuração protegida — nunca no código-fonte nem em repositório.

Não registre o header em log. Authorization: Basic ... é reversível em um comando; trate-o como a própria senha.

Sempre HTTPS.

Modos de Autenticação

Modo 1 — Authorization: Basic (recomendado)#

Exemplos#

Modo 2 — Headers username e password#

Exemplo#

Modo 3 — Token de callback (somente certificadoras)#

Regras de credencial que costumam pegar#

Autenticação não é autorização#

Códigos de erro de autenticação#

Boas práticas#