BeeL
Get StartedVeriFactuStripeAPI Reference
Invoices

Get invoice PDF download URL

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:

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.

Try this endpoint with Claude
Copy the prompt for any assistant, or open it directly in Claude Code (needs it installed).
GET
/v1/invoices/{invoice_id}/pdf

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

Path Parameters

invoice_idstring

Invoice ID

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/pdf"
{
  "success": true,
  "data": {
    "download_url": "https://minio.beel.es/beel-invoices/invoices/user-uuid/factura-uuid.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
    "expires_in_seconds": 300,
    "file_name": "factura_2025-001.pdf"
  },
  "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"
  },
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  },
  "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"
  }
}

Export invoices to Excel POST

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 by ID GET

Retrieves complete details of a specific invoice