Facturas

Create invoice

Creates a new invoice. **Idempotency:** Supports `X-Idempotency-Key` header to prevent duplicates.

POST
/facturas

Authorization

X-API-Key<token>

API Key authentication.

Format: X-API-Key: beel_sk_<key>

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-Idempotency-Key?string

UUID to prevent duplicates (recommended)

Formatuuid

Request Body

tipostring
  • ORDINARIA: Standard invoice
  • RECTIFICATIVA: Corrects or cancels a previous invoice
  • SIMPLIFICADA: Simplified invoice without all requirements (up to 400€)
Value in"ORDINARIA" | "RECTIFICATIVA" | "SIMPLIFICADA"
serie_id?string

Invoicing series ID (if not specified, uses default)

Formatuuid
fecha_emisionstring
Formatdate
fecha_vencimiento?string

If not specified, calculated according to payment method

Formatdate
receptor||
lineas
Items1 <= items
forma_pago?
observaciones?string
Lengthlength <= 1000
factura_rectificada_id?string

Required if tipo is "RECTIFICATIVA"

Formatuuid
motivo_rectificacion?string

Required if tipo is "RECTIFICATIVA"

Lengthlength <= 500
metadatos?

Additional metadata in key-value format. Useful for storing references to external systems like Stripe, order IDs, etc.

verifactu_habilitado?boolean

Whether VeriFactu information should be generated for this invoice

Defaultfalse
emitir_directamente?boolean

Controls whether the invoice is issued immediately or saved as a draft.

  • false (default): Creates invoice as BORRADOR (draft)

    • No invoice number assigned yet
    • Can be edited before issuing
    • PDF is NOT generated
    • Must call PUT /facturas/{id}/emitir to finalize

  • true: Creates invoice directly as EMITIDA (issued)

    • Assigns definitive invoice number (e.g., "A-2025-0001")
    • PDF is automatically generated
    • Invoice becomes immutable (cannot be edited)
    • Ready for sending or downloading immediately

Use cases for emitir_directamente: true:

  • Automated integrations (Stripe webhooks, ERPs)
  • Bulk invoice generation
  • APIs that don't need draft review
  • Payment confirmation flows
Defaultfalse
wait_for_pdf?boolean

Controls whether to wait for PDF generation before returning the response.

⚠️ Only applies when emitir_directamente: true

  • false (default): PDF generated asynchronously (background)

    • Response returns immediately (~100-300ms)
    • pdf_url and pdf_download_url will be null initially
    • PDF available after ~1-2 seconds
    • Use GET /facturas/{id} to check when pdf_url is populated

  • true: PDF generated synchronously (blocking)

    • Response waits for PDF (~1-3 seconds)
    • pdf_url and pdf_download_url included in response
    • Guarantees PDF is ready when you receive the response
    • Higher latency but simpler client logic

Recommendation:

  • Use false for bulk operations or when latency matters
  • Use true when you need the PDF URL immediately
Defaultfalse
enviar_automaticamente?boolean

Controls whether to send the invoice by email after processing.

⚠️ Only works when emitir_directamente: true (Drafts cannot be sent by email)

  • false (default): No email sent
  • true: Sends invoice email with PDF attachment

Email recipients priority:

  1. email_config.destinatarios (if provided)
  2. Receptor's email (from receptor.email or existing customer)

Requirements when true:

  • At least one valid email recipient
  • Invoice must be issued (not a draft)

Email is sent asynchronously via the outbox pattern. Check /facturas/{id}/emails for delivery status.

Defaultfalse
email_config?

Custom email configuration (optional).

Overrides default email settings when enviar_automaticamente: true.

Fields:

  • destinatarios: List of recipient emails (required if provided)
  • cc: List of CC emails (optional)
  • asunto: Custom subject line (optional, defaults to "Factura {numero}")
  • mensaje: Custom message body (optional)

Priority: If provided, email_config.destinatarios takes precedence over the receptor's email address.

Example use cases:

  • Send to multiple recipients
  • Add accounting department in CC
  • Customize subject for specific clients
  • Add personalized message

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/facturas" \  -H "Content-Type: application/json" \  -d '{    "tipo": "ORDINARIA",    "fecha_emision": "2025-01-20",    "receptor": {      "tipo_receptor": "EXISTENTE",      "cliente_id": "123e4567-e89b-12d3-a456-426614174000"    },    "lineas": [      {        "descripcion": "Desarrollo de página web corporativa",        "cantidad": 40,        "unidad": "horas",        "precio_unitario": 37.5,        "descuento_porcentaje": 0,        "impuesto_principal": {          "tipo": "IVA",          "porcentaje": 21,          "clave_regimen": "01"        }      }    ],    "forma_pago": {      "metodo": "TRANSFERENCIA",      "plazo_dias": 30    },    "observaciones": "Pago mediante transferencia bancaria"  }'

Invoice created successfully in BORRADOR state with draft number and totals

{
  "success": true,
  "data": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "numero_factura": "DRAFT-2025-001",
    "numero": 1,
    "tipo": "ORDINARIA",
    "estado": "BORRADOR",
    "fecha_emision": "2025-01-20",
    "emisor": {
      "nombre_fiscal": "Tu Empresa SL",
      "nif": "B12345678",
      "direccion": {
        "calle": "Calle Ejemplo",
        "numero": "123",
        "codigo_postal": "28001",
        "poblacion": "Madrid",
        "provincia": "Madrid",
        "pais": "España"
      }
    },
    "serie": {
      "id": "serie-general",
      "nombre": "General",
      "prefijo": "DRAFT"
    },
    "receptor": {
      "cliente_id": "123e4567-e89b-12d3-a456-426614174000",
      "nombre_fiscal": "Cliente Ejemplo SL",
      "nif": "B87654321",
      "email": "cliente@ejemplo.com",
      "direccion": {
        "calle": "Avenida Cliente",
        "numero": "456",
        "codigo_postal": "28013",
        "poblacion": "Madrid",
        "provincia": "Madrid",
        "pais": "España"
      }
    },
    "lineas": [
      {
        "id": "line-001",
        "descripcion": "Desarrollo de página web corporativa",
        "cantidad": 40,
        "unidad": "horas",
        "precio_unitario": 37.5,
        "descuento_porcentaje": 0,
        "base_imponible": 1500,
        "impuesto_principal": {
          "tipo": "IVA",
          "porcentaje": 21,
          "clave_regimen": "01",
          "importe": 315
        },
        "total_linea": 1815
      }
    ],
    "totales": {
      "base_imponible": 1500,
      "total_iva": 315,
      "total_irpf": 0,
      "total_recargo_equivalencia": 0,
      "total_factura": 1815
    },
    "forma_pago": {
      "metodo": "TRANSFERENCIA",
      "plazo_dias": 30
    },
    "observaciones": "Pago mediante transferencia bancaria",
    "verifactu": {
      "estado": "PENDIENTE"
    },
    "created_at": "2025-01-20T10:30:00Z",
    "updated_at": "2025-01-20T10:30:00Z"
  },
  "meta": {
    "timestamp": "2025-01-20T10:30:00Z",
    "request_id": "req_factura_001"
  }
}
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

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 client with NIF B12345678 already exists"
    }
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "req_error_004"
  }
}

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": "req_error_003"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Void invoice POST

Voids an invoice by changing its status to `anulada`. **Status change:** `borrador` or `enviada` → `anulada` **Validations:** - Cannot void invoices with status `pagada` - Requires a void reason **Note:** For Spanish tax compliance, consider creating a corrective invoice (rectificativa) instead of voiding.

Create corrective invoice POST

Creates a corrective invoice (factura rectificativa) to correct or void an issued invoice. **Rectification types:** - **TOTAL**: Completely voids the original invoice (original status → ANULADA) - **PARCIAL**: Partially corrects the original invoice (original status → RECTIFICADA) **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 EMITIDA, ENVIADA, PAGADA, VENCIDA or RECTIFICADA - Cannot rectify a BORRADOR invoice (must be issued first) - Cannot rectify an ANULADA invoice (final status) - For TOTAL rectification: Another total corrective cannot already exist - For PARCIAL rectification: Multiple partial correctives are allowed **Lines:** - TOTAL: Optional (if not provided, original lines are copied with negated amounts) - PARCIAL: REQUIRED (adjustment lines with positive or negative amounts)