NewThe SII in Live, under contract
BeeL
Get startedMulti-NIFVeriFactuSIIRulesStripeAPI referenceChangelog
Invoices

Send several invoices in one email

Scopeinvoices:write

Sends one email carrying the PDFs of several invoices of this company as attachments.

  • recipients: required, and must carry at least one address; no address is inferred from any profile.
  • Limit: up to 200 invoices per message (invoice_ids).
  • Failures: invoices whose PDF cannot be attached are reported in failures, and the message is still sent with the rest.

POST
/v1/companies/{company_id}/invoices/deliveries
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

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)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx other than 503, check whether the operation took effect before retrying with a new key
  • After a 503, retry first with the same key. If the response carries Idempotency-Replay: true, the operation may have taken effect: check the resource before using a new key. Without that header, the retry runs the operation once
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing
  • POST operations that only read data (exports, batch PDF downloads, previews) ignore this header: they run on every call and their response is never stored

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 for the Retry-After seconds (2) and retry with the same key a few times. If it keeps answering 409, the first response could not be stored: check the resource instead of retrying.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255
invoice_idsarray<UUID>
Items1 <= items <= 200
recipientsarray<Email>

Email recipients. At least one is required: no address is inferred from any profile. With a live key, the additional_recipients of the company's email configuration are added, and they count toward the sending restrictions and the quota. With a test key they are not added: only the recipients of the request are sent to.

Items1 <= items
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 in the defaults of the company's email configuration apply (the email_config.cc of the invoice applies only when the delivery carries one invoice); send an empty array to deliver the message without any copy.

subject?string

Custom email subject. When omitted, the email_config.subject of the invoice applies if the delivery carries one invoice, then the defaults.subject of the company's email configuration, then the standard subject. Variables resolve per delivery (see message).

Lengthlength <= 200
message?string

Custom message body. When omitted, the email_config.message of the invoice applies if the delivery carries one invoice, then the defaults.message of the company's email configuration, then the standard message. Variables in subject and message resolve per delivery, which is one email: {invoiceNumber} is the list of invoice numbers separated by ", ", {customerName} only when every invoice has the same customer, {issuerName} is the issuer, and the others (total, dates) are empty.

Lengthlength <= 2000
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/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices/deliveries" \  -H "Content-Type: application/json" \  -d '{    "invoice_ids": [      "550e8400-e29b-41d4-a716-446655440001",      "550e8400-e29b-41d4-a716-446655440002"    ],    "recipients": [      "accountant@example.com"    ],    "subject": "Invoices for January 2025",    "message": "Please find attached the invoices from last month for your review."  }'
{
  "success": true,
  "data": {
    "email_id": "550e8400-e29b-41d4-a716-446655440000",
    "sent_to": [
      "user@example.com"
    ],
    "sent_at": "2019-08-24T14:15:22Z",
    "total_invoices": 0,
    "invoices_attached": 0,
    "failures": [
      {
        "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
        "error_code": "NOT_FOUND",
        "error_message": "string"
      }
    ]
  },
  "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": "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"
  }
}