CreateCorrectiveInvoiceRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/beel-es/json-schema/beel-es-create-corrective-invoice-request-schema.json",
  "title": "CreateCorrectiveInvoiceRequest",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/beel-es-openapi.json#/components/schemas/CreateCorrectiveInvoiceRequest",
  "type": "object",
  "required": [
    "rectification_type",
    "rectification_code",
    "reason"
  ],
  "properties": {
    "rectification_type": {
      "$ref": "#/$defs/RectificationType"
    },
    "rectification_code": {
      "$ref": "#/$defs/VeriFactuRectificationCode"
    },
    "reason": {
      "type": "string",
      "minLength": 10,
      "maxLength": 1000,
      "description": "Detailed reason for rectification (minimum 10 characters)"
    },
    "lines": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "quantity"
        ],
        "properties": {
          "description": {
            "type": "string",
            "maxLength": 2000,
            "description": "Concept description. Required."
          },
          "quantity": {
            "type": "number",
            "description": "Quantity (can be negative for corrective invoices)"
          },
          "unit": {
            "type": "string"
          },
          "unit_price": {
            "type": "number",
            "maximum": 999999.9999,
            "description": "Unit price before taxes (can be negative in corrective invoices).\nSupports up to 4 decimal places for micro-pricing (e.g., €0.0897/unit for labels, packaging).\nFinal amounts are always rounded to 2 decimals.\n"
          },
          "total_excluding_tax": {
            "type": "number",
            "maximum": 99999999.99,
            "description": "Declared line total excluding taxes (total-declared mode, e.g. 300 units\ninvoiced for exactly 1.00). The taxable base of the line is EXACTLY this\namount — it is never recalculated from the unit price. The unit price\nbecomes derived and informational (`total / quantity`, 4 decimals).\nEach line must carry exactly one of `unit_price`, `total_excluding_tax`\nor `total_including_tax` (anything else is rejected with\n`LINE_UNIT_PRICE_XOR_DECLARED_TOTAL`). Incompatible with\n`discount_percentage` (`LINE_DECLARED_TOTAL_FORBIDS_DISCOUNT`): any\ndiscount is already included in the declared total. Can be negative\nin corrective invoices.\n"
          },
          "total_including_tax": {
            "type": "number",
            "maximum": 99999999.99,
            "description": "Declared line total including taxes (tax-inclusive total-declared\nmode): what the customer paid for this line — taxable base + VAT +\nequivalence surcharge. IRPF withholding is NOT part of it (it is a\nretention, not price; it is computed on the derived base as usual).\nThe engine works the breakdown backwards from the unrounded base\n(`base_raw = total / (1 + vat + surcharge)`, DGT V1919-18) so the\nrounded amounts add up to the declared total exactly (e.g. 100.00\nat 21% → 82.64 + 17.36 = 100.00). On exempt or 0% lines it is\nequivalent to `total_excluding_tax` (base = total, quota 0).\nEach line must carry exactly one of `unit_price`, `total_excluding_tax`\nor `total_including_tax` (anything else is rejected with\n`LINE_UNIT_PRICE_XOR_DECLARED_TOTAL`). Incompatible with\n`discount_percentage` (`LINE_DECLARED_TOTAL_FORBIDS_DISCOUNT`).\nCan be negative in corrective invoices.\n"
          },
          "discount_percentage": {
            "type": "number",
            "minimum": 0,
            "maximum": 100,
            "default": 0
          },
          "main_tax": {
            "$ref": "#/$defs/TaxInfo"
          },
          "equivalence_surcharge_rate": {
            "allOf": [
              {
                "$ref": "#/$defs/EquivalenceSurchargePercentage"
              }
            ],
            "description": "Equivalence surcharge rate for this line of the corrective\ninvoice.\n\n**Default behaviour:** if omitted, the line inherits the\nsurcharge **regime** of the invoice being amended — not the\ncompany's current tax profile, whose default does not apply to\ncorrective invoices. What travels from the original is the\non/off signal, not the rate: the rate is re-derived from this\nline's own VAT (21→5.2, 10→1.4, 5→0.62, 4→0.5), so a\ncorrective line at 10% gets 1.4 even when the original line it\namends was at 21%. If the original was outside the regime the\nline is pinned to `0`, so today's profile never adds a\nsurcharge to the credit note of an invoice that carried none.\nAn explicit value is always respected. If the original applies\nthe surcharge on some lines but not others there is no regime\nto inherit and the request fails with\n`422 CORRECTIVE_ORIGINAL_MIXED_SURCHARGE`: send\n`equivalence_surcharge_rate` on every line. The original's\n`SUPLIDO` lines carry no surcharge and are left out of that check.\n"
          },
          "irpf_rate": {
            "allOf": [
              {
                "$ref": "#/$defs/IrpfPercentage"
              }
            ],
            "description": "IRPF withholding rate for this line of the corrective invoice.\n\n**Default behaviour:** if omitted, the line inherits the rate\nof the invoice being amended — **not** the account's default\nIRPF rate from the tax profile, whose default does not apply to\ncorrective invoices: a profile that changed after the original\nwas issued must not alter what the credit note withholds. An\nexplicit value is always respected, `0` included, which is how\nyou issue a line **without** withholding. If the original\nwithholds different rates on different lines there is nothing\nunambiguous to inherit and the request fails with\n`422 CORRECTIVE_ORIGINAL_MIXED_IRPF`: send `irpf_rate` on every\nline. The original's `SUPLIDO` lines carry no IRPF and are left\nout of that check. On SIMPLIFIED invoices (F2) IRPF withholding is **not\nallowed** (AEAT forbids it on F2): sending an `irpf_rate` other\nthan 0 is **rejected** with `SIMPLIFICADA_FORBIDS_IRPF` — it is\nnot coerced to 0. Omit the field or send `irpf_rate: 0` on F2\nlines.\n"
          },
          "exemption_reason": {
            "$ref": "#/$defs/ExemptionReason",
            "nullable": true
          },
          "exemption_reason_text": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500
          },
          "line_type": {
            "allOf": [
              {
                "$ref": "#/$defs/InvoiceLineType"
              }
            ],
            "description": "Only `NORMAL` is accepted, which is also what an omitted value means. A\n`PARTIAL` corrective adjusts the taxable base or the tax of the original, and a\ndisbursement (`SUPLIDO`) is neither: it is outside the taxable base (Ley 37/1992,\nart. 78.Tres.3.º), so there is nothing in it to rectify. A `SUPLIDO` line fails\nwith `422 CORRECTIVE_PARTIAL_SUPLIDO_NOT_ALLOWED`. If an amount invoiced as a\ndisbursement did not qualify as one, it was part of the taxable base: rectify it\nas a `NORMAL` line with its tax.\n"
          }
        }
      },
      "description": "**TOTAL**: not accepted. A `TOTAL` corrective rectifies what is still invoiced on the\noriginal —its lines and those of its live correctives, negated, `SUPLIDO` lines included\nas they were— and a request with `lines` fails with `422 RECTIFICATIVA_TOTAL_CON_LINEAS`.\n**PARTIAL**: required. The adjustment lines, with positive or negative amounts; they\nmay not take the base of any rate below zero (`422 CORRECTIVE_EXCEEDS_INVOICED_AMOUNT`).\nThey are `NORMAL` lines only (`422 CORRECTIVE_PARTIAL_SUPLIDO_NOT_ALLOWED`).\n"
    },
    "circumstance_date": {
      "type": "string",
      "format": "date",
      "description": "When the circumstance that causes the rectification took place, if it is one of article\n80 of the VAT Act (Ley 37/1992): a discount granted after the sale, an operation cancelled\nor a price changed after it took place, the customer's insolvency, a bad debt. Optional.\n\nA corrective must be issued within four years from when the tax accrued or, for those\ncauses, from when the circumstance took place (RD 1619/2012, art. 15.3). Without this\ndate the four years count from the original's operation date (its `operation_date`, or\nits `issue_date` when it has none), the stricter of the two. Past the deadline the request\nfails with `422 CORRECTIVE_OUT_OF_TIME`.\n\nOnly for `R1`, `R2`, `R3` and `R5`: `R4` covers causes other than article 80, and sending\nit with `R4` fails with `422 CORRECTIVE_CIRCUMSTANCE_DATE_NOT_APPLICABLE`. It must lie\nbetween the original's operation date and today\n(`422 CORRECTIVE_CIRCUMSTANCE_DATE_OUT_OF_RANGE`).\n"
    },
    "recipient_is_business": {
      "type": "boolean",
      "description": "Declares that the recipient acted as a business or professional in the operation being\nrectified. Optional, and it only matters for a bad-debt corrective (`R3`) on an\noperation whose taxable base is 50 € or less: the law allows that reduction only when\nthe recipient acted as a business or professional, and the invoice does not say so\n(Ley 37/1992, art. 80.Cuatro.A.3.ª). Without it, that `R3` fails with\n`422 CORRECTIVE_BAD_DEBT_BASE_TOO_LOW`.\n"
    },
    "notes": {
      "type": "string",
      "maxLength": 1000,
      "description": "Additional observations about the rectification"
    },
    "series_id": {
      "type": "string",
      "format": "uuid",
      "description": "Series for the corrective invoice. Optional: if not specified, the company's\n**default series for corrective invoices** is used — not the original invoice's\nseries, which is an ordinary or simplified one and cannot hold a corrective.\nIf the company has no default corrective series, one is created on first use; a\nseries of the wrong type fails with `422 SERIES_INCOMPATIBLE_DOC_TYPE`.\n"
    },
    "external_ref": {
      "$ref": "#/$defs/ExternalRef"
    },
    "metadata": {
      "$ref": "#/$defs/InvoiceMetadata"
    },
    "recipient": {
      "allOf": [
        {
          "$ref": "#/$defs/Recipient"
        }
      ],
      "writeOnly": true,
      "description": "Only to correct the recipient's data. A corrective invoice carries the recipient of the\ninvoice it corrects, with that invoice's data, except when the invoice recorded that same\nrecipient with a wrong name, tax ID or address: then send the corrected recipient here,\nwith `rectification_type` `PARTIAL`, `rectification_code` `R4` and no `lines`. That\ncorrective leaves the amounts unchanged and the original `RECTIFIED`.\n\n- When the original went to a registered customer, send that same `customer_id`, with\n  its data already fixed; another customer fails with\n  `422 CORRECTIVE_RECIPIENT_IS_ANOTHER_PERSON` — an invoice issued to another person is\n  corrected in full (`TOTAL`) and issued again to the right customer.\n- The same name, tax ID and address as recorded fail with\n  `422 CORRECTIVE_RECIPIENT_UNCHANGED`.\n- A `recipient` in any other corrective fails with\n  `422 CORRECTIVE_RECIPIENT_NOT_ACCEPTED`, and nothing is created.\n"
    },
    "options": {
      "$ref": "#/$defs/InvoiceProcessingOptions"
    }
  },
  "$defs": {
    "Address": {
      "description": "Address you send when you create or update a company, a customer or an onboarding.\n\nA required field made only of whitespace passes the length checks below but leaves the\naddress without that part, so it is rejected with `422`: `STREET_EMPTY`,\n`POSTAL_CODE_EMPTY`, `CITY_EMPTY` or `PROVINCE_EMPTY`.\n\nAddresses you read back are described by their own schema.\n",
      "type": "object",
      "required": [
        "street",
        "postal_code",
        "city"
      ],
      "properties": {
        "street": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "Full address (street, number, floor, etc.) - Latin characters only"
        },
        "number": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "description": "Street number. Optional: omit it when the address has none, or when `street` already\ncarries the address in full.\n"
        },
        "floor": {
          "type": "string",
          "maxLength": 10,
          "description": "Floor or level"
        },
        "door": {
          "type": "string",
          "maxLength": 10,
          "description": "Door or apartment"
        },
        "postal_code": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "description": "Postal code (5 digits for Spain, free format for other countries)"
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "City or town - Latin characters only"
        },
        "province": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "Province or state - Latin characters only. Required for an address in Spain\n(`country_code` `ES`, or no country at all); optional elsewhere, where many addresses\nhave none. A Spanish address without it is rejected with a `422`.\n"
        },
        "country": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100,
          "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
          "description": "Country of the address, as its ISO 3166-1 alpha-2 code (`GB`) or its official name\nin Spanish, English or Catalan (`Reino Unido`, `United Kingdom`, `Regne Unit`;\ncase and accents are ignored). Anything else, such as `UK`, is rejected with\n`422 COUNTRY_CODE_REQUIRED`: send `country_code` instead. If it names a different\ncountry than `country_code`, `422 COUNTRY_CODE_MISMATCH` (`España` alone yields to\na foreign `country_code`: it was the old default). What is stored and\nreturned is always the Spanish name derived from the resulting code, never the\ntext sent. With neither field present, the address is Spanish (`España`).\n"
        },
        "country_code": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "minLength": 2,
          "maxLength": 2,
          "description": "ISO 3166-1 alpha-2 country code: the canonical field that decides the country of\nthe address. It must be a real country code (`GB`, not `UK`); otherwise\n`422 COUNTRY_CODE_REQUIRED`. When it is omitted, the code comes from `country`\n(see there). With neither field present, the address is stored as `ES`.\n"
        }
      }
    },
    "AlternativeIdentifier": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "type",
        "number"
      ],
      "description": "Alternative identifier for customers without Spanish Tax ID.\n\n### VeriFactu rules (checked when you send it, `422` on violation)\n- `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two\n  types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the\n  identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names\n  the field where it was sent: `alternative_id.country_code` on a customer,\n  `recipient.alternative_id.country_code` on an invoice recipient. Same code in both.\n- If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07)\n  (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`).\n- If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES`\n  (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a\n  Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`).\n  That DNI or NIE must not be one the AEAT census identifies: if it is, the identifier is\n  rejected with `ALTERNATIVE_ID_ACTUALLY_IN_CENSUS` and has to be sent as `nif`. A customer\n  is checked when it is saved; an invoice recipient, when the invoice is issued with\n  VeriFactu. If the census does not answer, the identifier is not rejected.\n- If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain\n  (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's\n  EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed\n  by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201`\n  (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in\n  uppercase. A customer from outside the EU is identified with another type, such as\n  `OTHER_DOCUMENT` or `COUNTRY_ID`.\n\nA `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`.\n\nWell-formed is not the same as registered: an EU VAT number that is not in the VIES\ncensus is still rejected by VeriFactu after the invoice is issued.\n\nAn identifier returned in a response is the one stored. A customer saved before a rule\nexisted keeps its identifier and can still be read; issuing an invoice to it with an\nidentifier that breaks these rules is rejected with the same code, before a number is used.\n\n### Matrix of allowed combinations\n| `type`                 | `country_code = ES` | `country_code ≠ ES` |\n|------------------------|:-------------------:|:-------------------:|\n| `NIF_IVA` (02)         | ✗                   | EU member states only |\n| `PASSPORT` (03)        | ✓                   | ✓                   |\n| `COUNTRY_ID` (04)      | ✗                   | ✓                   |\n| `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   |\n| `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   |\n| `NOT_REGISTERED` (07)  | ✓                   | ✗                   |\n",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "NIF_IVA",
            "PASSPORT",
            "COUNTRY_ID",
            "RESIDENCE_CERTIFICATE",
            "OTHER_DOCUMENT",
            "NOT_REGISTERED",
            "02",
            "03",
            "04",
            "05",
            "06",
            "07"
          ],
          "description": "Identifier type. Use descriptive names:\n- **NIF_IVA**: EU VAT number (intra-community) — *only for an EU member state other than Spain, with that country's VAT number structure*\n- **PASSPORT**: Passport — *allowed for any country*\n- **COUNTRY_ID**: Country of residence ID — *not allowed when `country_code = ES`*\n- **RESIDENCE_CERTIFICATE**: Residence certificate — *not allowed when `country_code = ES`*\n- **OTHER_DOCUMENT**: Other supporting document — *not allowed when `country_code = ES`*\n- **NOT_REGISTERED**: Not registered in AEAT — *requires `country_code = ES`*\n\n**⚠️ DEPRECATED numeric codes** (will be removed in v2):\n02, 03, 04, 05, 06, 07 — use the descriptive names above instead.\n"
        },
        "number": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20,
          "description": "Identifier number. For `NIF_IVA`, the full EU VAT number with its country prefix\n(e.g. `FR40303265045`); see the VeriFactu rules on the parent schema.\n"
        },
        "country_code": {
          "type": "string",
          "pattern": "^[A-Z]{2}$",
          "minLength": 2,
          "maxLength": 2,
          "description": "ISO 3166-1 alpha-2 code of the country that issued the document. Required except for\n`PASSPORT` and `NOT_REGISTERED`, where omitting it means `ES`. Constrains the allowed\n`type` values; see the VeriFactu rules on the parent schema.\n"
        }
      }
    },
    "Email": {
      "type": "string",
      "format": "email",
      "minLength": 5,
      "maxLength": 255,
      "description": "Email address (minimum valid email is 5 chars, e.g. a@b.co)"
    },
    "EmailConfiguration": {
      "type": "object",
      "description": "Who the invoice is emailed to when `send_automatically` is true. Every address in\n`recipients` and `cc` must have a domain with a dot, or the request answers\n`422 INVALID_EMAIL_FORMAT`. With `send_automatically` true and no recipients here, no\n`customer_id` and no recipient email, there is nobody to send to: `422`\n`AUTOMATIC_EMAIL_CONFIG_INVALID`.\n",
      "required": [
        "recipients"
      ],
      "properties": {
        "recipients": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Email"
          },
          "minItems": 1,
          "description": "List of recipient emails (at least 1 required)"
        },
        "cc": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Email"
          },
          "description": "List of CC emails (optional)"
        },
        "subject": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "description": "Custom email subject (optional). Priority: the request that sends the email > this\n`email_config.subject` > the `defaults.subject` of the company's email configuration >\nthe standard subject.\n"
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "maxLength": 2000,
          "description": "Custom message (optional, added to the email body). It is sent with the email.\nPriority: the request that sends the email > this `email_config.message` > the\n`defaults.message` of the company's email configuration > the standard message.\n"
        }
      }
    },
    "EquivalenceSurchargePercentage": {
      "type": "number",
      "enum": [
        0,
        0.26,
        0.5,
        0.62,
        1,
        1.4,
        1.75,
        5.2
      ],
      "description": "Equivalence surcharge percentage in decimal format, one of the values AEAT accepts.\nPairs allowed (VAT rate ↔ surcharge): 21↔5.2, 21↔1.75 (tobacco products), 10↔1.4,\n4↔0.5, and the temporary ones, only on operations of their period: 5↔0.5 up to\n2022-12-31, 5↔0.62 from 2023-01-01 to 2024-09-30, and 7.5↔1 and 2↔0.26 from\n2024-10-01 to 2024-12-31. A pair outside its period is rejected with\n`422 SURCHARGE_RATE_NOT_ACCEPTED_ON_DATE`. `GET /v1/tax-types` publishes every pair with\nits `valid_from` / `valid_until`.\nThe backend automatically normalizes equivalent formats (5.20 → 5.2).\n"
    },
    "ExemptionReason": {
      "type": "string",
      "enum": [
        "EXENTA_ART_20",
        "EXENTA_ART_21",
        "EXENTA_ART_22",
        "EXENTA_ART_24",
        "EXENTA_ART_25",
        "EXENTA_ART_26",
        "EXENTA_ART_140",
        "NO_SUJETA_ART_7_9",
        "NO_SUJETA_LOCALIZACION",
        "ISP_ART_84_2_A",
        "ISP_ART_84_2_B",
        "ISP_ART_84_2_C",
        "ISP_ART_84_2_D",
        "ISP_ART_84_2_E",
        "ISP_ART_84_2_F",
        "ISP_ART_84_2_G",
        "REGIMEN_ART_129",
        "REGIMEN_ART_135",
        "REGIMEN_ART_141",
        "REGIMEN_ART_154",
        "REGIMEN_ART_163_DECIES",
        "OTRO"
      ],
      "description": "Tax exemption reason code per the Spanish VAT Law (Ley 37/1992, LIVA), with the\nVeriFactu code each one is reported as.\n\n- `EXENTA_ART_20`: exempt, art. 20 (domestic operations such as medical, educational,\n  cultural and financial services, or housing rentals). E1.\n- `EXENTA_ART_21`: exempt, art. 21 (exports of goods). E2.\n- `EXENTA_ART_22`: exempt, art. 22 (operations treated as exports). E3.\n- `EXENTA_ART_24`: exempt, art. 24 (free zones, warehouses and customs regimes). E4.\n- `EXENTA_ART_25`: exempt, art. 25 (intra-community supplies of goods). E5.\n- `EXENTA_ART_26`: exempt, art. 26 (intra-community acquisitions of goods). It exempts the\n  buyer's acquisition, not a supply the seller invoices, so an invoice line that carries it\n  is rejected with `EXEMPTION_NOT_FOR_ISSUED_INVOICE`; a supply to another Member State is\n  `EXENTA_ART_25`.\n- `NO_SUJETA_ART_7_9`: not subject under art. 7 (such as the transfer of a business as\n  a going concern, art. 7.1º). N1.\n- `NO_SUJETA_LOCALIZACION`: not subject by the place-of-supply rules (intra-community\n  or non-EU services, arts. 69 and 70). N2.\n- `ISP_ART_84_2_A` … `ISP_ART_84_2_F`: reverse charge (the invoice states «inversión del\n  sujeto pasivo»), art. 84.Uno.2.º letters a) (supplier not established in Spain), b) (unwrought\n  or semi-finished gold), c) (scrap, waste and recovery materials, plastic, paper, cardboard, glass and textile waste, and semi-finished non-ferrous metal products), d) (greenhouse gas emission\n  allowances), e) (certain real estate supplies: in insolvency proceedings, with the exemption\n  waived, or enforcing a security) and f) (construction or renovation works). S2.\n- `ISP_ART_84_2_G`: reverse charge of letter g) (silver, platinum, palladium, mobile phones,\n  consoles, laptops and tablets). The law requires these supplies to be invoiced in a special\n  series, so an invoice line that carries it is rejected with\n  `REVERSE_CHARGE_CASE_NOT_SUPPORTED`.\n- `EXENTA_ART_140`: investment gold exemption, art. 140 bis (usually with `regime_key`\n  `04`). E6.\n- `REGIMEN_ART_129` (agriculture,\n  livestock and fishing, arts. 124 to 134 bis), `REGIMEN_ART_135` (second-hand goods,\n  art and antiques), `REGIMEN_ART_141` (travel agencies), `REGIMEN_ART_154` (equivalence\n  surcharge) and `REGIMEN_ART_163_DECIES` (cash basis, arts. 163 decies to 163\n  sexiesdecies): operations of special regimes, which VeriFactu identifies by the regime\n  key rather than by an exemption code. An\n  invoice line that carries one is rejected with `EXEMPTION_REGIME_NOT_SUPPORTED_IN_VERIFACTU`;\n  declare the regime with `regime_key` instead.\n- `OTRO`: any other provision. Requires the text in `exemption_reason_text`. E6.\n"
    },
    "ExternalRef": {
      "type": "string",
      "maxLength": 255,
      "description": "Client-supplied identifier from an external system (order, cart, contract…).\nStored as-is, echoed back on read, and filterable via GET /v1/invoices?external_ref=.\nOptional. Enforced UNIQUE per issuer for live standard/simplified invoices:\ncreating a second invoice with the same reference returns 409\n(INVOICE_DUPLICATE_EXTERNAL_REFERENCE); deleting the existing one lets you recreate.\nCorrective invoices are exempt from that uniqueness: a corrective carries the same\norder reference as the invoice it corrects, so both can coexist.\nThis is a business key, NOT the Idempotency-Key (which guards request retries).\n"
    },
    "InvoiceLineType": {
      "type": "string",
      "description": "Fiscal line type. `NORMAL` contributes to the taxable base and VAT;\n`SUPLIDO` is a payment made on behalf of the client and is excluded from both.\n",
      "enum": [
        "NORMAL",
        "SUPLIDO"
      ]
    },
    "InvoiceMetadata": {
      "type": "object",
      "additionalProperties": true,
      "description": "Your own key/value pairs to cross-reference this invoice with records in\nyour system (order ids, tenants, internal codes). Namespace them to avoid\nclashing with the system keys BeeL adds on payment-generated invoices.\nMetadata is not printed on the PDF; for values people read, filter or export,\nsuch as a store or a cost centre, use `custom_fields`.\n"
    },
    "InvoiceProcessingOptions": {
      "type": "object",
      "description": "Controls how the invoice is processed after creation.\nAll fields default to `false` if not specified.\n\nVeriFactu is **not** an option here: whether an invoice is registered with AEAT is a\nfact of the tax identity (NIF x environment), resolved at issue time against the\ncompany's regime. See `verifactu.enabled` in the invoice response for what was applied.\n\n**Common combinations:**\n- Draft (default): omit `options` or set all to `false`\n- Issue immediately: `{ issue_directly: true }`\n- Issue + wait for PDF: `{ issue_directly: true, wait_for_pdf: true }`\n- Issue + send email: `{ issue_directly: true, send_automatically: true }`\n- Full automation: `{ issue_directly: true, wait_for_pdf: true, send_automatically: true, email_config: { ... } }`\n",
      "properties": {
        "issue_directly": {
          "type": "boolean",
          "default": false,
          "description": "If `true`, creates the invoice directly as **ISSUED** with a definitive number and PDF.\nIf `false` (default), creates as **DRAFT** without number (editable, no PDF).\n"
        },
        "wait_for_pdf": {
          "type": "boolean",
          "default": false,
          "description": "Only applies when `issue_directly` is `true`.\nIf `true`, waits for PDF generation before returning the response (~1-3s).\nIf `false` (default), PDF is generated asynchronously in the background.\n"
        },
        "send_automatically": {
          "type": "boolean",
          "default": false,
          "description": "Only applies when `issue_directly` is `true`.\nIf `true`, sends the invoice by email with PDF attachment after issuing.\nThe email is sent asynchronously after the invoice is issued.\n"
        },
        "attach_source_invoices": {
          "type": "boolean",
          "default": false,
          "description": "Only applies when `send_automatically` is `true`. If `true`, the email sent after\nissuing also attaches a ZIP (`suplidos_<invoice-number>.zip`) with the PDFs of the\nsource invoices referenced by the invoice's SUPLIDO consolidation lines\n(`source_invoice_ids`). Each PDF inside the ZIP is named\n`<invoice-number>_<issuer-tax-id>.pdf`. Access to sources owned by managed accounts is\nre-checked with the same rules as issuing, and the request fails synchronously with an\nactionable error — never a partial ZIP — if the invoice has no consolidation sources\n(`ATTACH_SOURCE_INVOICES_NO_SOURCES`), a source is not reachable\n(`ATTACH_SOURCE_INVOICE_UNAVAILABLE`) or a source has no generated PDF\n(`ATTACH_SOURCE_PDF_MISSING`). The flag belongs to this issuing act only: it is never\nstored on the invoice.\n"
        },
        "email_config": {
          "allOf": [
            {
              "$ref": "#/$defs/EmailConfiguration"
            }
          ],
          "description": "Only applies when `send_automatically` is `true`.\nOverrides the `defaults` of the company's email configuration: its `subject`, `message`\nand `cc` are sent with the email. If it names no recipients, the email goes to the\ncustomer's `billing_emails`, or to the customer's `email` when there are none.\n"
        }
      }
    },
    "IrpfPercentage": {
      "type": "number",
      "enum": [
        0,
        1,
        2,
        2.8,
        6,
        7,
        7.6,
        9.5,
        15,
        19,
        24
      ],
      "description": "Withholding (IRPF) percentage, as the IRPF regulation (Royal Decree 439/2007) sets it: 0 (no withholding), 1 (pig fattening and poultry, and some activities\nunder objective estimation), 2 (other agricultural, livestock and forestry activities),\n7 (professional activity in its first three years, and the other 7 % cases), 15\n(professional activities, and intellectual property income), 19 (rent of urban property\nand other income of art. 75.2.b; also the general rate of the Corporate Income Tax\nwithholding) and 24 (image rights). A company that pays Corporate Income Tax can only use\n0, 19, 24 and 9.5: see `WithholdingOptions`.\n\nCeuta and Melilla: income with the Ceuta and Melilla deduction bears the base rate reduced as\nthe law sets it. Under IRPF, 15 % and 7 % (professional activities) and 19 % (rent of urban\nproperty located there) are reduced by 60 %: 6, 2.8 and 7.6. Under Corporate Income Tax, 19 %\non those rents is halved: 9.5, which only a company can use\n(`IRPF_RATE_ONLY_FOR_CORPORATE_ISSUER` otherwise). Whether the reduction applies is the\nissuer's choice: the NIF does not show it.\n\nThe value counts, not how it is written: `15.0` is `15` and `2.80` is `2.8`.\n"
    },
    "PhoneInput": {
      "type": "string",
      "minLength": 9,
      "maxLength": 20,
      "pattern": "^[+]?[0-9\\s\\-\\(\\)]+$",
      "description": "A phone number as this API accepts it: 9 to 20 characters, and only digits, spaces,\ndashes, parentheses and an optional leadi

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://artifacts.apis.io/beel-es/json-schema/beel-es-create-corrective-invoice-request-schema.json