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

# Read billing with the API

> Read invoices, pending charges, receipts, a patient's balance and their bonos with the Brelio REST API or from an assistant over MCP.

The billing operations read what Brelio's Facturación screen shows: invoices, what each patient owes (charges), money received (receipts), their balance and their bonos. For now they are read-only; recording payments, creating invoices and selling bonos come later. Issuing invoices (numbering, VeriFactu and TicketBAI) stays in the web.

## Before you start

* The clinic's `billing` [data area](https://docs.brelio.com/en/concepts/data-areas.md) is on. It is off by default; otherwise every call answers `403 DATA_AREA_OFF`.
* Your key has `billing.invoices.read` for invoices, `billing.payments.read` for charges, receipts and balances, and `billing.packages.read` for bonos.
* Responses name the patient by `id` only, never by name or fiscal data. For the name, read the patient with `GET /patients/{id}` (area `patients`).
* Every amount is in **cents**, with its `currency` (usually `EUR`).

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

## Does this patient owe anything?

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

```json Response 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` is what they owe and `credit` is money they paid that is not applied to anything yet. They are reported apart, never netted, as on the patient's record. `uninvoiced` is the total of their open charges that no invoice documents yet, collected or not.

## What they owe, session by session

Each priced session, bono sale or loose concept is a **charge**. Its `settlement` derives from what was collected: `pending`, `partial` or `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"
```

Also filter by `uninvoiced=true` (what is left to invoice) or by service date with `from` and `to` (`YYYY-MM-DD`). A voided charge (`status: "voided"`) owes nothing: courtesy, recording error, cancelled appointment or covered by a bono.

## Receipts

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

Each receipt says how much was received, by which method (`cash`, `card`, `bizum`, `transfer`, `other`) and which charges it paid (`applications`). A corrected receipt is `reversed` and counts for nothing; it only appears with `includeReversed=true`. The receipt's internal notes never leave through the API.

## Invoices

```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"
```

A draft has `number: null`; the fiscal number is given on issue. `pending` is what is left to collect. A rectificativa (series `R`) points to the invoice it corrects with `correctsInvoiceId`. Voided invoices only appear with `includeVoided=true`. To read the lines:

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

Each line carries its concept, quantity, unit price before tax, discount, VAT rate and, when it documents a charge, its `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` is the sessions left and `total` the sessions it was sold with. With a personal credential (MCP or a personal key) you read only the bonos of patients of your centers; the others answer `404`, as if they did not exist.

## From an assistant

Over MCP the same operations are `brelio_list_invoices`, `brelio_get_invoices`, `brelio_list_charges`, `brelio_list_receipts`, `brelio_get_balances` and `brelio_list_packages`. They appear only once the clinic turns Billing on and you hold the permission. Try: "Which sessions has Ana Pérez not paid yet?": the assistant finds the patient and reads their charges.


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