Concurrencia optimista (expectedVersion)

Una recepcionista edita un paciente en Brelio mientras tu integración actualiza el mismo paciente. Sin una comprobación, la última escritura gana sin avisar. Brelio lo evita: cada registro tiene una version, y cada cambio dice en qué versión se basa.

La regla

Lee el registro. Su version viene en la respuesta.
Envía ese valor sin tocarlo como expectedVersion en el cambio.
Si alguien cambió el registro entretanto, Brelio responde 409 y no cambia nada. Vuelve a leerlo, decide otra vez y reintenta.

# 1. Leer
curl https://api.brelio.app/v1/patients/$PATIENT_ID \
  -H "Authorization: Bearer $BRELIO_API_KEY"
# → { "id": "…", "phone": "+34 600 123 456", "version": "2026-11-09 17:59:58.817+00", … }

# 2. Cambiar, a partir de esa versión
curl -X PATCH https://api.brelio.app/v1/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"}'
# → 200, con la nueva "version"

Enviar otra vez la versión antigua responde:

409 VERSION_CONFLICT

{
  "type": "https://api.brelio.app/problems/version-conflict",
  "title": "Request refused",
  "status": 409,
  "code": "VERSION_CONFLICT",
  "detail": "Patient changed since it was read: d4ddb883-ee85-46d1-9719-5e0f7e585392",
  "request_id": "31adfde0-8936-43e6-9330-4abc092d6d20",
  "params": { "id": "d4ddb883-ee85-46d1-9719-5e0f7e585392" }
}

Trata la versión como opaca

Copia version exactamente como la leíste. No la construyas, no la interpretes, no la compares ni la incrementes. Su forma depende del recurso y puede cambiar:

Recurso	`version` tiene esta forma	Tipo de `expectedVersion`
Paciente	`"2026-11-09 17:59:58.817+00"`	string
Cita	`"2"`	string
Webhook	`2`	entero
Área de datos (`/v1/platform-policy`)	`0`	entero

Envíala con el tipo que te dio el recurso: string donde version es un string, número donde es un número.

Operaciones que la necesitan

Operación	Código de conflicto
`PATCH /v1/patients/{id}`, `POST /v1/patients/{id}/archive`	`VERSION_CONFLICT`
`POST /v1/appointments/{id}/reschedule`, `POST /v1/appointments/{id}/cancel`	`VERSION_CONFLICT`
`POST /v1/webhooks/{id}/rotate-secret`, `POST /v1/webhooks/{id}/delete`	`WEBHOOK_VERSION_CONFLICT`
`PATCH /v1/platform-policy/{id}`	`DATA_POLICY_VERSION_CONFLICT`

Las creaciones no la llevan: no hay nada que pisar.

Qué hacer con un 409

No repitas la misma petición: volverá a fallar. Lee el registro, comprueba si tu cambio sigue teniendo sentido con los datos nuevos (puede que la cita ya esté cancelada) y envía una petición nueva con la nueva versión y una Idempotency-Key nueva.

Node.js

const BASE = 'https://api.brelio.app/v1'
const AUTH = { Authorization: `Bearer ${process.env.BRELIO_API_KEY}` }

async function updatePhone(patientId, phone) {
  for (let attempt = 0; attempt < 3; attempt++) {
    const patient = await (await fetch(`${BASE}/patients/${patientId}`, { headers: AUTH })).json()
    const response = await fetch(`${BASE}/patients/${patientId}`, {
      method: 'PATCH',
      headers: { ...AUTH, 'Content-Type': 'application/json', 'Idempotency-Key': crypto.randomUUID() },
      body: JSON.stringify({ expectedVersion: patient.version, phone }),
    })
    if (response.status !== 409) return response.json()
  }
  throw new Error('The patient keeps changing; try later')
}

Empezar

Conceptos

Guías

Referencia MCP

Referencia

Concurrencia optimista (expectedVersion)

La regla

Trata la versión como opaca

Operaciones que la necesitan

Qué hacer con un 409

​La regla

​Trata la versión como opaca

​Operaciones que la necesitan

​Qué hacer con un 409

La regla

Trata la versión como opaca

Operaciones que la necesitan

Qué hacer con un 409