@fin.cx/einvoice 10.0.0 → 10.1.0

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

@@ -1,83 +1,174 @@
 import type { TAccountingDoc } from '../../interfaces/common.js';
+import type { finance } from '@tsclass/tsclass';
+type TAccountingDocItem = finance.TAccountingDocItem;
+import type { IEInvoiceStatedValues } from '../../interfaces/stated.values.js';
 /**
- * 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.
+ * 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 declare const VAT_CATEGORY_CODES: readonly TVatCategoryCode[];
+/**
+ * Whether a value is a VAT category code EN 16931 allows
+ * @param value The value
+ */
+export declare const isVatCategoryCode: (value: unknown) => value is TVatCategoryCode;
+/**
+ * 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 declare const VAT_CATEGORIES_WITH_EXEMPTION: readonly TVatCategoryCode[];
+/**
+ * The VAT exemption reason code (BT-121) and text (BT-120) a VAT breakdown
+ * states; at least one of them
  */
-export type TVatCategoryCode = 'S' | 'AE';
-/** The VAT exemption reason (BT-121 code, BT-120 text) a VAT category states */
 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 declare const VATEX_CODES: ReadonlySet<string>;
+/**
+ * Whether a VAT exemption reason code is on the CEF VATEX code list (BR-CL-22)
+ * @param code The code
+ */
+export declare const isVatexCode: (code: string) => boolean;
+/**
+ * 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 declare const getVatCategory: (accountingDoc: {
+export declare const getItemVatCategory: (accountingDoc: {
     reverseCharge?: boolean;
-}) => TVatCategoryCode;
+}, item: Pick<TAccountingDocItem, "vatCategory">) => TVatCategoryCode;
 /**
- * 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 declare const getItemVatExemption: (item: Pick<TAccountingDocItem, "vatExemptionReason" | "vatExemptionReasonCode">) => IVatExemption | undefined;
+/**
+ * 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 declare const getVatExemption: (category: TVatCategoryCode, language: string | undefined) => IVatExemption | undefined;
+export declare const getDefaultVatExemption: (category: TVatCategoryCode, language: string | undefined) => IVatExemption | 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 declare const mergeVatExemption: (stated: IVatExemption | undefined, categoryDefault: IVatExemption | undefined) => IVatExemption | undefined;
 /**
  * Whether a VAT rate is a number not greater than zero; a rate that is no
  * number is refused as such (`findInvalidItemAmounts`), not as BR-S-05
  * @param rate The rate
  */
 export declare const isRateNotAboveZero: (rate: unknown) => boolean;
-/** A line written as standard rated (S) whose VAT rate is not greater than zero */
-export interface IStandardRatedLineWithoutRate {
+/**
+ * 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 declare const standardRatedLineWithoutRateMessage: (line: {
     index: number;
     vatPercentage: number;
+}, statedCategory?: boolean) => string;
+/** 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 declare 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
+ * 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
  */
-export declare const findStandardRatedLineWithoutRate: (items: TAccountingDoc["items"] | undefined) => IStandardRatedLineWithoutRate | undefined;
+export declare const findVatCategoryViolations: (accountingDoc: Pick<TAccountingDoc, "items" | "from" | "to" | "deliveryDate" | "periodOfPerformance"> & {
+    reverseCharge?: boolean;
+    language?: string;
+    metadata?: {
+        deliveryAddress?: {
+            countryCode?: string;
+        };
+    };
+}, syntax?: "ubl" | "cii") => IVatCategoryViolation[];
 /**
- * The refusal or finding for such a line
- * @param line The line
+ * 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 declare const standardRatedLineWithoutRateMessage: (line: IStandardRatedLineWithoutRate) => string;
+export declare const assertVatCategoryWritable: (accountingDoc: TAccountingDoc, targetFormat: "ubl" | "cii") => void;
 /**
- * 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.
- * @param accountingDoc The document
- * @param targetFormat The format being written
+ * 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 declare const assertVatCategoryWritable: (accountingDoc: TAccountingDoc, targetFormat: string) => void;
+export declare const applyStatedVatCategories: (items: TAccountingDocItem[], statedValues: IEInvoiceStatedValues | undefined) => void;
+export {};