Contratos HTTP — Padrão de Governança

Objetivo

• Contrato versionado e machine-readable (OpenAPI 3.1)
• Clareza de request/response e semântica de erro
• Compatibilidade evolutiva (backward compatible)
• Rastreabilidade operacional por correlationId

Fonte da verdade

A especificação oficial vive em docs/openapi/bot-handler.openapi.yaml.

O playground interativo está disponível em API Reference.

Endpoints cobertos

Endpoint	Método	Descrição
/health	GET	Health check — estado do serviço e circuit breakers
/readyz	GET	Readiness probe — conectividade DynamoDB
/api/messages	POST	Recebe Activity do Bot Framework (Teams)

Headers obrigatórios

Header	Obrigatório	Descrição
Content-Type	✅	application/json
Authorization	Em produção	Bearer <Bot Framework JWT>
x-ms-bot-agent-signature	Configurável	HMAC para validação de origem

Semântica de erro

Status	Significado
200	Sucesso — resposta já entregue ao usuário
202	Aceito para processamento assíncrono
400	Payload inválido ou schema incorreto
401	Autenticação ausente ou inválida
429	Rate limit excedido
500	Erro interno — verificar logs e /health

Correlation ID

Todas as respostas de erro incluem correlationId para rastreamento em logs:

{
  "error": "rate_limit_exceeded",
  "correlationId": "a1b2c3d4-e5f6"
}