Endpoint
Headers de request
El body es el recurso FHIR R4 crudo. No se envuelve en
resource, Parameters
ni OperationOutcome.
Respuesta compatible
Inspect conservaValidateResponse como contrato público. Un recurso válido
responde 200 y uno inválido responde 422; ambos usan el mismo shape.
issues[] agrega, cuando corresponde, why, profileUrl, docsUrl,
suggestion, example, entryIndex y un quickFix con jsonPointer RFC
6901. engineDegraded: true indica que el motor remoto no completó la
validación; esa llamada no descuenta cuota.
Fhiron-Request-ID devuelve el UUID efectivo. Si el cliente no envía
Idempotency-Key, Fhiron genera uno; para que un retry sea idempotente el
cliente debe generar y conservar el UUID antes del primer intento.
Códigos HTTP
Los
5xx son fallas de infraestructura, no evidencia de que el recurso sea
válido o inválido. Reintenta con backoff y un máximo acotado de intentos,
conservando la misma Idempotency-Key para el mismo body, perfil y versión.
Cuota mensual y ráfaga
Las respuestas200 y 422 separan dos límites distintos:
Un plan sin tope devuelve
unlimited en los dos headers mensuales de límite y
remanente. Un 429 por ráfaga incluye Retry-After; un 429 por cuota incluye
los headers Fhiron-Quota-*. El remanente puede ser mayor que cero si un Bundle
necesita mas unidades que las disponibles; en ese caso no hay consumo parcial.
Tras un downgrade o fin de trial, el contador histórico puede superar el nuevo
límite: la API responde 429 con remanente cero, sin convertirlo en un 503.
Cuando engineDegraded: true, PostgreSQL no decide consumo y la respuesta omite
todos los headers Fhiron-Quota-*; nunca estima un remanente desde el plan.
Efectos operacionales
Inspect no persiste el body clínico recibido. Una validación procesada sí:- consume una unidad para un recurso individual y una por cada
Bundle.entry(minimo 1, maximo 200 por request); - registra metadatos del resultado y duración, sin el body;
- puede disparar el webhook configurado y la alerta de uso del tenant.
validations_log se confirman en una sola transacción. El UUID queda
asociado a un fingerprint HMAC opaco, no al body. Un replay con la misma clave y
request devuelve el snapshot de cuota original y no vuelve a cobrar, registrar
ni emitir validation.complete; la ruta vuelve a validar en HAPI y no cachea ni
reproduce el body HTTP. El webhook incluye validation_request_id para
correlación, sin persistir errores o warnings en el outbox. Usar esa clave con
otro request responde 409.
Las alertas del 80% usan un outbox sin PII y solo se marcan enviadas después del
ACK del proveedor; el cron autenticado reintenta un batch acotado.
Contrato descargable
OpenAPI 3.1
Fuente canónica de las rutas públicas implementadas.
Colección Postman
Generada desde OpenAPI, sin API keys ni datos clínicos reales.
Fixtures sintéticos
Patient de ejemplo; también hay un fixture inválido.
VS Code REST Client
Requests reproducibles usando
FHIRON_API_KEY desde el entorno.