API Pública da Ghloria e Integração com Agentes de IA

A Ghloria disponibiliza endpoints legíveis por máquina e uma especificação OpenAPI 3.1 que permite a agentes de IA, chamadas de funções LLM e integrações de software comunicar programaticamente com a infraestrutura operacional de agências de viagens.

Especificação OpenAPI 3.1

A especificação OpenAPI 3.1 completa está publicada em:

• URL Canónico: https://www.ghloria.com/openapi.json
• URL Alternativo: https://www.ghloria.com/api/openapi.yaml
• Formato: OpenAPI 3.1.0 JSON, compatível com OpenAI Functions, Anthropic Tools e LangChain

Endpoints Públicos

Os endpoints públicos não requerem autenticação e podem ser chamados diretamente por clientes HTTP e agentes de IA.

1. Estado da API e Descoberta de Capacidades

• Endpoint: GET /api/v1/status
• Descrição: Verifica a integridade do serviço, devolve a versão ativa da API e enumera os endpoints e ferramentas disponíveis.
• Formato: application/json

2. Calculadora de Comissões e Rentabilidade

• Endpoint: POST /api/v1/calculator/calculate (e GET /api/v1/calculator/calculate)
• Descrição: Calcula margens comerciais, comissões retidas após split com host agency, markups líquidos, imposto TOMS/IVA e rendimento horário do assessor.

3. Checklist de Auditoria de Propostas de Viagem

• Endpoint: GET /api/v1/proposals/quality-checklist
• Descrição: Devolve o framework de 25 pontos de controlo de qualidade para propostas de viagens complexas.

Respostas Estruturadas de Erro (RFC 7807)

Todos os erros da API Ghloria devolvem Problem Details estruturados em JSON com Content-Type: application/problem+json:

{
  "type": "https://www.ghloria.com/docs#api-route-not-found",
  "title": "API route not found",
  "status": 404,
  "detail": "The requested Ghloria API endpoint '/api/v1/unknown' does not exist.",
  "code": "api_route_not_found",
  "resolution": "Discover available public API endpoints through /openapi.json or /.well-known/api-catalog.",
  "documentation_url": "https://www.ghloria.com/docs"
}

DNS para Descoberta de IA (DNS-AID)

A Ghloria implementa o DNS-AID segundo o draft do IETF draft-mozleywilliams-dnsop-dnsaid e o RFC 9460 (SVCB/HTTPS):

• Ponto de Entrada do Índice Organizacional: _index._agents.ghloria.com
  • Registo: SVCB 1 www.ghloria.com. alpn="h2,h3" port=443 mandatory=alpn,port
  • TXT de fallback: v=dnsaid1; a2a=https://www.ghloria.com/.well-known/agent-card.json; openapi=https://www.ghloria.com/openapi.json; skills=https://www.ghloria.com/.well-known/agent-skills/index.json
• Ponto de Entrada Agent-to-Agent (A2A): _a2a._agents.ghloria.com
  • Registo: SVCB 1 www.ghloria.com. alpn="a2a" port=443 mandatory=alpn,port
• Ponto de Entrada Model Context Protocol (MCP): _mcp._agents.ghloria.com
  • Registo: SVCB 1 www.ghloria.com. alpn="mcp" port=443 mandatory=alpn,port

Ficheiro de zona publicado na base de código em dns/ghloria.com.zone e definições em dns/dns-aid.json.

Descoberta por Agentes (Machine-Readable)

• https://www.ghloria.com/llms.txt: Guia resumido para LLMs
• https://www.ghloria.com/llms-full.txt: Perfil completo da empresa e modelo de dados
• https://www.ghloria.com/AGENTS.md: Limites operacionais e regras para agentes
• https://www.ghloria.com/404.md: Guia de recuperação 404 em markdown
• https://www.ghloria.com/.well-known/agent-card.json: Descritor de capacidades A2A
• https://www.ghloria.com/.well-known/agent-skills/index.json: Catálogo de skills para agentes
• https://www.ghloria.com/.well-known/api-catalog: Linkset RFC 9264