API para desarrolladores

Qué es esto

La API pública de NormaLis permite que un sistema externo (Hosvital, Greenlane, SAP Salud, o un desarrollo propio de la IPS) reporte incidentes y eventos adversos directamente en NormaLis, sin que el personal clínico tenga que abrir una segunda plataforma. También expone, sin necesidad de autenticación, el checklist de requisitos de habilitación vigentes bajo la Res. 3100/2019 (incluyendo los que en su momento propuso la ahora revocada Resolución 1732 de 2026).

Está pensada para ser consumida servidor-a-servidor desde el backend de tu HCE, no desde el navegador del usuario final.

Base URL

https://normalis.fjfc1984.workers.dev

Autenticación

Los endpoints de escritura requieren una llave API, generada desde NormaLis → Integraciones API por el administrador de la IPS. Envíala en el header Authorization con el esquema Bearer:

Authorization: Bearer nlk_live_...

La llave se muestra una única vez al crearla — NormaLis solo guarda su hash y no puede recuperar el valor original. Si se pierde, hay que revocarla y generar una nueva.

GET /api/v1/checklist-1732

Devuelve el checklist de requisitos que en su momento propuso la Resolución 1732/2026 — revocada en su totalidad por la Res. 002080/2026 antes de entrar en vigencia (ver aviso en la respuesta). Los ítems con vigente: false no son exigibles hoy; solo la Res. 3100/2019 está vigente. No requiere autenticación — es contenido normativo, no datos de paciente.

Parámetros de consulta (opcionales)

• categoria — filtra por texto contenido en la categoría (ej. telemedicina)
• esNuevo — true para requisitos nuevos frente a la Res. 3100/2019, false para los que continúan vigentes

Ejemplo

curl "https://normalis.fjfc1984.workers.dev/api/v1/checklist-1732?esNuevo=true"

Respuesta

{
  "count": 12,
  "items": [
    {
      "id": "ihce_01",
      "categoria": "IHCE — Historia Clínica Electrónica Interoperable",
      "titulo": "Sistema de HC con capacidad de interoperabilidad",
      "descripcion": "...",
      "esNuevo": true,
      "urgencia": "alta",
      "plazo": "Diciembre 2026 (plan de adecuación progresiva)",
      "guia": "..."
    }
  ]
}

Límite: 30 solicitudes por minuto por IP.

POST /api/v1/incidentes

Registra un incidente o evento adverso en el módulo de Seguridad del Paciente de la IPS dueña de la llave. Requiere autenticación. La IPS de la llave debe tener su NIT registrado en NormaLis (si no, responde 409): los eventos se guardan por NIT para que los vea todo su equipo.

No envíes datos del paciente (nombre, documento, teléfono, correo). NormaLis no los guarda: si el texto trae números que parecen un documento o un teléfono, se omiten y la respuesta lo avisa.

Cuerpo de la solicitud

{
  "tipo": "Evento adverso",
  "severidad": "moderado",
  "desc": "Caída de paciente en habitación 204",
  "accion": "Se informó al médico de turno",
  "responsable": "Enfermera Jefe",
  "tipoEvento": "caida",
  "ambito": "hospitalizacion",
  "servicio": "Piso 2",
  "fechaHoraEvento": "2026-09-21T14:30:00-05:00"
}

Campos

Respuesta exitosa — 201

{ "ok": true, "id": "aB3xY9...", "consecutivo": "SEG-20260921-3XY9A" }

El evento queda registrado sin clasificar y visible en el módulo de Incidentes de la IPS con origen "sistema externo": la persona a cargo de la seguridad del paciente decide si fue un incidente o un evento adverso, el daño al paciente y si es un evento centinela. Por eso tipo y severidad se conservan solo como referencia en el historial. Un tipo de Accidente de trabajo se acepta, pero corresponde al SG-SST. Si se omitió algún número que parecía un identificador, la respuesta incluye avisos.

Límite: 60 solicitudes por minuto por llave.

POST /api/v1/ihce-eventos

Registra un evento de la bitácora de transmisiones IHCE/RDA de la IPS dueña de la llave. Requiere autenticación.

NormaLis no genera ni transmite el Bundle FHIR del RDA — eso sigue siendo responsabilidad de tu sistema de historia clínica. Este endpoint solo guarda la evidencia de que una transmisión ocurrió (folio, tipo de encuentro, estado), para la bitácora de cumplimiento de interoperabilidad de la IPS (Ley 2015/2020 · Res. 866/2021 · Res. 1888/2025).

Cuerpo de la solicitud

{
  "bundleId": "RDA-2026-000123",
  "encuentroTipo": "ambulatorio",
  "pacienteRef": "<id interno del HCE>",
  "estadoTransmision": "confirmado",
  "detalle": "",
  "fechaTransmision": "2026-09-06T14:30:00-05:00"
}

Campos

Respuesta exitosa — 201

{ "ok": true, "id": "aB3xY9..." }

El evento queda visible en la bitácora del módulo Historia Clínica de la IPS, con la etiqueta "HCE externo (API)".

Límite: 60 solicitudes por minuto por llave.

POST /api/v1/indicadores

Envía el numerador y el denominador de un indicador oficial de calidad (Res. 256/2016, Anexo técnico 1) en un trimestre. Requiere autenticación. Sirve para los 23 indicadores que la IPS reporta por PISIS: P.2.6 a P.2.12, P.2.15 y P.3.1 a P.3.15 (por ejemplo, la suma de los días de espera y el número de citas de P.3.1, o los egresos de P.2.10).

NormaLis no guarda esto como una medición ni lo verifica: lo guarda como un dato recibido y se lo sugiere a la persona de la IPS cuando registra ese indicador («Sugerido desde tu sistema»); ella lo confirma o lo corrige. Envía solo totales: nunca filas, nombres, documentos ni teléfonos (el servidor rechaza un sistema o una nota que parezca un número de documento o de teléfono).

Cuerpo de la solicitud — varios indicadores

{
  "periodo": "2026-Q3",
  "sistema": "Mi sistema de agenda",
  "nota": "corte del 5 de octubre",
  "indicadores": [
    { "indicador": "P.3.1", "numerador": 130, "denominador": 20 },
    { "indicador": "P.2.6", "numerador": 3, "denominador": 1200 }
  ]
}

También puedes enviar un solo indicador: { "indicador": "P.3.1", "periodo": "2026-Q3", "numerador": 130, "denominador": 20 }.

Campos

Respuesta exitosa — 200

{
  "ok": true,
  "periodo": "2026-Q3",
  "recibidos": [
    { "indicador": "P.3.1", "id": "P_3_1__2026-Q3" },
    { "indicador": "P.2.6", "id": "P_2_6__2026-Q3" }
  ]
}

Un reenvío del mismo indicador y trimestre reemplaza el dato anterior (así se corrige un envío). En los indicadores que son un porcentaje (P.2.15, P.3.14 y P.3.15), un numerador mayor que el denominador se acepta pero la respuesta trae avisos. Los datos recibidos se ven en la pantalla Integraciones de la IPS.

Límite: 60 solicitudes por minuto por llave; hasta 25 indicadores por solicitud.

Códigos de error

Estado de esta API

Esta es la versión 1 (v1) de la API pública de NormaLis, orientada a un primer caso de uso: reporte de incidentes desde sistemas externos. Estamos evaluando expandirla con más módulos (vencimientos, consulta de auditorías) según la demanda de integración de cada IPS. Si tu equipo técnico necesita un endpoint adicional, escríbenos.