API REST y FHIR R4 para integrar sistemas externos con los flujos clínicos de Abigail. Todo lo que ve aquí se genera desde el código, por lo que siempre coincide con el comportamiento real.
Responde sobre esta API usando solo la documentación. No escriba datos de pacientes, contraseñas ni llaves reales: se descartan automáticamente.
Se retiraron de su pregunta datos que parecían sensibles.
abi_test_… para pruebas y abi_live_… para producción.curl https://abigail.nfinnovations.com/api/v1/pingcurl https://abigail.nfinnovations.com/api/v1/patients?per_page=5 \
-H "X-API-Key: abi_test_SU_LLAVE" \
-H "Accept: application/json"¿Prefiere un cliente gráfico? Descargue la colección Postman o explore la referencia interactiva.
Hay dos formas, según quién llama:
| Método | Cabecera | Úselo para |
|---|---|---|
| Llave de API | X-API-Key: abi_live_… | Integraciones entre sistemas (servidor a servidor). Queda fija a una clínica. |
| Token personal | Authorization: Bearer … | Apps de personal clínico. Se obtiene con usuario y contraseña. |
curl -X POST https://abigail.nfinnovations.com/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"email":"medico@clinica.com","password":"••••••••••••","device_name":"mi-app","abilities":["patients:read"]}'Seguridad: tras 5 intentos fallidos la cuenta queda bloqueada 15 minutos (desde esa IP). Los tokens caducan; nunca se emiten con permisos totales (*) y no pueden superar los de su rol. Guarde las llaves en un gestor de secretos, nunca en el código ni en el repositorio.
El token recibe los permisos que solicite, siempre que su rol los tenga. Sin abilities recibe todos los de su rol.
| Permiso | Qué permite | super_admin_system | admin_clinica | doctor | enfermero | secretaria | laboratorio | bodega_farmacia | paciente | developer |
|---|---|---|---|---|---|---|---|---|---|---|
| catalogs:read | Consultar catálogos clínicos | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | — |
| patients:read | Consultar pacientes | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | — | — |
| interoperability:read | Consultar FHIR/HL7 | ✓ | ✓ | ✓ | — | — | — | — | — | — |
| interoperability:write | Enviar/ingerir FHIR/HL7 | ✓ | ✓ | — | — | — | — | — | — | — |
| medical-records:read | Leer el expediente: consultas, diagnósticos y tratamientos | ✓ | ✓ | ✓ | ✓ | — | — | — | — | — |
| prescriptions:read | Leer prescripciones médicas | ✓ | ✓ | ✓ | ✓ | — | — | — | — | — |
| recipes:read | Leer recetas emitidas | ✓ | ✓ | ✓ | ✓ | — | — | ✓ | — | — |
| recipes:write | Emitir la receta de una consulta (médico tratante) | ✓ | — | ✓ | — | — | — | — | — | — |
| recipes:dispense | Registrar la dispensación de una receta | ✓ | — | — | — | — | — | ✓ | — | — |
| practitioners:read | Consultar profesionales de la clínica | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | — | — |
| patients:write | Registrar pacientes | ✓ | ✓ | — | — | ✓ | — | — | — | — |
| consents:write | Registrar o retirar el consentimiento del paciente (solo personal de la clínica) | ✓ | ✓ | ✓ | — | ✓ | — | — | — | — |
| encounters:write | Registrar consultas con diagnóstico y prescripción (requiere profesional responsable) | ✓ | — | ✓ | — | — | — | — | — | — |
| appointments:read | Consultar la agenda y la disponibilidad | ✓ | ✓ | ✓ | ✓ | ✓ | — | — | — | — |
| appointments:write | Agendar turnos y cambiar su estado | ✓ | ✓ | — | — | ✓ | — | — | — | — |
Cada petición opera sobre una sola clínica; nunca se mezclan datos de varias. Una llave de API queda fija a la clínica con la que se emitió (si no tiene clínica asignada, no devuelve datos). Un token de usuario con varias clínicas indica cuál usar con X-Clinic-ID: 12. Pedir un recurso de otra clínica responde 404, igual que si no existiera.
// Éxito
{ "success": true, "message": "OK", "data": { ... } }
// Error
{ "success": false, "message": "Datos inválidos.", "errors": { "email": ["El campo email es obligatorio."] }, "request_id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" }Fechas en ISO-8601. Los textos de mensaje están en español. Excepción: los endpoints FHIR devuelven recursos y OperationOutcome estándar (application/fhir+json).
Los listados aceptan ?page=1&per_page=25 (máximo 100) y devuelven meta.page, meta.per_page y meta.total. Itere hasta que page × per_page ≥ total.
| Código | Causa habitual | Qué hacer |
|---|---|---|
| 401 | Llave o token ausente, inválido, expirado o revocado | Verifique la cabecera; renueve el token o pida una llave nueva. |
| 403 | Falta un permiso (abilities), rol insuficiente o política de acceso a datos clínicos | El mensaje indica el permiso. Pida al administrador que lo habilite. |
| 404 | El recurso no existe o pertenece a otra clínica | Revise el identificador y la clínica (X-Clinic-ID). |
| 422 | Datos inválidos | Lea errors: indica cada campo y la razón. |
| 429 | Límite de peticiones o bloqueo por intentos fallidos | Espere lo indicado en Retry-After y reintente con espera creciente. |
| 5xx | Error del servidor | Reintente; si persiste, contacte soporte con el X-Request-Id. |
Si una escritura (POST, PUT, PATCH, DELETE) se corta por red o tiempo de espera, reintentarla podría duplicar la consulta, receta o reclamo. Envíe una clave única por operación y el reintento devolverá la respuesta original:
curl -X POST https://abigail.nfinnovations.com/api/v1/emergency/form-008 \
-H "X-API-Key: abi_test_SU_LLAVE" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "Content-Type: application/json" -d '{ ... }'Idempotency-Key y mismo cuerpo → misma respuesta, con la cabecera Idempotent-Replayed: true.422. Aún en proceso → 409 con Retry-After.Cada llave tiene un límite de peticiones por minuto y una cuota mensual según su plan. Al superarlo recibe 429 con las cabeceras Retry-After, X-RateLimit-Limit y X-RateLimit-Remaining. Consulte su plan y consumo en API Management.
Los datos de pacientes son información de salud protegida. Cada acceso exitoso queda registrado (quién, desde dónde, qué ruta, qué clínica). Los endpoints que exponen historia clínica están sujetos a la política de acceso de la clínica (consentimiento, justificación o 2FA según su configuración). No almacene ni registre en logs datos clínicos que no necesite, y use siempre HTTPS.
GET /api/v1/ips/patient/{id}La versión mayor va en la URL (/api/v1). Dentro de una versión solo se añaden campos y endpoints (compatibles). Un cambio incompatible se publica como /v2, y la versión anterior se mantiene al menos 6 meses con aviso previo. Un endpoint en retirada responde con las cabeceras Deprecation: true y Sunset: <fecha> (más un enlace rel="deprecation") y aparece como deprecated en el contrato OpenAPI: monitoree esas cabeceras en su cliente.
Idempotency-Key en las escrituras: un reintento con la misma clave no duplica la operación.Deprecation y Sunset y se marcan deprecated en el contrato.*: cada token recibe un subconjunto de los permisos de su rol.api_clients.clinic_id); sin clínica asignada no devuelven datos.X-Request-Id; los errores incluyen request_id.X-Clinic-ID, Idempotency-Key, reintentos con Retry-After y un error con el X-Request-Id.Escriba a soporte@abigailsoft.com e incluya el valor de X-Request-Id de la petición con problemas: con él localizamos el caso exacto sin pedirle datos del paciente.