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>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

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€, or 3,000€ with NIF)
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 (always set to today) - 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.