> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brelio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestiona pacientes

> Busca, lee, crea, actualiza y archiva los datos administrativos de los pacientes con la API REST.

Las operaciones de pacientes cubren los datos administrativos: nombre, datos de contacto, fecha de nacimiento, códigos y estado. La historia clínica y las notas todavía no están en la API.

## Antes de empezar

* El [área de datos](https://docs.brelio.com/es/concepts/data-areas.md) `patients` de la clínica está activada y se ha aceptado el acceso a datos de pacientes para tu credencial. Si no, cada llamada de esta guía responde `403 DATA_AREA_OFF` o `403 PATIENT_DATA_CONSENT_REQUIRED`.
* Tu clave tiene `patients.administrative.read`, y `.create`, `.update` o `.archive` para las escrituras.
* Cada ficha de paciente que recibes cuenta para el techo de [2.000 fichas por hora](https://docs.brelio.com/es/concepts/rate-limits.md) de tu credencial.

```bash theme={null}
export BRELIO_API_KEY="…"
export BRELIO=https://api.brelio.app/v1
```

## Buscar

`search` encuentra por nombre, email, teléfono, código de paciente, código interno o número de identificación, igual que el buscador de Brelio:

```bash theme={null}
curl -s "$BRELIO/patients?search=ana&limit=10" \
  -H "Authorization: Bearer $BRELIO_API_KEY"
```

```json Respuesta theme={null}
{
  "data": [
    {
      "id": "c588eb77-12e8-4042-8cce-48fb0555408f",
      "code": "PAC-0001",
      "firstName": "Ana",
      "lastName": "Pérez",
      "birthDate": null,
      "sex": null,
      "email": "ana.perez@example.com",
      "phone": null,
      "status": "active",
      "identificationNumber": null,
      "identificationType": "dni",
      "internalCode": null,
      "responsibleId": null,
      "admittedAt": null,
      "lastSessionAt": null,
      "nextSessionAt": null,
      "archivedAt": null,
      "version": "2026-11-09 17:59:08.46+00",
      "createdAt": "2026-11-09T17:59:08.460Z",
      "updatedAt": "2026-11-09T17:59:08.460Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

Filtra por `status` (`active`, `inactive`, `discharged`). Los resultados se ordenan por apellido y están [paginados](https://docs.brelio.com/es/concepts/pagination.md).

## Leer uno

```bash theme={null}
curl -s "$BRELIO/patients/$PATIENT_ID" \
  -H "Authorization: Bearer $BRELIO_API_KEY"
```

## Crear

Busca antes para no crear un duplicado. Solo `firstName` es obligatorio.

```bash theme={null}
curl -s -X POST "$BRELIO/patients" \
  -H "Authorization: Bearer $BRELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "firstName": "Laura",
    "lastName": "Serra",
    "birthDate": "1990-05-14",
    "email": "laura.serra@example.com",
    "phone": "+34 600 123 456"
  }'
```

```json 201 Created theme={null}
{
  "id": "d4ddb883-ee85-46d1-9719-5e0f7e585392",
  "code": "PAC-0003",
  "firstName": "Laura",
  "lastName": "Serra",
  "birthDate": "1990-05-14",
  "email": "laura.serra@example.com",
  "phone": "+34 600 123 456",
  "status": "active",
  "version": "2026-11-09 17:59:58.817+00",
  "…": "…"
}
```

* `sex` acepta `male`, `female` u `other`.
* `centerId` vincula al paciente con un centro; por defecto, el centro principal de la clínica.
* Se aplican los mismos límites del plan que en la web, como el límite de pacientes activos.

## Actualizar

Envía solo los campos que cambian, con la `version` que leíste como `expectedVersion`. `null` vacía un campo; `lastName` no se puede vaciar.

```bash theme={null}
curl -s -X PATCH "$BRELIO/patients/$PATIENT_ID" \
  -H "Authorization: Bearer $BRELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "expectedVersion": "2026-11-09 17:59:58.817+00",
    "phone": "+34 600 765 432",
    "email": null
  }'
```

La respuesta es el paciente actualizado con una `version` nueva. Una `expectedVersion` antigua responde `409 VERSION_CONFLICT`; vuelve a leer el paciente. Consulta la [concurrencia](https://docs.brelio.com/es/concepts/concurrency.md).

## Archivar

Archivar retira a un paciente: desaparece de las listas y las búsquedas, y `GET /v1/patients/{id}` responde `404 PATIENT_NOT_FOUND`, pero su historial se conserva y se puede recuperar en Brelio.

```bash theme={null}
curl -s -X POST "$BRELIO/patients/$PATIENT_ID/archive" \
  -H "Authorization: Bearer $BRELIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"expectedVersion": "2026-11-09 17:59:58.866+00"}'
```

```json Respuesta theme={null}
{ "id": "d4ddb883-…", "status": "active", "archivedAt": "2026-11-09T17:59:58.967Z", "version": "2026-11-09 17:59:58.967+00", "…": "…" }
```

`status` y `archivedAt` son independientes: un paciente archivado conserva su último estado. No existe el borrado.

## Sincroniza los pacientes con otro sistema

```python sync_patients.py theme={null}
import os
import requests

BASE = "https://api.brelio.app/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['BRELIO_API_KEY']}"}


def patients(**filters):
    cursor = None
    while True:
        params = {**filters, "limit": 100, **({"cursor": cursor} if cursor else {})}
        response = requests.get(f"{BASE}/patients", params=params, headers=HEADERS, timeout=10)
        if response.status_code == 429:
            raise RuntimeError(f"Rate limited; retry in {response.headers['Retry-After']} s")
        response.raise_for_status()
        page = response.json()
        yield from page["data"]
        if not page["has_more"]:
            return
        cursor = page["next_cursor"]


for patient in patients(status="active"):
    print(patient["code"], patient["firstName"], patient["lastName"], patient["email"])
```

Prográmalo en horas tranquilas y ten en cuenta el techo de 2.000 fichas por hora en clínicas grandes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.