Guia 4/12

Convenções

Convenções comuns a todos os endpoints.

Envelope

Sucesso: {"ok":true,"dados":…,"meta":{…}}. Erro: {"ok":false,"erro":{"codigo","mensagem","campos"}} com o código HTTP certo (400, 401, 403, 404, 409, 413, 422, 429, 500). Os nomes dos campos e os códigos são estáveis; as mensagens seguem o Accept-Language.

{
  "ok": true,
  "dados": {"id": 41, "total": 4800.00, "moeda": "EUR", "criado_em": "2026-10-28T10:15:00+00:00"},
  "meta": {}
}

{
  "ok": false,
  "erro": {
    "codigo": "validacao",
    "mensagem": "Há dados por corrigir.",
    "campos": {"email": "Indique um email válido."}
  }
}

Cabeçalhos

• X-Request-Id em todas as respostas (pode enviar o seu); indique-o ao reportar um problema.
• Accept-Language: pt-PT (omissão), pt-BR, en, es, fr, de — rótulos como origem_rotulo vêm nessa língua.
• Idempotency-Key em POST (ver Idempotência).
• X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e Retry-After no 429.

Tipos de dados

• Datas: ISO 8601 com fuso (2026-10-28T10:15:00+00:00); só datas como 2026-10-28. A hora local da clínica é Europe/Lisbon.
• Dinheiro: número decimal com 2 casas e a moeda (EUR) no registo ou em x-moeda.
• Unidades: sempre explícitas no esquema (x-unidade): UF/cm², cabelos/cm², enxertos, cm², mm. Unidades foliculares, enxertos e cabelos nunca são intercambiáveis.
• Escolhas: chaves estáveis em enum, com rótulos legíveis em x-enum-rotulos e <campo>_rotulo nas respostas.
• Booleanos: true/false (na entrada aceita-se também 0/1).