Referência da API

A especificação viva é gerada pelo huma e fica disponível na própria aplicação:

• /docs — documentação interativa (Scalar)
• /openapi.json — OpenAPI 3.1

Esta seção documenta o que o OpenAPI não expressa: o comportamento por trás de cada rota.

Todas as rotas

Método	Path	OperationID	Tag	Visível no OpenAPI
GET	/ping	ping	Health	✅
GET	/mfa	mfa-page	—	✅
GET	/mfa/batch	mfa-batch-page	—	✅
POST	/mfa/send-token	mfa-send-token	—	✅
POST	/smiles/login	smiles-login	Smiles	✅
POST	/smiles/exists-session	smiles-exists-session	Smiles	✅
POST	/smiles/delete	smiles-delete	Smiles	✅
POST	/smiles/account-info	smiles-account-info	Smiles	❌
POST	/smiles/account-statement	smiles-account-statement	Smiles	❌
POST	/smiles/account-exp-points	smiles-account-expiring-points	Smiles	❌
GET	/smiles/dashboard	smiles-dashboard	Smiles	❌
POST	/latam/login	latam-login	Latam	✅
POST	/latam/exists-session	latam-exists-session	Latam	✅
POST	/latam/delete	latam-delete	Latam	✅
POST	/azul/login	azul-login	Azul	✅
POST	/azul/exists-session	azul-exists-session	Azul	✅
POST	/azul/delete	azul-delete	Azul	✅
GET	/metrics	—	—	❌ (registrado direto no chi)

Tudo é POST

Inclusive exists-session e delete, porque o CPF vai no corpo da requisição — nunca na URL. Isso evita CPF em log de acesso, em histórico de proxy e em URL de referrer.

Sem autenticação

O Khronos não tem autenticação nem autorização. Ele é um serviço interno, acessível apenas pela rede do cluster. Qualquer exposição externa precisaria de uma camada de auth na frente.

Comportamento comum

/{cia}/exists-session

{ "username": "12345678900" }

Resposta — sempre 200:

{ "message": "session found" }

Valores possíveis de message:

message	Significado
session found	Existe valor na chave
session not found	Chave vazia ou inexistente
an error occurred retrieving the session	Falha ao consultar o Redis

"Existe" não é "vale"

A rota só verifica se há algo na chave. Ela não valida o JSON, não checa IsValid() e não checa expiração. Uma sessão expirada continua respondendo session found.

/{cia}/delete

{ "username": "12345678900" }

Resposta — sempre 200:

{ "success": true, "message": "success" }

Em falha do Redis, success: false e message com o erro. O status HTTP continua 200; verifique success.

DEL de chave inexistente é sucesso

O Redis não erra ao apagar algo que não existe, então success: true não garante que havia sessão.

/{cia}/login

Corpo comum a todas as companhias (variações em cada página específica):

{
  "username": "12345678900",
  "password": "senha",
  "keyType": "E",
  "keyToken": "usuario@exemplo.com",
  "proxyUrl": "http://user:pass@proxy:8080",
  "force": false,
  "session": false
}

Códigos de resposta possíveis:

Status	Quando
200	Login concluído
401	Refresh token inválido
403	Bloqueio de antibot detectado
404	Credencial inválida, código MFA incorreto ou token não encontrado no Pigeon
412	Conta bloqueada por segurança
422	Requisição inválida para a companhia, ou autenticador MFA não encontrado
428	MFA necessário — reenvie com keyType e keyToken
500	Antibot na Azul, erro indefinido de OAuth ou falha interna
502	A companhia respondeu algo que não sabemos interpretar

O corpo de erro segue o formato RFC 7807 do huma:

{
  "$schema": "http://localhost:3000/schemas/ErrorModel.json",
  "title": "Precondition Required",
  "status": 428,
  "detail": "Solicitado codigo de verificacao"
}

Header X-Trace-ID

Toda resposta de rota registrada no huma traz X-Trace-ID. Use esse valor para achar o login inteiro no Graylog:

trace_id:"<valor do header>"

Ver Observabilidade.

/ping

curl http://localhost:3000/ping

{ "message": "pong" }

É o health check configurado no Helm (HEALTHCHECK: /ping). Não verifica Redis nem dependências — responde pong enquanto o processo HTTP estiver de pé.