NewProvince is only required for addresses in Spain
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Invoices

Export invoices

Scopeinvoices:read

Produces a spreadsheet with the invoices of this company and returns the file in the response.

  • Selection: the invoices named in invoice_ids, or, when that is absent, the ones matching filters. A request with neither is rejected with 400 EXPORT_SELECTION_REQUIRED.
  • Format: SUMMARY writes one row per invoice with aggregated totals, ITEMS one row per invoice line.
  • Values: the status, payment method, tax type and line type columns carry the same values the API returns (ISSUED, BANK_TRANSFER, IVA, SUPLIDO…). A proforma past its validity is exported as ACTIVE, not EXPIRED.
  • Limit: up to 50000 invoices per export. Going over it is rejected with 422 EXPORT_LIMIT_EXCEEDED — narrow the date range or split the selection. The export is never silently truncated.
POST
/v1/companies/{company_id}/invoices/exports

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Path Parameters

company_idstring

Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.

Formatuuid

Request Body

format?string
  • SUMMARY: one row per invoice with aggregated totals.
  • ITEMS: one row per invoice line.
Default"SUMMARY"
Value in"SUMMARY" | "ITEMS"
invoice_ids?array<UUID>

Specific invoices to export. When present, filters is ignored.

filters?

Selection criteria used when invoice_ids is not supplied. Max 50000 invoices: a wider match is rejected with 422 EXPORT_LIMIT_EXCEEDED, never truncated.

Response Body

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices/exports" \  -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"
  },
  "type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
  "title": "INVOICE_NO_LINES",
  "detail": "The invoice must have at least one line",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "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": "The invoice must have at least one line",
  "instance": "/v1/invoices/abc-123"
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid.",
    "details": {
      "legal_name": "The field 'legal_name' cannot be empty",
      "recipient.address.postal_code": "Contains invalid characters."
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again in 60 seconds."
  },
  "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"
  }
}
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Download the PDFs of several invoices as a ZIP POST

Returns a single ZIP with the PDFs of the invoices of this company named in `invoice_ids`. - **Limit:** up to 500 invoices per request. - **Missing PDFs:** invoices whose PDF is not available are left out of the archive. If no PDF at all is available the call fails with `400`. - **Counts:** `X-Bulk-Total`, `X-Bulk-Successful` and `X-Bulk-Failed` response headers report how many PDFs were requested and how many made it into the ZIP.

Send an invoice by email POST

Sends the invoice by email, attaching its PDF by default. When no recipient is given, the addresses configured on the customer are used.