> ## 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.

# Consulta la facturación con la API

> Lee las facturas, los cargos pendientes, los cobros, el saldo de un paciente y sus bonos con la API REST de Brelio o desde un asistente por MCP.

Las operaciones de facturación leen lo mismo que la pantalla Facturación de Brelio: facturas, lo que debe cada paciente (cargos), el dinero recibido (cobros), su saldo y sus bonos. Por ahora son solo de lectura; registrar cobros, crear facturas o vender bonos llega después. Emitir facturas (numeración, VeriFactu y TicketBAI) se queda en la web.

## Antes de empezar

* El [área de datos](https://docs.brelio.com/es/concepts/data-areas.md) `billing` de la clínica está activada. Está desactivada por defecto; si no, cada llamada responde `403 DATA_AREA_OFF`.
* Tu clave tiene `billing.invoices.read` para las facturas, `billing.payments.read` para cargos, cobros y saldos, y `billing.packages.read` para los bonos.
* Las respuestas identifican al paciente solo por su `id`, nunca por su nombre ni sus datos fiscales. Para el nombre, lee el paciente con `GET /patients/{id}` (área `patients`).
* Todos los importes van en **céntimos** y con su moneda (`currency`, normalmente `EUR`).

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
export BRELIO_API_KEY="…"
export BRELIO=https://api.brelio.app/v1
```

## ¿Este paciente debe algo?

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -s "$BRELIO/balances/$PATIENT_ID" \
  -H "Authorization: Bearer $BRELIO_API_KEY"
```

```json Respuesta theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "id": "7c2e4a6b-1d3f-4b5a-8c9d-0e1f2a3b4c5d",
  "pending": 9000,
  "received": 10000,
  "credit": 1000,
  "uninvoiced": 18000,
  "currency": "EUR"
}
```

`pending` es lo que debe y `credit` el dinero que pagó y todavía no se ha aplicado a nada. Se dan por separado, nunca compensados, igual que en la ficha del paciente. `uninvoiced` es el total de sus cargos abiertos que ninguna factura documenta todavía, cobrados o no.

## Qué debe, sesión a sesión

Cada sesión con precio, venta de bono o concepto suelto es un **cargo**. Su estado de cobro (`settlement`) sale de lo cobrado: `pending`, `partial` o `settled`.

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -s "$BRELIO/charges?patientId=$PATIENT_ID&settlement=pending" \
  -H "Authorization: Bearer $BRELIO_API_KEY"
```

Filtra también por `uninvoiced=true` (lo que falta por facturar) o por fecha de servicio con `from` y `to` (`YYYY-MM-DD`). Un cargo anulado (`status: "voided"`) no debe nada: cortesía, error de registro, cita cancelada o cubierto con bono.

## Cobros

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -s "$BRELIO/receipts?patientId=$PATIENT_ID" \
  -H "Authorization: Bearer $BRELIO_API_KEY"
```

Cada cobro dice cuánto se recibió, con qué método (`cash`, `card`, `bizum`, `transfer`, `other`) y a qué cargos se aplicó (`applications`). Un cobro corregido queda `reversed` y no cuenta; solo aparece con `includeReversed=true`. Las notas internas del cobro no salen por la API.

## Facturas

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -s "$BRELIO/invoices?patientId=$PATIENT_ID&status=issued" \
  -H "Authorization: Bearer $BRELIO_API_KEY"
```

Una factura en borrador tiene `number: null`; el número fiscal se asigna al emitirla. `pending` es lo que queda por cobrar. Una rectificativa (serie `R`) apunta a la factura que corrige con `correctsInvoiceId`. Las anuladas solo aparecen con `includeVoided=true`. Para ver las líneas:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -s "$BRELIO/invoices/$INVOICE_ID" \
  -H "Authorization: Bearer $BRELIO_API_KEY"
```

Cada línea lleva su concepto, cantidad, precio unitario sin impuestos, descuento, tipo de IVA y, si documenta un cargo, su `chargeId`.

## Bonos

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
curl -s "$BRELIO/packages?patientId=$PATIENT_ID" \
  -H "Authorization: Bearer $BRELIO_API_KEY"
```

`remaining` son las sesiones que le quedan y `total` las que tenía al venderse. Con una credencial personal (MCP o clave personal) solo se leen los bonos de pacientes de tus centros; los demás responden `404`, como si no existieran.

## Desde un asistente

Por MCP, las mismas operaciones son `brelio_list_invoices`, `brelio_get_invoices`, `brelio_list_charges`, `brelio_list_receipts`, `brelio_get_balances` y `brelio_list_packages`. Solo aparecen cuando la clínica activa Facturación y tú tienes el permiso. Prueba: «¿Qué sesiones tiene pendientes de pago Ana Pérez?»: el asistente busca a la paciente y lee sus cargos.


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