NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Invoices

Send an invoice by email

Scopeinvoices:write

Sends the invoice by email with its PDF attached.

POST
/v1/invoices/{invoice_id}/send

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

invoice_idstring

Invoice ID

Formatuuid

Header Parameters

Idempotency-Key?string

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • If the same key is sent twice, the result of the first operation is returned
  • Keys expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Request Body

recipients?array<Email>

If not specified, uses the customer's email

cc?array<Email>

CC recipients. Copied addresses count as recipients of the message: they are subject to the same sending restrictions and to the same quota as the addresses in recipients. When omitted, the CC addresses configured in the sender's email defaults apply; send an empty array to deliver the message without any copy.

subject?string

Email subject (optional, if not specified uses a default)

Length1 <= length <= 200
message?string

Custom message (optional, added before standard message)

Length1 <= length <= 2000
attach_pdf?boolean
Defaulttrue
attach_source_invoices?boolean

Attach a ZIP archive (suplidos_<invoice-number>.zip) containing the PDFs of the source invoices referenced by the invoice's SUPLIDO consolidation lines (source_invoice_ids). Each PDF inside the ZIP is named <invoice-number>_<issuer-tax-id>.pdf. Requires attach_pdf: true (the ZIP accompanies the invoice PDF). Access to sources owned by managed accounts is re-checked at send time with the same rules as issuing; the request fails with an actionable error — never a partial ZIP — if the invoice has no consolidation sources (ATTACH_SOURCE_INVOICES_NO_SOURCES), a source is not reachable (ATTACH_SOURCE_INVOICE_UNAVAILABLE), a source has no generated PDF (ATTACH_SOURCE_PDF_MISSING), or the ZIP exceeds the size limit (ATTACH_SOURCE_ZIP_TOO_LARGE).

Defaultfalse
language?string
Value in"es" | "en" | "ca"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/send" \  -H "Content-Type: application/json" \  -d '{}'
{
  "success": true,
  "data": {
    "email_id": "550e8400-e29b-41d4-a716-446655440000",
    "sent_to": [
      "user@example.com"
    ],
    "sent_at": "2019-08-24T14:15:22Z"
  },
  "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 is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "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": "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"
  }
}

Export invoices to a spreadsheet POST

Exports invoices to an XLSX file. - **Deprecated:** use `POST /v1/companies/{company_id}/invoices/exports`, which produces the same file. - **Difference:** the selection criteria are grouped there under `filters` instead of being top-level fields. - **Selection:** the invoices named in `invoice_ids`, or, when that list is absent, the ones matching the filters. - **Format:** `SUMMARY` gives one row per invoice with aggregated totals, `ITEMS` one row per invoice line.

Send multiple invoices by email POST

Sends one email carrying the PDFs of the requested invoices as attachments. - **Deprecated:** use `POST /v1/companies/{company_id}/invoices/deliveries`, which sends the same email from the same body, with `recipients` declared as required there. - **Limits:** up to 200 invoices per call, and the attachments are capped at 25MB. - **Eligible invoices:** only invoices in `ISSUED`, `SENT`, `PAID` or `OVERDUE` can be sent. - **Partial failures:** invoices whose PDF cannot be attached are reported in `failures` and the message is still sent with the rest.