Especificação Técnica

Versão: 1.0
Owner: Engenharia SOFIA
Última revisão: 2026
Aplicável a: Dev Integradores, Backend, Infra e Auditoria Técnica

Esta página define o contrato técnico oficial da API da SOFIA. O cumprimento destes padrões é obrigatório para integração estável em produção.

1. Headers Obrigatórios

1.1 Endpoints JSON (API REST)

Obrigatórios

• Accept: application/json
• Content-Type: application/json; charset=utf-8 (quando houver body)
• Authorization: Bearer <JWT> (quando o endpoint exigir autenticação)

Compatibilidade

• x-supabase-auth: <JWT> (aceito em rotas específicas)

Recomendados

• Idempotency-Key: <string> (operações não idempotentes)
• X-Request-Id: <uuid> (correlação de logs)

Requisições sem Accept ou com Content-Type incorreto podem ser rejeitadas.

2. Webhooks

Quando aplicável, a SOFIA pode enviar webhooks assinados.

Headers esperados:

• Content-Type: application/json
• X-SOFIA-Timestamp: <unix_ms>
• X-SOFIA-Signature: <hmac>
• Idempotency-Key: <string>

2.1 Validação obrigatória

O integrador deve:

1. Validar assinatura HMAC.
2. Verificar janela de tempo (anti-replay).
3. Implementar deduplicação por Idempotency-Key.

Falha nessas validações invalida a integração para produção.

Detalhes completos em: Webhook (Recomendado para produção)

3. Códigos HTTP

A API segue semântica HTTP padrão.

3.1 Sucesso (2xx)

• 200 OK
• 201 Created

3.2 Erro do Cliente (4xx)

• 400 Payload inválido
• 401 Token inválido ou ausente
• 403 Permissão insuficiente
• 404 Recurso inexistente
• 409 Conflito de estado
• 422 Dados semanticamente inválidos
• 429 Rate limit excedido

3.3 Erro do Servidor (5xx)

• 500 Erro interno
• 502 Dependência externa falhou
• 504 Timeout

4. Política de Retry

Retries agressivos podem resultar em bloqueio temporário.

5. Timeout

5.1 Servidor

Rotas críticas podem retornar 504 quando o tempo máximo for excedido.

5.2 Cliente (Recomendado)

• Leitura: 10–15s
• Operações compostas: 20–25s
• Webhook response: <= 2s

Processamentos longos devem ser desacoplados via fila/job.

6. Tamanho Máximo de Payload

Requisições

• Recomenda-se manter payloads abaixo de 100KB.

Requests acima desse limite podem ser rejeitados.

Boas práticas:

• Usar paginação
• Evitar arrays extensos
• Filtrar por período/status

Respostas

Sempre utilizar:

• limit
• offset
• filtros por período ou entidade

7. Encoding

UTF-8 é obrigatório.

Header recomendado:

Content-Type: application/json; charset=utf-8

Strings devem ser normalizadas antes de:

• Assinar payloads
• Comparar chaves
• Persistir dados críticos

8. Política de Erro

8.1 Formato padrão

{
  "success": false,
  "error": "Mensagem do erro",
  "details": {}
}

details é opcional e não deve ser tratado como contrato fixo.

8.2 Compatibilidade

{
  "message": "Mensagem do erro",
  "error": "Detalhe opcional"
}

Clientes devem tratar ambos formatos.

9. Segurança e Boas Práticas

É proibido:

• Expor tokens em frontend
• Logar Authorization
• Logar assinaturas de webhook
• Publicar URLs internas
• Incluir PII em exemplos públicos

Recomendações:

• Usar variáveis de ambiente
• Rotacionar credenciais periodicamente
• Implementar rate limiting no cliente
• Monitorar falhas repetidas de autenticação

10. Estabilidade e Versionamento

• Alterações incompatíveis exigem nova versão de endpoint.
• Mudanças de contrato serão comunicadas previamente.
• Integradores devem evitar depender de campos não documentados.