Crear Nueva Plantilla de Informe

Este endpoint permite crear una nueva plantilla de informe médico. La plantilla puede asociarse directamente a un usuario específico mediante su userId, en cuyo caso solo estará disponible para ese usuario. Alternativamente, puede asociarse al proveedor de salud mediante el providerId, lo que hará que esté disponible para todos los usuarios vinculados a ese proveedor.

🔒 Este endpoint requiere autenticación. Consulte la sección de Autenticación para obtener su token y cómo utilizarlo en la cabecera Authorization.

Endpoint

💡 Importante: Para conocer en detalle los métodos, parámetros requeridos, el formato del body y posibles respuestas, puede consultar la documentación específica en el Portal de desarrolladores o revisar el request configurado en el archivo de Postman previamente compartido.

🔐 Nota: Para obtener el catálogo de HealthAPI, debe autenticarse en ese mismo portal utilizando las credenciales otorgadas.

Cuerpo de la Solicitud (`application/json`)

Parámetros del Cuerpo

Parámetro	Tipo	Requerido	Descripción
`providerId`	number	Sí	ID del hospital o proveedor médico.
`userId`	string	Condicional	ID del usuario específico (solo añadir si la plantilla es para ese usuario en particular).
`name`	string	Sí	Nombre identificativo de la plantilla.
`type`	number	Sí	Tipo de plantilla: `0` (Consulta) o `1` (Cirugía).
`description`	string	No	Breve descripción del propósito de la plantilla.
`specialityId`	number	Sí	ID de la especialidad médica asociada. Consulte las especialidades disponibles haciendo click aqui.
`body`	string	Condicional	Estructura de la plantilla en formato Markdown o HTML.
`responseFormat`	string	Condicional	Estructura de la plantilla en formato JSON.

⚠️ Importante: responseFormat vs body

responseFormat: Utilice este campo únicamente cuando la configuración del centro médico requiera que la respuesta final sea un objeto JSON estructurado. En este caso, NO debe enviar el campo body.

body: Utilice este campo cuando la configuración del centro médico espere recibir un informe en formato MARKDOWN o HTML. En este caso, NO debe enviar el campo responseFormat.

Caso 1: Crear plantilla asociada directamente al `providerId`

{
  "providerId": 123, // ID del hospital, proporcionado previamente por el equipo de Speaknosis.
  "name": "Consulta General Adulto", // Nombre de la plantilla.
  "body": "### Consulta\nDolor abdominal.", // Contenido de la plantilla en formato Markdown.
  "type": 0, // Tipo de plantilla: 0 para consulta médica, 1 para cirugía.
  "description": "Plantilla básica para consulta médica general en adultos.", // Descripción de la plantilla.
  "specialityId": 1 // ID de la especialidad médica asociada a la plantilla.
}

Caso 2: Crear plantilla asociada a un `userId`

{
  "providerId": 123, // ID del hospital, proporcionado previamente por el equipo de Speaknosis.
  "userId": "321", // ID del usuario.
  "name": "Consulta General Adulto", // Nombre de la plantilla.
  "body": "### Consulta\nDolor abdominal.", // Contenido de la plantilla en formato Markdown.
  "type": 0, // Tipo de plantilla: 0 para consulta médica, 1 para cirugía.
  "description": "Plantilla básica para consulta médica general en adultos.", // Descripción de la plantilla.
  "specialityId": 1 // ID de la especialidad médica asociada a la plantilla.
}

Caso 3: Crear plantilla con formato JSON (`responseFormat`)

El campo responseFormat permite definir una estructura JSON específica que el sistema utilizará para generar el informe.

{
  "providerId": 123,
  "name": "Consulta Estructurada",
  "responseFormat": "[...]", // Ver sección "Estructura y Ejemplos de responseFormat" más abajo
  "type": 0,
  "description": "Plantilla que retorna un JSON con campos específicos.",
  "specialityId": 1
}

Estructura y Ejemplos de `responseFormat`

El campo responseFormat define el esquema JSON que se utilizará para extraer y estructurar la información clínica. Debe ser un array de objetos, donde cada objeto representa un campo a extraer.

Propiedades del Objeto `responseFormat`

Propiedad	Tipo	Requerido	Descripción
`title`	string	Sí	Título legible del campo (ej. "Motivo de Consulta").
`description`	string	Sí	Descripción para el modelo de IA sobre qué información extraer.
`type`	string	Sí	Tipo de dato: `"string"`, `"number"`, `"boolean"`, `"array"`, `"object"`, `"select"`, `"radio"`, `"checkbox"`.
`key`	string	Sí	Clave única para el JSON de respuesta (ej. `motivoConsulta`).
`nullable`	boolean	No	Si es `true`, el campo puede ser `null` si no se encuentra información (por defecto `true`).
`options`	array	Condicional	Requerido SOLO si `type` es `select` o `radio`. Lista de opciones permitidas. Puede ser un array de strings `["A", "B"]` o un array de objetos `[{"value": "a", "text": "Opción A"}]`.
`items`	object	Condicional	Requerido si `type` es `array`. Define la estructura de los elementos del array.
`properties`	object	Condicional	Requerido si `type` es `object` (o dentro de `items`). Define los campos anidados.

⚠️ Nota sobre checkbox vs select:

Utilice checkbox para campos binarios (Sí/No, Verdadero/Falso). Este tipo se convierte internamente en boolean y NO debe llevar la propiedad options.

Utilice select o radio cuando necesite que el usuario elija un valor específico de una lista (ej. "Tipo de Sangre"). Estos tipos se convierten en string y SÍ requieren la propiedad options.

Ejemplos de Configuración JSON

Ejemplo 1: Consulta General

[
  {
    "title": "Motivo de consulta",
    "description": "Razón principal por la que el paciente acude",
    "type": "string",
    "key": "motivoConsulta",
    "nullable": true
  },
  {
    "title": "Diagnóstico",
    "description": "Diagnóstico clínico del médico",
    "type": "string",
    "key": "diagnostico",
    "nullable": true
  }
]

Ejemplo 2: Inputs Avanzados (Select, Checkbox)

Ideal para campos estructurados con opciones predefinidas simples.

[
  {
    "key": "estadoCivil",
    "title": "Estado Civil",
    "description": "Estado legal actual del paciente",
    "type": "select",
    "options": ["Soltero", "Casado", "Divorciado", "Viudo"]
  },
  {
    "key": "esFumador",
    "title": "¿Es Fumador?",
    "description": "Indicar verdadero si el paciente fuma actualmente",
    "type": "checkbox"
    // Nota: NO incluir 'options' aquí, ya que es un valor booleano (true/false)
  }
]

Ejemplo 3: Opciones con Clave-Valor (Select/Radio)

Permite separar el texto visible (text) del valor técnico (value) que se guarda en el JSON.

[
  {
    "key": "pais",
    "title": "País de Origen",
    "description": "Seleccione su país",
    "type": "select",
    "options": [
      { "text": "España", "value": "ES" },
      { "text": "México", "value": "MX" },
      { "text": "Argentina", "value": "AR" }
    ]
  },
  {
    "key": "genero",
    "title": "Género",
    "description": "Género del paciente",
    "type": "radio",
    "options": [
      { "text": "Masculino", "value": "M" },
      { "text": "Femenino", "value": "F" }
    ]
  }
]

Ejemplo 4: Protocolo Operatorio

[
  {
    "title": "Intervención Realizada",
    "description": "Nombre técnico de la cirugía efectuada",
    "type": "string",
    "key": "intervencion",
    "nullable": false
  },
  {
    "title": "Cirujano Principal",
    "description": "Nombre del médico que lideró el procedimiento",
    "type": "string",
    "key": "cirujano",
    "nullable": false
  }
]

Ejemplos de Respuesta Exitosa (`201 Created`)

Para una plantilla asociada directamente al providerId:

{
  "success": true,
  "code": 201,
  "response": {
    "message": "Success Response",
    "id": 374,
    "name": "Consulta General Adulto",
    "description": "Plantilla básica para consulta médica general en adultos.",
    "type": 0,
    "body": "### Consulta\nDolor abdominal.",
    "specialityId": 1,
    "isValidated": true,
    "ownerType": "HEALTH_PROVIDER",
    "providerId": "123",
    "responseFormat": null
  }
}

Para una plantilla asociada a un userId:

{
  "success": true,
  "code": 201,
  "response": {
    "message": "Success Response",
    "id": 375,
    "name": "Consulta General Adulto",
    "description": "Plantilla básica para consulta médica general en adultos.",
    "type": 0,
    "body": "### Consulta\nDolor abdominal.",
    "specialityId": 1,
    "isValidated": true,
    "ownerType": "USER",
    "providerId": "123",
    "userId": "1052",
    "responseFormat": null
  }
}

Para una plantilla creada con responseFormat (JSON):

Nota: Cuando se crea una plantilla enviando responseFormat, el sistema genera automáticamente un campo body en formato Markdown basado en la estructura del JSON, además de guardar el responseFormat original.

{
  "success": true,
  "code": 201,
  "response": {
    "message": "Success Response",
    "id": 376,
    "name": "Consulta Estructurada",
    "description": "Plantilla que retorna un JSON con campos específicos.",
    "type": 0,
    "body": "### Motivo de consulta\n(Contenido autogenerado...)\n\n### Diagnostico\n(Contenido autogenerado...)",
    "specialityId": 1,
    "isValidated": true,
    "ownerType": "HEALTH_PROVIDER",
    "providerId": "123",
    "responseFormat": [
      {
        "title": "Motivo de consulta",
        "description": "Razón principal por la que el paciente acude",
        "type": "string",
        "key": "motivoConsulta",
        "nullable": true
      },
      {
        "title": "Diagnóstico",
        "description": "Diagnóstico clínico del médico",
        "type": "string",
        "key": "diagnostico",
        "nullable": true
      }
    ]
  }
}

Endpoint​

Cuerpo de la Solicitud (application/json)​

Parámetros del Cuerpo​

Caso 1: Crear plantilla asociada directamente al providerId​

Caso 2: Crear plantilla asociada a un userId​

Caso 3: Crear plantilla con formato JSON (responseFormat)​

Estructura y Ejemplos de responseFormat​

Propiedades del Objeto responseFormat​

Ejemplos de Configuración JSON​

Ejemplos de Respuesta Exitosa (201 Created)​