@fin.cx/einvoice 10.0.0 → 10.1.0

package/ts/formats/utils/vat.category.ts

@@ -1,47 +1,152 @@
 import type { TAccountingDoc } from '../../interfaces/common.js';
+import type { finance } from '@tsclass/tsclass';
+
+type TAccountingDocItem = finance.TAccountingDocItem;
 import { EInvoiceFormatError } from '../../errors.js';
+import type { IEInvoiceStatedValues } from '../../interfaces/stated.values.js';
+
+/**
+ * The VAT category codes (UNTDID 5305, EN 16931 BT-118/BT-151) an item can
+ * state (`TAccountingDocItem.vatCategory`): standard rated (S), zero rated (Z),
+ * exempt (E), reverse charge (AE), intra-community supply (K), export outside
+ * the EU (G), not subject to VAT (O), IGIC (L) and IPSI (M).
+ */
+export type TVatCategoryCode = finance.TVatCategory;
+
+/** Every VAT category code EN 16931 allows, in the order of `TVatCategoryCode` */
+export const VAT_CATEGORY_CODES: readonly TVatCategoryCode[] = ['S', 'Z', 'E', 'AE', 'K', 'G', 'O', 'L', 'M'];
 
 /**
- * The VAT category codes (UNTDID 5305, EN 16931 BT-118/BT-151) the encoders
- * write: standard rated, or reverse charge. The envelope states reverse charge
- * for the whole document (`reverseCharge`); an item carries no category of its
- * own, so a document cannot mix reverse charge lines with standard rated ones.
+ * Whether a value is a VAT category code EN 16931 allows
+ * @param value The value
  */
-export type TVatCategoryCode = 'S' | 'AE';
+export const isVatCategoryCode = (value: unknown): value is TVatCategoryCode =>
+  typeof value === 'string' && (VAT_CATEGORY_CODES as readonly string[]).includes(value);
 
-/** The VAT exemption reason (BT-121 code, BT-120 text) a VAT category states */
+/**
+ * The categories whose VAT breakdown states an exemption reason, as a code
+ * (BT-121) or a text (BT-120): exempt (BR-E-10), reverse charge (BR-AE-10),
+ * intra-community supply (BR-IC-10), export (BR-G-10) and not subject to VAT
+ * (BR-O-10). The others state none (BR-S-10, BR-Z-10, BR-AF-10, BR-AG-10).
+ */
+export const VAT_CATEGORIES_WITH_EXEMPTION: readonly TVatCategoryCode[] = ['E', 'AE', 'K', 'G', 'O'];
+
+/**
+ * The VAT exemption reason code (BT-121) and text (BT-120) a VAT breakdown
+ * states; at least one of them
+ */
 export interface IVatExemption {
-  code: string;
-  reason: string;
+  code?: string;
+  reason?: string;
 }
 
 /**
- * The VAT category of every line of a document: reverse charge (`AE`) when the
- * document states it, standard rated (`S`) otherwise.
+ * The CEF VATEX code list, as the CEN/TC 434 EN 16931 validation artefacts
+ * 1.3.16 check a VAT exemption reason code (BT-121) against it (BR-CL-22,
+ * compared in upper case)
+ */
+export const VATEX_CODES: ReadonlySet<string> = new Set(
+  (
+    'VATEX-EU-79-C VATEX-EU-132 VATEX-EU-132-1A VATEX-EU-132-1B VATEX-EU-132-1C VATEX-EU-132-1D VATEX-EU-132-1E ' +
+    'VATEX-EU-132-1F VATEX-EU-132-1G VATEX-EU-132-1H VATEX-EU-132-1I VATEX-EU-132-1J VATEX-EU-132-1K VATEX-EU-132-1L ' +
+    'VATEX-EU-132-1M VATEX-EU-132-1N VATEX-EU-132-1O VATEX-EU-132-1P VATEX-EU-132-1Q VATEX-EU-135-1 VATEX-EU-143 ' +
+    'VATEX-EU-143-1A VATEX-EU-143-1B VATEX-EU-143-1C VATEX-EU-143-1D VATEX-EU-143-1E VATEX-EU-143-1F VATEX-EU-143-1FA ' +
+    'VATEX-EU-143-1G VATEX-EU-143-1H VATEX-EU-143-1I VATEX-EU-143-1J VATEX-EU-143-1K VATEX-EU-143-1L VATEX-EU-144 ' +
+    'VATEX-EU-146-1E VATEX-EU-159 VATEX-EU-309 VATEX-EU-148 VATEX-EU-148-A VATEX-EU-148-B VATEX-EU-148-C VATEX-EU-148-D ' +
+    'VATEX-EU-148-E VATEX-EU-148-F VATEX-EU-148-G VATEX-EU-151 VATEX-EU-151-1A VATEX-EU-151-1AA VATEX-EU-151-1B ' +
+    'VATEX-EU-151-1C VATEX-EU-151-1D VATEX-EU-151-1E VATEX-EU-G VATEX-EU-O VATEX-EU-IC VATEX-EU-AE VATEX-EU-D VATEX-EU-F ' +
+    'VATEX-EU-I VATEX-EU-J VATEX-FR-FRANCHISE VATEX-FR-CNWVAT VATEX-EU-153 VATEX-FR-CGI261-1 VATEX-FR-CGI261-2 ' +
+    'VATEX-FR-CGI261-3 VATEX-FR-CGI261-4 VATEX-FR-CGI261-5 VATEX-FR-CGI261-7 VATEX-FR-CGI261-8 VATEX-FR-CGI261A ' +
+    'VATEX-FR-CGI261B VATEX-FR-CGI261C-1 VATEX-FR-CGI261C-2 VATEX-FR-CGI261C-3 VATEX-FR-CGI261D-1 VATEX-FR-CGI261D-1BIS ' +
+    'VATEX-FR-CGI261D-2 VATEX-FR-CGI261D-3 VATEX-FR-CGI261D-4 VATEX-FR-CGI261E-1 VATEX-FR-CGI261E-2 VATEX-FR-CGI277A ' +
+    'VATEX-FR-CGI275 VATEX-FR-298SEXDECIESA VATEX-FR-CGI295 VATEX-FR-AE'
+  ).split(' '),
+);
+
+/**
+ * Whether a VAT exemption reason code is on the CEF VATEX code list (BR-CL-22)
+ * @param code The code
+ */
+export const isVatexCode = (code: string): boolean => VATEX_CODES.has(code.trim().toUpperCase());
+
+/**
+ * The VAT category of an item: the one it states (`vatCategory`, BT-151), else
+ * reverse charge (AE) when the document states `reverseCharge`, standard rated
+ * (S) otherwise.
  * @param accountingDoc The document
+ * @param item The item
  */
-export const getVatCategory = (accountingDoc: { reverseCharge?: boolean }): TVatCategoryCode =>
-  accountingDoc.reverseCharge ? 'AE' : 'S';
+export const getItemVatCategory = (
+  accountingDoc: { reverseCharge?: boolean },
+  item: Pick<TAccountingDocItem, 'vatCategory'>,
+): TVatCategoryCode => item.vatCategory ?? (accountingDoc.reverseCharge ? 'AE' : 'S');
 
 /**
- * The exemption reason a reverse charge VAT breakdown states (BR-AE-10): the
- * code `VATEX-EU-AE` and the wording the law prescribes, "Steuerschuldnerschaft
- * des Leistungsempfängers" (§ 14a Abs. 1 and 5 UStG). A document in another
- * language may use the wording of Article 226 Nr. 11a of the VAT Directive in
- * that language, "Reverse charge" in English (Abschnitt 14a.1 Abs. 6 Satz 2
- * UStAE). Other categories state none.
+ * The exemption reason an item states: its VATEX code (BT-121) and its text
+ * (BT-120), each trimmed; undefined when it states neither
+ * @param item The item
+ */
+export const getItemVatExemption = (
+  item: Pick<TAccountingDocItem, 'vatExemptionReason' | 'vatExemptionReasonCode'>,
+): IVatExemption | undefined => {
+  const code = item.vatExemptionReasonCode?.trim();
+  const reason = item.vatExemptionReason?.trim();
+  if (!code && !reason) {
+    return undefined;
+  }
+  return { ...(code ? { code } : {}), ...(reason ? { reason } : {}) };
+};
+
+/**
+ * The exemption reason a VAT breakdown of a category states when none of its
+ * items states one.
+ * - Reverse charge (AE): the code `VATEX-EU-AE` and the wording the law
+ *   prescribes, "Steuerschuldnerschaft des Leistungsempfängers" (§ 14a Abs. 1
+ *   and 5 UStG). A document in another language may use the wording of
+ *   Article 226 Nr. 11a of the VAT Directive in that language, "Reverse charge"
+ *   in English (Abschnitt 14a.1 Abs. 6 Satz 2 UStAE).
+ * - Intra-community supply (K), export outside the EU (G) and not subject to
+ *   VAT (O): the VATEX code that means the category, `VATEX-EU-IC`,
+ *   `VATEX-EU-G` and `VATEX-EU-O`, which BR-IC-10, BR-G-10 and BR-O-10 accept.
+ * - Exempt (E): none. The reason depends on the exemption applied, which only
+ *   the issuer knows; a document with an exempt item that states none is
+ *   refused (BR-E-10).
  * @param category The VAT category
  * @param language The document language
  */
-export const getVatExemption = (category: TVatCategoryCode, language: string | undefined): IVatExemption | undefined =>
-  category === 'AE'
-    ? {
+export const getDefaultVatExemption = (category: TVatCategoryCode, language: string | undefined): IVatExemption | undefined => {
+  switch (category) {
+    case 'AE':
+      return {
         code: 'VATEX-EU-AE',
-        reason: (language ?? '').toLowerCase().startsWith('de')
-          ? 'Steuerschuldnerschaft des Leistungsempfängers'
-          : 'Reverse charge',
-      }
-    : undefined;
+        reason: (language ?? '').toLowerCase().startsWith('de') ? 'Steuerschuldnerschaft des Leistungsempfängers' : 'Reverse charge',
+      };
+    case 'K':
+      return { code: 'VATEX-EU-IC' };
+    case 'G':
+      return { code: 'VATEX-EU-G' };
+    case 'O':
+      return { code: 'VATEX-EU-O' };
+    default:
+      return undefined;
+  }
+};
+
+/**
+ * The exemption reason a VAT breakdown states: the code and the text its items
+ * state, each completed by the category's default where they state none
+ * (`getDefaultVatExemption`); undefined when there is neither
+ * @param stated The exemption the items state
+ * @param categoryDefault The category's default
+ */
+export const mergeVatExemption = (stated: IVatExemption | undefined, categoryDefault: IVatExemption | undefined): IVatExemption | undefined => {
+  const code = stated?.code ?? categoryDefault?.code;
+  const reason = stated?.reason ?? categoryDefault?.reason;
+  if (!code && !reason) {
+    return undefined;
+  }
+  return { ...(code ? { code } : {}), ...(reason ? { reason } : {}) };
+};
 
 /**
  * Whether a VAT rate is a number not greater than zero; a rate that is no
@@ -50,87 +155,313 @@ export const getVatExemption = (category: TVatCategoryCode, language: string | u
  */
 export const isRateNotAboveZero = (rate: unknown): boolean => typeof rate === 'number' && Number.isFinite(rate) && !(rate > 0);
 
-/** A line written as standard rated (S) whose VAT rate is not greater than zero */
-export interface IStandardRatedLineWithoutRate {
-  index: number;
-  vatPercentage: number;
+/**
+ * The refusal or finding for a standard rated line whose VAT rate is not
+ * greater than zero (BR-S-05)
+ * @param line The line index and its rate
+ * @param statedCategory Whether the item states the category S itself
+ */
+export const standardRatedLineWithoutRateMessage = (
+  line: { index: number; vatPercentage: number },
+  statedCategory = false,
+): string =>
+  `In an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is "Standard rated" the Invoiced item VAT rate (BT-152) shall be greater than zero; items[${line.index}].vatPercentage is ${String(line.vatPercentage)}. ` +
+  (statedCategory
+    ? `items[${line.index}].vatCategory states S`
+    : `An item outside reverse charge that states no category (items[${line.index}].vatCategory) is standard rated (S); an item that is zero rated, exempt, an intra-community supply, an export or not subject to VAT states its category, Z, E, K, G or O`);
+
+/** One rule a VAT category finding names */
+export interface IVatCategoryViolation {
+  /** the EN 16931 rule ID, or the package's own code for a check no official rule states */
+  ruleId: string;
+  /** what is wrong, with the field */
+  message: string;
+  /** the envelope field concerned */
+  field: string;
 }
 
+/** The package's own check: the items of one VAT breakdown state different exemption reasons */
+export const VAT_EXEMPTION_DIFFERS = 'EINVOICE-VAT-EXEMPTION-DIFFERS';
+
 /**
- * The first line of a document that is not reverse charge whose VAT rate is not
- * greater than zero. The encoders write every such line as standard rated (S),
- * and EN 16931 BR-S-05 asks a standard rated line for a rate greater than zero;
- * the category the line has (zero rated Z, exempt E, intra-community supply K,
- * export G, not subject to VAT O) cannot be stated until an item carries a VAT
- * category of its own.
- * @param items The document's items
+ * The item VAT rate each category allows: greater than zero for S (BR-S-05);
+ * 0 for Z, E, AE, K and G (BR-Z-05, BR-E-05, BR-AE-05, BR-IC-05, BR-G-05);
+ * 0 or greater for L and M (BR-AF-05, BR-AG-05). An item not subject to VAT
+ * (O) is written without a rate (BR-O-05), so it states 0.
  */
-export const findStandardRatedLineWithoutRate = (
-  items: TAccountingDoc['items'] | undefined,
-): IStandardRatedLineWithoutRate | undefined => {
-  const index = (items ?? []).findIndex((item) => isRateNotAboveZero(item.vatPercentage));
-  return index < 0 ? undefined : { index, vatPercentage: items![index].vatPercentage };
+const RATE_RULES: Record<TVatCategoryCode, { ruleId: string; allows: (rate: number) => boolean; expected: string }> = {
+  S: { ruleId: 'BR-S-05', allows: (rate) => rate > 0, expected: 'greater than zero' },
+  Z: { ruleId: 'BR-Z-05', allows: (rate) => rate === 0, expected: '0' },
+  E: { ruleId: 'BR-E-05', allows: (rate) => rate === 0, expected: '0' },
+  AE: { ruleId: 'BR-AE-05', allows: (rate) => rate === 0, expected: '0' },
+  K: { ruleId: 'BR-IC-05', allows: (rate) => rate === 0, expected: '0' },
+  G: { ruleId: 'BR-G-05', allows: (rate) => rate === 0, expected: '0' },
+  O: { ruleId: 'BR-O-05', allows: (rate) => rate === 0, expected: '0, as an item not subject to VAT is written without a VAT rate' },
+  L: { ruleId: 'BR-AF-05', allows: (rate) => rate >= 0, expected: '0 or greater' },
+  M: { ruleId: 'BR-AG-05', allows: (rate) => rate >= 0, expected: '0 or greater' },
+};
+
+/**
+ * BR-AF-05 as the CII binding of the CEN/TC 434 artefacts 1.3.16 checks it:
+ * `ram:RateApplicablePercent > 0`, where the rule text and the UBL binding
+ * allow 0. A CII document with IGIC at 0 fails the official check, so it is
+ * not written.
+ */
+const CII_IGIC_RATE_RULE = {
+  ruleId: 'BR-AF-05',
+  allows: (rate: number) => rate > 0,
+  expected: 'greater than zero in CII, whose binding of the CEN artefacts checks BR-AF-05 so; UBL allows 0',
+};
+
+/** The rule a VAT breakdown of each category breaks by stating, or by lacking, an exemption reason */
+const EXEMPTION_RULES: Record<TVatCategoryCode, string> = {
+  S: 'BR-S-10',
+  Z: 'BR-Z-10',
+  E: 'BR-E-10',
+  AE: 'BR-AE-10',
+  K: 'BR-IC-10',
+  G: 'BR-G-10',
+  O: 'BR-O-10',
+  L: 'BR-AF-10',
+  M: 'BR-AG-10',
 };
 
 /**
- * The refusal or finding for such a line
- * @param line The line
- */
-export const standardRatedLineWithoutRateMessage = (line: IStandardRatedLineWithoutRate): string =>
-  `In an Invoice line (BG-25) where the Invoiced item VAT category code (BT-151) is "Standard rated" the Invoiced item VAT rate (BT-152) shall be greater than zero; items[${line.index}].vatPercentage is ${String(line.vatPercentage)}. A line outside reverse charge is written as standard rated (S); its category, zero rated, exempt, intra-community supply or export (Z, E, K, G or O), cannot be stated until an item carries a VAT category of its own`;
-
-/**
- * Refuses a document whose lines cannot be written with a valid VAT category,
- * naming the rule: a line outside reverse charge whose rate is not greater than
- * zero (BR-S-05), and a reverse charge document that lacks what EN 16931
- * requires of one; no value is put in place of a missing one.
- * - BR-AE-05: every line of a reverse charge document has the VAT rate 0; the
- *   recipient owes the tax, and the invoice states none (§ 14a Abs. 5 Satz 2
- *   UStG; a stated amount would be owed under § 14c Abs. 1 UStG).
- * - BR-AE-02: the seller states a VAT identifier (BT-31) or a tax
- *   registration identifier (BT-32, `registrationDetails.taxNumber`, the
- *   Steuernummer, which § 14 Abs. 4 Satz 1 Nr. 2 UStG allows instead), and the
- *   buyer a VAT identifier (BT-48) or a legal registration identifier (BT-47).
- *   The rule also accepts a tax representative's VAT identifier (BT-63) for
- *   the seller; the envelope cannot state one, so a seller with neither BT-31
- *   nor BT-32 is refused.
- * The envelope has no place of supply, so whether a document is one for a
- * supply in another member state, whose invoice states the VAT identification
- * numbers of both parties (§ 14a Abs. 1 Satz 3 UStG), cannot be told here: a
- * domestic § 13b supply to a buyer based in another member state is taxed in
- * Germany and may state a tax number. Only what BR-AE-02 requires is checked;
- * the issuing application enforces § 14a Abs. 1.
+ * Every rule of EN 16931 on the VAT categories of a document's items that the
+ * envelope can break, in item order and then per document; an empty list when
+ * the document can be written. Amounts that are no number are not checked
+ * here (`findInvalidItemAmounts`).
+ * - The rate each category allows (BR-S-05, BR-Z-05, BR-E-05, BR-AE-05,
+ *   BR-IC-05, BR-G-05, BR-O-05, BR-AF-05, BR-AG-05).
+ * - The exemption reason: stated for E, AE, K, G and O (a default for AE, K,
+ *   G and O, `getDefaultVatExemption`), not stated for S, Z, L and M (the
+ *   BR-x-10 rules); a code on the VATEX list (BR-CL-22); one reason per VAT
+ *   breakdown, as a breakdown states one (`EINVOICE-VAT-EXEMPTION-DIFFERS`).
+ * - The parties' identifiers: for Z, E, L and M the seller VAT identifier
+ *   (BT-31) or tax registration identifier (BT-32) (BR-Z-02, BR-E-02,
+ *   BR-AF-02, BR-AG-02); for AE that and the buyer VAT identifier (BT-48) or
+ *   legal registration identifier (BT-47) (BR-AE-02); for K the seller and the
+ *   buyer VAT identifier (BR-IC-02); for G the seller VAT identifier
+ *   (BR-G-02); for O neither VAT identifier (BR-O-02). The rules also accept
+ *   a seller tax representative (BT-63), which the envelope cannot state.
+ * - An intra-community supply states the delivery date (BT-72) or the
+ *   invoicing period (BG-14) (BR-IC-11) and the deliver to country (BT-80,
+ *   `metadata.deliveryAddress.countryCode`) (BR-IC-12).
+ * - A document not subject to VAT has no item of another category (BR-O-11,
+ *   BR-O-12).
+ * The rule for a standard rated item holds whether it states S or is S
+ * because it states no category, so an item at the rate 0 outside reverse
+ * charge that states no category breaks BR-S-05. Whether a document in
+ * reverse charge meets § 14a Abs. 1 UStG (both VAT identification numbers for
+ * a supply in another member state) cannot be told from the envelope, which
+ * has no place of supply; the issuing application enforces it.
  * @param accountingDoc The document
- * @param targetFormat The format being written
- */
-export const assertVatCategoryWritable = (accountingDoc: TAccountingDoc, targetFormat: string): void => {
-  const refuse = (rule: string, message: string): never => {
-    throw new EInvoiceFormatError(`${rule}: ${message}`, { targetFormat, unsupportedFeatures: [rule] });
-  };
-  if (!accountingDoc.reverseCharge) {
-    const line = findStandardRatedLineWithoutRate(accountingDoc.items);
-    if (line) {
-      refuse('BR-S-05', standardRatedLineWithoutRateMessage(line));
+ */
+export const findVatCategoryViolations = (
+  accountingDoc: Pick<TAccountingDoc, 'items' | 'from' | 'to' | 'deliveryDate' | 'periodOfPerformance'> & {
+    reverseCharge?: boolean;
+    language?: string;
+    metadata?: { deliveryAddress?: { countryCode?: string } };
+  },
+  syntax?: 'ubl' | 'cii',
+): IVatCategoryViolation[] => {
+  const violations: IVatCategoryViolation[] = [];
+  const items = accountingDoc.items ?? [];
+  const categories = items.map((item) => getItemVatCategory(accountingDoc, item));
+
+  items.forEach((item, index) => {
+    const category = categories[index];
+    const rule = syntax === 'cii' && category === 'L' ? CII_IGIC_RATE_RULE : RATE_RULES[category];
+    if (typeof item.vatPercentage === 'number' && Number.isFinite(item.vatPercentage) && !rule.allows(item.vatPercentage)) {
+      violations.push({
+        ruleId: rule.ruleId,
+        field: `items[${index}].vatPercentage`,
+        message:
+          category === 'S'
+            ? standardRatedLineWithoutRateMessage({ index, vatPercentage: item.vatPercentage }, item.vatCategory === 'S')
+            : `an item of the VAT category ${category} has the VAT rate ${rule.expected}; items[${index}].vatPercentage is ${String(item.vatPercentage)}`,
+      });
     }
-    return;
-  }
-  for (const [index, item] of (accountingDoc.items ?? []).entries()) {
-    if (item.vatPercentage !== 0) {
-      refuse('BR-AE-05', `a reverse charge line has the VAT rate 0, items[${index}].vatPercentage is ${String(item.vatPercentage)}`);
+    const code = item.vatExemptionReasonCode?.trim();
+    if (code && !isVatexCode(code)) {
+      violations.push({
+        ruleId: 'BR-CL-22',
+        field: `items[${index}].vatExemptionReasonCode`,
+        message: `the VAT exemption reason code (BT-121) belongs to the CEF VATEX code list; items[${index}].vatExemptionReasonCode is ${code}`,
+      });
+    }
+  });
+
+  // one VAT breakdown per category and rate, as the encoders write them (computeDocumentTotals)
+  const groups = new Map<string, { category: TVatCategoryCode; indexes: number[] }>();
+  items.forEach((item, index) => {
+    const key = `${categories[index]}|${item.vatPercentage}`;
+    const group = groups.get(key) ?? { category: categories[index], indexes: [] };
+    group.indexes.push(index);
+    groups.set(key, group);
+  });
+  for (const { category, indexes } of groups.values()) {
+    const stated = indexes
+      .map((index) => ({ index, exemption: getItemVatExemption(items[index]) }))
+      .filter((entry): entry is { index: number; exemption: IVatExemption } => entry.exemption !== undefined);
+    const distinct = new Set(stated.map((entry) => `${entry.exemption.code ?? ''}|${entry.exemption.reason ?? ''}`));
+    const fields = indexes.map((index) => `items[${index}]`).join(', ');
+    if (distinct.size > 1) {
+      violations.push({
+        ruleId: VAT_EXEMPTION_DIFFERS,
+        field: stated.map((entry) => `items[${entry.index}]`).join(', '),
+        message: `the items of one VAT breakdown (category ${category}) state one exemption reason, as the breakdown states one (BT-120, BT-121); ${stated
+          .map((entry) => `items[${entry.index}] states ${[entry.exemption.code, entry.exemption.reason].filter(Boolean).join(' ')}`)
+          .join(', ')}`,
+      });
+    }
+    const withExemption = VAT_CATEGORIES_WITH_EXEMPTION.includes(category);
+    if (withExemption && stated.length === 0 && !getDefaultVatExemption(category, accountingDoc.language)) {
+      violations.push({
+        ruleId: EXEMPTION_RULES[category],
+        field: fields,
+        message: `a VAT breakdown of the category ${category} states a VAT exemption reason code (BT-121) or text (BT-120); ${fields} state neither vatExemptionReasonCode nor vatExemptionReason`,
+      });
+    }
+    if (!withExemption && stated.length > 0) {
+      violations.push({
+        ruleId: EXEMPTION_RULES[category],
+        field: stated.map((entry) => `items[${entry.index}]`).join(', '),
+        message: `a VAT breakdown of the category ${category} states no VAT exemption reason (BT-120, BT-121); ${stated
+          .map((entry) => `items[${entry.index}]`)
+          .join(', ')} state one`,
+      });
     }
   }
+
+  const has = (category: TVatCategoryCode) => categories.includes(category);
   const seller = accountingDoc.from?.registrationDetails;
-  if (!seller?.vatId && !seller?.taxNumber) {
-    refuse(
-      'BR-AE-02',
-      'a reverse charge document states the seller VAT identifier (BT-31) or tax registration identifier (BT-32), from.registrationDetails.vatId and .taxNumber are missing; the rule would also accept a tax representative (BT-63), which the envelope cannot state',
-    );
-  }
   const buyer = accountingDoc.to?.registrationDetails;
-  if (!buyer?.vatId && !buyer?.registrationId) {
-    refuse(
-      'BR-AE-02',
-      'a reverse charge document states the buyer VAT identifier (BT-48) or legal registration identifier (BT-47), to.registrationDetails.vatId and .registrationId are missing',
-    );
+  const sellerVatId = !!seller?.vatId?.trim();
+  const sellerTaxNumber = !!seller?.taxNumber?.trim();
+  const buyerVatId = !!buyer?.vatId?.trim();
+  const sellerNeither = (rule: string, category: string) =>
+    violations.push({
+      ruleId: rule,
+      field: 'from.registrationDetails',
+      message: `a document with an item of the VAT category ${category} states the seller VAT identifier (BT-31) or tax registration identifier (BT-32); from.registrationDetails.vatId and .taxNumber are missing. The rule would also accept a tax representative (BT-63), which the envelope cannot state`,
+    });
+  for (const [category, rule] of [['Z', 'BR-Z-02'], ['E', 'BR-E-02'], ['L', 'BR-AF-02'], ['M', 'BR-AG-02'], ['AE', 'BR-AE-02']] as const) {
+    if (has(category) && !sellerVatId && !sellerTaxNumber) {
+      sellerNeither(rule, category);
+    }
+  }
+  if (has('AE') && !buyerVatId && !buyer?.registrationId?.trim()) {
+    violations.push({
+      ruleId: 'BR-AE-02',
+      field: 'to.registrationDetails',
+      message:
+        'a reverse charge document states the buyer VAT identifier (BT-48) or legal registration identifier (BT-47), to.registrationDetails.vatId and .registrationId are missing',
+    });
+  }
+  if (has('K') && (!sellerVatId || !buyerVatId)) {
+    violations.push({
+      ruleId: 'BR-IC-02',
+      field: !sellerVatId ? 'from.registrationDetails.vatId' : 'to.registrationDetails.vatId',
+      message:
+        'a document with an intra-community supply (K) states the seller VAT identifier (BT-31) and the buyer VAT identifier (BT-48) (§ 14a Abs. 3 Satz 2 UStG); ' +
+        [!sellerVatId ? 'from.registrationDetails.vatId' : '', !buyerVatId ? 'to.registrationDetails.vatId' : ''].filter(Boolean).join(' and ') +
+        ' missing. The rule would also accept a seller tax representative (BT-63), which the envelope cannot state',
+    });
+  }
+  if (has('K') && accountingDoc.deliveryDate === undefined && accountingDoc.periodOfPerformance === undefined) {
+    violations.push({
+      ruleId: 'BR-IC-11',
+      field: 'deliveryDate',
+      message: 'a document with an intra-community supply (K) states the actual delivery date (BT-72) or the invoicing period (BG-14); deliveryDate and periodOfPerformance are missing',
+    });
+  }
+  if (has('K') && !accountingDoc.metadata?.deliveryAddress?.countryCode?.trim()) {
+    violations.push({
+      ruleId: 'BR-IC-12',
+      field: 'metadata.deliveryAddress.countryCode',
+      message: 'a document with an intra-community supply (K) states the deliver to country code (BT-80); metadata.deliveryAddress.countryCode is missing',
+    });
+  }
+  if (has('G') && !sellerVatId) {
+    violations.push({
+      ruleId: 'BR-G-02',
+      field: 'from.registrationDetails.vatId',
+      message:
+        'a document with an export outside the EU (G) states the seller VAT identifier (BT-31); from.registrationDetails.vatId is missing. The rule would also accept a seller tax representative (BT-63), which the envelope cannot state',
+    });
   }
+  if (has('O') && (sellerVatId || buyerVatId)) {
+    violations.push({
+      ruleId: 'BR-O-02',
+      field: sellerVatId ? 'from.registrationDetails.vatId' : 'to.registrationDetails.vatId',
+      message: `a document with an item not subject to VAT (O) states neither the seller VAT identifier (BT-31) nor the buyer VAT identifier (BT-48); ${[
+        sellerVatId ? 'from.registrationDetails.vatId' : '',
+        buyerVatId ? 'to.registrationDetails.vatId' : '',
+      ]
+        .filter(Boolean)
+        .join(' and ')} stated`,
+    });
+  }
+  if (has('O') && categories.some((category) => category !== 'O')) {
+    violations.push({
+      ruleId: 'BR-O-11',
+      field: categories.map((category, index) => (category === 'O' ? '' : `items[${index}].vatCategory`)).filter(Boolean).join(', '),
+      message: `a document with an item not subject to VAT (O) has no item of another VAT category, as its VAT breakdown is the one of O; ${categories
+        .map((category, index) => (category === 'O' ? '' : `items[${index}] is ${category}`))
+        .filter(Boolean)
+        .join(', ')}`,
+    });
+  }
+  return violations;
+};
+
+/**
+ * Refuses a document whose items cannot be written with a valid VAT category
+ * (`findVatCategoryViolations`), naming the first rule it breaks; no value is
+ * put in place of a missing one.
+ * @param accountingDoc The document
+ * @param targetFormat The syntax being written
+ */
+export const assertVatCategoryWritable = (accountingDoc: TAccountingDoc, targetFormat: 'ubl' | 'cii'): void => {
+  const [violation] = findVatCategoryViolations(accountingDoc, targetFormat);
+  if (violation) {
+    throw new EInvoiceFormatError(`${violation.ruleId}: ${violation.message}`, {
+      targetFormat,
+      unsupportedFeatures: [violation.ruleId],
+    });
+  }
+};
+
+/**
+ * Gives the items of a decoded document the VAT category their lines state
+ * (BT-151) and the exemption reason (BT-120) and code (BT-121) of the VAT
+ * breakdown they belong to: the one of their category and rate, or of their
+ * category for an item not subject to VAT, which states no rate. A line that
+ * states no category, or a code EN 16931 does not allow, keeps none; the item
+ * is then read as AE or S (`getItemVatCategory`) and the code list rules
+ * report the code.
+ * @param items The decoded items, in line order
+ * @param statedValues What the document states; undefined for a ZUGFeRD 1.0 document
+ */
+export const applyStatedVatCategories = (items: TAccountingDocItem[], statedValues: IEInvoiceStatedValues | undefined): void => {
+  if (!statedValues) {
+    return;
+  }
+  items.forEach((item, index) => {
+    const category = statedValues.lines[index]?.vatCategoryCode;
+    if (!isVatCategoryCode(category)) {
+      return;
+    }
+    item.vatCategory = category;
+    const breakdown = statedValues.vatBreakdown.find(
+      (group) => group.categoryCode === category && (category === 'O' || group.rate === item.vatPercentage),
+    );
+    if (breakdown?.exemptionReason) {
+      item.vatExemptionReason = breakdown.exemptionReason;
+    }
+    if (breakdown?.exemptionReasonCode) {
+      item.vatExemptionReasonCode = breakdown.exemptionReasonCode;
+    }
+  });
 };