Primeiros Passos e Autenticação

Guia rápido para integrar com a API QTrust.

A API QTrust expõe dois estilos de endpoint no mesmo serviço:

REST/JSON — requisições GET e POST que devolvem objetos JSON (ou XML, quando o endpoint oferece a opção).

SOAP/XML — operações que recebem um envelope SOAP no corpo e devolvem outro envelope. O contrato autoritativo de cada operação é o WSDL, obtido no mesmo caminho via GET ...?wsdl.

Não há SDK nem biblioteca obrigatória: qualquer cliente HTTP serve.

1. URL base

A URL é construída a partir do domínio do cliente QTrust:

https://{dominio-cliente}-ws.qtrust.com.br

Substitua {dominio-cliente} pelo domínio específico. Exemplo: o cliente quicksoft resulta em https://quicksoft-ws.qtrust.com.br.

Todos os caminhos citados neste guia são relativos a essa base. Se você não souber qual é o seu domínio, veja Credenciais e Suporte.

💡 Defina dominio-cliente como variável de ambiente na sua ferramenta de teste (Postman, Insomnia, Apidog) para alternar entre clientes e ambientes sem reescrever cada chamada.

🔒 Use sempre HTTPS. As credenciais viajam em Base64 no header.

2. O que a API oferece

Estilo	Método	Caminho	Para quê
REST	`GET`	`/consulta/operacao`	Situação das operações de uma data
REST	`GET`	`/consulta/detalheOperacao`	Recebíveis de uma operação, pelo nome do arquivo
REST	`GET`	`/operacoes/{id}/documentos`	Consulta paginada dos recebíveis de uma operação
REST	`POST`	`/v1/import-bank-return/`	Importação de arquivo de retorno bancário
SOAP	`POST`	`/soap/importacaoArquivoCnab`	Importação de arquivo de remessa CNAB
SOAP	`POST`	`/soap/aprovacaoOperacaoConsultoria`	Aprovação da operação pela Consultoria
SOAP	`POST`	`/soap/aprovacaoConsultoria`	Aprovação da Consultoria com conta corrente
SOAP	`POST`	`/soap/aprovacaoOperacaoGestor`	Aprovação da operação pela Gestora
SOAP	`POST`	`/soap/cedente/consulta/contaCorrente`	Consulta de contas correntes do cedente
SOAP	`POST`	`/soap/cadastroCedenteAprovado`	Cadastro de cedente aprovado
SOAP	`POST`	`/soap/agendador/relatorioEstoque`	Agendamento do relatório de estoque
SOAP	`POST`	`/soap/agendador/consultarRelatorio`	Consulta da situação do agendamento
SOAP	`POST`	`/soap/agendador/realizarDownload`	Download do relatório de estoque
Callback	`POST`	`/v2/certifier-callback/qcertifica`	Recebimento do retorno da certificadora

Todo caminho soap/... também responde a GET com ?wsdl, devolvendo o WSDL da operação. Sem a query string, o GET responde 404.

3. Autenticação: uma etapa, não duas

⚠️ Não existe endpoint de geração de token na API QTrust. Não há rota de /authentication, nem JWT, nem Bearer. A credencial vai em cada requisição.

São três modos de autenticação, e cada endpoint aceita um subconjunto deles:

Modo	Como se envia	Onde vale
1. Basic	`Authorization: Basic base64(usuario:senha)`	Todos os endpoints REST e SOAP
2. Headers separados	`username: usuario` + `password: senha`	Todos, exceto `/v1/import-bank-return/`
3. Token de callback	Header e valor cadastrados por certificadora	Somente `/v2/certifier-callback/*`

O modo 2 é um fallback do modo 1: o serviço primeiro procura o header Authorization; só quando ele está ausente ou malformado é que lê username e password. Prefira sempre o modo 1 — é o padrão HTTP, tem suporte nativo em qualquer cliente e é o único aceito em todos os endpoints.

Os detalhes de cada modo, com exemplos, estão em Modos de Autenticação.

4. Códigos de resposta usuais

Código	Significado
`200 OK`	Requisição processada. Nos endpoints SOAP isso não garante sucesso — veja a seção 5.
`400 Bad Request`	Corpo, envelope ou parâmetros inválidos.
`401 Unauthorized`	Credenciais ausentes, recusadas ou — nos endpoints SOAP e de consulta — usuário sem permissão.
`403 Forbidden`	Usuário autenticado sem permissão. Só `/v1/import-bank-return/` usa este código; os demais devolvem `401` também para falta de permissão.
`404 Not Found`	Caminho inexistente, ou `GET` em rota SOAP sem `?wsdl`.
`500 Internal Server Error`	Exceção não tratada.

5. Atenção: nos endpoints SOAP, `200` não significa sucesso

Falha de negócio não vira status de erro. As operações de estoque, de cadastro de cedente e de importação de remessa respondem 200 com um envelope de erro no corpo.

A leitura correta está no campo do envelope, não no status HTTP:

Operação	Campo que indica o resultado
Relatório de estoque (`soap/agendador/*`)	`tipoRetorno` — `SUCESSO` ou `ERRO`
Aprovações (`soap/aprovacao*`)	`statusCode` e `mensagem`
Importação CNAB (`soap/importacaoArquivoCnab`)	`idMensagem`

Só falhas de autenticação (401) e de envelope/validação de entrada (400) chegam como SOAP Fault.

6. Três formatos de erro diferentes

A API não tem um envelope de erro único. Trate os três:

a) ExceptionResponse — usado por /v1/import-bank-return/:

{
  "Error": {
    "Code": "ValidationError",
    "Message": "O campo 'FileName' é obrigatório.",
    "Target": null,
    "InnerError": null
  }
}

b) FromtisError — usado pelas rotas de consulta (/consulta/*, /operacoes/*), por compatibilidade com o contrato Fromtis:

{
  "error": "ValidationError",
  "message": "Parâmetro 'data' inválido. Use o formato DD/MM/AAAA."
}

c) SOAP Fault — usado por todas as rotas soap/*:

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <S:Fault>
      <faultcode>MissingCredentials</faultcode>
      <faultstring>Credenciais ausentes. Informe 'username' e 'password' nos headers da requisição.</faultstring>
    </S:Fault>
  </S:Body>
</S:Envelope>

Nos três casos, o campo de código (Error.Code, error ou faultcode) é o que você deve usar para ramificar o tratamento — a mensagem é para leitura humana e pode mudar.

7. Próximos passos

Modos de Autenticação — cada modo em detalhe, com exemplos e os erros de cada um.

Credenciais e Suporte — como obter usuário e senha, e como acionar o suporte.

Compressão gzip — obrigatória no envio do retorno bancário.

Sua primeira requisição — um exemplo REST e um SOAP, do começo ao fim.

8. Suporte

Dúvidas de integração, credenciais ou erros que você não conseguiu resolver com este guia: suporte@qtrust.com.br. O que enviar junto está em Credenciais e Suporte.

Primeiros Passos e Autenticação

1. URL base#

2. O que a API oferece#

3. Autenticação: uma etapa, não duas#

4. Códigos de resposta usuais#

5. Atenção: nos endpoints SOAP, 200 não significa sucesso#

6. Três formatos de erro diferentes#

7. Próximos passos#

8. Suporte#