BeeL
Get StartedVeriFactuStripeAPI Reference
Invoices

Create invoice

Creates a new invoice.

Idempotency: Supports Idempotency-Key header to prevent duplicates.

Try this endpoint with Claude
Copy the prompt for any assistant, or open it directly in Claude Code (needs it installed).
POST
/v1/invoices

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

Header Parameters

X-Active-Profile?string

UUID of the business profile (sub-account / company) to operate as for this request.

Use with a master account API key to act on behalf of any owned sub-account without provisioning a separate key per company. Without this header the request operates as the API key owner.

Requirements:

  • The API key must belong to a master account (sub-account keys ignore this header).
  • The API key must have the business_profiles:read scope.
  • The target profile must be a sub-account owned by the key owner.

Returns 403 Forbidden if the profile is not owned by the key owner.

Formatuuid
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 after processing
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Request Body

typestring
  • STANDARD: Standard invoice
  • CORRECTIVE: Corrects or cancels a previous invoice
  • SIMPLIFIED: Simplified invoice without all recipient requirements (up to 3,000€ VAT included)
  • PROFORMA: Commercial document (formal quote) with no fiscal validity. Never enters VeriFactu (no QR, no AEAT submission) and verifactu_enabled is always forced to false. Requires full recipient data, like STANDARD. Cannot be corrective nor reference a rectified invoice.
Value in"STANDARD" | "CORRECTIVE" | "SIMPLIFIED" | "PROFORMA"
series_id?string

Invoicing series ID (if not specified, uses default)

Formatuuid
operation_date?string

Date when the operation actually occurred. Optional.

Use when invoicing for a past operation (e.g., services delivered last month but invoiced this month). Must be today or a past date.

If omitted, the operation date is assumed to be the same as the issue date (today).

The issue_date is always set automatically to today per Spanish anti-fraud law (Ley Antifraude / VeriFactu). To issue an invoice on a future date, create a draft and use POST /v1/invoices/{id}/schedule.

Formatdate
due_date?string

Payment due date. If not specified, calculated according to payment method. Must be the same as or after the issue date (today).

Formatdate
valid_until?string

Offer validity date. Only rendered on PROFORMA invoices; on any other invoice type the field is inert (accepted and stored, but never shown on the document). Optional and purely informational — nothing is triggered automatically when it passes. Not to be confused with due_date (payment due date).

Formatdate
recipient
lines
Items1 <= items
payment_info?
notes?string
Lengthlength <= 1000
rectified_invoice_id?string

Required if type is "CORRECTIVE"

Formatuuid
rectification_reason?string

Required if type is "CORRECTIVE"

Lengthlength <= 500
metadata?

Your own key/value pairs to cross-reference this invoice with records in your system (order ids, tenants, internal codes). Namespace them to avoid clashing with the system keys BeeL adds on payment-generated invoices.

options?

Controls how the invoice is processed after creation. All fields default to false if not specified.

Common combinations:

  • Draft (default): omit options or set all to false
  • Issue immediately: { issue_directly: true }
  • Issue + wait for PDF: { issue_directly: true, wait_for_pdf: true }
  • Issue + send email: { issue_directly: true, send_automatically: true }
  • Full automation: { issue_directly: true, wait_for_pdf: true, send_automatically: true, email_config: { ... } }

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/invoices" \  -H "Content-Type: application/json" \  -d '{    "type": "STANDARD",    "recipient": {      "customer_id": "123e4567-e89b-12d3-a456-426614174000"    },    "lines": [      {        "description": "Corporate website development",        "quantity": 40,        "unit": "hours",        "unit_price": 37.5,        "discount_percentage": 0,        "main_tax": {          "type": "IVA",          "percentage": 21,          "regime_key": "01"        }      }    ],    "payment_info": {      "method": "BANK_TRANSFER",      "iban": "ES9121000418450200051332",      "payment_term_days": 30    },    "notes": "Payment via bank transfer"  }'

Invoice created successfully in DRAFT state with draft number and totals

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "invoice_number": null,
    "number": null,
    "type": "STANDARD",
    "status": "DRAFT",
    "issue_date": "2025-01-20",
    "issuer": {
      "legal_name": "Tu Empresa SL",
      "nif": "B12345678",
      "address": {
        "street": "Calle Ejemplo",
        "number": "123",
        "postal_code": "28001",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España"
      }
    },
    "series": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "A"
    },
    "recipient": {
      "customer_id": "123e4567-e89b-12d3-a456-426614174000",
      "legal_name": "Cliente Ejemplo SL",
      "nif": "B87654321",
      "email": "cliente@ejemplo.com",
      "address": {
        "street": "Avenida Cliente",
        "number": "456",
        "postal_code": "28013",
        "city": "Madrid",
        "province": "Madrid",
        "country": "España"
      }
    },
    "lines": [
      {
        "description": "Corporate website development",
        "quantity": 40,
        "unit": "hours",
        "unit_price": 37.5,
        "discount_percentage": 0,
        "taxable_base": 1500,
        "main_tax": {
          "type": "IVA",
          "percentage": 21,
          "regime_key": "01"
        },
        "line_total": 1815
      }
    ],
    "totals": {
      "taxable_base": 1500,
      "total_vat": 315,
      "total_irpf": 0,
      "total_equivalence_surcharge": 0,
      "vat_breakdown": [
        {
          "type": 21,
          "base": 1500,
          "amount": 315
        }
      ],
      "invoice_total": 1815
    },
    "payment_info": {
      "method": "BANK_TRANSFER",
      "payment_term_days": 30
    },
    "notes": "Payment via bank transfer",
    "verifactu": {
      "enabled": false
    },
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  },
  "meta": {
    "timestamp": "2025-01-20T10:30:00Z",
    "request_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"
  }
}
{
  "success": false,
  "error": {
    "code": "INVALID_JSON_FORMAT",
    "message": "The field 'due_date' has an invalid date format: '2026-03-04fds'. Expected format: YYYY-MM-DD.",
    "details": {
      "field": "due_date",
      "invalid_value": "2026-03-04fds",
      "expected_format": "YYYY-MM-DD"
    }
  },
  "meta": {
    "timestamp": "2026-03-05T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Duplicate resource exists (NIF, email, invoice number, series code)

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Resource already exists",
    "details": {
      "conflict_type": "DUPLICATE_NIF",
      "field": "nif",
      "value": "B12345678",
      "existing_resource_id": "123e4567-e89b-12d3-a456-426614174000",
      "message": "A customer with NIF B12345678 already exists"
    }
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "d4d4d4d4-0004-4000-a000-000000000004"
  }
}

Request data fails validation (missing fields, invalid format, business rules)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "nif",
          "message": "Invalid NIF format. Expected 9 characters (8 digits + letter or letter + 8 digits)",
          "value": "B123INVALID"
        },
        {
          "field": "lineas",
          "message": "At least one line item is required",
          "value": []
        },
        {
          "field": "receptor.direccion.codigo_postal",
          "message": "Invalid postal code format. Expected 5 digits",
          "value": "280"
        },
        {
          "field": "lineas[0].precio_unitario",
          "message": "Unit price must be greater than or equal to 0",
          "value": -10.5
        }
      ]
    }
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "c3c3c3c3-0003-4000-a000-000000000003"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Create corrective invoice POST

Creates a corrective invoice to correct or void an issued invoice. **Rectification types:** - **TOTAL**: Completely voids the original invoice (original status → VOIDED) - **PARTIAL**: Partially corrects the original invoice (original status → RECTIFIED) **VeriFactu codes:** - R1: Legal error and Art. 80 One, Two and Six LIVA - R2: Article 80 Three LIVA (Bankruptcy) - R3: Article 80 Four LIVA (Bad debts) - R4: Other causes - R5: Simplified invoices (only for simplified) **Validations:** - Original invoice must be in status ISSUED, SENT, PAID, OVERDUE or RECTIFIED - Cannot rectify a DRAFT invoice (must be issued first) - Cannot rectify a VOIDED invoice (final status) - For TOTAL rectification: Another total corrective cannot already exist - For PARTIAL rectification: Multiple partial correctives are allowed **Lines:** - TOTAL: Optional (if not provided, original lines are copied with negated amounts) - PARTIAL: REQUIRED (adjustment lines with positive or negative amounts)

Delete invoice DELETE

Deletes (marks as deleted) an invoice. **Soft delete:** The invoice is not physically deleted, only marked as deleted. **Restriction:** Only invoices in `DRAFT` status can be deleted.