# Versionado y deprecación

> Cómo cambian las interfaces FHIR R4 y REST v1, las cargas útiles de webhook y los SDK, y cómo se anuncian los cambios disruptivos.

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

- **FHIR R4** en `/fhir/R4` y **REST v1** en `/v1` son interfaces estables. Los cambios aditivos (nuevos campos, nuevos tipos de recursos, nuevos puntos de conexión, nuevos tipos de eventos) se publican sin previo aviso; los SDK y `docs/openapi.json` se regeneran en el mismo commit y, de lo contrario, una prueba fallará.
- Los **cambios disruptivos** obtienen un nuevo prefijo (`/v2`) y al menos **6 meses** de operación paralela; el prefijo antiguo responde con una cabecera `Deprecation` y `Sunset` durante ese período.
- Las **cargas útiles de webhook** llevan un `type`; los nuevos tipos son aditivos. Un suscriptor a `*` debe ignorar los tipos desconocidos.
- Los **SDK** siguen semver; una versión principal del SDK puede eliminar un prefijo de API obsoleto.
- Las **correcciones de seguridad** pueden endurecer la validación (por ejemplo, conjuntos de valores) sin un cambio de versión; dicho endurecimiento se anuncia en el registro de cambios con 30 días de antelación, a menos que cierre una vulnerabilidad activa.

## Historial de Cambios

### 14 de Octubre de 2026 (aditivo: marca de página de consentimiento, inicio de sesión único para equipos)

- Inicio de sesión único para equipos: una organización puede vincularse a su proveedor SAML u OIDC y a sus dominios de correo electrónico
  (`PUT /admin/organizations/{id}/sso`, administradores de plataforma), y se puede requerir el inicio de sesión único para
  los miembros. `GET /admin/sso/discover?email=` (sin autenticación) devuelve el proveedor para un correo electrónico de trabajo. `OrganizationOut`
  obtiene `sso_provider_id`, `sso_domains` y `sso_required`. Consulte [Inicio de sesión único para su equipo](https://developers.anpheros.com/es/guides/team-sso).

- `PUT /admin/applications/{id}/branding` establece el logotipo de una aplicación (URI de datos PNG/JPEG/WebP, hasta 64 KB) y
  el color de acento (contraste de al menos 4.5:1 con texto blanco), que se muestra en la página de consentimiento alojada. `ApplicationOut`
  obtiene `logo` y `brand_color`. Consulte [Autenticación y OAuth](auth-and-oauth.md#your-brand-on-the-consent-page).
- Página de precios y [precios](https://developers.anpheros.com/es/guides/pricing): una nota de beta privada. La producción se abre después de la verificación y un DPA firmado,
  los planes se facturan por correo electrónico y las asignaciones aún no se aplican automáticamente.

### 14 de Octubre de 2026 (correcciones de forma de error y mapeo de laboratorio)
- Importación de laboratorio: *Uree* / *Urea* se mapea a urea (`3091-6`; `22664-7` en mmol/L) en lugar de nitrógeno de urea (`3094-0`), que
  se mantiene para *BUN* / *Nitrógeno de urea* (`14937-7` en mmol/L). Los valores no se convierten. Ningún dato de producción utilizó el mapeo antiguo.
- Importación de laboratorio: LDL con un método en el informe se mapea a LDL calculado (`13457-7`) o LDL directo (`18262-6`); sin un
  método, permanece `2089-1`. *Directo* es ahora un calificador, por lo que *Bilirubina directa* ya no se mapea a bilirrubina total
  (`1975-2`); conserva el código del laboratorio. Ningún dato de producción utilizó el mapeo antiguo.
- Puntos finales y métodos desconocidos bajo `/v1` responden en la forma de error documentada (`404 not-found`, `405 not-supported`)
  en lugar de `{"detail": "Not Found"}`; los parámetros de consulta no válidos y el límite de tasa por IP bajo `/v1` utilizan
  `{"error": …}` en lugar de un `OperationOutcome` (sin cambios bajo `/fhir/R4`); un `500` inesperado bajo `/v1` lleva
  `error.type = "exception"` (llevaba `error.code`).
- Importación de laboratorio: resultados HL7 v2 con un sistema de codificación local o no LOINC conservan el código del laboratorio bajo `urn:anpheros:lab-code`
  (anteriormente `urn:hl7:<system>`, por ejemplo `urn:hl7:l`). Los resultados ya almacenados no se modifican.
- Importación de laboratorio: los nombres y sinónimos de LOINC en inglés son reconocidos (*Hemoglobin A1c*, *Glicemia de hemoglobina*, *Colesterol HDL*,
  *Colesterol LDL*, *Hemoglobina*); un *Glucosa* simple se mapea a suero o plasma (2345-7) como *Glicemia*. Los nombres con un
  calificador que el concepto no tiene (*orina*, *no HDL*…) ya no se emparejan con una prueba relacionada: antes de este cambio
  *Colesterol HDL* y *Colesterol LDL* enviados sin un código LOINC se almacenaban como colesterol total (2093-3).
- Importación de laboratorio: reenviar un informe ya no duplica resultados cuando cambia el mapeo LOINC. Los nuevos resultados llevan un
  segundo identificador, `urn:anpheros:lab-import:v2`, construido a partir del informe (ID del informe, nombre y código en el informe,
  fecha, valor, unidad); los identificadores existentes no cambian y los resultados anteriores se reconocen por nombre, fecha, valor, unidad
  e ID del informe. Dos resultados con nombres diferentes en el informe pero el mismo código LOINC, fecha y valor (por ejemplo
  *Glucosa* y *Glicemia*) ya no se fusionan en uno solo.

### 13 de Octubre de 2026 (aditivo, sin cambio de contrato)
- El consentimiento se aplica en cada vista derivada (`/v1/context`, `/v1/patients/{id}/timeline`, portal, `$everything`) con una
  regla compartida; una sección solicitada pero no cubierta aparece en el `omitted` del contexto.
- OpenAPI ahora declara `servers`, `securitySchemes` (`bearer`, `apiKey`, `oauth2`, `firebase`), `security` por operación
  y un esquema de respuesta para cada operación; los clientes generados obtienen respuestas tipificadas.
- Cada `401` lleva `WWW-Authenticate: Bearer`.
- El CapabilityStatement anuncia SMART (extensión `oauth-uris`, servicio `SMART-on-FHIR`) y la guía de implementación IPS.
- Las redirecciones detrás del proxy conservan `https://`.
- `python-multipart` 0.0.20 → 0.0.32; `pip-audit` bloquea la compilación en vulnerabilidades conocidas.
- Las URL de webhook deben ser HTTPS públicas: localhost (anteriormente aceptado en el sandbox pero nunca entregado), direcciones privadas y reservadas, y nombres que resuelven a ellas se rechazan en el registro con 400 en `url`; las entregas se conectan solo a las direcciones IP que acaban de verificar (rebind de DNS).

## Aplicación de conformidad (anunciado el 23 de septiembre de 2026)

Las escrituras que no cumplan los requisitos de laboratorio de IPS / HL7 Europe actualmente devuelven `201`/`200` con una cabecera `Anpheros-Conformance`. Tras un período de observación (planificado: 60-90 días a partir de este aviso), la plataforma cambiará al modo de **bloqueo**: dichas escrituras responderán con `422` y una `OperationOutcome` que enumera cada discrepancia. Los integradores que necesiten más tiempo pueden quedar exentos por proyecto durante la transición. Tipos de recursos añadidos el 23 de septiembre de 2026: `Procedure`, `DiagnosticReport`, `CarePlan`, `FamilyMemberHistory`, `ServiceRequest`, `Goal` (aditivo).