Create a corrective invoice

Issues a corrective invoice that amends an issued invoice.

Deprecated: use POST /v1/companies/{company_id}/invoices/{invoice_id}/corrective, which behaves identically.
Rectification type: a TOTAL rectification leaves the original VOIDED; a PARTIAL one leaves it RECTIFIED.

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

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 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.

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, the company's default series for corrective invoices is used — not the original invoice's series, which is an ordinary or simplified one and cannot hold a corrective. If the company has no default corrective series the request fails with 422 SERIES_DEFAULT_NOT_FOUND; a series of the wrong type fails with 422 SERIES_INCOMPATIBLE_DOC_TYPE.

Formatuuid

external_ref?string

Client-supplied identifier from an external system (order, cart, contract…). Stored as-is, echoed back on read, and filterable via GET /v1/invoices?external_ref=. Optional. Enforced UNIQUE per issuer for live standard/simplified invoices: creating a second invoice with the same reference returns 409 (INVOICE_DUPLICATE_EXTERNAL_REFERENCE); deleting the existing one lets you recreate. Corrective invoices are exempt from that uniqueness: a corrective carries the same order reference as the invoice it corrects, so both can coexist. This is a business key, NOT the Idempotency-Key (which guards request retries).

Lengthlength <= 255

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, except verifactu_enabled, which falls back to the company's declared preference (see its description).

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

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."
  }'

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": {
    "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,
          "regime_key": "18"
        }
      ],
      "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": "QUEUED",
        "sent_at": "2025-01-29T18:45:00Z",
        "external_message_id": "string",
        "error": "string"
      }
    ],
    "deleted_at": "2019-08-24T14:15:22Z",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2019-08-24T14:15:22Z",
    "updated_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 is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "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"
}

An explicit series_id was sent, but that series is not typed for corrective invoices (e.g. an ordinary series). Pass a corrective series, or omit series_id to use the company default.

{
  "success": false,
  "error": {
    "code": "SERIES_INCOMPATIBLE_DOC_TYPE",
    "message": "The selected series is not compatible with this document type. Please select a series of the correct type.",
    "details": {
      "expected_document_type": "FACTURA_RECTIFICATIVA",
      "defaults_status_endpoint": "GET /v1/companies/7c9e6679-7425-40de-944b-e07fc1f90ae7/series/defaults"
    }
  },
  "meta": {
    "timestamp": "2025-02-01T10:20:00Z",
    "request_id": "b2b2b2b2-0810-4000-a000-000000000422"
  }
}

{
  "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"
  }
}

{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Create a corrective invoice

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

422application/json

429application/json

500application/json

defaultapplication/json

Explicit series of the wrong type (422)

No default corrective series (422)

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json