Idempotencia en endpoints FHIR

Los endpoints POST /fhir/r4/{ResourceType}/$register son idempotentes: múltiples envíos del mismo recurso con la misma combinación de identificadores (tenant + identifier.system + identifier.value) no generan nuevos recursos.

El siguiente diagrama ilustra el flujo de decisión del servidor:

Comportamiento

Creación inicial

Cuando se envía un recurso con una combinación de identificadores que no existe previamente para la organización autenticada, la plataforma crea el recurso y responde con 201 Created.

Reenvío de un recurso previamente registrado

Si se reenvía el mismo recurso con la misma combinación de identifier.system e identifier.value para la misma organización autenticada, la plataforma no crea un nuevo recurso. En su lugar, retorna el recurso existente con 201 Created.

La respuesta es idéntica al caso de creación inicial. Esto es intencional: la idempotencia es transparente para el cliente.

Nota sobre los ejemplos: Los ejemplos a continuación utilizan el recurso DiagnosticReport a modo ilustrativo. El mismo comportamiento aplica a cualquier recurso FHIR que implemente el patrón $register.

Ejemplo — Recurso creado exitosamente:

// Response - 201 Created
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "diagnosticReport",
      "resource": {
        "resourceType": "DiagnosticReport",
        "id": "ea58008d-d5cd-4023-a916-d242ea10f55b",
        "meta": {
          "versionId": 1,
          "lastUpdated": "2026-05-04T12:33:15.887Z"
        },
        "status": "final",
        "identifier": [
          {
            "system": "https://misistema.com/laboratorio/informes",
            "value": "INF-2024-000123"
          }
        ]
      }
    },
    {
      "name": "issues",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "information",
            "code": "informational",
            "diagnostics": "Resource created successfully"
          }
        ]
      }
    }
  ]
}

Combinación de unicidad

La unicidad de un recurso está determinada por la combinación de los siguientes tres elementos:

• Tenant: Organización autenticada mediante OAuth 2.0 (se determina automáticamente a partir del token de acceso).
• identifier.system: URI del sistema de identificación.
• identifier.value: Identificador único del recurso dentro del sistema.

Esta combinación es utilizada por la plataforma para prevenir registros duplicados. La misma combinación de system + value puede existir para distintas organizaciones, ya que el tenant las diferencia automáticamente y las aísla en espacios de nombres separados.

La documentación específica de cada recurso define la estructura particular del campo identifier.

Header If-None-Exist

El endpoint soporta opcionalmente el encabezado FHIR estándar If-None-Exist para compatibilidad con clientes FHIR existentes. Sin embargo, la garantía de idempotencia es responsabilidad del servidor y no depende de la presencia de este encabezado. La plataforma previene la duplicación incluso cuando el header no está presente.

Uso recomendado: El valor del header debe ser una expresión de búsqueda FHIR que identifique de forma única el recurso:

If-None-Exist: identifier=https://misistema.com/laboratorio/informes|INF-2024-000123

Donde el formato es identifier={system}|{value}.

Comportamiento:

Escenario	Header If-None-Exist	Resultado
Recurso nuevo, no existe previamente	Ausente	201 Created - se crea el recurso
Recurso nuevo, no existe previamente	Presente	201 Created - se crea el recurso
Recurso ya existe para la misma combinación	Ausente	201 Created - no se duplica
Recurso ya existe para la misma combinación	Presente	201 Created - no se duplica

La idempotencia está garantizada por el servidor independientemente del header If-None-Exist. El header se ofrece únicamente para compatibilidad con clientes FHIR estándar que lo requieran.