Padrões de Integração

Nossa API segue os princípios RESTful, utilizando JSON como formato principal para intercâmbio de dados. Para garantir consistência, todas as respostas seguem um padrão de "envelope", facilitando o parsing por parte do cliente.

Padrão de Envelope

Utilizamos um envelope padronizado para que o cliente sempre saiba onde encontrar os dados ou as mensagens de erro, independentemente do endpoint acessado:

{
  "success": true,
	"data": {},
  "meta": {
    "request_id": "c9d911a41d7bc806696be43c4410e65a", // Identificador da requisição
    "timestamp": "2026-01-01T15:25:55.249438496Z" // RFC 3339
  }
}

Para caso de erros, o campo muda da seguinte forma:

{
  "error": {
    "code": "ERR001",
    "message": "An error occurred"
  },
  "meta": {
    "request_id": "12345",
    "timestamp": "2024-01-01T12:00:00Z",
  },
  "success": false
}

Autenticação e Autorização (JWT)

A segurança da nossa API é baseada em JSON Web Tokens (JWT). Para acessar os recursos, você deve incluir o token no cabeçalho das requisições sob a diretiva Authorization: Bearer <seu_token>

Veja como criar um token de autorização em: Criar token de autorização

🚧

Token de Expiração

Normalmente, todos os tokens gerados pela API possuem um prazo de expiração (por padrão, 5 minutos). Essa trava impede que tokens sejam vazados e possam ser consumidos por terceiros sem autorização

Exemplo:

GET /v1/connect/transfer/12345 HTTP/1.1
Host: api.qesh.ai
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...