# Versionamento e descontinuação

> Como as interfaces FHIR R4 e REST v1, cargas úteis de webhook e SDKs mudam, e como as alterações disruptivas são anunciadas.

Source: https://developers.anpheros.com/pt/guides/versioning

- **FHIR R4** em `/fhir/R4` e **REST v1** em `/v1` são interfaces estáveis. Alterações aditivas (novos campos, novos tipos de recursos, novos endpoints, novos tipos de eventos) são lançadas sem aviso prévio; os SDKs e `docs/openapi.json` são regenerados no mesmo commit e um teste falha caso contrário.
- **Alterações disruptivas** recebem um novo prefixo (`/v2`) e pelo menos **6 meses** de operação paralela; o prefixo antigo responde com um cabeçalho `Deprecation` e `Sunset` durante esse período.
- **Cargas úteis de webhook** carregam um `type`; novos tipos são aditivos. Um assinante de `*` deve ignorar tipos desconhecidos.
- **SDKs** seguem semver; uma versão principal do SDK pode descartar um prefixo de API descontinuado.
- **Correções de segurança** podem apertar a validação (por exemplo, conjuntos de valores) sem um aumento de versão; tal aperto é anunciado no changelog com 30 dias de antecedência, a menos que feche uma vulnerabilidade ativa.

## Changelog

### 14 de Outubro de 2026 (aditivo: branding da página de consentimento, single sign-on para equipas)

- Single sign-on para equipas: uma organização pode ser associada ao seu fornecedor SAML ou OIDC e aos seus domínios de e-mail
  (`PUT /admin/organizations/{id}/sso`, administradores de plataforma), e o single sign-on pode ser exigido para
  membros. `GET /admin/sso/discover?email=` (sem autenticação) devolve o fornecedor para um e-mail de trabalho. `OrganizationOut`
  ganha `sso_provider_id`, `sso_domains` e `sso_required`. Ver [Single sign-on para a sua equipa](https://developers.anpheros.com/pt/guides/team-sso).

- `PUT /admin/applications/{id}/branding` define o logótipo de uma aplicação (dados URI PNG/JPEG/WebP, até 64 KB) e
  a cor de destaque (contraste de pelo menos 4,5:1 com texto branco), apresentados na página de consentimento alojada. `ApplicationOut`
  ganha `logo` e `brand_color`. Ver [Autenticação e OAuth](auth-and-oauth.md#your-brand-on-the-consent-page).
- Página de preços e [preços](https://developers.anpheros.com/pt/guides/pricing): uma nota de beta privado. A produção abre após verificação e um DPA assinado,
  os planos são faturados por e-mail, e os limites ainda não são aplicados automaticamente.

### 14 de Outubro de 2026 (correções de formato de erro e mapeamento de laboratório)
- Importação de laboratório: *Uree* / *Urea* é mapeado para ureia (`3091-6`; `22664-7` em mmol/L) em vez de azoto ureico (`3094-0`), que
  é mantido para *BUN* / *Urea nitrogen* (`14937-7` em mmol/L). Os valores não são convertidos. Nenhum dado de produção utilizou o mapeamento antigo.
- Importação de laboratório: LDL com um método no relatório é mapeado para LDL calculado (`13457-7`) ou LDL direto (`18262-6`); sem um
  método, permanece `2089-1`. *Direct* é agora um qualificador, pelo que *Bilirubina directa* já não é mapeado para bilirrubina total
  (`1975-2`); mantém o código do laboratório. Nenhum dado de produção utilizou o mapeamento antigo.
- Endpoints e métodos desconhecidos sob `/v1` respondem no formato de erro documentado (`404 not-found`, `405 not-supported`)
  em vez de `{"detail": "Not Found"}`; parâmetros de consulta inválidos e o limite de taxa por IP sob `/v1` utilizam
  `{"error": …}` em vez de um `OperationOutcome` (inalterado sob `/fhir/R4`); um `500` inesperado sob `/v1` carrega
  `error.type = "exception"` (carregava `error.code`).
- Importação de laboratório: resultados HL7 v2 com um sistema de codificação local ou não-LOINC mantêm o código do laboratório sob `urn:anpheros:lab-code`
  (anteriormente `urn:hl7:<system>`, por exemplo `urn:hl7:l`). Os resultados já armazenados não são alterados.
- Importação de laboratório: nomes e sinónimos LOINC em inglês são reconhecidos (*Hemoglobin A1c*, *Glycated hemoglobin*, *HDL cholesterol*,
  *LDL cholesterol*, *Haemoglobin*); um *Glucose* simples é mapeado para soro ou plasma (2345-7) como *Glicemie*. Nomes com um
  qualificador que o conceito não possui (*urine*, *non-HDL*…) já não são correspondidos a um teste relacionado: antes desta alteração
  *HDL cholesterol* e *LDL cholesterol* enviados sem um código LOINC eram armazenados como colesterol total (2093-3).
- Importação de laboratório: reenviar um relatório já não duplica resultados quando o mapeamento LOINC muda. Novos resultados carregam um
  segundo identificador, `urn:anpheros:lab-import:v2`, construído a partir do relatório (ID do relatório, nome e código no relatório,
  data, valor, unidade); os identificadores existentes permanecem inalterados e os resultados anteriores são reconhecidos por nome, data, valor, unidade
  e ID do relatório. Dois resultados com nomes diferentes no relatório mas o mesmo código LOINC, data e valor (por exemplo
  *Glucose* e *Glicemie*) já não são fundidos num só.

### 13 de Outubro de 2026 (aditivo, sem alteração de contrato)
- O consentimento é aplicado em todas as vistas derivadas (`/v1/context`, `/v1/patients/{id}/timeline`, portal, `$everything`) com uma
  regra partilhada; uma secção solicitada mas não coberta aparece no `omitted` do contexto.
- OpenAPI declara agora `servers`, `securitySchemes` (`bearer`, `apiKey`, `oauth2`, `firebase`), `security` por operação
  e um esquema de resposta para cada operação; os clientes gerados obtêm respostas tipificadas.
- Cada `401` carrega `WWW-Authenticate: Bearer`.
- O CapabilityStatement anuncia SMART (extensão `oauth-uris`, serviço `SMART-on-FHIR`) e o guia de implementação IPS.
- Redirecionamentos atrás do proxy mantêm `https://`.
- `python-multipart` 0.0.20 → 0.0.32; `pip-audit` bloqueia a compilação em vulnerabilidades conhecidas.
- URLs de webhook devem ser HTTPS público: localhost (anteriormente aceite na sandbox mas nunca entregue), endereços privados e reservados, e nomes que resolvam para eles são recusados no registo com 400 em `url`; as entregas conectam-se apenas aos endereços IP que acabaram de verificar (DNS rebinding).

## Aplicação de conformidade (anunciado a 23 de setembro de 2026)

Escritas que não cumprem os requisitos de laboratório IPS / HL7 Europe devolvem atualmente `201`/`200` com um cabeçalho `Anpheros-Conformance`. Após um período de observação (planeado: 60–90 dias a partir desta notificação), a plataforma muda para o modo de **bloqueio**: tais escritas responderão com `422`, com um `OperationOutcome` listando cada lacuna. Integradores que necessitem de mais tempo podem ser isentos por projeto durante a transição. Tipos de recursos adicionados a 23 de setembro de 2026: `Procedure`, `DiagnosticReport`, `CarePlan`, `FamilyMemberHistory`, `ServiceRequest`, `Goal` (aditivo).