# Cómo integrar sistemas de clínicas con un backend FHIR

> Tutorial: conecta un EMR de clínica a los registros FHIR R4 de pacientes — directorio de médicos, coincidencia por número de registro, una visita como una transacción con el médico como autor, informes de laboratorio, datos de otros proveedores y webhooks.

Source: https://developers.anpheros.com/es/guides/integrate-clinic-systems-fhir

**Este tutorial conecta el software de una clínica (un EMR, un sistema de gestión de consultorios o una herramienta de reserva) a los registros HL7 FHIR R4 de pacientes en Anpheros: la clínica y sus médicos se registran en el directorio, los pacientes se emparejan por el número de registro de la clínica, una visita se registra como una transacción con el médico nombrado como autor, y la clínica se entera de los datos que otros proveedores agregan.** Cada solicitud se `curl` contra el sandbox gratuito, y las respuestas son propias de la plataforma.

La integración se ejecuta en el servidor de la clínica, con una clave API de proyecto para los pacientes que la clínica registra y, para las personas que ya tienen un registro Anpheros, una concesión OAuth que aprueban.

## Qué se mapea a qué

| En el sistema de la clínica | En FHIR R4 |
|---|---|
| la clínica, sus departamentos | `Organization` |
| un médico o enfermero | `Practitioner` |
| esa persona trabajando en esa clínica, con una especialidad | `PractitionerRole` |
| el archivo del paciente y su número | `Patient` con un `identifier` en el sistema de la clínica |
| una visita | `Encounter` |
| signos vitales, resultados medidos durante la visita | `Observation` vinculados a la `Encounter` |
| un diagnóstico | `Condition` (ICD-10), con `verificationStatus` provisional o confirmado |
| una prescripción, tratamiento actual | `MedicationStatement` (ATC) |
| una carta, un resumen de alta, un escaneo | `DocumentReference` con el archivo |
| resultados de laboratorio | el [conector de laboratorio](https://developers.anpheros.com/es/guides/lab-connector), en `Observation` |

## Paso 1: registrar la clínica y sus médicos

Los recursos de directorio no tienen pacientes. Otros proyectos en el mismo entorno pueden leerlos, por lo que otros proveedores de un paciente ven quién escribió qué, pero solo su proyecto puede modificarlos.

```bash
export BASE=https://platform.anpheros.com/fhir/R4
export KEY=sk_test_…
H=(-H "Authorization: Bearer $KEY" -H "Content-Type: application/fhir+json")

curl -X POST $BASE/Organization "${H[@]}" -d '{"resourceType": "Organization", "active": true, "name": "Clinica Cardio Nord",
  "identifier": [{"system": "https://clinic.example/org", "value": "CCN"}]}'

curl -X POST $BASE/Practitioner "${H[@]}" -d '{"resourceType": "Practitioner", "active": true,
  "name": [{"family": "Popescu", "given": ["Ana"], "prefix": ["Dr."]}]}'

curl -X POST $BASE/PractitionerRole "${H[@]}" -d '{"resourceType": "PractitionerRole", "active": true,
  "practitioner": {"reference": "Practitioner/'$PRACTITIONER'"},
  "organization": {"reference": "Organization/'$ORG'"},
  "code": [{"text": "Cardiologist"}]}'
```

Conserve los IDs devueltos junto a los registros de su personal. Cuando alguien se marche, establezca su `PractitionerRole` a `"active": false`; sus escritos anteriores conservan su nombre y ya no podrán actuar a través de su sistema.

## Paso 2: emparejar pacientes

Para los pacientes que la clínica registra, cree el `Patient` con el número de registro de la clínica como identificador:

```bash
curl -X POST $BASE/Patient "${H[@]}" -d '{"resourceType": "Patient",
  "identifier": [{"system": "https://clinic.example/mrn", "value": "MRN-20981"}],
  "name": [{"family": "Dinu", "given": ["Andrei"]}], "gender": "male", "birthDate": "1968-11-05"}'
```

A partir de entonces, busque al paciente por ese número, nunca por nombre y fecha de nacimiento:

```bash
curl "$BASE/Patient?identifier=https://clinic.example/mrn|MRN-20981" -H "Authorization: Bearer $KEY"
```

**Cuando la persona ya tiene un registro en Anpheros**, desde su propia aplicación u otro proveedor, la clínica no crea un segundo. Solicita a la persona acceso con OAuth, desde una tableta en el mostrador de recepción o un enlace enviado antes de la visita, utilizando una aplicación **confidencial** (el servidor de la clínica mantiene el secreto). La persona elige su registro y por cuánto tiempo la clínica puede acceder a él. Los pasos se encuentran en [Cómo implementar el consentimiento del paciente con SMART on FHIR](https://developers.anpheros.com/es/guides/smart-on-fhir-backend); el campo `patient` del token es el id a almacenar con su archivo.

## Paso 3: Escribir una visita como una transacción

Una visita produce varios recursos que pertenecen juntos. Envíelos en una `transaction` para que se almacenen todos a la vez o ninguno, y especifique quién está trabajando: `X-Anpheros-Acting-As` nombra el rol del médico. Se convierte en el autor en Provenance, se escribe en el registro de acceso y se muestra al paciente por nombre.

```bash
curl -X POST $BASE "${H[@]}" \
  -H "X-Anpheros-Acting-As: PractitionerRole/$ROLE" \
  -H "X-Anpheros-Author-Type: practitioner" \
  -H "X-Anpheros-Source-System: ccn-emr" -d '{
  "resourceType": "Bundle", "type": "transaction",
  "entry": [
    {"fullUrl": "urn:uuid:aa000000-0000-4000-8000-000000000001",
     "resource": {"resourceType": "Encounter", "status": "finished",
       "class": {"system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "AMB", "display": "ambulatory"},
       "subject": {"reference": "Patient/'$PID'"},
       "serviceProvider": {"reference": "Organization/'$ORG'"},
       "participant": [{"individual": {"reference": "PractitionerRole/'$ROLE'"}}],
       "period": {"start": "2026-10-09T10:00:00Z", "end": "2026-10-09T10:30:00Z"}},
     "request": {"method": "POST", "url": "Encounter"}},
    {"resource": {"resourceType": "Observation", "status": "final",
       "category": [{"coding": [{"system": "http://terminology.hl7.org/CodeSystem/observation-category", "code": "vital-signs"}]}],
       "code": {"coding": [{"system": "http://loinc.org", "code": "8867-4", "display": "Heart rate"}]},
       "subject": {"reference": "Patient/'$PID'"},
       "encounter": {"reference": "urn:uuid:aa000000-0000-4000-8000-000000000001"},
       "effectiveDateTime": "2026-10-09T10:10:00Z",
       "valueQuantity": {"value": 92, "unit": "/min", "system": "http://unitsofmeasure.org", "code": "/min"}},
     "request": {"method": "POST", "url": "Observation"}},
    {"resource": {"resourceType": "Condition",
       "subject": {"reference": "Patient/'$PID'"},
       "encounter": {"reference": "urn:uuid:aa000000-0000-4000-8000-000000000001"},
       "clinicalStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-clinical", "code": "active"}]},
       "verificationStatus": {"coding": [{"system": "http://terminology.hl7.org/CodeSystem/condition-ver-status", "code": "provisional"}]},
       "code": {"coding": [{"system": "http://hl7.org/fhir/sid/icd-10", "code": "I48.0", "display": "Paroxysmal atrial fibrillation"}]}},
     "request": {"method": "POST", "url": "Condition"}}
  ]}'
```

El `transaction-response` tiene `201 Created` para el Encounter, el Observation y el Condition. El Observation y el Condition ahora apuntan al `Encounter/0ca25459-…` real. La Provenance de cada uno nombra el rol del médico, la clínica y el sistema de origen:

```json
"agent": [{"who": {"reference": "PractitionerRole/e6d8c227-…",
                   "identifier": {"system": "https://anpheros.com/fhir/CodeSystem/author-type", "value": "practitioner"}},
           "onBehalfOf": {"reference": "Organization/c3a56a4b-…", "display": "Clinica Cardio Nord"}}],
"entity": [{"role": "source", "what": {"identifier": {"system": "ccn-emr"}}}]
```

El diagnóstico está `provisional` hasta que se confirme. Actualícelo a `confirmed` más tarde, y el historial conserva ambos. El significado de cada campo se explica en [Explicación de la procedencia de datos médicos](https://developers.anpheros.com/es/guides/medical-data-provenance).

## Paso 4: Resultados de laboratorio y documentos

Los resultados del laboratorio propio de la clínica, o los informes que trae el paciente, pasan por el conector de laboratorio en una solicitud por informe:

```bash
curl -X POST "https://platform.anpheros.com/v1/patients/$PID/labs/import" -H "Authorization: Bearer $KEY" \
     -H "Content-Type: x-application/hl7-v2+er7" -H "X-Anpheros-Source-System: ccn-lab" --data-binary @oru.hl7
```

Las cartas y los resúmenes de alta son documentos: cree un `DocumentReference` a través de `/v1/patients/{id}/documents` y cargue el PDF. El archivo original nunca se modifica, y los valores extraídos de él apuntan de vuelta a él. Consulte [Cómo importar resultados de laboratorio a un registro FHIR](https://developers.anpheros.com/es/guides/import-lab-results-fhir) y [API de datos médicos](https://developers.anpheros.com/es/guides/medical-data-api).

## Paso 5: Lea lo que otros proveedores escribieron y manténgase en su carril

Con el consentimiento del paciente, la clínica lee el registro completo dentro de sus alcances, incluyendo lo que otras clínicas, laboratorios y el paciente agregaron. Solo puede cambiar lo que escribió. Una actualización o eliminación de un recurso de otra organización responde `403`, y el original permanece como estaba. Para corregir algo que otro proveedor escribió, escriba su propio recurso (por ejemplo, un nuevo `Condition` con su evaluación) y deje que el registro muestre ambos, cada uno con su autor.

Antes de una visita, `GET $BASE/Patient/$PID/$summary` proporciona el Resumen Internacional del Paciente del registro: problemas, medicamentos, alergias y signos vitales recientes, de todas las fuentes.

## Paso 6: Recibir notificaciones de nuevos datos

Registre un webhook una vez para el proyecto de la clínica:

```bash
curl -X POST https://platform.anpheros.com/v1/webhooks -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
     -d '{"url": "https://ccn.example/anpheros/hook", "events": ["resource.created", "resource.updated", "consent.revoked"]}'
```

Cuando otro proyecto escribe en un registro al que su clínica puede acceder, el evento lo indica con `data.external: true` y la fuente, de modo que su EMR pueda mostrar "nuevos resultados de otro laboratorio" sin necesidad de sondeos. Un evento `consent.revoked` significa que la persona ha revocado el acceso de la clínica: deje de sincronizar ese registro. Las firmas, reintentos y cargas útiles se cubren en [Webhooks](https://developers.anpheros.com/es/guides/webhooks).

## Lo que ve el paciente

El paciente ve la visita, la frecuencia cardíaca y el diagnóstico provisional en su registro, cada uno marcado como añadido por la Dra. Ana Popescu en la Clínica Cardio Nord. En sus conexiones, la aplicación de la clínica enumera cada acceso, por nombre cuando un profesional estaba actuando. Esa transparencia es lo que hace que los pacientes estén dispuestos a conceder acceso a la siguiente clínica.

## Lista de verificación para la puesta en marcha

- [ ] Organización, Profesionales y Roles de Profesionales registrados; los que abandonan se establecen como inactivos
- [ ] Pacientes emparejados por el identificador de la clínica, nunca por nombre
- [ ] Registros existentes accedidos a través del consentimiento OAuth, no duplicados
- [ ] Cada solicitud del personal clínico lleva `X-Anpheros-Acting-As`
- [ ] Visitas registradas como transacciones; diagnósticos con el estado de verificación correcto
- [ ] Sistema de origen establecido en cada escritura; informes de laboratorio a través del conector
- [ ] Punto final de Webhook verificando firmas; `consent.revoked` manejado
- [ ] Proyecto de producción con un DPA firmado (claves `sk_live_…`); consulte [Precios](https://developers.anpheros.com/es/guides/pricing)

## Preguntas frecuentes

### ¿Anpheros tiene un conector prefabricado para mi EMR?
No. No existen conectores prefabricados para EMRs o sistemas de laboratorio específicos; la integración se construye contra las API REST y FHIR R4, generalmente como un pequeño servicio junto al EMR. Los mensajes de laboratorio HL7 v2 se aceptan tal cual.

### ¿Puede un médico trabajar para dos clínicas?
Sí. Un `Practitioner` puede tener un `PractitionerRole` en cada organización. El rol nombrado en `X-Anpheros-Acting-As` decide para qué clínica se registra cada escritura.

### ¿Qué sucede cuando el paciente revoca el acceso de la clínica?
Las llamadas de la clínica para ese registro responden `401`, y se envía un webhook `consent.revoked`. Lo que la clínica escribió permanece en el registro del paciente con su procedencia; la clínica simplemente ya no puede leerlo ni modificarlo.

## Relacionado

- [Integraciones de salud](https://developers.anpheros.com/es/guides/healthcare-integrations): todos los patrones de integración de un vistazo
- [Procedencia de datos médicos explicada](https://developers.anpheros.com/es/guides/medical-data-provenance)
- [Cómo implementar el consentimiento del paciente con SMART on FHIR](https://developers.anpheros.com/es/guides/smart-on-fhir-backend)
- [Cómo importar resultados de laboratorio a un registro FHIR](https://developers.anpheros.com/es/guides/import-lab-results-fhir)
- [Interoperabilidad de datos de salud](https://developers.anpheros.com/es/guides/interoperability)