# API de datos médicos

> Dónde va cada tipo de dato médico en la API de Anpheros, cómo se codifica y cómo escribirlo, filtrarlo, rastrearlo, corregirlo y eliminarlo — con ejemplos funcionales.

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

**Una API de datos médicos proporciona a los programas acceso estructurado al contenido de los registros de pacientes: crear un paciente, registrar una lectura de presión arterial, listar medicamentos activos, adjuntar un informe de laboratorio, rastrear quién escribió qué.** Esta página describe las operaciones de datos de la API de Anpheros — qué tipo de dato médico va a dónde, cómo se codifica y cómo leerlo — con ejemplos que funcionan contra el sandbox.

Las aplicaciones utilizan estas operaciones para tratar Anpheros como la base de datos médica de su producto: los registros de pacientes residen en el almacén HL7 FHIR R4 de la plataforma, y la aplicación los lee y escribe a través de la API en lugar de mantener sus propias tablas de datos médicos.

Para una visión más amplia (autenticación, consentimiento, eventos), consulte [API de Salud](https://developers.anpheros.com/es/guides/healthcare-api).

## Dónde va cada tipo de dato médico

| Dato médico | REST v1 | Recurso FHIR | Codificación |
|---|---|---|---|
| La persona | `POST /v1/patients` | `Patient` | nombre, fecha de nacimiento, género, identificadores |
| Signos vitales, resultados de laboratorio, síntomas, actividad, encuestas | `/v1/patients/{id}/observations` | `Observation` | LOINC (síntomas: capítulo R de ICD-10); unidades UCUM |
| Diagnósticos y problemas | `/v1/patients/{id}/conditions` | `Condition` | ICD-10 |
| Medicamentos | `/v1/patients/{id}/medications` | `MedicationStatement` | ATC, nombre del producto conservado como texto |
| Documentos (PDF, imágenes) | `/v1/patients/{id}/documents` | `DocumentReference` | Tipos de documentos LOINC |
| Un informe de laboratorio completo | `POST /v1/patients/{id}/labs/import` | `Observation` (laboratory) | LOINC cuando se conoce, el código propio del laboratorio en caso contrario |
| Dosis tomadas u omitidas, vacunaciones, alergias, procedimientos, informes, planes de atención, objetivos, referencias, visitas, citas, equipos de atención, historial familiar, cuestionarios | `/fhir/R4/{type}` | `MedicationAdministration`, `Immunization`, `AllergyIntolerance`, `Procedure`, `DiagnosticReport`, `CarePlan`, `Goal`, `ServiceRequest`, `Encounter`, `Appointment`, `CareTeam`, `FamilyMemberHistory`, `QuestionnaireResponse` | por [sistemas de códigos FHIR](https://developers.anpheros.com/es/guides/fhir-code-systems) |

Los objetos REST v1 y los recursos FHIR son los mismos registros con los mismos IDs; cada objeto v1 lleva su referencia `fhir`.

## Escribiendo datos médicos

```bash
# a lab result with its reference range, linked to the report it came from
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": "4548-4", "display": "Hemoglobin A1c", "category": "laboratory",
  "value": 6.4, "unit": "%", "effective_at": "2026-09-01T08:00:00Z",
  "reference_range": {"low": 4.0, "high": 5.6},
  "derived_from": ["DocumentReference/'$DOC'"], "author_type": "import"
}'
```

- **Categorías de observación:** `vital-signs`, `laboratory`, `symptom`, `activity`, `survey`, `exam`, `imaging`, `social-history`.
- **Mediciones compuestas**, como la presión arterial, utilizan `components` (sistólica `8480-6`, diastólica `8462-4` dentro del panel `85354-9`).
- **Tipos de autor:** `patient`, `practitioner`, `device`, `import`, `ai`. Sin uno, la plataforma registra `import`.
- **Códigos que no se sabe de memoria:** `GET /v1/terminology/loinc?q=hba1c` busca el subconjunto LOINC incluido y `GET /v1/search?q=metformin` el catálogo de síntomas, afecciones y medicamentos; una observación escrita sin un nombre de visualización obtiene automáticamente el nombre LOINC.

## Lectura de datos médicos

```bash
curl "https://platform.anpheros.com/v1/patients/$PID/observations?category=laboratory&code=4548-4&from=2026-01-01" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/conditions?clinical_status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/medications?status=active" -H "Authorization: Bearer $KEY"
curl "https://platform.anpheros.com/v1/patients/$PID/timeline?from=2026-06-01" -H "Authorization: Bearer $KEY"
```

| Endpoint | Filtros |
|---|---|
| observations | `category`, `code`, `from`, `to` |
| conditions | `clinical_status` |
| medications | `status` |
| documents | `kind` |
| timeline | `from`, `to`, `types` |

Las listas se paginan con `limit` y `cursor`. La **timeline** fusiona observaciones, condiciones, medicamentos, documentos, visitas, citas, vacunaciones y episodios de atención en una lista cronológica — la entrada natural para una pantalla de historial del paciente.

Para cualquier cosa que los filtros REST no cubran, utilice la búsqueda FHIR: `GET /fhir/R4/Observation?patient=$PID&code=http://loinc.org|4548-4&_sort=-date` ([plataforma FHIR](https://developers.anpheros.com/es/guides/fhir)).

## Trazabilidad y corrección de datos

- **Quién lo escribió:** `GET /v1/patients/{id}/provenance/{type}/{resourceId}` — una entrada por versión, con tipo de autor, proyecto, organización y sistema de origen.
- **Cada versión:** `GET /fhir/R4/{type}/{id}/_history`; actualiza con `If-Match` para evitar sobrescribir el cambio de otra persona.
- **Propiedad:** con consentimiento puedes leer lo que otras organizaciones escribieron, pero cambia o elimina solo lo que tu proyecto escribió (`403` de lo contrario).
- **Eliminación:** `DELETE /v1/{observations|conditions|medications}/{id}`; eliminar un `Patient` elimina el registro completo.

## Documentos

Cree el documento (obtendrá un destino de carga), cargue los bytes a través de la plataforma o directamente al almacenamiento, y luego finalícelo. Después de la finalización, el original es inmutable; se registran su SHA-256 y tamaño. Hasta 25 MiB por archivo.

## Relacionado

- [Cómo normalizar datos médicos](https://developers.anpheros.com/es/guides/normalize-medical-data): códigos, unidades, fechas, duplicados, validación
- [Procedencia de datos médicos explicada](https://developers.anpheros.com/es/guides/medical-data-provenance): quién escribió qué y cómo registrarlo
- [API de salud](https://developers.anpheros.com/es/guides/healthcare-api)
- [Historial médico del paciente](https://developers.anpheros.com/es/guides/patient-medical-record)
- [Crear una aplicación de salud](https://developers.anpheros.com/es/guides/build-a-healthcare-app)
- [Referencia de la API (OpenAPI)](https://developers.anpheros.com/docs) · [Primeros pasos](https://developers.anpheros.com/es/guides/getting-started)