OrderController API Documentation

Este módulo permite gestionar órdenes RIS en el sistema.

Endpoints

Base Path

Todos los endpoints están prefijados con /api/v1/orders.

Global Standards

Consulte Common.md para detalles sobre:

• Autenticación (X-Api-Key o token de usuario)
• Paginación y ordenamiento
• Estructura global de errores
• Guía de Filtrado completa

---

Attributes (Order)

Filtros Adicionales (GET /api/v1/orders)

• filter[accession_number]: Número de acceso (búsqueda exacta =)
• filter[patient_identifier]: Cédula o número de documento del paciente (búsqueda exacta =)
• filter[priority]: Prioridad (búsqueda exacta: ROUTINE, URGENT, STAT)
• filter[status]: Estado de la orden (búsqueda exacta: ORDERED, SCHEDULED, CANCELED, COMPLETED)
• filter[modality]: Modalidad radiológica (búsqueda exacta, ej. CR, CT, MR, DX)

---

Endpoints Detail

Obtiene una lista paginada de órdenes RIS.

Ejemplo cURL (Listar todas las órdenes)

curl -X GET "http://worklist.dicomline.com/api/v1/orders" \
  -H "X-Api-Key: TU_API_KEY"

Ejemplo cURL (Filtrar por Accession Number)

curl -X GET "http://worklist.dicomline.com/api/v1/orders?filter[accession_number]=202600100001" \
  -H "X-Api-Key: TU_API_KEY"

Ejemplo cURL (Filtrar por identificación del paciente)

curl -X GET "http://worklist.dicomline.com/api/v1/orders?filter[patient_identifier]=100940" \
  -H "X-Api-Key: TU_API_KEY"

Ejemplo cURL (Filtrar por estado y prioridad)

curl -X GET "http://worklist.dicomline.com/api/v1/orders?filter[status]=ORDERED&filter[priority]=URGENT" \
  -H "X-Api-Key: TU_API_KEY"

{
  "data": [
    {
      "id": "c7a8b41f-829d-4e9a-9e1d-8f2a63b0194e",
      "accession_number": "202600100001",
      "patient_identifier": "100940",
      "requested_procedure_id": "REQ0001",
      "exam_description": "Radiografía de Columna Lumbar AP y Lateral",
      "referring_physician": "House^Gregory^^Dr.",
      "special_instructions": "Paciente refiere dolor intenso",
      "priority": "ROUTINE",
      "status": "ORDERED",
      "created_at": "2026-07-07 12:30:00"
    }
  ],
  "_links": {
    "self": { "href": "http://worklist.dicomline.com/api/v1/orders?page=1" },
    "first": { "href": "http://worklist.dicomline.com/api/v1/orders?page=1" },
    "last": { "href": "http://worklist.dicomline.com/api/v1/orders?page=1" }
  },
  "_meta": {
    "totalCount": 1,
    "pageCount": 1,
    "currentPage": 1,
    "perPage": 20
  }
}

---

Obtiene una orden específica utilizando su UUID ({id} representa el UUID de la orden).

Parámetros URL:

• {id}: string (UUID de la orden)

Ejemplo cURL

curl -X GET "http://worklist.dicomline.com/api/v1/orders/c7a8b41f-829d-4e9a-9e1d-8f2a63b0194e" \
  -H "X-Api-Key: TU_API_KEY"

{
  "id": "c7a8b41f-829d-4e9a-9e1d-8f2a63b0194e",
  "accession_number": "202600100001",
  "patient_identifier": "100940",
  "requested_procedure_id": "REQ0001",
  "exam_description": "Radiografía de Columna Lumbar AP y Lateral",
  "referring_physician": "House^Gregory^^Dr.",
  "special_instructions": "Paciente debe estar en ayunas 6 horas",
  "priority": "ROUTINE",
  "status": "ORDERED",
  "created_at": "2026-07-07 12:30:00"
}

Respuestas de error:

• 404 Not Found: Si la orden no existe o no pertenece a la institución autenticada.

---

Crea una nueva orden RIS en el sistema.

Headers Requeridos

• Content-Type: application/json
• X-Api-Key: <TU_API_KEY>

Estructura del Payload

El cuerpo de la solicitud JSON se compone de dos partes:

1. Atributos de la Orden (Nivel Raíz): Datos del estudio radiológico (código del procedimiento, prioridad, médico, etc.).
2. Objeto patient (Nivel Anidado): Datos de identificación y demografía del paciente.

Lógica de Resolución del Paciente

• El API busca automáticamente si ya existe un paciente registrado en la institución con el patient_identifier.
• Si el paciente ya existe: Se asocia automáticamente a la orden. No es necesario enviar nuevamente todos sus datos demográficos.
• Si el paciente NO existe: Se crea automáticamente en la institución con los datos demográficos incluidos en el objeto patient.

---

1. Atributos de la Orden (Nivel Raíz)

---

2. Atributos del Paciente (Objeto anidado patient)

---

Ejemplos de Solicitud (Request Body) y cURL

Caso A: Paciente Nuevo con datos completos

curl -X POST "http://worklist.dicomline.com/api/v1/orders" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: TU_API_KEY" \
  -d '{
    "procedure_code": "CT_HEAD_WO",
    "patient": {
      "patient_identifier": "100940",
      "patient_name": "Perez^Juan^Carlos",
      "identification_type": "NI",
      "sex": "M",
      "date_of_birth": "1980-01-01"
    },
    "clinical_indication": "Dolor lumbar persistente con irradiacion",
    "special_instructions": "Paciente debe estar en ayunas 6 horas",
    "referring_physician": "House^Gregory^^Dr.",
    "priority": "URGENT",
    "status": "ORDERED"
  }'

Caso B: Mínimo Obligatorio

Si solo envías los datos indispensables (el número de acceso y secuencia se generan automáticamente):

curl -X POST "http://worklist.dicomline.com/api/v1/orders" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: TU_API_KEY" \
  -d '{
    "procedure_code": "RX-COL-001",
    "patient": {
      "patient_identifier": "100940",
      "patient_name": "Perez^Juan^Carlos"
    }
  }'

Caso C: Paciente Preexistente en la Institución

Si el paciente ya está registrado en la institución, basta con enviar su identificador:

curl -X POST "http://worklist.dicomline.com/api/v1/orders" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: TU_API_KEY" \
  -d '{
    "procedure_code": "RX-COL-001",
    "patient": {
      "patient_identifier": "100940"
    },
    "clinical_indication": "Control rutinario anual",
    "priority": "ROUTINE"
  }'

---

Respuestas

{
  "id": "c7a8b41f-829d-4e9a-9e1d-8f2a63b0194e",
  "accession_number": "202600100001",
  "patient_identifier": "100940",
  "requested_procedure_id": "REQ0001",
  "exam_description": "Radiografía de Columna Lumbar AP y Lateral",
  "referring_physician": "House^Gregory^^Dr.",
  "special_instructions": "Paciente debe estar en ayunas 6 horas",
  "priority": "URGENT",
  "status": "ORDERED",
  "created_at": "2026-07-07 12:30:00"
}

Si falla la validación del procedimiento o de la orden:

{
  "procedure_code": [
    "Seleccione un procedimiento valido de la lista."
  ]
}

Si falla la validación de los datos del paciente:

{
  "patient": {
    "patient_name": [
      "patient_name debe enviarse como \"LAST NAME^FIRST NAME^MIDDLE NAME\"."
    ]
  }
}

---

Actualiza los datos de una orden existente utilizando su UUID ({id} representa el UUID de la orden).

Nota: Solo pueden modificarse órdenes en estado ORDERED. Si la orden ya se encuentra en otro estado, la solicitud retornará un error 403 Forbidden.

Parámetros URL:

• {id}: string (UUID de la orden)

Ejemplo cURL

curl -X PUT "http://worklist.dicomline.com/api/v1/orders/c7a8b41f-829d-4e9a-9e1d-8f2a63b0194e" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: TU_API_KEY" \
  -d '{
    "clinical_indication": "Control postquirurgico y seguimiento",
    "special_instructions": "Revisar imagenes previas antes del estudio",
    "referring_physician": "Strange^Stephen^^Dr.",
    "priority": "STAT"
  }'

{
  "id": "c7a8b41f-829d-4e9a-9e1d-8f2a63b0194e",
  "accession_number": "202600100001",
  "patient_identifier": "100940",
  "requested_procedure_id": "REQ0001",
  "exam_description": "Radiografía de Columna Lumbar AP y Lateral",
  "referring_physician": "Strange^Stephen^^Dr.",
  "special_instructions": "Revisar imágenes previas antes del estudio",
  "priority": "STAT",
  "status": "ORDERED",
  "created_at": "2026-07-07 12:30:00"
}

---

Cancela una orden cambiando su estado a CANCELED ({id} representa el UUID de la orden).

Parámetros URL:

• {id}: string (UUID de la orden)

Ejemplo cURL

curl -X POST "http://worklist.dicomline.com/api/v1/orders/c7a8b41f-829d-4e9a-9e1d-8f2a63b0194e/cancel" \
  -H "X-Api-Key: TU_API_KEY"

{
  "id": "c7a8b41f-829d-4e9a-9e1d-8f2a63b0194e",
  "accession_number": "202600100001",
  "patient_identifier": "100940",
  "requested_procedure_id": "REQ0001",
  "exam_description": "Radiografía de Columna Lumbar AP y Lateral",
  "referring_physician": "House^Gregory^^Dr.",
  "special_instructions": "Paciente debe estar en ayunas 6 horas",
  "priority": "ROUTINE",
  "status": "CANCELED",
  "created_at": "2026-07-07 12:30:00"
}

---

Elimina una orden existente utilizando su UUID ({id} representa el UUID de la orden).

Parámetros URL:

• {id}: string (UUID de la orden)

Ejemplo cURL

curl -X DELETE "http://worklist.dicomline.com/api/v1/orders/c7a8b41f-829d-4e9a-9e1d-8f2a63b0194e" \
  -H "X-Api-Key: TU_API_KEY"

{
  "message": "Orden eliminada exitosamente."
}

---

Notas Finales

• Consulte Common.md para los códigos de estado y la estructura de errores globales.
• Los resultados están limitados a los datos autorizados para la clave API utilizada.