Primeiros Passos & Autenticação

Guia rápido para começar a integrar com a Qprof API.

O Qprof API é uma API REST: o sistema faz requisições à URL da API enviando os parâmetros via GET, POST, PUT, PATCH ou DELETE, e cada requisição retorna um objeto JSON.

1. URL base

A URL é formada a partir do domínio do cliente Qprof:

https://{dominio_do_cliente}.qprof.com.br/QProfApi/api

Substitua {dominio_do_cliente} pelo domínio do cliente. Ex.: cliente quicksoft →
https://quicksoft.qprof.com.br/QProfApi/api.

💡 No Apidog, configure dominio_do_cliente como variável de ambiente para alternar entre clientes/ambientes sem editar cada requisição.

2. Autenticação em 2 etapas (token JWT)

Todas as rotas (exceto a própria autenticação) exigem um token JWT no cabeçalho Authorization.

Fluxo

1. POST /authentication  { username, password }   ──►  recebe o token JWT
2. Demais requisições  →  Header: Authorization: Bearer <token>

Passo 1 — Obter o token

POST /authentication

{
  "username": "usuario",
  "password": "senha"
}

200 → o corpo é o token (JWT em texto puro) quando resultFormat=plain.

204 → o token é devolvido no cookie SkelJwtToken (sem resultFormat).

401 → credenciais inválidas ({ "tipoFalhaAutenticacao", "mensagem" }).

O parâmetro de query opcional resultFormat=plain define o formato da resposta do token.

Passo 2 — Usar o token

Envie em todas as demais chamadas:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

🔒 O token JWT tem validade limitada (expira). Ao receber 401 nas demais rotas, gere um novo token. Recomenda-se reutilizar o mesmo token enquanto válido em vez de autenticar a cada chamada.

3. Códigos de resposta usuais

Código	Significado
`200 OK`	Requisição bem-sucedida.
`204 No Content`	Autenticação bem-sucedida com token retornado via cookie (rota `/authentication`).
`400 Bad Request`	Parâmetros ausentes/inválidos (ver corpo da resposta).
`401 Unauthorized`	Falha de autenticação ou sem permissão.
`404 Not Found`	Recurso não encontrado.
`422 Unprocessable Entity`	Regra de negócio não atendida (ver mensagem).
`500 Internal Server Error`	Erro interno (ex.: Importar Retorno Bancário).
`501 Request Failed`	Método de solicitação incorreto.

4. Próximos passos

Veja Compressão gzip — vários métodos exigem o corpo comprimido.

Para integrações de retorno (callbacks que você implementa), veja as pastas Monitoramento NFe e Retorno de Status de Operação.

Primeiros Passos & Autenticação

1. URL base#

2. Autenticação em 2 etapas (token JWT)#

Fluxo#

Passo 1 — Obter o token#

Passo 2 — Usar o token#

3. Códigos de resposta usuais#