Patients API Documentation

Este módulo permite gestionar pacientes en el sistema.

Endpoints

Base Path

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

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 (Patient)

• id: string (UUID v7, identificador único universal del recurso, autogenerado, solo lectura)
• identification_number: string (requerido al crear, máx 255; documento de identidad o historia clínica; único por centro/tenant; coincidencia exacta)
• identification_type: string (requerido al crear, máx 50; tipos válidos: NI, PPN, MR, DL, SS, PI, AN, PN, XX)
• first_name: string (requerido al crear, máx 255; nombres del paciente)
• last_name: string (requerido al crear, máx 255; apellidos del paciente)
• date_of_birth: string date (opcional; formato YYYY-MM-DD)
• gender: string (opcional, máx 10; valores permitidos: M = Masculino, F = Femenino, O = Otro)
• created_at: string datetime (solo lectura, fecha y hora de creación)

Tipos de Identificación Permitidos (identification_type)

Filtros Disponibles (GET /api/v1/patients)

• filter[identification_number]: Búsqueda exacta (=) por número de documento
  • Ejemplo: filter[identification_number]=12345678
• filter[first_name]: Búsqueda parcial (LIKE) en nombre o apellido
• filter[identification_type]: Búsqueda exacta por tipo de documento (NI, PPN, etc.)
• filter[gender]: Búsqueda exacta por género (M, F, O)
• filter[date_of_birth]: Fecha de nacimiento (soporta operadores: [>, <, >=, <=, =])
  • Ejemplo: filter[date_of_birth][<]=1990-01-01

---

Endpoints Detail

Obtiene una lista paginada de pacientes pertenecientes al centro (tenant) autenticado.

Ejemplo cURL (Listar todos)

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

Ejemplo cURL (Filtrar por cédula / identificación exacta)

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

{
    "data": [
        {
            "id": "01955b20-8025-7091-bfec-607faeb3fa15",
            "identification_number": "12345678",
            "identification_type": "NI",
            "first_name": "Juan",
            "last_name": "Pérez",
            "date_of_birth": "1990-01-01",
            "gender": "M",
            "created_at": "2024-01-01 10:00:00"
        }
    ],
    "_links": {
        "self": { "href": "http://worklist.dicomline.com/api/v1/patients?page=1" },
        "first": { "href": "http://worklist.dicomline.com/api/v1/patients?page=1" },
        "last": { "href": "http://worklist.dicomline.com/api/v1/patients?page=1" }
    },
    "_meta": {
        "totalCount": 1,
        "pageCount": 1,
        "currentPage": 1,
        "perPage": 20
    }
}

---

Obtiene los detalles de un paciente específico utilizando su identificador único (uuid).

Parámetros URL:

• {id}: string (UUID del paciente)

Ejemplo cURL

curl -X GET "http://worklist.dicomline.com/api/v1/patients/01955b20-8025-7091-bfec-607faeb3fa15" \
  -H "X-Api-Key: TU_API_KEY"

{
    "id": "01955b20-8025-7091-bfec-607faeb3fa15",
    "identification_number": "12345678",
    "identification_type": "NI",
    "first_name": "Juan",
    "last_name": "Pérez",
    "date_of_birth": "1990-01-01",
    "gender": "M",
    "created_at": "2024-01-01 10:00:00"
}

Respuestas de error:

• 404 Not Found: Si el paciente no existe o no pertenece al centro autenticado.

---

Crea un nuevo paciente dentro del centro (tenant) autenticado.

Headers Requeridos:

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

Campos Requeridos en el Body:

• identification_number (string)
• identification_type (string)
• first_name (string)
• last_name (string)

Campos Opcionales:

• date_of_birth (string, YYYY-MM-DD)
• gender (string, M, F, O)

Ejemplo cURL

curl -X POST "http://worklist.dicomline.com/api/v1/patients" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: TU_API_KEY" \
  -d '{
    "identification_number": "87654321",
    "identification_type": "NI",
    "first_name": "Ana",
    "last_name": "García",
    "date_of_birth": "1995-05-15",
    "gender": "F"
  }'

Request Body (JSON):

{
    "identification_number": "87654321",
    "identification_type": "NI",
    "first_name": "Ana",
    "last_name": "García",
    "date_of_birth": "1995-05-15",
    "gender": "F"
}

{
    "id": "01955b20-8025-7091-bfec-607faeb3fa20",
    "identification_number": "87654321",
    "identification_type": "NI",
    "first_name": "Ana",
    "last_name": "García",
    "date_of_birth": "1995-05-15",
    "gender": "F",
    "created_at": "2024-01-01 12:00:00"
}

Response (Error de Validación 422 Unprocessable Entity):

[
    {
        "field": "identification_number",
        "message": "Ya existe un paciente registrado con este número de documento en su centro."
    }
]

---

Actualiza un paciente existente utilizando su identificador único (uuid).

Parámetros URL:

• {id}: string (UUID del paciente)

Ejemplo cURL

curl -X PUT "http://worklist.dicomline.com/api/v1/patients/01955b20-8025-7091-bfec-607faeb3fa20" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: TU_API_KEY" \
  -d '{
    "first_name": "Ana María",
    "last_name": "García"
  }'

Request Body (JSON):

{
    "first_name": "Ana María",
    "last_name": "García"
}

{
    "id": "01955b20-8025-7091-bfec-607faeb3fa20",
    "identification_number": "87654321",
    "identification_type": "NI",
    "first_name": "Ana María",
    "last_name": "García",
    "date_of_birth": "1995-05-15",
    "gender": "F",
    "created_at": "2024-01-01 12:00:00"
}

---

Elimina un paciente utilizando su identificador único (uuid).

Parámetros URL:

• {id}: string (UUID del paciente)

Ejemplo cURL

curl -X DELETE "http://worklist.dicomline.com/api/v1/patients/01955b20-8025-7091-bfec-607faeb3fa20" \
  -H "X-Api-Key: TU_API_KEY"

Response (Success 204 No Content): Sin cuerpo en la respuesta.

---

Notas Finales

• Consulte Common.md para los códigos de estado y la estructura de errores globales.
• Todos los pacientes quedan asociados automáticamente al tenant_id del token o API Key utilizado. No es necesario ni posible especificar tenant_id manualmente.