Schedule or reschedule an invoice
Scopeinvoices:writeReplaces the scheduling of a draft invoice, whether it had one or not: scheduling for the first time and moving an existing schedule are the same act on the same sub-resource.
generation_mode is required. There is no default on purpose: silently falling back to
DRAFT would downgrade an ISSUE_AND_SEND and the invoice would never be issued.
Requires the scheduled_invoices feature.
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
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.
uuidInvoice ID
uuidHeader Parameters
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.
| Status | Code | When |
|---|---|---|
400 | INVALID_IDEMPOTENCY_KEY | The key breaks the format rules above. |
409 | IDEMPOTENCY_KEY_PROCESSING | The first request is still in flight. Wait and retry with the same key. |
409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
^[a-zA-Z0-9_-]+$length <= 255Date on which the invoice should be processed. Today or later.
dateAction to perform when processing a scheduled invoice:
- DRAFT: Create as draft for manual review
- ISSUE_AND_SEND: Issue and send automatically via email
"DRAFT" | "ISSUE_AND_SEND"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices/550e8400-e29b-41d4-a716-446655440000/schedule" \ -H "Content-Type: application/json" \ -d '{ "scheduled_for": "2025-02-15", "generation_mode": "DRAFT" }'{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"invoice_number": "2025/0001",
"series": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"code": "FAC"
},
"number": 1,
"type": "STANDARD",
"status": "SCHEDULED",
"issue_date": "2025-01-15",
"operation_date": "2025-01-10",
"due_date": "2025-02-14",
"valid_until": "2025-02-28",
"payment_date": "2025-01-20",
"sent_at": "2025-01-29T18:45:00Z",
"paid_at": "2025-02-05T10:30:00Z",
"auto_emit_after": "2025-03-20",
"scheduled_for": "2025-02-15",
"scheduled_action": "DRAFT",
"issuer": {
"legal_name": "Juan Pérez García",
"trade_name": "JP Web Development",
"nif": "12345678A",
"address": {
"street": "Calle Mayor, 123",
"number": "123",
"floor": "2º A",
"door": "A",
"postal_code": "28001",
"city": "Madrid",
"province": "Madrid",
"country": "España",
"country_code": "ES"
},
"phone": "+34 612 345 678",
"email": "user@example.com",
"website": "https://beel.es",
"logo_url": "string",
"additional_info": "Nº Colegiado: 12345"
},
"recipient": {
"customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
"legal_name": "Empresa SL",
"trade_name": "Empresa",
"nif": "12345678A",
"alternative_id": {
"type": "NIF_IVA",
"number": "string",
"country_code": "st"
},
"address": {
"street": "Calle Mayor, 123",
"number": "123",
"floor": "2º A",
"door": "A",
"postal_code": "28001",
"city": "Madrid",
"province": "Madrid",
"country": "España",
"country_code": "ES"
},
"phone": "+34 612 345 678",
"email": "user@example.com"
},
"lines": [
{
"description": "Web application development",
"quantity": 40,
"unit": "hours",
"unit_price": 50,
"discount_percentage": 10,
"main_tax": {
"type": "IVA",
"percentage": 21,
"regime_key": "01"
},
"equivalence_surcharge_rate": 5.2,
"irpf_rate": 15,
"exemption_reason": "EXENTA_ART_20",
"exemption_reason_text": "string",
"taxable_base": 1800,
"line_total": 2178,
"pricing_mode": "UNIT_PRICE",
"total_excluding_tax": 1,
"total_including_tax": 100,
"line_type": "NORMAL",
"source_invoice_reference": "string",
"source_invoice_ids": [
"497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}
],
"totals": {
"taxable_base": 2000,
"total_discounts": 0,
"vat_breakdown": [
{
"type": 21,
"base": 2000,
"amount": 420
}
],
"total_vat": 420,
"surcharge_breakdown": [
{
"type": 0,
"base": 0,
"amount": 0
}
],
"total_equivalence_surcharge": 0,
"irpf_breakdown": [
{
"type": 0,
"base": 0,
"amount": 0
}
],
"total_irpf": 300,
"invoice_total": 2120,
"total_disbursements": 0,
"total_to_pay": 2120
},
"payment_info": {
"method": "BANK_TRANSFER",
"iban": "ES1234567890123456789012",
"swift": "ABCDESMMXXX",
"payment_term_days": 30
},
"notes": "string",
"void_cause": "VOID_REQUEST",
"void_reason": "string",
"voided_at": "2025-01-20T09:12:44Z",
"rectified_invoice_id": "986b41f8-8e28-4058-9e03-5286d0c42999",
"source_proforma_id": "5f6c4143-c67e-4332-9fbc-f68d1420128f",
"converted_invoice_id": "c85716fe-5512-4945-9dc8-daa0106a270b",
"rectification_reason": "string",
"recurring_invoice_id": "e6018980-fb8b-475b-a83d-b7bb0aa7423a",
"recurring_invoice_name": "string",
"rectification_type": "TOTAL",
"rectification_code": "R1",
"external_ref": "ORD-2025-0042",
"metadata": {
"external_customer_id": "cus_ULGk8bzIr88aag",
"external_payment_id": "pi_3NqFGb2eZvKYlo2C0z1234AB",
"payment_intent_id": "pi_3NqFGb2eZvKYlo2C0z1234AB",
"charge_id": "ch_3NqFGb2eZvKYlo2C1234CDEF",
"payment_provider": "STRIPE_CONNECT",
"external_order_id": "ORD-2025-0042"
},
"send_automatically": true,
"email_config": {
"recipients": [
"client@example.com"
],
"cc": [
"accounting@example.com"
],
"subject": "Invoice 2025/0001 - Development services",
"message": "Please find attached the requested invoice. We remain at your disposal for any clarification."
},
"pdf_download_url": "/v1/companies/7c9e6679-7425-40de-944b-e07fc1f90ae7/invoices/550e8400-e29b-41d4-a716-446655440000/pdf",
"verifactu": {
"enabled": false,
"invoice_hash": "3A5B7C9D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B",
"chaining_hash": "7F8E9D0C1B2A3F4E5D6C7B8A9F0E1D2C3B4A5F6E7D8C9B0A1F2E3D4C5B6A7F8",
"registration_number": "VERIFACTU2025000001",
"qr_url": "https://verifactu.agenciatributaria.gob.es/v?id=ABC123XYZ",
"qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADI...",
"registered_at": "2019-08-24T14:15:22Z",
"submission_status": "ACCEPTED",
"skip_reason": "CONFIG_DISABLED",
"error_code": "3000",
"error_message": "Factura ya existe en el sistema"
},
"attachments": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"url": "string",
"type": "string"
}
],
"sending_history": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"recipients": [
"string"
],
"cc": [
"string"
],
"subject": "string",
"status": "SENT",
"sent_at": "2025-01-29T18:45:00Z",
"external_message_id": "string",
"error": "string"
}
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_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 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": "NOT_FOUND",
"message": "Resource not found"
},
"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": "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"
}
}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.
Get the scheduling of an invoice GET
Returns the date and generation mode currently scheduled for this invoice. An invoice that is not scheduled answers `404`: the sub-resource does not exist yet. This read is what makes `generation_mode` tolerable as a required field on the `PUT`: a client that only wants to move the date can read the current mode and send it back.