eMedic Platform — Referencia de la API (1.2.0)

Crea una receta en la plataforma y la hace disponible para la red de farmacias. Pensado para clínicas y sistemas emisores (también lo usa internamente la ingesta por email una vez validada por un humano).

Requiere scope prescriptions:write.

• Farmacias (prescriptions:read): requiere patientIdentityNumber (el paciente presenta su documento en mostrador). Devuelve solo recetas dispensables (active o partially_dispensed) salvo que se filtre por estado.
• Clínicas (prescriptions:write): lista las recetas emitidas por la propia organización; patientIdentityNumber es opcional.

Incluye el estado de dispensación por línea (cantidades dispensadas/restantes y en qué farmacia/sucursal). Requiere prescriptions:read, o prescriptions:write si la consulta la clínica emisora.

Solo la clínica emisora (prescriptions:write). No se puede anular una receta con dispensaciones registradas (PRESCRIPTION_HAS_DISPENSATIONS); las líneas aún no dispensadas quedan bloqueadas al anular.

Devuelve el documento original tal como lo emitió el médico (PDF o imagen), cuando la receta entró por ingesta. Es el documento autoritativo: el farmacéutico dispensa mirándolo. Los datos estructurados de la receta son una extracción derivada, útil para cargar el sistema de la farmacia sin tipeo, pero no reemplazan al documento — ante discrepancia, manda el documento.

Acceso:

• Clínica emisora: solo el de sus propias recetas.
• Farmacia: mientras la receta sea dispensable (active o partially_dispensed), o siempre que esa misma farmacia haya registrado una dispensación sobre ella (para su respaldo posterior).

Devuelve 404 si la receta se emitió por API nativa o por adaptador, porque en ese caso no existe documento original: la receta es el dato estructurado.

Registra la entrega de una o más líneas de la receta por una farmacia. Soporta dispensación parcial: por línea se indica la cantidad entregada, que no puede exceder la restante (QUANTITY_EXCEEDS_REMAINING). Distintas líneas (o el resto de una línea) pueden dispensarse después en otra farmacia o sucursal.

Requiere scope dispensations:write. La operación es atómica: si alguna línea falla la validación, no se registra nada.

Se envía a farmacias suscritas cuando una receta entra en estado active. Todas las entregas de webhooks incluyen los headers:

• X-Emedic-Event: tipo de evento.
• X-Emedic-Delivery: ID único de la entrega (para deduplicar reintentos).
• X-Emedic-Timestamp: epoch en segundos.
• X-Emedic-Signature: v1= + HMAC-SHA256 hex de "{timestamp}.{cuerpo}" con el secret del endpoint. Rechazar si la firma no coincide o el timestamp tiene más de 5 minutos.

Entregas con reintento y backoff exponencial durante 24 h ante respuestas no 2xx.

Se envía a la clínica emisora cada vez que una farmacia registra una dispensación.

Evento DIRIGIDO a cada clínica que ya le emitió una receta a ese paciente: nadie se entera de un paciente que no atendió. El paciente verifica el dato nuevo antes de que se propague (código de un solo uso al número nuevo), así que lo que llega acá ya está confirmado. El evento no lleva nada clínico: solo cédula y contacto.

data: { patient: { identityType, identityNumber, phone?, email? }, updatedAt }.

Se envía a la aseguradora dueña del padrón con cada intento (verde o rojo). La familia completa: identity.enrollment.completed, identity.enrollment.revoked, identity.verification.completed y identity.exception.recorded — todos con la misma forma de entrega y firma que el resto de los webhooks. Nunca llevan datos clínicos: cédula, resultado, código y quién operó.

La familia de órdenes, toda dirigida y con la misma entrega firmada:

• order.issued y order.item.review → a la aseguradora (lo emitido contra ella y lo que espera a su auditor).
• order.item.authorized / order.item.rejected (con motivo), order.fulfilled y result.available → al emisor, al instante. Ningún evento lleva el contenido clínico del resultado: avisan que está disponible y se lee por la API con la credencial propia.

El laboratorio cargó el resultado: el médico tratante se entera al instante y el paciente lo ve en su app a la par (y recibe un aviso SMS sin datos clínicos si tiene cuenta). El evento solo referencia (orderId, itemId, studyCode, abnormal, y — si la orden los trajo — practitionerLicense y externalReference para rutear a la bandeja del médico en tu sistema) — el contenido clínico se lee por GET /orders con la credencial del emisor. La marca abnormal permite priorizar sin esperar la lectura.

Representa a toda la familia de eventos de agendamiento — appointment.booked, appointment.confirmed, appointment.cancelled, appointment.completed y appointment.no_show — todos con el mismo payload y SIEMPRE dirigidos a la clínica dueña de la agenda: así su sistema (HIS, calendario, recordatorios) se sincroniza sin consultar. El data lleva solo appointmentId, practitionerLicense, patientIdentityNumber, startAt, endAt y status — el motivo de consulta y las notas jamás viajan por webhook.

Representa a transcription.completed y transcription.failed, SIEMPRE dirigidos a la clínica dueña y SIN contenido clínico: el data lleva solo transcriptionId, status, durationSeconds y — si se mandaron — practitionerLicense y externalReference para rutear a la bandeja del médico en tu sistema. La nota se lee por GET /transcriptions/{id} con tu credencial.

Representa a imaging.completed e imaging.failed, SIEMPRE dirigidos a la organización dueña y SIN contenido clínico: el data lleva analysisId, status, modality, la urgency sugerida (para priorizar la bandeja del médico sin exponer hallazgos) y — si se mandaron — practitionerLicense y externalReference. El informe se lee por GET /imaging/analyses/{id} con tu credencial.

Registra una URL HTTPS de la organización para recibir eventos. La respuesta incluye el secret (solo se muestra una vez) con el que se firma cada entrega. Requiere scope webhooks:manage.

Lista los formatos de origen que la plataforma sabe interpretar. Cada entrada identifica un adaptador (id) que traduce el modelo del sistema emisor al modelo canónico de eMedic.

El formato del emisor no es su problema, es el nuestro. El hospital envía la receta tal como la produce su sistema (FHIR R4, el modelo del eMedic original, o el que se le construya) y la plataforma la transforma al modelo canónico.

La puerta final es invariable: el resultado de la transformación se valida contra el mismo schema que POST /prescriptions. Un adaptador nunca puede colar una receta que la API nativa rechazaría. Si la transformación falla o el resultado no valida, la respuesta es 400 VALIDATION_ERROR con details señalando el campo de origen.

El cuerpo es libre: su forma la define el adaptador elegido, no este contrato. Solo organizaciones emisoras; una farmacia recibe 403.

El registro de remitentes es la identidad del médico en la ingesta por correo: la plataforma no puede validar a un desconocido, así que solo acepta recetas de direcciones dadas de alta por la propia clínica. Lo que el registro dice sobre el médico (nombre, matrícula) tiene prioridad sobre lo que la extracción lea del documento.

Baja lógica: el remitente deja de poder emitir, pero las recetas que ya envió conservan su trazabilidad.

Entrada para recetas que no vienen de una integración: el médico manda un PDF por correo y la clínica (o su gateway de correo) lo deposita aquí.

Puertas de confianza, en orden:

1. Origen email con senderVerified: false — si el gateway no pudo validar DKIM/SPF/DMARC, el ítem entra pero nunca se auto-aprueba: un correo falsificable no puede emitir recetas a nombre de un médico.
2. Remitente no registrado — sin alta previa (POST /intake/senders) no hay médico identificable, así que tampoco hay auto-aprobación.
3. Documento adjunto — la auto-aprobación exige el original: es lo que el farmacéutico va a mirar para dispensar.

La extracción estructurada corre en segundo plano; cuando pasa las puertas, la receta se emite sola y prescriptionId queda apuntando a ella. Cuando no, el ítem se devuelve al médico por correo (rebote) explicando qué corregir — nunca queda esperando revisión humana de eMedic.