BeeL
Get StartedVeriFactuStripeAPI Reference
Invoices

Create corrective invoice

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)
Try this endpoint with Claude
Copy the prompt for any assistant, or open it directly in Claude Code (needs it installed).
POST
/v1/invoices/{invoice_id}/corrective

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

invoice_idstring

Invoice ID to rectify

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

Request Body

rectification_typestring

Type of rectification applied to a corrective invoice:

  • TOTAL: Completely cancels the original invoice (status → VOIDED)
  • PARTIAL: Partially corrects the original invoice (status → RECTIFIED)
Value in"TOTAL" | "PARTIAL"
rectification_codestring

Rectification codes according to VeriFactu regulations (AEAT):

  • R1: Error founded in law and Art. 80 One, Two and Six LIVA
  • R2: Article 80 Three LIVA (Bankruptcy proceedings)
  • R3: Article 80 Four LIVA (Uncollectable debts)
  • R4: Other causes
  • R5: Simplified invoices (Art. 80 One and Two LIVA) - ONLY for simplified invoices
Value in"R1" | "R2" | "R3" | "R4" | "R5"
reasonstring

Detailed reason for rectification (minimum 10 characters)

Length10 <= length <= 1000
lines?

TOTAL: Optional (if not sent, original invoice lines are copied negated) PARTIAL: REQUIRED (adjustment lines with positive or negative amounts)

notes?string

Additional observations about the rectification

Lengthlength <= 1000
series_id?string

Series for the corrective invoice (optional, if not specified uses the original invoice's series)

Formatuuid
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

application/json

curl -X POST "https://app.beel.es/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/corrective" \  -H "Content-Type: application/json" \  -d '{    "rectification_type": "TOTAL",    "rectification_code": "R1",    "reason": "Cancellation of invoice issued due to a legally founded error under Art. 80 Uno LIVA. The transaction was not completed due to project cancellation before commencement.",    "notes": "Original invoice F/2025/0042 fully cancelled. Customer notified."  }'
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "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",
      "web": "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
      }
    ],
    "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
    },
    "payment_info": {
      "method": "BANK_TRANSFER",
      "iban": "ES1234567890123456789012",
      "swift": "ABCDESMMXXX",
      "payment_term_days": 30
    },
    "notes": "string",
    "rectified_invoice_id": "986b41f8-8e28-4058-9e03-5286d0c42999",
    "source_proforma_id": "5f6c4143-c67e-4332-9fbc-f68d1420128f",
    "rectification_reason": "string",
    "recurring_invoice_id": "e6018980-fb8b-475b-a83d-b7bb0aa7423a",
    "recurring_invoice_name": "string",
    "rectification_type": "TOTAL",
    "rectification_code": "R1",
    "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/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...",
      "registration_date": "2019-08-24T14:15:22Z",
      "submission_status": "PENDING",
      "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",
        "date": "2019-08-24T14:15:22Z",
        "recipient": "user@example.com",
        "status": "SENT",
        "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": "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": "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": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Convert a proforma into an invoice POST

Converts a proforma (a commercial quote accepted by the customer) into a real invoice. Only proformas in status `ISSUED` or `SENT` can be converted. The source proforma **survives intact** (keeping its `PRO-...` number and PDF as the record of what the customer accepted) and transitions to the terminal status `CONVERTED`. The result is a **new** `STANDARD` invoice in `DRAFT` status, linked back to the source proforma via `source_proforma_id`. Fine-tune the draft by editing it, then issue it through the normal issuance flow. **Status changes:** - Proforma: `ISSUED`/`SENT` → `CONVERTED` - New invoice: created as `STANDARD` / `DRAFT` (no definitive number yet) **Emit in the same act (`issue: true`):** the resulting invoice is emitted immediately — a definitive fiscal number is assigned and the quota, ledger and VeriFactu→PDF pipeline run through the normal issuance flow. The operation is **atomic**: if the emission fails (quota exhausted, unsigned NIF, misconfigured series…), the whole conversion is rolled back — no invoice is created, and the proforma stays `ISSUED`/`SENT` and convertible. When omitted or `false`, the invoice is left in `DRAFT` for you to fine-tune first. **Idempotency:** `CONVERTED` is terminal, so a second call returns a business error instead of creating another invoice. **Validations:** - The document must be a proforma (`CONVERSION_REQUIRES_PROFORMA` otherwise) - Must be in `ISSUED` or `SENT` status (`PROFORMA_NOT_CONVERTIBLE` otherwise) - Must not have been converted already (`PROFORMA_ALREADY_CONVERTED`)

Create invoice POST

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