NewTell a voided invoice from a totally rectified one, without a second call
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Invoices

Send several invoices in one email

Scopeinvoices:write

Sends one email carrying the PDFs of several invoices of this company as attachments. At least one recipient is required: no address is inferred from any profile.

POST
/v1/companies/{company_id}/invoices/deliveries

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

company_idstring

NIF (company) the operation acts on. 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 NIF you do not reach answers 403, and so does a NIF that does not exist, so the existence of a NIF 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)
  • 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

invoice_idsarray<UUID>
Items1 <= items <= 200
recipientsarray<Email>

Email recipients. At least one is required: no address is inferred from any profile.

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 configured in the sender's email defaults apply; send an empty array to deliver the message without any copy.

subject?string

Custom email subject. Defaults to the standard template.

Lengthlength <= 200
message?string

Custom message body. Defaults to the standard template.

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

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-446655440000"    ],    "recipients": [      "user@example.com"    ]  }'
{
  "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": "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": "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": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": {
      "field_name": "Field is required"
    }
  },
  "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"
  }
}

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.

Set the status of an invoice PUT

Sets the commercial status of an invoice: paid, sent, or back to issued. It is the same concept the batch expresses with `{"operation": "STATUS"}`, so there is one vocabulary and not a verb per transition. Issuing and voiding are **not** statuses set here: they are fiscal acts with their own operations. The domain rejects any transition it does not allow.