Invoices

Export invoices to Excel

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

POST
/v1/invoices/export/excel

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Obtaining Keys: API Keys are managed from the BeeL dashboard

Security: API Keys are secret credentials. Do not share them or store them in source code

In: header

Request Body

invoice_ids?array<UUID>

List of specific invoice IDs to export. If provided, filters are ignored.

format?string

Export format.

  • SUMMARY: One row per invoice with totals (default)
  • ITEMS: One row per invoice line item
Default"SUMMARY"
Value in"SUMMARY" | "ITEMS"
status?string
  • SCHEDULED: Scheduled invoice to be issued automatically on a future date
  • DRAFT: Draft invoice not sent yet (modifiable)
  • ISSUED: Finalized invoice with definitive number but not sent
  • SENT: Invoice sent to customer
  • PAID: Invoice paid
  • OVERDUE: Overdue invoice (not paid after due date)
  • RECTIFIED: Partially corrected invoice (one or more PARTIAL corrective invoices)
  • VOIDED: Completely cancelled invoice (TOTAL corrective invoice)
Value in"SCHEDULED" | "DRAFT" | "ISSUED" | "SENT" | "PAID" | "OVERDUE" | "RECTIFIED" | "VOIDED"
type?string
  • STANDARD: Standard invoice
  • CORRECTIVE: Corrects or cancels a previous invoice
  • SIMPLIFIED: Simplified invoice without all requirements (up to 400€)
Value in"STANDARD" | "CORRECTIVE" | "SIMPLIFIED"
date_from?string

Issue date from (YYYY-MM-DD)

Formatdate
date_to?string

Issue date to (YYYY-MM-DD)

Formatdate
customer_id?string

Universally Unique Identifier (UUID v4)

Formatuuid
recipient_name?string

Filter by recipient name (partial match)

recipient_nif?string

Filter by recipient NIF (partial match)

series_code?string

Filter by series code

Response Body

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/invoices/export/excel" \  -H "Content-Type: application/json" \  -d '{    "invoice_ids": [      "550e8400-e29b-41d4-a716-446655440001",      "550e8400-e29b-41d4-a716-446655440002",      "550e8400-e29b-41d4-a716-446655440003"    ]  }'
"string"
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Duplicate invoice as draft POST

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.

Get invoice PDF download URL GET

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.