# BeeL API Documentation

> Public invoicing API for self-employed professionals in Spain with full VeriFactu support.

## Documentation Pages

- [Authentication](https://docs.beel.es/auth.mdx) - How to authenticate your requests to the BeeL. API
- [Changelog](https://docs.beel.es/changelog.mdx) - Track all updates to the BeeL. API.
- [Claude Code](https://docs.beel.es/claude-code.mdx) - Use the BeeL. API skill for Claude Code to integrate the BeeL. API in your projects with AI assistance.
- [BeeL. API](https://docs.beel.es/index.mdx) - Invoicing API for freelancers and small businesses in Spain with VeriFactu compliance.
- [API Pricing](https://docs.beel.es/pricing.mdx) - Developer plan pricing, volume tiers, and how billing works for the BeeL. API.
- [Glossary](https://docs.beel.es/guides/glossary.mdx) - Spanish-English glossary of fiscal and business terms used in the BeeL. API.
- [HTTP Methods](https://docs.beel.es/guides/http-methods.mdx) - Complete guide on using GET, POST, PUT and DELETE in the BeeL. API.
- [Idempotency](https://docs.beel.es/guides/idempotency.mdx) - How to use idempotency keys to prevent duplicate operations in the BeeL. API.
- [Rate Limits](https://docs.beel.es/guides/rate-limits.mdx) - Understand the rate limits applied to the BeeL API and how to handle them.
- [SDKs](https://docs.beel.es/sdks.mdx) - Official SDKs to integrate BeeL in your application — coming soon.
- [Java SDK](https://docs.beel.es/sdks/java.mdx) - Java SDK for the BeeL API — coming soon.
- [Node.js / TypeScript SDK](https://docs.beel.es/sdks/node.mdx) - TypeScript SDK for the BeeL API — coming soon.
- [Python SDK](https://docs.beel.es/sdks/python.mdx) - Python SDK for the BeeL API — coming soon.
- [How Taxes Are Applied](https://docs.beel.es/stripe/configuracion-impuestos.mdx) - What taxes BeeL uses in invoices generated from Stripe and where to configure them.
- [Configure Proforma Invoices in Stripe](https://docs.beel.es/stripe/configuracion-proforma.mdx) - Set up Stripe invoices as proforma so the official ones are generated by BeeL.
- [Overview](https://docs.beel.es/stripe.mdx) - Connect your Stripe account with BeeL to automatically generate official invoices with every payment.
- [Deduplication](https://docs.beel.es/webhooks/deduplication.mdx) - Safely handle duplicate webhook deliveries using the BeeL-Event-Id header.
- [Events](https://docs.beel.es/webhooks/events.mdx) - All webhook event types and their payload schemas.
- [Overview](https://docs.beel.es/webhooks.mdx) - Receive real-time notifications in your application when events happen in BeeL.
- [Retries & Delivery Logs](https://docs.beel.es/webhooks/retries.mdx) - How BeeL. retries failed deliveries and how to inspect the delivery history.
- [Signature Verification](https://docs.beel.es/webhooks/signatures.mdx) - Verify that webhook requests genuinely come from BeeL. using HMAC-SHA256.
- [Cancel representation](https://docs.beel.es/companies/cancelRepresentation.mdx) - Cancels the current representation process.
- [Create a company (sub-account)](https://docs.beel.es/companies/createCompany.mdx) - Creates a new NIF/company under the authenticated account.
Invoice series are created automatically with default values.

- [Create API key scoped to a company](https://docs.beel.es/companies/createCompanyApiKey.mdx) - Creates an API key that authenticates directly as this company.
The created key cannot have more scopes than the parent key.

- [Delete a company](https://docs.beel.es/companies/deleteCompany.mdx) - Deletes a company (sub-account). Cannot delete the primary profile.

- [Download representation PDF](https://docs.beel.es/companies/downloadRepresentation.mdx) - Returns a presigned URL (5min) to download the representation PDF.
- [Generate unsigned representation PDF](https://docs.beel.es/companies/generateRepresentation.mdx) - Generates the VeriFactu representation PDF for digital signature.
- [Get company details](https://docs.beel.es/companies/getCompany.mdx) - Returns details of a specific company including VeriFactu status.
- [Get representation status](https://docs.beel.es/companies/getRepresentationStatus.mdx) - Returns the current status of the VeriFactu representation process.
- [List all companies](https://docs.beel.es/companies/listCompanies.mdx) - Returns all companies (sub-accounts) under the authenticated account.
- [List API keys for a company](https://docs.beel.es/companies/listCompanyApiKeys.mdx) - Returns all API keys associated with this company.
- [Revoke an API key](https://docs.beel.es/companies/revokeCompanyApiKey.mdx) - Revokes (deletes) an API key associated with this company.
- [Submit signed representation PDF](https://docs.beel.es/companies/submitRepresentation.mdx) - Uploads the digitally signed representation PDF.
VeriFactu will validate the signature asynchronously.

- [Update company details](https://docs.beel.es/companies/updateCompany.mdx) - Updates editable fields of a company.
NIF, legal name, and entity type are immutable after creation.

- [Create customer](https://docs.beel.es/customers/createCustomer.mdx) - Creates a new customer
- [Create or validate multiple customers](https://docs.beel.es/customers/createCustomersBulk.mdx) - Creates multiple customers in a single operation or validates data without persisting.

**Validation flow:**
1. `dry_run=true`: Full validation only (NIFs, duplicates, format) without persistence
2. `dry_run=false`: Validation + actual creation

**Validations performed:**
- Individual validation of each customer (same rules as single customer creation)
- Detection of duplicate NIFs within the batch
- Detection of duplicate NIFs against existing database
- Parallel NIF validation against AEAT registry (VeriFactu)
- Field format verification (email, phone, etc.)

**Result statuses:**
- `VALID`: Customer valid, ready to create
- `WARNING`: Customer valid but with warnings (e.g., missing email)
- `ERROR`: Customer invalid, cannot process
- `DUPLICATE`: Duplicate NIF (in batch or existing DB)
- `NIF_INVALID`: NIF not valid in AEAT registry

**Atomicity:**
- `dry_run=true`: Validation only, no persistence
- `dry_run=false`: If any customer fails, ALL customers are rejected (full atomicity)

- [Deactivate customer](https://docs.beel.es/customers/deactivateCustomer.mdx) - Deactivates (marks as deleted) a customer.

**Soft delete:** The customer is not physically deleted, only marked as inactive.

**Restriction:** Cannot deactivate a customer with associated invoices.

- [Delete multiple customers](https://docs.beel.es/customers/deactivateCustomersBulk.mdx) - Deactivates (marks as deleted) multiple customers in a single operation.

**Soft delete:** Customers are not physically deleted, only marked as inactive.

**Partial behavior:** Valid customers will be deactivated, failures are reported in the errors array.

- [Download CSV template for customers](https://docs.beel.es/customers/downloadCustomerTemplateCsv.mdx) - Downloads a sample CSV file for customer import.

**Format**: The file includes the required headers and example rows
with UTF-8 BOM for Excel compatibility.

- [Get customer by ID](https://docs.beel.es/customers/getCustomer.mdx) - Retrieves complete details of a specific customer
- [Import customers from CSV with structured preview](https://docs.beel.es/customers/importCustomersCsvPreview.mdx) - Imports multiple customers from a CSV file with full preview of all records.

**Key features**:
- **Structured preview**: Returns all parsed records (valid and with errors)
- **Parallel validation**: NIFs validated concurrently against VeriFactu
- **Granular feedback**: Customer-specific errors and warnings
- **Editable data**: Structured JSON for editable table in frontend

**Recommended flow**:
1. **Initial upload**: Call with `dry_run=true` to get preview
2. **Display table**: Frontend shows parsed data with errors/warnings
3. **Inline editing**: User corrects data directly in the table
4. **Final import**: Send corrected data with `dry_run=false`

**Format**: Must follow CSV template format (downloadable from `/customers/template-csv`).

**Security limits**:
- Max size: 5MB
- Max 1,000 records per file
- Rate limiting: 3 imports per hour

**Validation**:
- Required headers per template
- Full validation of each row with business rules
- Parallel NIF validation against AEAT registry (VeriFactu)
- Duplicate detection in CSV and database

**Validation statuses**:
- `VALID`: Customer valid, ready to import
- `WARNING`: Customer valid but with warnings (eg: missing email)
- `ERROR`: Customer invalid, cannot process
- `DUPLICATE`: Duplicate customer (in CSV or DB)
- `NIF_INVALID`: NIF invalid in AEAT registry

- [Import contacts from Holded Excel](https://docs.beel.es/customers/importHoldedContacts.mdx) - Imports multiple customers from an Excel file exported from Holded.

**Key features**:
- **Specific parsing**: Reads exact structure of Holded contacts Excel (29 columns)
- **Automatic mapping**: Converts Holded contacts to Customer entities automatically
- **Full validation**: Validates NIFs, addresses and required data
- **Preview mode**: Allows viewing parsed data before importing

**Recommended flow**:
1. **Initial upload**: Call with `preview=true` to get preview
2. **Display data**: Frontend shows parsed Holded contacts
3. **Final import**: Call with `preview=false` to import definitively

**Expected Excel structure** (contacts exported from Holded):
- Sheet: "Holded"
- Rows to skip: 2 (header + empty)
- Headers in row 2: Created, Name, ID, Email, Phone, Mobile, etc. (29 columns)
- Footer: "Report created automatically with Holded..."

**Security limits**:
- Max size: 10MB
- Max 5,000 records per file
- Rate limiting: 5 imports per hour

**Automatic Holded → Customer mapping**:
- Name → legal_name
- ID → identifier (NIF/CIF)
- Email → email
- Phone/Mobile → phone (prioritizes mobile)
- Full address → address
- Tags → notes

- [List customers](https://docs.beel.es/customers/listCustomers.mdx) - Returns a paginated list of customers with optional filters
- [Update customer](https://docs.beel.es/customers/updateCustomer.mdx) - Updates an existing customer
- [Create invoice series](https://docs.beel.es/invoice-series/createSeries.mdx) - Creates a new invoice series.

**Note:** The first series created by a user is automatically marked as default.

- [Delete series](https://docs.beel.es/invoice-series/deleteSeries.mdx) - Soft-deletes an invoice series. If the series is active, it is automatically
deactivated before deletion. The series code becomes available for reuse.

**Restriction:** Cannot delete the default series. Assign another series as default first.

- [List invoice series](https://docs.beel.es/invoice-series/listSeries.mdx) - Retrieves all invoice series for the user
- [Mark series as default](https://docs.beel.es/invoice-series/setDefaultSeries.mdx) - Marks an invoice series as the user's default.

**Business rules:**
- Only one series can be default per user
- The series must be active (cannot mark an inactive series)
- The previous default series is automatically unmarked

**Note:** This operation is idempotent - calling it multiple times
with the same series has no additional effects.

- [Update invoice series](https://docs.beel.es/invoice-series/updateSeries.mdx) - Updates an existing invoice series.

Can only update:
- Description
- Active/inactive status
- Whether it is default

Cannot modify: code, prefix, number_format (to maintain consistency with existing invoices).

Business rules:
- Cannot deactivate a default series (must set another as default first)
- Cannot mark an inactive series as default

- [Change status of multiple invoices](https://docs.beel.es/invoices/changeInvoicesStatusBulk.mdx) - Changes the status of multiple invoices in a single operation.

**Supported status changes:**
- **SENT:** Mark multiple invoices as sent (from ISSUED)
- **PAID:** Mark multiple invoices as paid (from ISSUED, SENT, or OVERDUE)

**Partial success:** If some invoices cannot be updated, the operation
continues with the others. The response includes details of failures.

**Limits:**
- Maximum 50 invoices per request

**Validations:**
- All invoices must belong to the authenticated user
- Each invoice must be in a valid status for the requested transition
- For PAID: payment_date is required

- [Create corrective invoice](https://docs.beel.es/invoices/createCorrectiveInvoice.mdx) - Creates a corrective invoice to correct or void an issued invoice.

**Rectification types:**
- **TOTAL**: Completely voids the original invoice (original status → VOIDED)
- **PARTIAL**: Partially corrects the original invoice (original status → RECTIFIED)

**VeriFactu codes:**
- R1: Legal error and Art. 80 One, Two and Six LIVA
- R2: Article 80 Three LIVA (Bankruptcy)
- R3: Article 80 Four LIVA (Bad debts)
- R4: Other causes
- R5: Simplified invoices (only for simplified)

**Validations:**
- Original invoice must be in status ISSUED, SENT, PAID, OVERDUE or RECTIFIED
- Cannot rectify a DRAFT invoice (must be issued first)
- Cannot rectify a VOIDED invoice (final status)
- For TOTAL rectification: Another total corrective cannot already exist
- For PARTIAL rectification: Multiple partial correctives are allowed

**Lines:**
- TOTAL: Optional (if not provided, original lines are copied with negated amounts)
- PARTIAL: REQUIRED (adjustment lines with positive or negative amounts)

- [Create invoice](https://docs.beel.es/invoices/createInvoice.mdx) - Creates a new invoice.

**Idempotency:** Supports `Idempotency-Key` header to prevent duplicates.

- [Delete invoice](https://docs.beel.es/invoices/deleteInvoice.mdx) - Deletes (marks as deleted) an invoice.

**Soft delete:** The invoice is not physically deleted, only marked as deleted.

**Restriction:** Only invoices in `DRAFT` status can be deleted.

- [Download multiple invoice PDFs as ZIP](https://docs.beel.es/invoices/downloadInvoicesPdfBulk.mdx) - Downloads multiple invoice PDFs as a single ZIP file.

**Limits:**
- Maximum 20 invoices per request
- Maximum 50MB total ZIP size

**Partial success:** If some PDFs are not available (not generated, not found),
the response will include a `failures` array with details. The ZIP will still
be generated with the available PDFs.

**Error handling:**
- If NO PDFs are available, returns 400 Bad Request
- If some PDFs are unavailable, returns 200 with partial ZIP + failures list

- [Duplicate invoice as draft](https://docs.beel.es/invoices/duplicateInvoice.mdx) - Creates a copy of an existing invoice as a new draft.

**Use case:** Quickly create a new invoice based on an existing one,
useful for recurring invoices to the same customer.

**What is copied:**
- Customer data (recipient)
- Invoice lines (descriptions, quantities, prices, taxes)
- Payment method
- Series (if specified, otherwise uses default)
- Observations

**What is NOT copied (reset to defaults):**
- Invoice number (null - assigned when issued)
- Status (always DRAFT)
- Issue date (defaults to today, can be overridden)
- Due date (recalculated based on new issue date)
- VeriFactu data
- PDF
- Payment date
- Sent date

**Result:** A new draft invoice ready for review and emission.

**Note:** Send `Content-Type: application/json` even when body is empty.

- [Export invoices to Excel](https://docs.beel.es/invoices/exportInvoicesExcel.mdx) - Exports invoices to an Excel file (XLSX format).

**Two modes of operation:**
- **By IDs:** Export specific invoices by providing `invoice_ids`
- **By filters:** Export all invoices matching filter criteria

**Two export formats (like Holded):**
- **SUMMARY:** One row per invoice with aggregated totals (default)
- **ITEMS:** One row per invoice line item, ideal for import compatibility

**Columns for SUMMARY format:**
- Date, Number, Due Date, Customer, NIF
- Description, Subtotal, IVA, Withholding, Equivalence Surcharge
- Total, Collected, Pending, Status, Payment Method

**Columns for ITEMS format:**
- Invoice Number, Date, Due Date, Draft, Contact, Contact NIF
- Address, Postal Code, City, Province, Country
- SKU, Item, Units, Unit Price, Discount %
- Subtotal, Tax Type, Tax %, Tax Amount
- Surcharge %, Surcharge Amount, IRPF %, IRPF Amount, Total

**Limits:**
- Maximum 5000 invoices per export
- All invoices must belong to the authenticated user (RLS enforced)

**Usage example (Frontend):**
```javascript
const response = await fetch('/v1/invoices/export/excel', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ invoice_ids: [...], format: 'ITEMS' })
});
const blob = await response.blob();
// Download the blob as file
```

- [Get invoice PDF download URL](https://docs.beel.es/invoices/generateInvoicePdf.mdx) - Generates a temporary pre-signed URL to download the invoice PDF.

**Security:**
- URL expires automatically in 5 minutes
- HMAC signature prevents tampering
- Only allows download (GET), no modification

**Benefits:**
- Direct download from storage (bypasses backend)
- Better performance and lower server load
- Compatible with browser cache and CDN
- Ideal for large files

**Frontend usage:**
```javascript
const response = await fetch('/v1/invoices/{id}/pdf');
const { download_url } = await response.json();
window.open(download_url, '_blank'); // Direct download
```

**Format:** PDF is generated according to Spanish tax regulations.

- [Get invoice by ID](https://docs.beel.es/invoices/getInvoice.mdx) - Retrieves complete details of a specific invoice
- [Issue invoice (DRAFT → ISSUED)](https://docs.beel.es/invoices/issueInvoice.mdx) - Finalizes a draft invoice and marks it as issued.

**Status change:** `DRAFT` → `ISSUED`

**Actions performed:**
- Assigns definitive invoice number according to configured series
- Marks invoice as finalized (not modifiable)
- Prepares invoice for sending to customer

**Validations:**
- Invoice must be in DRAFT status
- All invoice data must be complete and valid

**Note:** After issuing, the invoice can be sent to the customer via
the `/invoices/{id}/send` endpoint

- [List invoices](https://docs.beel.es/invoices/listInvoices.mdx) - Returns a paginated list of invoices with optional filters
- [Mark invoice as paid](https://docs.beel.es/invoices/markInvoicePaid.mdx) - Marks an invoice as paid.

**Status change:** `SENT` → `PAID`

**Note:** Send `Content-Type: application/json` even when body is empty.

- [Mark invoice as sent](https://docs.beel.es/invoices/markInvoiceSent.mdx) - Marks an invoice as sent manually.

**Use case:** When the invoice was sent via WhatsApp, paper, or any other
channel outside of the email system.

**Status change:** `ISSUED` → `SENT`

**Records:** Sets `sent_at` timestamp for tracking.

**Note:** Send `Content-Type: application/json` even when body is empty.

- [Preview draft invoice PDF](https://docs.beel.es/invoices/previewDraftInvoicePdf.mdx) - Generates a PDF preview for a draft invoice and returns the binary content directly.

**Requirements:**
- Invoice must be in BORRADOR (draft) status
- The PDF shows "BORRADOR" as the invoice number
- No VeriFactu QR code is included

**Behavior:**
- PDF is generated on-the-fly (not stored)
- Each request regenerates the PDF (reflects latest draft changes)
- Response is `application/pdf` for direct browser preview

- [Reschedule invoice](https://docs.beel.es/invoices/rescheduleInvoice.mdx) - Changes the scheduled date for a scheduled invoice.

**Status:** Remains `SCHEDULED`

The new date must be today or in the future.

- [Revert invoice to issued status](https://docs.beel.es/invoices/revertInvoiceToIssued.mdx) - Reverts an invoice from SENT to ISSUED status.

**Use case:** To correct errors when an invoice was marked as sent by mistake.

**Status change:** `SENT` → `ISSUED`

**Side effects:** Clears the `sent_at` timestamp.

- [Schedule invoice for future processing](https://docs.beel.es/invoices/scheduleInvoice.mdx) - Schedules a draft invoice to be automatically processed on a future date.

**Status change:** `DRAFT` → `SCHEDULED`

**Actions available:**
- `DRAFT`: Convert to draft for manual review on the scheduled date
- `ISSUE_AND_SEND`: Issue and send automatically on the scheduled date

- [Send invoice by email](https://docs.beel.es/invoices/sendInvoiceEmail.mdx) - Sends the invoice by email to the customer.

**Email:** Sent to the billing emails configured for the customer.

**Attachments:** Includes the invoice PDF.

- [Send multiple invoices by email](https://docs.beel.es/invoices/sendInvoicesBulkEmail.mdx) - Sends multiple invoices by email to the specified recipients.

**Limits:**
- Maximum 20 invoices per request
- Maximum 25MB total attachment size

**Email behavior:**
- Single email with all PDFs as attachments
- Uses BULK_INVOICES template

**Validations:**
- Invoices must have status ISSUED, PAID, SENT or OVERDUE (not DRAFT or VOIDED)
- At least one recipient required (from request or user's accountant email)

**Partial success:** If some invoices cannot be attached, the email will
still be sent with available PDFs. Response includes `failures` array.

- [Cancel scheduled invoice](https://docs.beel.es/invoices/unscheduleInvoice.mdx) - Cancels a scheduled invoice and converts it back to draft.

**Status change:** `SCHEDULED` → `DRAFT`

The invoice can then be edited or manually issued.

- [Update invoice](https://docs.beel.es/invoices/updateInvoice.mdx) - Updates an existing draft invoice.

**Restriction:** Only invoices in `DRAFT` status can be modified.

- [Void invoice](https://docs.beel.es/invoices/voidInvoice.mdx) - Voids an invoice by changing its status to `VOIDED`.

**Status change:** `ISSUED`, `SENT`, `OVERDUE`, `PAID` or `RECTIFIED` → `VOIDED`

**Use when:** The operation never took place (invoice issued by mistake, duplicate, etc.)
For invoices already submitted to VeriFactu, the cancellation is sent to AEAT automatically.

**Note:** If the operation did take place but with errors, use the corrective invoice endpoint instead.

- [Validate NIF against AEAT registry](https://docs.beel.es/nif-validation/validateNif.mdx) - **Public endpoint** to validate a NIF/CIF against the AEAT registry using VeriFactu.

This endpoint is useful for:
- Pre-validation before registration (proactive feedback)
- Validating customer NIFs before creating invoices
- Verifying that a NIF exists in the registry

**Behavior:**
- **VALID**: The NIF exists in the AEAT registry. Returns the fiscal name.
- **INVALID**: The NIF has correct format but doesn't exist in the registry.
- **PENDING**: VeriFactu API is temporarily unavailable. The NIF has valid syntax but couldn't be verified against the registry.
- **ERROR**: Technical error during validation (invalid syntax, timeout, etc.)

**Note about PENDING:**
If you use this endpoint for pre-validation during registration, a PENDING status
indicates that the NIF has valid format and the user can continue. The system
will validate the NIF automatically when the service becomes available.

**Rate limiting:**
- With API Key: 100 requests/hour
- With Session Cookie: 1000 requests/hour

**Authentication:**
This endpoint accepts both API Keys and Session Cookies.

- [Get invoice customization options](https://docs.beel.es/preferences/getInvoiceCustomizationOptions.mdx) - Retrieves available option catalogs to customize invoices:

**Template types:**
- MODERN_TABLE: Structured table design, ideal for standard products/services
- PROFESSIONAL_SERVICE: Text-based design, ideal for notaries/consultancies

**Suggested color palette:**
- BeeL default colors (orange, blue)
- Professional palette (dark grays)
- Creative palette (violet, pink, amber, emerald green)
- Classic palette (blue, red, green, purple)

**Usage:**
User can choose a template and accent color to customize
their invoices. These values are saved in their profile and automatically applied
when generating new invoice PDFs.

Template and color names are returned translated to the user's invoice language preference.

- [Update user preferred language](https://docs.beel.es/preferences/updateLanguage.mdx) - Updates the authenticated user's preferred language.

This language is used for:
- UI translations
- Template names and colors in invoice customization
- Emails sent to the user

**Supported languages:**
- `es` - Spanish (default)
- `en` - English
- `ca` - Catalan

- [Create new product/service](https://docs.beel.es/products/createProduct.mdx) - Creates a new product or service in the catalog
- [Create multiple products](https://docs.beel.es/products/createProductsBulk.mdx) - Creates multiple products in one operation (max 100)
- [Delete product](https://docs.beel.es/products/deleteProduct.mdx) - Deletes a product from catalog
- [Delete multiple products](https://docs.beel.es/products/deleteProductsBulk.mdx) - Deletes multiple products from catalog (max 100)
- [Get product by ID](https://docs.beel.es/products/getProduct.mdx) - Retrieves details of a specific product
- [List products/services from catalog](https://docs.beel.es/products/listProducts.mdx) - Returns a paginated list of products/services with optional filters
- [Search and autocomplete](https://docs.beel.es/products/searchProducts.mdx) - Optimized endpoint for active product autocomplete
- [Update product](https://docs.beel.es/products/updateProduct.mdx) - Updates an existing product
- [Create a recurring invoice from an existing invoice](https://docs.beel.es/recurring-invoices/createRecurringFromInvoice.mdx) - Creates a new recurring invoice template using the lines, recipient, and configuration from an existing invoice.
- [Create a recurring invoice from scratch](https://docs.beel.es/recurring-invoices/createRecurringInvoice.mdx) - Creates a new recurring invoice template with all template data (lines, recipient, series, payment) and recurrence configuration, without needing an existing invoice.
- [Delete a recurring invoice](https://docs.beel.es/recurring-invoices/deleteRecurringInvoice.mdx) - Permanently deletes a recurring invoice and cancels any pending scheduled generations.
- [Generate an invoice now from a recurring template](https://docs.beel.es/recurring-invoices/generateInvoiceNow.mdx) - Manually triggers invoice generation from a recurring template.
- [Get generation history for a recurring invoice](https://docs.beel.es/recurring-invoices/getRecurringHistory.mdx) - Returns the list of invoices previously generated from this recurring template, including their status and generation dates.
- [Get a recurring invoice by ID](https://docs.beel.es/recurring-invoices/getRecurringInvoice.mdx) - Retrieves the full details of a recurring invoice including its schedule, template lines, and next generation date.
- [List recurring invoices](https://docs.beel.es/recurring-invoices/listRecurringInvoices.mdx) - Lists all recurring invoices for the authenticated user with filters and pagination.
- [Pause a recurring invoice](https://docs.beel.es/recurring-invoices/pauseRecurringInvoice.mdx) - Pauses automatic invoice generation. The recurring invoice can be resumed later without losing its schedule configuration.
- [Preview next invoice from recurring template](https://docs.beel.es/recurring-invoices/previewRecurringInvoice.mdx) - Returns a computed preview of what the next invoice would look like when
generated from this recurring template. Uses current issuer, recipient,
and series data. Nothing is persisted.

- [Resume a paused recurring invoice](https://docs.beel.es/recurring-invoices/resumeRecurringInvoice.mdx) - Resumes automatic invoice generation for a previously paused recurring invoice. The next generation date is recalculated from the current date.
- [Skip the next generation](https://docs.beel.es/recurring-invoices/skipNextGeneration.mdx) - Skips the next scheduled invoice generation and advances the generation date to the following period.
- [Update a recurring invoice](https://docs.beel.es/recurring-invoices/updateRecurringInvoice.mdx) - Updates the schedule, template lines, or recipient of a recurring invoice. Only allowed while the invoice is active or paused.
- [Get user tax configuration](https://docs.beel.es/tax-configuration/getTaxConfiguration.mdx) - Retrieves the user's tax configuration, including:
- Default tax regime (VAT, IGIC, IPSI, OTHERS)
- Default main tax percentage
- IRPF and equivalence surcharge configuration

- [Get complete tax types catalog](https://docs.beel.es/tax-configuration/getTaxTypes.mdx) - Retrieves the complete catalog of available tax types with structured information
for tax configuration in Spain:

- **Tax regimes**: VAT (Peninsula), IGIC (Canary Islands), IPSI (Ceuta/Melilla), OTHERS
- **Percentages per regime**: Valid percentages for each tax type
- **Regime codes**: VeriFactu codes for each tax type
- **IRPF**: Available withholding percentages
- **Equivalence surcharge**: Automatic mappings based on VAT percentage
- **Utilities**: Validation functions and geographic auto-detection

This endpoint provides all necessary information for the frontend
without duplicating tax validation logic.

- [Update tax configuration](https://docs.beel.es/tax-configuration/updateTaxConfiguration.mdx) - Updates the user's tax configuration
- [Get VeriFactu configuration](https://docs.beel.es/verifactu/getVeriFactuConfiguration.mdx) - Retrieves the current VeriFactu configuration
- [Update VeriFactu configuration](https://docs.beel.es/verifactu/updateVeriFactuConfiguration.mdx) - Updates the user's VeriFactu configuration.

**Business rules:**
- If `enabled` is false, `apply_by_default` must also be false
- If `apply_by_default` is true, `enabled` must be true

- [Create webhook subscription](https://docs.beel.es/webhooks/createWebhookSubscription.mdx) - Register an HTTPS endpoint to receive real-time event notifications. Every delivery is signed with BeeL-Signature (HMAC-SHA256). The secret is returned once on creation — store it securely. Maximum 10 active webhook subscriptions per account.
- [Delete webhook subscription](https://docs.beel.es/webhooks/deleteWebhookSubscription.mdx) - Permanently deletes a webhook subscription. No further events will be delivered.
- [List webhook delivery logs](https://docs.beel.es/webhooks/listWebhookDeliveries.mdx) - Returns the last 50 delivery attempts for a webhook subscription.
- [List webhook subscriptions](https://docs.beel.es/webhooks/listWebhookSubscriptions.mdx) - Returns all webhook subscriptions for the authenticated account.
- [Retry a failed webhook delivery](https://docs.beel.es/webhooks/retryWebhookDelivery.mdx) - Immediately retries a webhook delivery using the original payload.
Creates a new delivery log entry with the result.

- [Rotate webhook secret](https://docs.beel.es/webhooks/rotateWebhookSecret.mdx) - Generates a new HMAC secret for a webhook subscription.
The old secret is **immediately invalidated** — update your signature verification
logic before rotating to avoid missing events during the transition.
The new secret is only returned **once** in this response.

- [Update webhook subscription](https://docs.beel.es/webhooks/updateWebhookSubscription.mdx) - Partially updates a webhook subscription. Only provided fields are updated.

Use this endpoint to:
- **Change the endpoint URL** (`url`)
- **Change subscribed events** (`events`)
- **Enable or disable** the subscription (`active`)


## Full Documentation

For the complete documentation in a single file, see: https://docs.beel.es/llms-full.txt