InvoiceLifecycle

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 rectifies what is still invoiced on the original, its live correctives included, and leaves it VOIDED; a PARTIAL one leaves it RECTIFIED and may not take the base of any rate below zero (422 CORRECTIVE_EXCEEDS_INVOICED_AMOUNT).
  • Fiscal inheritance on a PARTIAL: lines that omit irpf_rate or equivalence_surcharge_rate take them from the original invoice, not from the company's current tax profile; an ambiguous original fails with 422 CORRECTIVE_ORIGINAL_MIXED_IRPF or 422 CORRECTIVE_ORIGINAL_MIXED_SURCHARGE. The successor operation documents the rule in full.

Retires on 9 December 2026. See the migration guide for what moved where and what changes when you switch.

post/v1/invoices/{invoice_id}/corrective

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/invoices/{invoice_id}/corrective
  • Auth: HTTP bearer

Path parameters

invoice_idstring uuid required

Universally Unique Identifier (UUID v4)

Example:550e8400-e29b-41d4-a716-446655440000

Invoice ID to rectify

Headers

Idempotency-Keystring

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)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses 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.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

rectification_type'TOTAL' | 'PARTIAL' required

Type of rectification applied to a corrective invoice:

  • TOTAL: Rectifies everything still invoiced on the original, its live correctives included (status → VOIDED)
  • PARTIAL: Partially corrects the original invoice (status → RECTIFIED)
rectification_code'R1' | 'R2' | 'R3' | 'R4' | 'R5' required

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: Corrective of a simplified invoice - ONLY for simplified invoices
reasonstring required

Detailed reason for rectification (minimum 10 characters)

circumstance_datestring date

When the circumstance that causes the rectification took place, if it is one of article 80 of the VAT Act (Ley 37/1992): a discount granted after the sale, an operation cancelled or a price changed after it took place, the customer's insolvency, a bad debt. Optional.

A corrective must be issued within four years from when the tax accrued or, for those causes, from when the circumstance took place (RD 1619/2012, art. 15.3). Without this date the four years count from the original's operation date (its operation_date, or its issue_date when it has none), the stricter of the two. Past the deadline the request fails with 422 CORRECTIVE_OUT_OF_TIME.

Only for R1, R2, R3 and R5: R4 covers causes other than article 80, and sending it with R4 fails with 422 CORRECTIVE_CIRCUMSTANCE_DATE_NOT_APPLICABLE. It must lie between the original's operation date and today (422 CORRECTIVE_CIRCUMSTANCE_DATE_OUT_OF_RANGE).

recipient_is_businessboolean

Declares that the recipient acted as a business or professional in the operation being rectified. Optional, and it only matters for a bad-debt corrective (R3) on an operation whose taxable base is 50 € or less: the law allows that reduction only when the recipient acted as a business or professional, and the invoice does not say so (Ley 37/1992, art. 80.Cuatro.A.3.ª). Without it, that R3 fails with 422 CORRECTIVE_BAD_DEBT_BASE_TOO_LOW.

notesstring

Additional observations about the rectification

series_idstring uuid

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, one is created on first use; a series of the wrong type fails with 422 SERIES_INCOMPATIBLE_DOC_TYPE.

external_refstring

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

metadataInvoiceMetadata

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. Metadata is not printed on the PDF; for values people read, filter or export, such as a store or a cost centre, use custom_fields.

Example request

{
  "rectification_type": "PARTIAL",
  "rectification_code": "R4",
  "reason": "Amount correction due to calculation error in hours worked during the project",
  "lines": [
    {
      "description": "Adjustment for hours error - Sprint 1",
      "quantity": -5,
      "unit": "hours",
      "unit_price": 50,
      "main_tax": {
        "type": "IVA",
        "percentage": 21,
        "regime_key": "01"
      },
      "irpf_rate": 15
    }
  ],
  "notes": "Rectification agreed with the customer on 2025-01-20",
  "external_ref": "ORD-2025-0042",
  "metadata": {
    "project_code": "PROJ-123"
  },
  "options": {
    "issue_directly": true,
    "send_automatically": false
  }
}

Response

Corrective invoice created successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "invoice_number": "2025/0001",
    "series": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "code": "FAC"
    },
    "number": 1,
    "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",
    "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",
      "additional_info": "Nº Colegiado: 12345"
    },
    "recipient": {
      "legal_name": "Empresa SL",
      "trade_name": "Empresa",
      "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"
    },
    "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",
        "taxable_base": 1800,
        "line_total": 2178,
        "total_excluding_tax": 1,
        "total_including_tax": 100,
        "line_type": "NORMAL"
      }
    ],
    "totals": {
      "taxable_base": 2000,
      "vat_breakdown": [
        {
          "type": 21,
          "base": 2000,
          "amount": 420,
          "regime_key": "18"
        }
      ],
      "total_vat": 420,
      "total_irpf": 300,
      "invoice_total": 2120,
      "total_to_pay": 2120
    },
    "payment_info": {
      "method": "BANK_TRANSFER",
      "iban": "ES1234567890123456789012",
      "swift": "ABCDESMMXXX",
      "payment_term_days": 30
    },
    "voided_at": "2025-01-20T09:12:44Z",
    "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"
    },
    "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": {
      "invoice_hash": "3A5B7C9D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B",
      "registration_number": "4f8c2a1e-9b3d-4e7a-8c5f-1d2e3f4a5b6c",
      "qr_url": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345674&numserie=A%2F2025%2F0042&fecha=20-01-2025&importe=1590.00",
      "qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADI...",
      "submission_status": "ACCEPTED",
      "skip_reason": "CONFIG_DISABLED",
      "error_code": "3000",
      "error_message": "Factura ya existe en el sistema"
    },
    "sending_history": [
      {
        "sent_at": "2025-01-29T18:45:00Z"
      }
    ],
    "email_delivery": {
      "status": "REJECTED",
      "reason": "error.email.envio_no_permitido"
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "custom_fields": [
      {
        "key": "store",
        "label": "Store",
        "value": "Gran Vía 12"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.