API SATI-Q · Contrato V2026. Esta página se genera a partir del cuestionario publicado: siempre refleja lo que el servidor exige hoy.

Enviar episodios a SATI-Q

Cómo conectar el sistema informático de un centro para que envíe sus episodios de UCI de forma automática, usando FHIR R4.

Introducción

Esta guía es para el equipo de desarrollo del sistema de un centro que participa del programa. Se asume experiencia con APIs REST y JSON; no hace falta conocer FHIR.

Qué se envía

Un episodio de internación en UCI ya finalizado, con el conjunto mínimo de datos del EDS: identificación interna del paciente, fechas de ingreso y egreso, datos demográficos, motivo y procedencia, score de gravedad, dispositivos con sus días, complicaciones y resultado al egreso.

No se envían datos identificatorios del paciente. El identificador que viaja es el número interno con el que el centro lo reconoce en su propio sistema.

Qué no hace todavía la API

• No permite buscar ni listar: sólo leer uno puntual por su identificador, que hay que conocer de antemano.
• No permite enviar varios episodios en un mismo pedido.

Direcciones

Obtener credenciales

Las genera el propio centro desde el formulario web de SATI-Q, en la opción Conexión con mi sistema del menú. No hay que pedirlas a nadie: quien tiene el usuario del centro las genera y las entrega al equipo de desarrollo.

Se obtienen dos valores: un client_id, que identifica al cliente, y un client_secret, que es la clave.

Cada credencial queda atada a un centro. El servidor determina a qué centro corresponde cada episodio a partir de las credenciales, no de un campo del envío: un cliente no puede cargar ni leer episodios de otro centro.

Autenticación

La API usa OAuth2 con el flujo client credentials, pensado para comunicación entre sistemas sin intervención de una persona.

Pedir un token

Las credenciales pueden ir en el encabezado Authorization como Basic, que es lo recomendado, o en el cuerpo del pedido.

POST https://fhir.hardineros.net/oauth/token
Authorization: Basic BASE64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

La respuesta:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "episodio.read episodio.write"
}

Usar el token

Va en el encabezado de cada pedido a QuestionnaireResponse.

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Permisos

Recomendaciones

• El token dura una hora. Conviene guardarlo en memoria y reusarlo hasta que falte poco para que venza, en lugar de pedir uno nuevo en cada envío.
• No hay refresh token: cuando vence, se pide otro con las mismas credenciales.
• Ante un 401 con un token que parecía válido, pedir uno nuevo y reintentar una vez.
• El client_secret no debe quedar en el código fuente ni en un repositorio: va en configuración del entorno.

El cuestionario es el contrato

Todo lo que el servidor exige está declarado en el recurso Questionnaire. No hay validaciones ocultas.

GET https://fhir.hardineros.net/fhir/Questionnaire/eds-2026

Ahí figuran los campos con su tipo, cuáles son obligatorios, los rangos, las opciones de cada campo codificado, las dependencias entre campos y las reglas que combinan varios. Conviene leerlo desde el sistema en lugar de copiar esta página a mano, sobre todo las listas de códigos: si el EDS cambia, el cuestionario lo refleja.

Cómo se arma el envío

El recurso a enviar es un QuestionnaireResponse:

{
  "resourceType": "QuestionnaireResponse",
  "questionnaire": "https://fhir.hardineros.net/fhir/Questionnaire/eds-2026",
  "status": "completed",
  "item": [
    {
      "linkId": "internacion",
      "item": [
        { "linkId": "FECHING", "answer": [{ "valueDate": "2026-06-03" }] }
      ]
    }
  ]
}

Reglas de armado

• El elemento questionnaire debe apuntar a la URL canónica exacta. Se admite con sufijo de versión, por ejemplo terminando en |V2026.
• El status debe ser completed o amended.
• Cada respuesta es un item con su linkId y un arreglo answer con un único elemento.
• Los items se pueden agrupar como en el cuestionario o mandarse sueltos en la raíz: el servidor acepta ambas formas.

Formatos

Un campo codificado se ve así:

{
  "linkId": "TIPO",
  "answer": [{
    "valueCoding": {
      "system": "https://fhir.hardineros.net/fhir/CodeSystem/satiq-tipo",
      "code": "A"
    }
  }]
}

Tres cosas que suelen sorprender

El centro no se envía

No existe un campo para indicarlo: lo determina el servidor a partir de las credenciales.

La estadía la informa el centro

ESTADIA es obligatoria y se guarda tal como se envía. El servidor no la recalcula a partir de las fechas ni la corrige. Tampoco tiene tope: sólo se exige que sea 1 o más, igual que los días de cada dispositivo.

Un campo ausente no significa que no ocurrió

Las quince banderas de dispositivos y complicaciones son obligatorias y hay que enviarlas todas, incluso las que valen false. Omitir una es un error, no una forma de decir que no ocurrió.

Campos

Los 48 campos del cuestionario. Los que tienen condición sólo se exigen si esa condición se cumple, y enviarlos cuando no corresponde también es un error.

Identificación

Internación

Paciente

Clasificación del ingreso

Gravedad al ingreso

Dispositivos

Complicaciones y eventos

TISS-28

Egreso

Listas de códigos

Cada campo con opciones tiene su sistema publicado. Ese valor es el que va en system dentro del Coding.

Tipo de paciente (EDS SATI-Q)

GET https://fhir.hardineros.net/fhir/CodeSystem/satiq-tipo

Sexo (EDS SATI-Q)

GET https://fhir.hardineros.net/fhir/CodeSystem/satiq-sexo

Motivo de ingreso a UCI (EDS SATI-Q)

GET https://fhir.hardineros.net/fhir/CodeSystem/satiq-moting

Los códigos 1 a 4 son para pacientes adultos y los 5 a 10 para pediátricos y neonatales. El 99 vale para cualquiera. Usar un código que no corresponde al tipo de paciente es un error.

Procedencia del paciente (EDS SATI-Q)

GET https://fhir.hardineros.net/fhir/CodeSystem/satiq-procedencia

Resultado al egreso de UCI (EDS SATI-Q)

GET https://fhir.hardineros.net/fhir/CodeSystem/satiq-resultado

Reglas de validación

Además de la estructura, el servidor verifica reglas que combinan varios campos. Están declaradas en el propio cuestionario como extensiones questionnaire-constraint, y cada una tiene una clave que aparece en el error cuando se incumple.

La edad se expresa en la unidad que corresponde al tipo de paciente: años para adultos, meses para pediátricos y días para neonatales. El campo es siempre un entero; la unidad la deduce el servidor del tipo.

Tres reglas que dependen del centro

Estos controles no están en el cuestionario, porque necesitan mirar lo que el centro ya tiene cargado:

• Año cerrado: si el centro cerró el año del egreso, el envío se rechaza con 422.
• Episodio repetido: no puede haber dos episodios del mismo paciente con la misma fecha y hora de ingreso. Se rechaza con 409.
• Internaciones superpuestas: un paciente no puede estar internado dos veces a la vez en la misma unidad. Si el período informado se solapa con otro episodio suyo, se rechaza con 409 indicando con cuál choca. Egresar y reingresar el mismo día es válido: los extremos que se tocan no cuentan como superposición.

Probar sin guardar

$validate corre las validaciones del cuestionario y sus reglas, pero no guarda nada y no requiere credenciales.

POST https://fhir.hardineros.net/fhir/QuestionnaireResponse/$validate
Content-Type: application/fhir+json

{ ...el QuestionnaireResponse... }

Siempre responde 200. Lo que cambia es el contenido: si el recurso está bien, un único issue con severity information; si no, un issue por cada problema.

Enviar, leer y corregir

POST Enviar un episodio

POST https://fhir.hardineros.net/fhir/QuestionnaireResponse
Authorization: Bearer TOKEN
Content-Type: application/fhir+json

{ ...el QuestionnaireResponse... }

Si sale bien, la respuesta es 201, el encabezado Location trae la URL del recurso creado y el cuerpo devuelve el episodio tal como quedó guardado. El último segmento de esa URL es el identificador que conviene conservar.

GET Leer un episodio

GET https://fhir.hardineros.net/fhir/QuestionnaireResponse/{id}
Authorization: Bearer TOKEN

Devuelve el episodio reconstruido desde lo que está guardado, no una copia literal de lo enviado: si fue corregido después desde el formulario web, la lectura refleja el estado actual.

PUT Corregir un episodio

Requiere el alcance episodio.write.

PUT https://fhir.hardineros.net/fhir/QuestionnaireResponse/{id}
Authorization: Bearer TOKEN
Content-Type: application/fhir+json

{ ...el QuestionnaireResponse completo... }

Reemplaza el recurso completo: hay que enviar todos los campos, no sólo los que cambian. Si el recurso trae id, tiene que ser el mismo de la dirección. Responde 200 con el episodio tal como quedó guardado.

Se aplican las mismas validaciones que en el alta, más los controles de episodio repetido y de superposición, que ignoran al propio episodio que se está corrigiendo.

DELETE Eliminar un episodio

Requiere el alcance episodio.delete, que no se concede por defecto.

DELETE https://fhir.hardineros.net/fhir/QuestionnaireResponse/{id}
Authorization: Bearer TOKEN

Responde 204 sin cuerpo. Borra el episodio junto con su TISS día por día y su historial de envíos, y no tiene vuelta atrás. Eliminar algo que ya no existe también devuelve 204: el resultado buscado ya se cumplió.

Reintentos

Cada POST que llega es un alta. Ahora bien, no se puede cargar dos veces el mismo paciente con la misma fecha y hora de ingreso: el segundo intento devuelve 409. Ante un error de red del que no se sabe si el envío llegó, conviene reintentar: si el primero había entrado, el 409 lo confirma.

Errores

Todos los errores de la API se devuelven como OperationOutcome. Los del endpoint de token siguen el formato de OAuth2, con error y error_description.

Cómo leer un error de validación

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "business-rule",
    "details": {
      "coding": [{
        "system": ".../CodeSystem/satiq-validacion",
        "code": "edad-por-tipo"
      }],
      "text": "La edad debe corresponder al tipo de paciente..."
    },
    "diagnostics": "Edad fuera de rango para paciente neonatal: debe estar entre 0 y 28 dias.",
    "expression": ["QuestionnaireResponse.repeat(item).where(linkId='EDAD')"]
  }]
}

• code indica la naturaleza: required si falta un campo obligatorio, invalid si la estructura está mal, business-rule si se incumple una regla.
• details.coding.code es la clave de la regla, la misma que figura en el cuestionario. Sirve para mapear el error a un mensaje propio.
• expression apunta al campo que hay que corregir.
• diagnostics es el texto explicativo, pensado para mostrarle a una persona.

Ejemplo completo

Adulto de 74 años, ingreso por cirugía de urgencia, doce días de internación, con ventilación invasiva y no invasiva, tres complicaciones y fallecimiento al egreso. Es un envío válido: se puede probar tal cual contra $validate.

{
  "resourceType": "QuestionnaireResponse",
  "questionnaire": "https://fhir.hardineros.net/fhir/Questionnaire/eds-2026",
  "status": "completed",
  "authored": "2026-06-16T09:12:00-03:00",
  "item": [
    {
      "linkId": "identificacion",
      "item": [
        { "linkId": "IDPACIENTE", "answer": [{ "valueInteger": 48217 }] },
        { "linkId": "REINGRESO", "answer": [{ "valueBoolean": false }] }
      ]
    },
    {
      "linkId": "internacion",
      "item": [
        { "linkId": "FECHING", "answer": [{ "valueDate": "2026-06-03" }] },
        { "linkId": "HORAING", "answer": [{ "valueTime": "23:40" }] },
        { "linkId": "FECEGR", "answer": [{ "valueDate": "2026-06-15" }] },
        { "linkId": "HORAEGR", "answer": [{ "valueTime": "06:20" }] },
        { "linkId": "ESTADIA", "answer": [{ "valueInteger": 12 }] }
      ]
    },
    {
      "linkId": "paciente",
      "item": [
        { "linkId": "TIPO", "answer": [{ "valueCoding": { "system": "https://fhir.hardineros.net/fhir/CodeSystem/satiq-tipo", "code": "A" } }] },
        { "linkId": "EDAD", "answer": [{ "valueInteger": 74 }] },
        { "linkId": "SEXO", "answer": [{ "valueCoding": { "system": "https://fhir.hardineros.net/fhir/CodeSystem/satiq-sexo", "code": "M" } }] }
      ]
    },
    {
      "linkId": "ingreso",
      "item": [
        { "linkId": "MOTING", "answer": [{ "valueCoding": { "system": "https://fhir.hardineros.net/fhir/CodeSystem/satiq-moting", "code": "2" } }] },
        { "linkId": "PROCEDENCIA", "answer": [{ "valueCoding": { "system": "https://fhir.hardineros.net/fhir/CodeSystem/satiq-procedencia", "code": "11" } }] }
      ]
    },
    {
      "linkId": "gravedad",
      "item": [
        { "linkId": "SCORE", "answer": [{ "valueDecimal": 24 }] },
        { "linkId": "PROBABMORT", "answer": [{ "valueDecimal": 46.8 }] }
      ]
    },
    {
      "linkId": "dispositivos",
      "item": [
        { "linkId": "VI", "answer": [{ "valueBoolean": true }] },
        { "linkId": "DIASVI", "answer": [{ "valueInteger": 9 }] },
        { "linkId": "VNI", "answer": [{ "valueBoolean": true }] },
        { "linkId": "DIASVNI", "answer": [{ "valueInteger": 2 }] },
        { "linkId": "CAFO", "answer": [{ "valueBoolean": false }] },
        { "linkId": "CVC", "answer": [{ "valueBoolean": true }] },
        { "linkId": "DIASCVC", "answer": [{ "valueInteger": 11 }] },
        { "linkId": "SV", "answer": [{ "valueBoolean": true }] },
        { "linkId": "DIASSV", "answer": [{ "valueInteger": 12 }] },
        { "linkId": "SNG", "answer": [{ "valueBoolean": true }] },
        { "linkId": "DIASSNG", "answer": [{ "valueInteger": 10 }] },
        { "linkId": "SE", "answer": [{ "valueBoolean": true }] },
        { "linkId": "DIASSE", "answer": [{ "valueInteger": 8 }] }
      ]
    },
    {
      "linkId": "complicaciones",
      "item": [
        { "linkId": "NEUMONIA", "answer": [{ "valueBoolean": true }] },
        { "linkId": "NEUMONIANUM", "answer": [{ "valueInteger": 1 }] },
        { "linkId": "AUTOEXTUBACION", "answer": [{ "valueBoolean": false }] },
        { "linkId": "INFCATETER", "answer": [{ "valueBoolean": false }] },
        { "linkId": "INFURINARIA", "answer": [{ "valueBoolean": true }] },
        { "linkId": "INFURINARIANUM", "answer": [{ "valueInteger": 1 }] },
        { "linkId": "ESCARAS", "answer": [{ "valueBoolean": true }] },
        { "linkId": "ESCARASNUM", "answer": [{ "valueInteger": 2 }] },
        { "linkId": "INFHERIDAS", "answer": [{ "valueBoolean": false }] },
        { "linkId": "DESLIZSNG", "answer": [{ "valueBoolean": false }] },
        { "linkId": "DESLIZCAMA", "answer": [{ "valueBoolean": false }] }
      ]
    },
    {
      "linkId": "tiss",
      "item": [
        { "linkId": "TISSMIN", "answer": [{ "valueDecimal": 22 }] },
        { "linkId": "TISSMAX", "answer": [{ "valueDecimal": 41 }] },
        { "linkId": "TISSPROMEDIO", "answer": [{ "valueDecimal": 31.5 }] }
      ]
    },
    {
      "linkId": "egreso",
      "item": [
        { "linkId": "RESULTADO", "answer": [{ "valueCoding": { "system": "https://fhir.hardineros.net/fhir/CodeSystem/satiq-resultado", "code": "5" } }] }
      ]
    }
  ]
}

Preguntas frecuentes

¿Puedo enviar varios episodios del mismo paciente?

Sí. Un paciente puede reingresar las veces que haga falta, incluso varias en el mismo año. Lo único que no se acepta es repetir el mismo momento de ingreso, o informar un período que se superponga con otra internación suya en esa unidad.

¿Hay un tope de días de internación?

No. Ni la estadía ni los días de cada dispositivo tienen máximo: sólo se exige que sean 1 o más. Las cantidades de complicaciones sí están limitadas a 99.

¿Puedo enviar episodios de años anteriores?

Sí, mientras ese año no esté cerrado para el centro. Al cerrar un año deja de aceptarse cualquier episodio con egreso en él.

¿Qué pasa si me equivoqué en un episodio ya enviado?

Se corrige con un PUT sobre su dirección, enviando el recurso completo, o desde el formulario web. Si el año está cerrado, primero hay que reabrirlo desde el formulario.

¿Puedo mandar varios episodios en un solo pedido?

No. Un pedido, un episodio.

¿Hay límite de frecuencia?

No hay límite declarado, pero conviene enviar de a uno y con una pausa mínima entre pedidos en las cargas masivas iniciales.

¿El TISS-28 es obligatorio?

No. Los tres campos de TISS son los únicos opcionales del cuestionario. Si se envían, tienen que estar ordenados de mínimo a máximo.

¿Qué pasa si el cuestionario cambia?

Los cambios se publican en el propio cuestionario, y esta página los refleja automáticamente. Conviene releerlo periódicamente en lugar de dejar los códigos fijos en el código, sobre todo las listas de opciones.

API © 2026+ SATI-Q. Contrato V2026 basado en FHIR 4.0.1. Publicado por Hardineros SAS. Última revisión 2026-08-12
Enlaces: Cuestionario · Sistemas de códigos · CapabilityStatement · Formulario web