Docfav Public API

Get the authenticated user information.

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "fullname": "John Doe",
    "firstname": "John",
    "lastname": "Doe",
    "timezone": "Europe/Madrid",
    "locale": "es_ES",
    "country_code": "ES",
    "status": "active"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

List all professional profiles for the authenticated user.

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "type": "professional",
      "back_office_clinic_id": "550e8400-e29b-41d4-a716-446655440002",
      "last_selected": true
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

List all back office clinics associated with the authenticated user.

{
  "data": [
    {
      "id": "6edafcff-732d-4cce-8f16-f0d50d2b22b2",
      "name": "Central Clinic",
      "business_name": "Central Clinic S.L.",
      "vat_number": "B12345678",
      "address": "Main Street 1",
      "city": "Madrid",
      "zip_code": "28001",
      "has_logo": true,
      "subscription_status": "active"
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Get details of a specific back office clinic.

{
  "data": {
    "id": "6edafcff-732d-4cce-8f16-f0d50d2b22b2",
    "name": "Central Clinic",
    "business_name": "Central Clinic S.L.",
    "vat_number": "B12345678",
    "issuer_type": "company",
    "address": "Main Street 1",
    "city": "Madrid",
    "zip_code": "28001",
    "has_logo": true,
    "custom_email": "[email protected]",
    "default_appointments_behaviour": "confirmed",
    "subscription_status": "active"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

List all calendars for a clinic. A calendar represents a physical location.

{
  "data": [
    {
      "id": "6e8e058e-f01b-454b-8d49-77589dadc7bd",
      "name": "Centro Getxo",
      "address": "Getxo, España",
      "city": "Getxo",
      "zip_code": "48993",
      "type": "onsite",
      "is_active": true
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

List all staff members for a clinic.

{
  "data": [
    {
      "id": "e727a18f-edf0-45f5-a866-d2c629113758",
      "name": "Pedro",
      "surname": "García",
      "fullname": "Pedro García",
      "email": "[email protected]",
      "is_active": true
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

List staff calendars for a clinic. A staff calendar links a staff member to a calendar with specific settings. Supports optional filtering by calendar or staff.

{
  "data": [
    {
      "id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
      "back_office_staff_id": "e727a18f-edf0-45f5-a866-d2c629113758",
      "calendar_id": "6e8e058e-f01b-454b-8d49-77589dadc7bd",
      "email": "[email protected]",
      "telephone": "+34600000000",
      "slot_duration": 15,
      "is_active": true,
      "timezone": "Europe/Madrid"
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

List the clinic service catalogue (treatments). Optionally filter by staff member (staff_id) or calendar/gabinete (calendar_id), and expand the staff/calendar tuples each service is configured for via expand=staff_calendars. Amounts are returned in cents.

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Fisioterapia",
      "service_category": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
      "amount": 5000,
      "duration": 30,
      "price_type": 1,
      "color": "#4CAF50",
      "is_active": true,
      "vat_rate": "21",
      "note": null,
      "location_type": "onsite",
      "scope": "individual",
      "max_participants": null,
      "position": 1,
      "staff_calendars": [
        { "id": "9cf404c3-951e-4895-8a14-18c68bd91ef4", "staff_id": "e727a18f-edf0-45f5-a866-d2c629113758", "calendar_id": "6e8e058e-f01b-454b-8d49-77589dadc7bd" }
      ]
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

List all clients for a clinic with pagination, filtering and sorting.

{
  "data": {
    "clients": [
      {
        "id": "68b70480-e924-4841-8038-e2e695971ff6",
        "client_number": 1234,
        "firstname": "Carlos",
        "lastname": "Garcia",
        "fullname": "Carlos Garcia",
        "email": "[email protected]",
        "phone": "+34600000000",
        "gender": "male",
        "date_of_birth": { "dayOfBirth": "15", "monthOfBirth": "03", "yearOfBirth": "1990" },
        "address": "Calle Mayor 1",
        "city": "Madrid",
        "province": "Madrid",
        "post_code": "28001",
        "country_code": "ES",
        "id_card": "12345678A",
        "note": "Paciente habitual",
        "tags": ["vip"],
        "is_active": true,
        "is_company": false,
        "walk_in": false,
        "receive_reminders": true,
        "receive_campaigns": true,
        "has_photo": false,
        "created_at": "2026-01-15T10:00:00+00:00"
      }
    ],
    "meta": {
      "limit": 10,
      "offset": 0,
      "total": 156
    }
  },
  "errors": [],
  "meta": { "timestamp": "2026-03-04T12:00:00+00:00", "api_version": "v1" }
}

Get details of a specific client by ID.

{
  "data": {
    "id": "68b70480-e924-4841-8038-e2e695971ff6",
    "client_number": 1234,
    "firstname": "Carlos",
    "lastname": "García",
    "fullname": "Carlos García",
    "email": "[email protected]",
    "phone": "+34600000000",
    "gender": "male",
    "date_of_birth": { "dayOfBirth": "15", "monthOfBirth": "03", "yearOfBirth": "1990" },
    "address": "Calle Mayor 1",
    "city": "Madrid",
    "province": "Madrid",
    "post_code": "28001",
    "country_code": "ES",
    "id_card": "12345678A",
    "note": "Paciente habitual",
    "tags": ["vip"],
    "is_active": true,
    "is_company": false,
    "walk_in": false,
    "receive_reminders": true,
    "receive_campaigns": true,
    "has_photo": false,
    "created_at": "2026-01-15T10:00:00+00:00"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Search clients by name, surname, email, phone or ID card. Supports partial and accent-insensitive matching.

{
  "data": [
    {
      "id": "68b70480-e924-4841-8038-e2e695971ff6",
      "fullname": "Carlos García",
      "email": "[email protected]",
      "telephone": "+34600000000",
      "client_number": 1234
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Create a new client. firstname/lastname/phone are the canonical field names (they match what the GET endpoints return); name/surname/telephone are accepted as legacy aliases. If both forms are sent in the same request, the canonical value wins. The response includes both the canonical fields and the legacy aliases for backwards compatibility.

{
  "firstname": "Carlos",
  "lastname": "García",
  "phone": "+34600000000",
  "email": "[email protected]"
}

{
  "data": {
    "id": "68b70480-e924-4841-8038-e2e695971ff6",
    "client_number": 1234,
    "firstname": "Carlos",
    "lastname": "García",
    "fullname": "Carlos García",
    "email": "[email protected]",
    "phone": "+34600000000",
    "name": "Carlos",
    "surname": "García",
    "telephone": "+34600000000"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Get staff working hours (schedules) for a date range. Returns day offs and time offs as well.

{
  "data": [
    {
      "staff_id": "e727a18f-edf0-45f5-a866-d2c629113758",
      "staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
      "name": "Pedro García",
      "schedules": [
        {
          "day": "THURSDAY",
          "date": "2026-02-05",
          "type": "REGULAR_DAY",
          "hours": [
            { "start": "08:00", "end": "14:00", "type": "WORKING_DAY" },
            { "start": "16:00", "end": "20:00", "type": "WORKING_DAY" }
          ]
        }
      ]
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Get all occupied time slots: appointments, time reservations, group reservations, day offs, and working hours.

{
  "data": [
    {
      "staff_id": "e727a18f-edf0-45f5-a866-d2c629113758",
      "staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
      "name": "Pedro García",
      "working_hours": [
        { "date": "2026-02-05", "from": "08:00", "to": "20:00", "type": "WORKING_DAY" }
      ],
      "day_offs": [],
      "time_offs": [],
      "appointments": [
        {
          "id": "31bd18a6-52be-4ad3-9b9f-78b684fc6f2a",
          "from": "2026-02-05T17:00:00Z",
          "to": "2026-02-05T17:30:00Z",
          "behaviour": "confirmed",
          "client_id": "68b70480-e924-4841-8038-e2e695971ff6",
          "service_name": "Fisioterapia"
        }
      ],
      "time_reservations": [
        {
          "id": "ac14f29b-89f0-4d16-873c-772dae27650f",
          "from": "2026-02-05T13:00:00Z",
          "to": "2026-02-05T14:00:00Z",
          "reason": "Lunch break"
        }
      ],
      "group_reservations": []
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Check if a specific time slot is available. Returns conflicts if not available.

{
  "data": {
    "available": false,
    "requested": {
      "from": "2026-02-05T13:00:00Z",
      "to": "2026-02-05T14:00:00Z",
      "staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4"
    },
    "conflicts": [
      {
        "type": "time_reservation",
        "id": "ac14f29b-89f0-4d16-873c-772dae27650f",
        "from": "2026-02-05T13:00:00Z",
        "to": "2026-02-05T14:00:00Z",
        "reason": "Lunch break"
      }
    ]
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Get all time slots with availability status. Useful for rendering a booking calendar.

{
  "data": [
    {
      "staff_id": "e727a18f-edf0-45f5-a866-d2c629113758",
      "staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
      "name": "Pedro García",
      "timezone": "Europe/Madrid",
      "slot_duration": 15,
      "available_slots": [
        {
          "date": "2026-02-05",
          "day": "THURSDAY",
          "type": "REGULAR_DAY",
          "slots": [
            { "from": "2026-02-05T08:00:00Z", "to": "2026-02-05T08:15:00Z", "available": true, "hour_type": "WORKING_DAY" },
            { "from": "2026-02-05T13:00:00Z", "to": "2026-02-05T13:15:00Z", "available": false, "hour_type": "WORKING_DAY" }
          ]
        }
      ]
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Convenience endpoint for conversational agents: resolves the calendar (gabinete) from calendar_name and returns the same availability payload as the by-id endpoint, including the optional period/weekdays/date filters. Name matching is Unicode-aware and case-insensitive (Á ↔ á, Í ↔ í). By default accents matter; pass accent_insensitive=true to also ignore diacritics (Podologia ↔ Podología). Returns 404 (CALENDAR_NOT_FOUND) when no calendar matches and 409 (CALENDAR_NAME_AMBIGUOUS) when more than one calendar shares the name — candidates are listed in meta.candidates.

{
  "data": [
    {
      "staff_id": "e727a18f-edf0-45f5-a866-d2c629113758",
      "staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
      "name": "Pedro García",
      "timezone": "Europe/Madrid",
      "slot_duration": 15,
      "available_slots": [
        {
          "date": "2026-02-05",
          "day": "THURSDAY",
          "type": "REGULAR_DAY",
          "slots": [
            { "from": "2026-02-05T08:00:00Z", "to": "2026-02-05T08:15:00Z", "available": true, "hour_type": "WORKING_DAY" }
          ]
        }
      ]
    }
  ],
  "errors": [],
  "meta": {
    "timestamp": "2026-02-05T12:00:00+00:00",
    "api_version": "v1",
    "calendar": { "id": "5c3f...", "name": "Gabinete 1" }
  }
}

Get appointments, time reservations, group reservations, and recurring events for a date range. Maximum range: 7 days.

{
  "data": {
    "appointments": [
      {
        "id": "31bd18a6-52be-4ad3-9b9f-78b684fc6f2a",
        "client_id": "68b70480-e924-4841-8038-e2e695971ff6",
        "client_name": "Carlos Garcia",
        "service_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "service_name": "Consulta general",
        "calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
        "staff_id": "e727a18f-edf0-45f5-a866-d2c629113758",
        "booked_from": "2026-03-06T09:00:00Z",
        "booked_to": "2026-03-06T09:30:00Z",
        "status": "confirmed",
        "sale_status": "pending",
        "note": "Primera visita",
        "price": 5000,
        "source": "backoffice"
      }
    ],
    "time_reservations": [
      {
        "id": "ac14f29b-89f0-4d16-873c-772dae27650f",
        "back_office_staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
        "name": "Lunch break",
        "booked_from": "2026-03-06T12:00:00Z",
        "booked_to": "2026-03-06T13:00:00Z",
        "note": null
      }
    ],
    "group_reservations": [],
    "recurring_events": [
      {
        "id": "b5c6d7e8-f9a0-1234-5678-9abcdef01234",
        "back_office_staff_calendar_id": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
        "name": "Weekly team meeting",
        "booked_from": "2026-03-06T08:00:00",
        "booked_to": "2026-03-06T08:30:00",
        "is_recurring_event": true,
        "original_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "timezone": "Europe/Madrid"
      }
    ]
  },
  "errors": [],
  "meta": { "timestamp": "2026-03-06T12:00:00+00:00", "api_version": "v1" }
}

IMPORTANT — Recurring Events (recurring_events):
Recurring events are generated from EventSchedules and calculated based on the clinic's local timezone, not UTC. To receive them, you MUST provide both local_start_date and local_end_date in YYYY-MM-DD format (e.g., 2026-03-06). If these parameters are omitted, the recurring_events array will be empty. The start_date/end_date parameters (UTC, ISO 8601) are used for appointments, time_reservations, and group_reservations only.

Create one or more appointments.

{
  "client": "68b70480-e924-4841-8038-e2e695971ff6",
  "timezone": "Europe/Madrid",
  "appointments": [
    {
      "service": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "back_office_staff_calendar": "9cf404c3-951e-4895-8a14-18c68bd91ef4",
      "from": "2026-02-05T15:00:00Z",
      "to": "2026-02-05T15:30:00Z",
      "note": "First consultation"
    }
  ],
  "send_reminder": true,
  "behaviour": "confirmed"
}

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "appointment_number": 12346,
      "client_id": "68b70480-e924-4841-8038-e2e695971ff6",
      "service_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "service_name": "Fisioterapia",
      "booked_from": "2026-02-05T15:00:00Z",
      "booked_to": "2026-02-05T15:30:00Z",
      "status": "confirmed",
      "note": "First consultation"
    }
  ],
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Change the behaviour (status) of an appointment. Use this to confirm, cancel, mark as no-show, or revert to unconfirmed.

{
  "behaviour": "cancelled"
}

{
  "data": {
    "appointment_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "behaviour": "cancelled",
    "message": "Appointment behaviour updated successfully"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

Delete an appointment permanently. The appointment id is obtained from the availability or create endpoints.

{
  "data": {
    "message": "Appointment deleted successfully"
  },
  "errors": [],
  "meta": { "timestamp": "2026-02-05T12:00:00+00:00", "api_version": "v1" }
}

List sales for a clinic (light view, paginated, ordered by saleNumber DESC). Each row carries only the aggregate-level fields (id, saleNumber, status, saleStatus, createdAt, paidAt, invoiceId, pit). Products and payments are NOT included — drill down with GET /sales/{saleNumber} for the full detail. The date window applies to the sale's created_at, is required, and capped at 366 days.

{
  "data": {
    "sales": [
      {
        "id": "sale-uuid",
        "saleNumber": 1234,
        "status": "active",
        "saleStatus": "paid_partially",
        "createdAt": "2026-05-20T11:30:00Z",
        "paidAt": null,
        "invoiceId": "550e8400-e29b-41d4-a716-446655440099",
        "pit": "0.00"
      }
    ],
    "meta": { "limit": 50, "offset": 0, "total": 1 }
  },
  "errors": [],
  "meta": { "timestamp": "2026-05-20T12:00:00+00:00", "api_version": "v1" }
}

Get the full sale aggregate by its per-clinic sale number: payments[], appointments[], clientVouchers[], clientItems[], clientBudgets[], clientSubscriptions[], invoiceId, saleStatus, pit, receipt. Use the saleNumber returned by /payments or /sales to drill down.

{
  "data": {
    "id": "sale-uuid",
    "saleNumber": 1234,
    "payments": [],
    "pit": null,
    "invoiceIssuer": null,
    "discountValue": null,
    "discountType": "amount",
    "discountScope": "sale",
    "discountedProducts": [],
    "appointments": [],
    "clientVouchers": [],
    "clientItems": [],
    "clientBudgets": [],
    "clientSubscriptions": [],
    "invoiceId": null,
    "receipt": null
  },
  "errors": [],
  "meta": { "timestamp": "2026-05-20T12:00:00+00:00", "api_version": "v1" }
}

List sold products for a clinic, one row per line item, ordered by product/appointment date DESC. Monetary values (subTotal, tax, irpf, price, amountPaid, commission) come in the clinic's local currency (not cents). amountPaid is the portion of price already collected — compare against price to spot partial payments. The client's DNI is exposed under client.idCard. Use by_payments=true to swap the date window semantics from product/appointment date to payment registration date (Spanish 'fecha de cobro') — handy for cash-flow reconciliation by charge date. Drill-downs: sale.sequenceNumber → GET /sales/{saleNumber}; invoice.id (when non-null) → GET /invoices/{id}. Date window is required and capped at 366 days.

{
  "data": {
    "products": [
      {
        "id": "product-uuid",
        "type": "appointment",
        "name": "Consulta inicial",
        "sequenceNumber": 4521,
        "subTotal": 50.00,
        "tax": 10.50,
        "irpf": 0.00,
        "price": 60.50,
        "amountPaid": 60.50,
        "commission": 0.00,
        "sale": {
          "id": "sale-uuid",
          "sequenceNumber": 1234,
          "paymentStatus": "completed",
          "paymentMethod": "tarjeta",
          "paidAt": "2026-05-20T11:30:00Z"
        },
        "client": {
          "id": "client-uuid",
          "name": "María García",
          "phone": "+34600000000",
          "clientNumber": 56,
          "idCard": "12345678A"
        },
        "employee": { "id": "staff-uuid", "name": "Dra. López" },
        "calendar": { "id": "cal-uuid", "name": "Consulta 1" },
        "invoice": { "id": "invoice-uuid", "sequenceNumber": 99 }
      }
    ],
    "meta": { "limit": 50, "offset": 0, "total": 1 }
  },
  "errors": [],
  "meta": { "timestamp": "2026-05-20T12:00:00+00:00", "api_version": "v1" }
}

List payment transactions for a clinic, ordered by paidAt DESC. amountRefunded semantics: on PAYMENT rows, the cumulative amount already returned FROM this specific charge. On REFUND rows, always 0 (refunds are not refundable). Do NOT use amountRefunded to compute period nets — sum amount instead. Drill-down: every row carries saleNumber (per-clinic sequential ID). Use it with GET /sales/{saleNumber} to fetch the full sale (products, invoice, aggregated payments). The optional client_id filter walks payments → sale_payments → sales → products (JOINED inheritance) and matches the client_id stored on each Product subclass. Date window is required and capped at 366 days.

{
  "data": {
    "payments": [
      {
        "id": "payment-uuid",
        "sequence": 4321,
        "amount": 60.50,
        "paymentMethod": "tarjeta",
        "saleNumber": 1234,
        "paidAt": "2026-05-20T11:35:00Z",
        "user": "[email protected]",
        "amountRefunded": 0,
        "transactionType": "PAYMENT",
        "customPaymentMethodId": null
      },
      {
        "id": "refund-uuid",
        "sequence": 4322,
        "amount": -5.00,
        "paymentMethod": "tarjeta",
        "saleNumber": 1234,
        "paidAt": "2026-05-21T09:00:00Z",
        "user": "[email protected]",
        "amountRefunded": 0,
        "transactionType": "REFUND",
        "customPaymentMethodId": null
      }
    ],
    "meta": { "limit": 50, "offset": 0, "total": 2 }
  },
  "errors": [],
  "meta": { "timestamp": "2026-05-20T12:00:00+00:00", "api_version": "v1" }
}

List invoices and rectified invoices (unified, light view), paginated, ordered by issue date DESC. Each row carries a type discriminator (invoice / rectified_invoice). On rectified_invoice rows, references_invoice_id points to the original invoice. Status semantics: created (live), rectified (a rectified_invoice references it), voided. links.pdf gives a relative URL to download the invoice PDF. For the optional TicketBai XML link, use the detail endpoint. For full detail (lines, totals, addresses), use GET /invoices/{invoiceId}. The date window applies to the document's issue date and is capped at 366 days.

{
  "data": {
    "invoices": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440099",
        "type": "invoice",
        "invoice_number": "A-0001",
        "date": "2026-05-20",
        "status": "created",
        "client": {
          "id": "client-uuid",
          "name": "María García",
          "id_card": "12345678A",
          "number": 56
        },
        "business_name": "María García",
        "references_invoice_id": null,
        "rectification": null,
        "links": {
          "pdf": "/api-connector/v1/backofficeclinics/{backOfficeClinicId}/invoices/550e8400-e29b-41d4-a716-446655440099/pdf"
        },
        "created_at": "2026-05-20T11:40:00Z"
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440111",
        "type": "rectified_invoice",
        "invoice_number": "R-0001",
        "date": "2026-05-21",
        "status": "created",
        "client": {
          "id": "client-uuid",
          "name": "María García",
          "id_card": "12345678A",
          "number": 56
        },
        "business_name": "María García",
        "references_invoice_id": "550e8400-e29b-41d4-a716-446655440099",
        "rectification": { "type": "ordinary" },
        "links": {
          "pdf": "/api-connector/v1/backofficeclinics/{backOfficeClinicId}/invoices/660e8400-e29b-41d4-a716-446655440111/pdf"
        },
        "created_at": "2026-05-21T09:05:00Z"
      }
    ],
    "meta": { "limit": 50, "offset": 0, "total": 2 }
  },
  "errors": [],
  "meta": { "timestamp": "2026-05-21T10:00:00+00:00", "api_version": "v1" }
}

Show a single invoice or rectified invoice by UUID. The endpoint resolves the UUID transparently in both tables — the client doesn't need to know upfront which family the document belongs to. Monetary semantics: type=invoice carries positive amounts; type=rectified_invoice carries NEGATIVE amounts by convention. Sum invoices + rectified_invoices to get net revenue. links: pdf (always present) and xml_tbai (only on TicketBai-enabled invoices, otherwise null).

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440099",
    "type": "invoice",
    "invoice_number": "A-0001",
    "date": "2026-05-20",
    "status": "created",
    "client": {
      "id": "client-uuid",
      "name": "María García",
      "id_card": "12345678A",
      "number": 56
    },
    "business_name": "María García",
    "vat_number": "B12345678",
    "address": "Calle Mayor 1, 28013 Madrid",
    "lines": [
      { "name": "Consulta inicial", "quantity": 1, "subtotal": 50.00, "tax": 10.50, "total": 60.50 }
    ],
    "totals": { "subtotal": 50.00, "taxes": 10.50, "total": 60.50 },
    "references_invoice_id": null,
    "rectification": null,
    "links": {
      "pdf": "/api-connector/v1/backofficeclinics/{backOfficeClinicId}/invoices/550e8400-e29b-41d4-a716-446655440099/pdf",
      "xml_tbai": null
    }
  },
  "errors": [],
  "meta": { "timestamp": "2026-05-21T10:05:00+00:00", "api_version": "v1" }
}

Download the invoice PDF as a binary stream (Content-Type: application/pdf). Works for both invoice and rectified_invoice. Returns 404 INVOICE_PDF_NOT_AVAILABLE if the PDF has not been generated yet for this document.

(binary PDF body — Content-Type: application/pdf)

Download the TicketBai XML for the invoice (Content-Type: application/xml). Only available on invoices registered with TicketBai (Basque Country territory). Returns 404 TBAI_NOT_AVAILABLE for non-TBAI invoices.

(TBAI XML body — Content-Type: application/xml)

List all invoice issuers configured for the clinic, with their fiscal data (id, name, vat_number, address, business_name, …). Use the returned id to filter or interpret invoice responses.

{
  "data": {
    "invoice_issuers": [
      {
        "id": "issuer-uuid",
        "name": "María García Autónoma",
        "business_name": "María García",
        "vat_number": "12345678A",
        "address": "Calle Mayor 1, 28013 Madrid"
      }
    ]
  },
  "errors": [],
  "meta": { "timestamp": "2026-05-21T10:10:00+00:00", "api_version": "v1" }
}