# API de Salud: qué es y cómo funciona

> Qué es una API de salud, cómo funciona una llamada, qué buscar y una API de salud FHIR R4 gratuita con consentimiento del paciente, procedencia y alojamiento en la UE — con ejemplos y preguntas frecuentes.

Source: https://developers.anpheros.com/es/guides/healthcare-api

**Una API de salud es una interfaz programática a través de la cual el software lee y escribe datos de salud —registros de pacientes, observaciones, diagnósticos, medicamentos, documentos— y a través de la cual se autoriza el acceso a esos datos.** La API de la Plataforma Anpheros es una API de salud sobre un registro HL7 FHIR R4 controlado por el paciente: las aplicaciones la utilizan para almacenar y recuperar datos médicos, para obtener el consentimiento de un paciente y para ser notificadas de cambios.

<!-- visual: hapi-hero -->

## Cómo funciona una llamada a una API de salud

Independientemente del proveedor, una llamada a una API de salud pasa por los mismos puntos de control: quién llama, a qué paciente y qué datos pueden tocar, dónde se almacenan los datos, quién los escribió y quién necesita saber que han cambiado.

<!-- visual: hapi-request -->

## Tipos de APIs de salud

| Tipo | Qué intercambia | Uso típico |
|---|---|---|
| APIs REST FHIR | Recursos FHIR sobre HTTP (`GET /Observation?patient=…`) | el estándar moderno para el intercambio de datos clínicos |
| SMART on FHIR / OAuth | autorización para APIs FHIR | permitir que aplicaciones de terceros accedan a un registro con el permiso del usuario |
| Mensajería HL7 v2 | mensajes delimitados por tubería (`ORU^R01` para resultados, `ADT` para admisiones) | sistemas de laboratorio y hospitalarios, a menudo a través de interfaces en lugar de HTTP |
| Intercambio de documentos | documentos clínicos (PDF, CDA, paquetes de documentos FHIR) | resúmenes, cartas de alta, derivaciones |
| APIs REST propietarias | JSON específico del proveedor | la aplicación móvil o las integraciones de un solo producto |

Anpheros combina las dos primeras como su núcleo, acepta resultados de laboratorio HL7 v2 como entrada, almacena documentos con sus originales y produce paquetes de documentos FHIR (el Resumen Internacional del Paciente). También ofrece una API REST más simple sobre los mismos datos para desarrolladores que no desean trabajar directamente con FHIR.

## Qué buscar en una API de salud

<!-- visual:hapi-checklist:replace -->

- **Un modelo de datos estándar**, para que los datos puedan moverse entre sistemas sin mapeo personalizado.
- **Autorización que el paciente controla**, no solo credenciales que la aplicación controla.
- **Procedencia**: quién escribió cada valor, en nombre de quién, desde qué sistema.
- **Historial**: versiones en lugar de sobrescrituras silenciosas.
- **Auditoría** de lecturas, no solo de escrituras.
- **Reintentos seguros** (idempotencia) y **errores predecibles**, porque los datos de salud no deben duplicarse ni perderse.
- **Aislamiento** entre las aplicaciones que comparten la misma infraestructura.
- **Residencia de datos** que coincida con la ubicación de los pacientes.

El resto de esta página muestra cómo aparece cada uno de estos elementos en la API de Anpheros.

## La API de Anpheros de un vistazo

| Superficie | Ruta base | Propósito |
|---|---|---|
| FHIR R4 | `/fhir/R4` | 26 tipos de recursos; leer, buscar, crear, actualizar, eliminar, historial, transacciones, `$everything`, `$summary`, `$validate` |
| REST v1 | `/v1` | pacientes, observaciones, condiciones, medicamentos, documentos, línea de tiempo, procedencia, contexto de IA, importación de laboratorio, terminología, webhooks |
| OAuth 2.1 | `/oauth` | página de consentimiento, tokens (PKCE), revocación, claves de OpenID Connect |
| Lado del paciente | `/me` | los propios registros de una persona, quién tiene acceso, registro de acceso, revocar |
| Descubrimiento | `/fhir/R4/metadata`, `/fhir/R4/.well-known/smart-configuration`, `/openapi.json` | descripciones de la API legibles por máquina |

URL base: `https://platform.anpheros.com`. El entorno sandbox y producción comparten la misma URL; la clave decide el plano de datos.

### Autenticación

- **Claves de API** (`sk_test_…`, `sk_live_…`) para sus servidores; ven los pacientes que su proyecto creó.
- **Tokens de acceso OAuth** (`at_…`) para una aplicación que actúa en nombre de un paciente bajo un consentimiento.

```bash
curl https://platform.anpheros.com/v1/patients -H "Authorization: Bearer $KEY"
```

### Escritura segura

Las solicitudes `POST` aceptan un `Idempotency-Key`: una solicitud reintentada con la misma clave devuelve la respuesta original y no crea nada. Cada escritura recibe un `Provenance`; el tipo de autor se envía en el cuerpo (`author_type`) o en encabezados como `X-Anpheros-Author-Type`, `X-Anpheros-Source-System`, `X-Anpheros-Origin-Id` y `X-Anpheros-On-Behalf-Of`.

```bash
curl -X POST https://platform.anpheros.com/v1/patients/$PID/observations \
     -H "Authorization: Bearer $KEY" -H 'content-type: application/json' -H "Idempotency-Key: $(uuidgen)" \
     -d '{"code": "29463-7", "display": "Body weight", "category": "vital-signs",
          "value": 71.4, "unit": "kg", "effective_at": "2026-09-28T07:30:00Z", "author_type": "patient"}'
```

### Errores y límites

Los endpoints de FHIR responden con `OperationOutcome`; los demás con `{"error": {"type", "message", "field"}}`. Cada respuesta lleva `Anpheros-Request-Id`. El límite predeterminado es de 600 solicitudes por minuto por clave y por IP. [Errores](https://developers.anpheros.com/es/guides/errors) · [Límites](https://developers.anpheros.com/es/guides/limits)

### Eventos

Webhooks firmados para `resource.created`, `resource.updated`, `resource.deleted`, `consent.granted`, `consent.revoked`, `document.finalized` y `ping`. [Webhooks](https://developers.anpheros.com/es/guides/webhooks)

## Elección entre FHIR y REST v1

Utilice **FHIR** si ya trabaja con FHIR, necesita tipos de recursos que `/v1` no cubre (por ejemplo, `Immunization`, `Procedure` o `CarePlan`), o intercambia datos con otros sistemas FHIR. Utilice **REST v1** para código de aplicación que desee JSON plano para los casos comunes. Ambos leen y escriben los mismos recursos con los mismos IDs, por lo que un proyecto puede mezclarlos. [API de datos médicos](https://developers.anpheros.com/es/guides/medical-data-api) describe las operaciones de datos en detalle.

## Preguntas frecuentes

### ¿Qué es una API de salud?
Una interfaz programática a través de la cual el software lee y escribe datos de salud —registros de pacientes, observaciones, diagnósticos, medicamentos y documentos— y a través de la cual se autoriza el acceso a esos datos. Las API de salud modernas utilizan HL7 FHIR R4 para los datos y OAuth 2.0 o 2.1 con SMART on FHIR para la autorización.

### ¿Cuál es la diferencia entre una API de salud y una API FHIR?
FHIR es un estándar que una API de salud puede seguir. Una API FHIR intercambia recursos FHIR sobre REST; una API de salud también puede aceptar mensajes HL7 v2, documentos o JSON propietario. Anpheros ofrece una API FHIR R4 y una API REST más sencilla sobre los mismos datos.

### ¿Existe una API de salud gratuita para desarrolladores?
Sí. El sandbox de Anpheros es gratuito y de autoservicio: inicie sesión con Google, obtenga una clave de API y trabaje con 30 pacientes sintéticos sobre FHIR R4 o REST. La producción comienza en 99 € al mes, con el primer mes gratis.

### ¿Cómo dan los pacientes su consentimiento a una API de salud?
A través de OAuth 2.1 con PKCE: la aplicación envía a la persona a una página de consentimiento con ámbitos SMART on FHIR; la persona elige qué compartir y durante cuánto tiempo, puede ver un registro de acceso y puede revocar el acceso en cualquier momento.

### ¿Dónde se almacenan los datos?
En la Unión Europea: el servicio y sus bases de datos se ejecutan en Google Cloud `europe-west4` (Países Bajos).

### ¿Qué API de salud debo elegir?
Compare el estándar de datos, quién autoriza el acceso, la procedencia y la auditoría, la residencia de los datos, cómo se comportan los reintentos y los errores, y si puede probar con datos realistas de forma gratuita. [Plataforma de API de salud: qué incluye y cómo elegir](https://developers.anpheros.com/es/guides/healthcare-api-platform) convierte estos puntos en preguntas para cualquier proveedor.

<!-- visual:cta-hapi -->

## Relacionado

- [API de EHR y API de registros médicos](https://developers.anpheros.com/es/guides/ehr-api)
- [Plataforma de API de salud: qué incluye y cómo elegir](https://developers.anpheros.com/es/guides/healthcare-api-platform)
- [Cómo crear una API de salud con TypeScript](https://developers.anpheros.com/es/guides/healthcare-api-typescript): tutorial paso a paso con Express
- [Cómo almacenar registros médicos usando FHIR R4](https://developers.anpheros.com/es/guides/store-medical-records-fhir): tutorial paso a paso con curl
- [API de salud con consentimiento del paciente](https://developers.anpheros.com/es/guides/healthcare-api-patient-consent)
- [Backend de SMART on FHIR](https://developers.anpheros.com/es/guides/smart-on-fhir-backend)
- [API de datos médicos](https://developers.anpheros.com/es/guides/medical-data-api)
- [Plataforma FHIR](https://developers.anpheros.com/es/guides/fhir)
- [Interoperabilidad de datos de salud](https://developers.anpheros.com/es/guides/interoperability)
- [Integraciones de salud](https://developers.anpheros.com/es/guides/healthcare-integrations)
- [Referencia de API (OpenAPI)](https://developers.anpheros.com/docs) · [Autenticación y OAuth](https://developers.anpheros.com/es/guides/authentication)