beel_create_corrective_invoice

Added value: +{
+  "additionalProperties": false,
+  "description": "Address you send when you create or update a company, a customer or an onboarding.\n\nAddresses you read back are described by their own schema.\n",
+  "properties": {
+    "city": {
+      "description": "City or town - Latin characters only",
+      "maxLength": 100,
+      "minLength": 1,
+      "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
+      "type": "string"
+    },
+    "country": {
+      "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",
+      "maxLength": 100,
+      "minLength": 1,
+      "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
+      "type": "string"
+    },
+    "country_code": {
+      "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",
+      "maxLength": 2,
+      "minLength": 2,
+      "pattern": "^[A-Z]{2}$",
+      "type": "string"
+    },
+    "door": {
+      "description": "Door or apartment",
+      "maxLength": 10,
+      "type": "string"
+    },
+    "floor": {
+      "description": "Floor or level",
+      "maxLength": 10,
+      "type": "string"
+    },
+    "number": {
+      "description": "Street number. Optional: omit it when the address has none, or when `street` already\ncarries the address in full.\n",
+      "maxLength": 20,
+      "minLength": 1,
+      "type": "string"
+    },
+    "postal_code": {
+      "description": "Postal code (5 digits for Spain, free format for other countries)",
+      "maxLength": 20,
+      "minLength": 1,
+      "type": "string"
+    },
+    "province": {
+      "description": "Province or state - Latin characters only",
+      "maxLength": 100,
+      "minLength": 1,
+      "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
+      "type": "string"
+    },
+    "street": {
+      "description": "Full address (street, number, floor, etc.) - Latin characters only",
+      "maxLength": 255,
+      "minLength": 1,
+      "pattern": "^[a-zA-Z0-9À-ÿ\\u0100-\\u017F\\u00B7\\u2018\\u2019\\u0060\\u00B4\\s\\.,\\-\\/'ºª°:;\"()&#]+$",
+      "type": "string"
+    }
+  },
+  "required": [
+    "street",
+    "postal_code",
+    "city",
+    "province"
+  ],
+  "type": "object"
+}

Added value: +{
+  "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- 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": {
+    "country_code": {
+      "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",
+      "maxLength": 2,
+      "minLength": 2,
+      "pattern": "^[A-Z]{2}$",
+      "type": "string"
+    },
+    "number": {
+      "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",
+      "maxLength": 20,
+      "minLength": 1,
+      "type": "string"
+    },
+    "type": {
+      "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",
+      "enum": [
+        "NIF_IVA",
+        "PASSPORT",
+        "COUNTRY_ID",
+        "RESIDENCE_CERTIFICATE",
+        "OTHER_DOCUMENT",
+        "NOT_REGISTERED",
+        "02",
+        "03",
+        "04",
+        "05",
+        "06",
+        "07"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "type",
+    "number"
+  ],
+  "type": [
+    "object",
+    "null"
+  ]
+}

Added value: +{
+  "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",
+  "format": "date",
+  "type": "string"
+}

Previous value: -"**TOTAL**: Optional (if not sent, original invoice lines are copied negated)\n**PARTIAL**: REQUIRED (adjustment lines with positive or negative amounts)\n"New value: +"**TOTAL**: not accepted. A `TOTAL` corrective rectifies what is still invoiced on the\noriginal —its lines and those of its live correctives, negated— and a request with\n`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`).\n"

Removed value: -"#/$defs/EquivalenceSurchargePercentage"

Added value: +[
+  {
+    "$ref": "#/$defs/EquivalenceSurchargePercentage"
+  }
+]

Added value: +"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. `SUPLIDO` lines\nnever carry a surcharge and are ignored on both sides.\n"

Previous value: -"IRPF withholding rate for this line.\n\n**Default behaviour:** if omitted, the line inherits the\naccount's default IRPF rate (configured in the tax profile,\ne.g. 15%). To issue a line **without** withholding you must\nsend `irpf_rate: 0` explicitly. On SIMPLIFIED invoices (F2)\nIRPF withholding is **not allowed** (AEAT forbids it on F2):\nsending an `irpf_rate` other than 0 is **rejected** with\n`SIMPLIFICADA_FORBIDS_IRPF` — it is not coerced to 0. Omit the\nfield or send `irpf_rate: 0` on F2 lines. On all other invoice\ntypes an explicit value is always respected.\n"New value: +"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. `SUPLIDO` lines never carry IRPF and are ignored on both\nsides. 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"

Added value: +{
+  "allOf": [
+    {
+      "$ref": "#/$defs/Recipient"
+    }
+  ],
+  "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"
+}

Added value: +{
+  "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",
+  "type": "boolean"
+}

Previous value: -"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 the request fails with\n`422 SERIES_DEFAULT_NOT_FOUND`; a series of the wrong type fails with\n`422 SERIES_INCOMPATIBLE_DOC_TYPE`.\n"New value: +"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"

Previous value: -"Equivalence surcharge percentage in decimal format.\nPairs allowed (rate ↔ recargo): 4↔0.5, 5↔0.625 (RD-ley 11/2022), 10↔1.4, 21↔5.2.\nThe backend automatically normalizes equivalent formats (5.20 → 5.2).\n"New value: +"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"

Previous value: -[
-  0,
-  0.5,
-  0.625,
-  1.4,
-  5.2
-]New value: +[
+  0,
+  0.26,
+  0.5,
+  0.62,
+  1,
+  1.4,
+  1.75,
+  5.2
+]

Previous value: -"Tax exemption reason code per Spanish VAT Law (Ley 37/1992 LIVA).\nVeriFactu mapping: EXENTA_ART_20→E1, EXENTA_ART_21→E2, EXENTA_ART_22→E3,\nEXENTA_ART_24→E4, EXENTA_ART_25→E5, rest→E6. ISP→S2, NO_SUJETA→N1/N2.\nWhen OTRO, a custom text must be provided in exemption_reason_text.\n"New value: +"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"

Previous value: -[
-  "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_E",
-  "ISP_ART_84_2_F",
-  "REGIMEN_ART_129",
-  "REGIMEN_ART_135",
-  "REGIMEN_ART_141",
-  "REGIMEN_ART_154",
-  "REGIMEN_ART_163_DECIES",
-  "OTRO"
-]New value: +[
+  "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"
+]

Previous value: -"Controls how the invoice is processed after creation.\nAll fields default to `false` if not specified, **except `verifactu_enabled`**,\nwhich falls back to the company's declared preference (see its description).\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"New value: +"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"

Previous value: -"Only applies when `send_automatically` is `true`.\nOverrides default email settings. If not provided, uses the recipient's email.\n"New value: +"Only applies when `send_automatically` is `true`.\nOverrides default email settings. 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"

Removed value: -{
-  "description": "Whether VeriFactu information should be generated for this invoice.\n\n**If omitted, the company's declared preference applies** (the\n\"apply VeriFactu by default\" setting, `apply_by_default`). If the company\nhas no VeriFactu configuration, it resolves to `false`.\nSend the field explicitly (`true` or `false`) to override the preference.\n\nA `PROFORMA` always forces `false`, whatever the preference or the value sent.\n",
-  "type": "boolean"
-}

Previous value: -"Personal income tax/withholding percentage in integer format.\nAllowed values: 0 (exempt), 1 (agricultural/livestock/forestry), 2 (reduced for modules), 7, 15, 19, 24 (non-residents).\n"New value: +"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"

Previous value: -[
-  0,
-  1,
-  2,
-  7,
-  15,
-  19,
-  24
-]New value: +[
+  0,
+  1,
+  2,
+  2.8,
+  6,
+  7,
+  7.6,
+  9.5,
+  15,
+  19,
+  24
+]

Previous value: -"integer"New value: +"number"

Added value: +{
+  "description": "A phone number as this API accepts it: 9 to 20 characters, and only digits, spaces,\ndashes, parentheses and an optional leading `+`. Every request that takes a phone number\nuses this schema.\n\nIt is `Phone` plus the rules enforced on input. A value this schema accepts always\nsatisfies `Phone`, so anything you send here is something a response can return.\n",
+  "maxLength": 20,
+  "minLength": 9,
+  "pattern": "^[+]?[0-9\\s\\-\\(\\)]+$",
+  "type": "string"
+}

Added value: +{
+  "additionalProperties": false,
+  "description": "Invoice recipient: either a registered customer (`customer_id`) or the recipient's\ndata inline (`legal_name`, `nif`, `address`…), never both. Sending `customer_id`\ntogether with any other recipient field returns 422\n`RECIPIENT_CUSTOMER_AND_DATA_EXCLUSIVE`, on create and on edit.\n\nAll fields are optional at schema level, but for an ad-hoc recipient (no\ncustomer_id) on non-SIMPLIFIED invoices the API requires legal_name, address and\nnif (or alternative_id); omitting the address returns 422\nRECIPIENT_ADDRESS_REQUIRED.\n",
+  "properties": {
+    "address": {
+      "$ref": "#/$defs/Address"
+    },
+    "alternative_id": {
+      "allOf": [
+        {
+          "$ref": "#/$defs/AlternativeIdentifier"
+        },
+        {
+          "description": "Alternative identifier for foreign customers (mutually exclusive with nif).\nNot accepted on SIMPLIFIED invoices, like `nif`: BeeL. requires a STANDARD\ninvoice when the recipient is identified.\n"
+        }
+      ]
+    },
+    "customer_id": {
+      "description": "UUID of a registered customer. The invoice takes the recipient data stored on\nthat customer. Send it alone: combined with any other recipient field it returns\n422 `RECIPIENT_CUSTOMER_AND_DATA_EXCLUSIVE`. To change the recipient's data, edit\nthe customer or send the data inline without `customer_id`.\n",
+      "format": "uuid",
+      "type": "string"
+    },
+    "email": {
+      "$ref": "#/$defs/Email"
+    },
+    "legal_name": {
+      "description": "Recipient legal name. Required when customer_id is not provided\n(except for SIMPLIFIED invoices where all fields are optional).\n",
+      "maxLength": 255,
+      "minLength": 1,
+      "type": "string"
+    },
+    "nif": {
+      "description": "Spanish Tax ID (9 alphanumeric characters).\nRequired when customer_id is not provided and alternative_id is absent.\nNot accepted on SIMPLIFIED invoices: BeeL. requires a STANDARD invoice when the\nrecipient is identified.\n",
+      "maxLength": 9,
+      "minLength": 9,
+      "pattern": "^[A-Za-z0-9]{9}$",
+      "type": "string"
+    },
+    "phone": {
+      "$ref": "#/$defs/PhoneInput"
+    },
+    "trade_name": {
+      "description": "Recipient trade name (optional)",
+      "maxLength": 255,
+      "minLength": 1,
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "type": "object"
+}

Previous value: -"Type of rectification applied to a corrective invoice:\n- TOTAL: Completely cancels the original invoice (status → VOIDED)\n- PARTIAL: Partially corrects the original invoice (status → RECTIFIED)\n"New value: +"Type of rectification applied to a corrective invoice:\n- TOTAL: Rectifies everything still invoiced on the original, its live correctives included (status → VOIDED)\n- PARTIAL: Partially corrects the original invoice (status → RECTIFIED)\n"

Previous value: -"Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies:\n- 01: General regime operation\n- 02: Export\n- 03: Used goods, art, antiques\n- 04: Investment gold\n- 05: Travel agencies\n- 06: Group of entities\n- 07: Cash basis\n- 08: IPSI/IVA/IGIC operations\n- 09: Mediating agencies\n- 10: Third-party collections\n- 11: Local rental\n- 14: VAT pending in certifications\n- 15: VAT pending successive tract\n- 17: OSS and IOSS\n- 18: Equivalence surcharge\n- 19: REAGYP\n- 20: Simplified regime\n\n**One exception to \"a key you send is the key you get\":** when the line ends up\ncarrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate`\nor it was inherited from the company's tax configuration — a `01` is rewritten to\n`18`, because a surcharge under the general regime is fiscally incoherent. Send\n`equivalence_surcharge_rate: 0` explicitly to keep `01`. See\n`equivalence_surcharge_rate` in the invoice line for the full rules.\n"New value: +"Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies:\n- 01: General regime operation\n- 02: Export (IVA and IGIC; not IPSI, whose AEAT list is `01, 08, 11, 18, 19, 20`)\n- 03: Used goods, art, antiques (not accepted, see below)\n- 04: Investment gold\n- 05: Travel agencies\n- 06: Group of entities (not accepted, see below)\n- 07: Cash basis\n- 08: Operation subject to another indirect tax — IPSI or IGIC on an IVA line, IPSI or IVA\n  on an IGIC line. It is **not** the general regime of IGIC, which is `01`.\n- 09: Mediating agencies\n- 10: Third-party collections\n- 11: Local rental\n- 14: VAT pending in certifications (not accepted, see below)\n- 15: VAT pending successive tract\n- 17: OSS and IOSS\n- 18: Equivalence surcharge\n- 19: REAGYP\n- 20: Simplified regime\n\n**What AEAT requires with each key** (Validaciones VERI*FACTU 3.1.3.15.6), checked on\nIVA and IGIC lines before the invoice is numbered. Otherwise the request is rejected with\n`422` and the code in brackets:\n- `04`: only reverse charge (an `ISP_ART_84_2_*` reason) or an exemption\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `08`: only `exemption_reason: NO_SUJETA_LOCALIZACION`, at 0 %\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `10`: only `exemption_reason: NO_SUJETA_ART_7_9`, on a `STANDARD` invoice whose\n  recipient has a `nif` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`,\n  `REGIME_KEY_REQUIRES_STANDARD_INVOICE`, `REGIME_KEY_REQUIRES_RECIPIENT_NIF`).\n- `11` (IVA): a subject line only at 21 %, and no reverse charge\n  (`REGIME_KEY_REQUIRES_VAT_RATE`, `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `06` and `14` are not accepted (`REGIME_KEY_NOT_SUPPORTED`): AEAT requires with them\n  data the invoice does not carry (a cost-based taxable base; an operation date after the\n  issue date and a public-administration recipient).\n- `03` (used goods) is not accepted (`REGIME_KEY_NOT_SUPPORTED`): under it the invoice\n  must not show the tax separately (RD 1619/2012, art. 16.2.c), and it always does. The\n  corrective of an invoice that already carried `03` keeps it.\n- `05` (travel agencies) and `07` (cash basis) are accepted, and the invoice PDF carries\n  the mention of their regime (RD 1619/2012, art. 6.1 n and p). `07`: no reverse charge,\n  no non-subject reason and, of the exemptions, only art. 20 or `OTRO`\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n`GET /v1/tax-types` only offers the keys that are accepted.\n\n**One exception to \"a key you send is the key you get\":** when the line ends up\ncarrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate`\nor it was inherited from the company's tax configuration — a `01` is rewritten to\n`18`, because a surcharge under the general regime is fiscally incoherent. Send\n`equivalence_surcharge_rate: 0` explicitly to keep `01`. See\n`equivalence_surcharge_rate` in the invoice line for the full rules.\n"

Previous value: -"Complete tax information with cross-validations:\n- IVA: real rates 4, 5, 10, 21 (see below for 0)\n- IGIC: 0, 3, 5, 7, 9.5, 15, 20 — here 0 is the real \"Tipo Cero\"\n- IPSI: real rates 0.5, 1, 2, 4, 8, 10 (see below for 0)\n- OTHER: any percentage between 0 and 100\n\n**0 % under IVA and IPSI is not a rate, it is the exemption sentinel.** It is accepted\non a line, but only together with an `exemption_reason` (exempt or non-subject\noperation); on its own it says nothing and the line is rejected. That is why\n`GET /v1/tax-types` publishes 4, 5, 10 and 21 for IVA and not 0: the legitimate way\nto a 0 % IVA line is through an exemption reason, which the same response also\npublishes. IGIC is different — its 0 % is a real legal rate (basic necessities) and\nneeds no reason.\n\n**IVA 5 %** (RD-ley 11/2022 and its extensions, on electricity, gas and basic\nfoodstuffs) is no longer in force for new operations, but it stays valid: corrective\ninvoices and late-filed invoices for the periods when it applied must be able to carry\nit. Its equivalence surcharge pair is 0.625.\n\nException: when regime_key = \"17\" (OSS/IOSS) the invoice applies the destination\ncountry VAT instead of the Spanish one, so any percentage in the EU range [0, 27]\nis accepted regardless of the tax type set — including 0 without an exemption reason.\n"New value: +"Complete tax information with cross-validations:\n- IVA: real rates 4, 10, 21, and the temporary 2, 5 and 7.5 (see below for 0)\n- IGIC: 0, 3, 5, 7, 9.5, 15, 20 — here 0 is the real \"Tipo Cero\"\n- IPSI: real rates 0.5, 1, 2, 4, 8, 10 (see below for 0)\n- OTHER: any percentage between 0 and 100\n\n**0 % under IVA and IPSI is not a rate, it is the exemption sentinel.** It is accepted\non a line, but only together with an `exemption_reason` (exempt or non-subject\noperation); on its own it says nothing and the line is rejected. That is why\n`GET /v1/tax-types` publishes the IVA rates without 0: the legitimate way\nto a 0 % IVA line is through an exemption reason, which the same response also\npublishes. IGIC is different — its 0 % is a real legal rate (basic necessities) and\nneeds no reason.\n\n**IVA 5 %** (the temporary rate applied from 2022 to electricity, gas and certain\nfoodstuffs) is no longer in force for new operations. AEAT only accepts it on operations\ndated from 2022-07-01 to 2024-09-30: send the `operation_date` of that period, because\nwithout one the issue date decides and a line at 5 % is rejected with\n`422 VAT_RATE_NOT_ACCEPTED_ON_DATE`. Its equivalence surcharge pair is 0.5 up to 2022-12-31\nand 0.62 from 2023-01-01. **IVA 2 % and 7.5 %** (temporary rates of the last quarter of 2024)\nare accepted only on operations dated from 2024-10-01 to 2024-12-31, with surcharges 0.26\nand 1.\n\nException: when regime_key = \"17\" (OSS/IOSS) the invoice applies the destination\ncountry VAT instead of the Spanish one, so any percentage in the EU range [0, 27]\nis accepted regardless of the tax type set — including 0 without an exemption reason.\n"

Previous value: -"Tax type by territory:\n- IVA: Iberian Peninsula and Balearic Islands (4%, 5%, 10%, 21%)\n- IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%)\n- IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%)\n- OTHER: Configurable 0%-100%\n\nUnder IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject\nsentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate.\nSee `TaxInfo` for the full rules.\n"New value: +"Tax type by territory:\n- IVA: Iberian Peninsula and Balearic Islands (4%, 10%, 21%; 2%, 5% and 7.5% only on operations of their period)\n- IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%)\n- IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%)\n- OTHER: Configurable 0%-100%\n\nUnder IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject\nsentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate.\nSee `TaxInfo` for the full rules.\n"

Previous value: -"Rectification codes according to VeriFactu regulations (AEAT):\n- R1: Error founded in law and Art. 80 One, Two and Six LIVA\n- R2: Article 80 Three LIVA (Bankruptcy proceedings)\n- R3: Article 80 Four LIVA (Uncollectable debts)\n- R4: Other causes\n- R5: Simplified invoices (Art. 80 One and Two LIVA) - ONLY for simplified invoices\n"New value: +"Rectification codes according to VeriFactu regulations (AEAT):\n- R1: Error founded in law and Art. 80 One, Two and Six LIVA\n- R2: Article 80 Three LIVA (Bankruptcy proceedings)\n- R3: Article 80 Four LIVA (Uncollectable debts)\n- R4: Other causes\n- R5: Corrective of a simplified invoice - ONLY for simplified invoices\n"

Added value: +false

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

Added value: +false

Removed value: -"Adjustment for incorrectly invoiced hours"

Removed value: -"#/$defs/ExemptionReason"

Added value: +[
+  {
+    "$ref": "#/$defs/ExemptionReason"
+  },
+  {
+    "type": "null"
+  }
+]

Removed value: --10

Removed value: -1

Removed value: -100

Removed value: -"hours"

Removed value: -50

Removed value: -"Rectification requested by the customer due to quantity error"

Removed value: -"Amount correction due to calculation error in hours worked during the project"

Removed value: -"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Removed value: -"user@example.com"

Added value: +false

Removed value: -{
-  "cc": [
-    "accounting@example.com"
-  ],
-  "message": "Please find attached the requested invoice. We remain at your disposal for any clarification.",
-  "recipients": [
-    "client@example.com"
-  ],
-  "subject": "Invoice 2025/0001 - Development services"
-}

Removed value: -[
-  "copy@example.com"
-]

Removed value: -"Dear customer, please find attached the invoice for the services provided. Thank you for your trust."

Removed value: -[
-  "client@example.com"
-]

Removed value: -"Invoice 2025/0001 - Web development services"

Removed value: -5.2

Removed value: -"EXENTA_ART_20"

Removed value: -"ORD-2025-0042"

Removed value: -{
-  "external_order_id": "ORD-2025-0042",
-  "project_code": "PROJ-123",
-  "tenant": "acme"
-}

Added value: +false

Removed value: -{
-  "issue_directly": true,
-  "send_automatically": false,
-  "verifactu_enabled": false,
-  "wait_for_pdf": false
-}

Removed value: -15

Removed value: -"01"

Added value: +false

Removed value: -{
-  "percentage": 21,
-  "regime_key": "01",
-  "type": "IVA"
-}

Removed value: -21

Removed value: -"IVA"

Removed value: -"550e8400-e29b-41d4-a716-446655440000"

Added value: +false

Previous value: -"NIF (company) the operation acts on. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A NIF you do not reach answers `403`, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed."New value: +"Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed."