From 6e2890821fed451754aa395330ca47149fdbee6f Mon Sep 17 00:00:00 2001 From: Alvaro Olivie <77957082+alvarolivie@users.noreply.github.com> Date: Thu, 20 Nov 2025 15:10:25 +0100 Subject: [PATCH 1/5] Remove attached document fields and add new terms --- terms/en16931.yaml | 67 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 61 insertions(+), 6 deletions(-) diff --git a/terms/en16931.yaml b/terms/en16931.yaml index edf8ed2..aa61447 100644 --- a/terms/en16931.yaml +++ b/terms/en16931.yaml @@ -922,12 +922,6 @@ terms: name: "External document location" paths: - $.doc.attachments[*].uri - - id: BT-125 - name: "Attached document" - paths: - - $.doc.attachments[*].data - - $.doc.attachments[*].mime - - $.doc.attachments[*].name - id: BG-25 name: "INVOICE LINE" @@ -1063,3 +1057,64 @@ terms: name: "PRICE DETAILS" paths: - $.doc.lines[*].item + terms: + - id: BT-146 + name: "Item net price" + paths: + - $.doc.lines[*].item.price + + - id: BG-30 + name: "LINE VAT INFORMATION" + paths: + - $.doc.lines[*].taxes[cat='VAT'] + terms: + - id: BT-151 + name: "Invoiced item VAT category code" + paths: + - $.doc.lines[*].taxes[cat='VAT'].key + - $.doc.lines[*].taxes[cat='VAT'].ext['untdid-tax-category'] + notes: |- + Taxes keys are mapped automatically to UNTDID 3505 tax category + codes or can be set manually if required. + - id: BT-152 + name: "Invoiced item VAT rate" + paths: + - $.doc.lines[*].taxes[cat='VAT'].percent + + - id: BG-31 + name: "ITEM INFORMATION" + paths: + - $.doc.lines[*].item + terms: + - id: BT-153 + name: "Item name" + paths: + - $.doc.lines[*].item.name + - id: BT-154 + name: "Item description" + paths: + - $.doc.lines[*].item.description + - id: BT-155 + name: "Item Seller's identifier" + paths: + - $.doc.lines[*].item.ref + - id: BT-157 + name: "Item standard identifier" + paths: + - $.doc.lines[*].item.identities[*].code + - $.doc.lines[*].item.identities[*].ext['iso-scheme-id'] + - id: BR-32 + name: "ITEM ATTRIBUTES" + paths: + - $.doc.lines[*].item.meta + terms: + - id: BT-160 + name: "Item attribute name" + paths: + - $.doc.lines[*].item.meta.key + - id: BT-161 + name: "Item attribute value" + paths: + - $.doc.lines[*].item.meta[key].value + + From 1deefbcd8f9354430b7c13e74c11de53f388bf67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Olivi=C3=A9?= Date: Fri, 28 Nov 2025 10:33:43 +0000 Subject: [PATCH 2/5] Update terms --- terms/en16931.yaml | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/terms/en16931.yaml b/terms/en16931.yaml index aa61447..a9062bc 100644 --- a/terms/en16931.yaml +++ b/terms/en16931.yaml @@ -962,7 +962,7 @@ terms: notes: |- Reflects the net amount of the line, after applying discounts or charges. GOBL also supports the `tax_included` property which when used implies that - the prices are tax-inclusive. In this case, its important to use the + the prices are tax-inclusive. In this case, its important to use the "Remove Included Taxes" function of GOBL when converting. - id: BT-132 name: "Referenced purchase order line reference" @@ -1057,7 +1057,7 @@ terms: name: "PRICE DETAILS" paths: - $.doc.lines[*].item - terms: + terms: - id: BT-146 name: "Item net price" paths: @@ -1080,7 +1080,7 @@ terms: name: "Invoiced item VAT rate" paths: - $.doc.lines[*].taxes[cat='VAT'].percent - + - id: BG-31 name: "ITEM INFORMATION" paths: @@ -1098,9 +1098,13 @@ terms: name: "Item Seller's identifier" paths: - $.doc.lines[*].item.ref + - id: BT-156 + name: "Item Buyer's identifier" + paths: + - $.doc.lines[*].item.identities[*].code - id: BT-157 name: "Item standard identifier" - paths: + paths: - $.doc.lines[*].item.identities[*].code - $.doc.lines[*].item.identities[*].ext['iso-scheme-id'] - id: BR-32 @@ -1116,5 +1120,3 @@ terms: name: "Item attribute value" paths: - $.doc.lines[*].item.meta[key].value - - From 5d6e8b94fa7a8082cbe0d7cd68b9ef6c3d7ace2d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Olivi=C3=A9?= Date: Thu, 26 Feb 2026 15:15:55 +0000 Subject: [PATCH 3/5] run go mod tidy --- go.mod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/go.mod b/go.mod index 7ff1d9e..9e0f3f2 100644 --- a/go.mod +++ b/go.mod @@ -1,6 +1,6 @@ module github.com/invopop/gobl.docs -go 1.24 +go 1.24.0 toolchain go1.24.3 From ee45c770be4920a77958c3ad2a349d7cc66a5349 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Olivi=C3=A9?= Date: Thu, 26 Feb 2026 15:17:29 +0000 Subject: [PATCH 4/5] Update gobl version --- addons/ar-arca-v4.mdx | 316 +++++++++++++++++ addons/br-nfse-v1.mdx | 45 +++ addons/es-sii-v1.mdx | 293 ++++++++++++++++ addons/es-verifactu-v1.mdx | 26 +- addons/fr-ctc-flow2-v1.mdx | 58 ++++ addons/gr-mydata-v1.mdx | 182 ++++++++-- addons/pl-favat-v3.mdx | 674 +++++++++++++++++++++++++++++++++++++ addons/pt-saft-v1.mdx | 3 + catalogues/untdid.mdx | 7 + regimes/ae.mdx | 13 + regimes/ar.mdx | 43 ++- regimes/at.mdx | 9 + regimes/be.mdx | 13 + regimes/br.mdx | 22 +- regimes/ca.mdx | 16 + regimes/ch.mdx | 15 + regimes/co.mdx | 20 ++ regimes/de.mdx | 14 + regimes/dk.mdx | 46 +++ regimes/el.mdx | 17 + regimes/es.mdx | 20 ++ regimes/fr.mdx | 19 +- regimes/gb.mdx | 15 + regimes/ie.mdx | 13 + regimes/in.mdx | 20 ++ regimes/it.mdx | 20 ++ regimes/mx.mdx | 21 ++ regimes/nl.mdx | 16 + regimes/pl.mdx | 15 + regimes/pt.mdx | 17 + regimes/se.mdx | 21 ++ regimes/sg.mdx | 31 +- regimes/us.mdx | 16 + 33 files changed, 2009 insertions(+), 67 deletions(-) create mode 100644 addons/ar-arca-v4.mdx create mode 100644 addons/es-sii-v1.mdx create mode 100644 addons/fr-ctc-flow2-v1.mdx create mode 100644 addons/pl-favat-v3.mdx create mode 100644 regimes/dk.mdx diff --git a/addons/ar-arca-v4.mdx b/addons/ar-arca-v4.mdx new file mode 100644 index 0000000..fcb0238 --- /dev/null +++ b/addons/ar-arca-v4.mdx @@ -0,0 +1,316 @@ +--- +title: Argentina ARCA V4 +--- + +Key: ar-arca-v4 + +Support for the Argentina ARCA v4 standard for electronic invoicing. + +## Sources +- [Argentina ARCA V4](https://www.afip.gob.ar/ws/documentacion/manuales/manual-desarrollador-ARCA-COMPG-v4-0.pdf) + +## Correction Definitions + +Auto-generation of corrective invoices or credit and debit notes is +supported. + +### Invoice Types + +The types of invoices that can be created with a preceding definition: +- credit-note +- debit-note + +### Extension Keys + +One or all of the following extensions may be required as part of the correction +options. See the [Extensions](#extensions) section for possible values. +- ar-arca-doc-type + +## Extensions +### Argentina ARCA Document Type + +Code used to identify the type of document being issued. + +This can always be set directly. If not provided, GOBL will automatically determine it during +normalization based on the following rules: + +Type C (Simplified Tax Scheme / Monotributo supplier): If the invoice has the +`monotax` tag set, the document type will be `11` (Invoice C), `13` (Credit Note C), +or `12` (Debit Note C). + +Type A (B2B with VAT-registered customers): If the customer's `ar-arca-vat-status` extension +is one of `1` (Registered Company), `6` (Monotributo Responsible), `13` (Social Monotributista), +or `16` (Promoted Independent Worker), the document type will be `1` (Invoice A), `3` (Credit +Note A), or `2` (Debit Note A). + +Type B (B2C or other scenarios): For all other cases (final consumers, foreign customers, +exempt entities, or when no customer is provided), the document type will be `6` (Invoice B), +`8` (Credit Note B), or `7` (Debit Note B). + +For other document types the value must be set manually. + + + +| Code | Name | +| ---- | ---- | +| 1 | Invoice A | +| 2 | Debit Note A | +| 3 | Credit Note A | +| 4 | Receipt A | +| 5 | Cash Sales Note A | +| 6 | Invoice B | +| 7 | Debit Note B | +| 8 | Credit Note B | +| 9 | Receipt B | +| 10 | Cash Sales Note B | +| 11 | Invoice C | +| 12 | Debit Note C | +| 13 | Credit Note C | +| 15 | Receipt C | +| 34 | Invoices A per Annex I, Section A, subsection f), R.G. No. 1415 | +| 35 | Vouchers B per Annex I, Section A, subsection f), R.G. No. 1415 | +| 39 | Other Vouchers A compliant with R.G. No. 1415 | +| 40 | Other Vouchers B compliant with R.G. No. 1415 | +| 49 | Used Goods Purchase Invoice to Final Consumer | +| 51 | Invoice A with Legend 'Subject to Withholding' | +| 52 | Debit Note A with Legend 'Subject to Withholding' | +| 53 | Credit Note A with Legend 'Subject to Withholding' | +| 54 | Receipt A with Legend 'Subject to Withholding' | +| 60 | Sales Account and Product Settlement A | +| 61 | Sales Account and Product Settlement B | +| 63 | Settlement A | +| 64 | Settlement B | +| 201 | MiPyMEs Electronic Credit Invoice (FCE) A | +| 202 | MiPyMEs Electronic Debit Note (FCE) A | +| 203 | MiPyMEs Electronic Credit Note (FCE) A | +| 206 | MiPyMEs Electronic Credit Invoice (FCE) B | +| 207 | MiPyMEs Electronic Debit Note (FCE) B | +| 208 | MiPyMEs Electronic Credit Note (FCE) B | +| 211 | MiPyMEs Electronic Credit Invoice (FCE) C | +| 212 | MiPyMEs Electronic Debit Note (FCE) C | +| 213 | MiPyMEs Electronic Credit Note (FCE) C | + +### Argentina ARCA Concept (Goods, services, or both) + +Code used to identify the invoice concept, indicating whether the invoice covers +goods, services, or both. + +This extension is automatically determined by GOBL based on the `key` field of each +line item: + +- `1` (Products): All line items have `key` set to `goods`. +- `2` (Services): All line items have `key` empty, unset, or set to any value other than `goods`. +- `3` (Products and Services): The invoice contains a mix of both goods and services. + +When the concept is `2` (Services) or `3` (Products and Services), the invoice must +include an ordering period and payment terms with due dates. + + + +| Code | Name | +| ---- | ---- | +| 1 | Goods | +| 2 | Services | +| 3 | Goods and services | + +### Argentina ARCA Tax Type + +Code used to identify the type of tax applied as a charge. This is used for taxes other than +VAT that need to be included in the invoice (national taxes, provincial taxes, withholdings, etc.). + +These taxes must be added as invoice charges (not in line items) with the charge `key` set +to `tax`, a `percent` value (required, amounts are not accepted), and this extension to +specify the tax type. + +Example - Tax applied to invoice total: + +```json +"charges": [ + { + "key": "tax", + "percent": "3%", + "ext": { + "ar-arca-tax-type": "1" + } + } +] +``` + +Example - Tax applied to a specific base: + +```json +"charges": [ + { + "key": "tax", + "percent": "3%", + "base": "1000.00", + "ext": { + "ar-arca-tax-type": "1" + } + } +] +``` + +Validation rules: + +- When a charge has `key: tax`, this extension is required. +- The `percent` field is required when this extension is present. +- When using code `99` (Other), the charge `reason` field is required to describe the tax. + + + +| Code | Name | +| ---- | ---- | +| 1 | National Taxes | +| 2 | Provincial Taxes | +| 3 | Municipal Taxes | +| 4 | Internal Taxes | +| 5 | Gross Income Tax | +| 6 | VAT Prepayment | +| 7 | Gross Income Tax Prepayment | +| 8 | Municipal Taxes Prepayment | +| 9 | Other Prepayments | +| 13 | VAT Not Categorized Prepayment | +| 99 | Other | + +### Argentina ARCA VAT Rate + +Code used to identify the VAT rate applied to line items. + +This extension is automatically determined by GOBL based on the tax rate key defined in +the Argentine tax regime: + +- `zero` rate (0%) → code `3` +- `reduced` rate (10.5%) → code `4` +- `standard` rate (21%) → code `5` +- `increased` rate (27%) → code `6` + +For the special reduced rates of 5% and 2.5%, the extension must be set manually on the +line tax as these are not covered by the standard rate keys: + +- 5% → code `8` +- 2.5% → code `9` + + + +| Code | Name | +| ---- | ---- | +| 3 | 0% | +| 4 | 10.5% | +| 5 | 21% | +| 6 | 27% | +| 8 | 5% | +| 9 | 2.5% | + +### Argentina ARCA Customer Identity Type + +Code used to identify the type of identity document in the customer's `identities` field. + +This extension is typically only needed for B2C operations where the customer needs to +provide an identification number but does not have a tax ID. Common examples include +DNI (code `96`), passport, or provincial identity cards. + +When the customer has a CUIT, CUIL, or a valid foreign tax identification number, +these should be included in the `tax_id` field instead, and this extension is not required. + +Example usage for a final consumer with DNI: + +```json +"customer": { + "name": "John Doe", + "identities": [ + { + "code": "12345678", + "ext": { + "ar-arca-identity-type": "96" + } + } + ], + "ext": { + "ar-arca-vat-status": "5" + } +} +``` + + + +| Code | Name | +| ---- | ---- | +| 00 | CI Capital Federal | +| 01 | CI Buenos Aires | +| 02 | CI Catamarca | +| 03 | CI Córdoba | +| 04 | CI Corrientes | +| 05 | CI Entre Ríos | +| 06 | CI Jujuy | +| 07 | CI Mendoza | +| 08 | CI La Rioja | +| 09 | CI Salta | +| 10 | CI San Juan | +| 11 | CI San Luis | +| 12 | CI Santa Fe | +| 13 | CI Santiago del Estero | +| 14 | CI Tucumán | +| 16 | CI Chaco | +| 17 | CI Chubut | +| 18 | CI Formosa | +| 19 | CI Misiones | +| 20 | CI Neuquén | +| 21 | CI La Pampa | +| 22 | CI Río Negro | +| 23 | CI Santa Cruz | +| 24 | CI Tierra del Fuego | +| 80 | CUIT (Unique Tax Identification Number) | +| 86 | CUIL (Unique Labor Identification Number) | +| 87 | CDI | +| 89 | LE | +| 90 | LC | +| 91 | Foreign CI | +| 92 | In Process | +| 93 | Birth Certificate | +| 94 | Passport | +| 95 | CI Bs. As. RNP | +| 96 | DNI | +| 99 | Final Consumer | + +### Customer VAT Status + +Code used to identify the VAT status of the customer. This extension must be included +in the customer's `ext` field when the customer is required. + +GOBL will automatically normalize this value based on the customer's tax identification: + +Customer without tax ID (final consumers): Defaults to `5` (Final Consumer). Also +accepts `4` (Exempt Subject), `7` (Uncategorized), `10` (VAT Exempt Law 19640), +or `15` (VAT Not Applicable). + +Customer with foreign tax ID: Defaults to `9` (Foreign Customer). Also accepts +`8` (Foreign Supplier). + +Customer with Argentine tax ID (CUIT/CUIL): Defaults to `1` (Registered VAT Company). +Also accepts `6` (Monotributo), `13` (Social Monotributista), `16` (Promoted Independent +Worker), `4` (Exempt Subject), `7` (Uncategorized), `10` (VAT Exempt Law 19640), +or `15` (VAT Not Applicable). + +The VAT status is validated against the document type: + +- Type A documents (`1`, `2`, `3`, etc.): Require VAT status `1`, `6`, `13`, or `16`. +- Type B documents (`6`, `7`, `8`, etc.): Cannot have VAT status `1`, `6`, `13`, or `16`. +- Document type `49` (Used Goods Purchase Invoice): Requires VAT status `5` (Final Consumer). + + + +| Code | Name | +| ---- | ---- | +| 1 | Registered VAT Company | +| 4 | VAT Exempt Subject | +| 5 | Final Consumer | +| 6 | Monotributo Responsible | +| 7 | Uncategorized Subject | +| 8 | Foreign Supplier | +| 9 | Foreign Customer | +| 10 | VAT Exempt - Law N° 19.640 | +| 13 | Social Monotributista | +| 15 | VAT Not Applicable | +| 16 | Promoted Independent Worker Monotributista | + \ No newline at end of file diff --git a/addons/br-nfse-v1.mdx b/addons/br-nfse-v1.mdx index 980ada2..bef17d6 100644 --- a/addons/br-nfse-v1.mdx +++ b/addons/br-nfse-v1.mdx @@ -87,4 +87,49 @@ Indicates a special tax regime that a party is subject to. | 4 | Cooperative | | 5 | Single micro-entrepreneur (MEI) | | 6 | Micro-enterprise or Small Business (ME EPP) | + +### Operation Indicator + +Indicates the operation type for the determination of the IBS and CBS taxes by the +tax authorities. + +Maps to the `cIndOp` field in the NFS-e national layout. + +List of possible values: + +* https://www.gov.br/nfse/pt-br/biblioteca/documentacao-tecnica/rtc/anexovii-indop_ibscbs_v1-00-00.xlsx + + + +Pattern: ^\d{6}$ + +### Tax Status Code (CST) + +Indicates the tax status of the operation for the determination of the IBS and CBS +taxes by the tax authorities. + +Maps to the `CST` field in the NFS-e national layout. + +List of possible values: + +* https://dfe-portal.svrs.rs.gov.br/DFE/ClassificacaoTributaria + + + +Pattern: ^\d{3}$ + +### Tax Classification Code + +Indicates the tax classification code for the determination of the IBS and CBS taxes +by the tax authorities. + +Maps to the `cClassTrib` field in the NFS-e national layout. + +List of possible values: + +* https://dfe-portal.svrs.rs.gov.br/DFE/ClassificacaoTributaria + + + +Pattern: ^\d{6}$ \ No newline at end of file diff --git a/addons/es-sii-v1.mdx b/addons/es-sii-v1.mdx new file mode 100644 index 0000000..f14b9ae --- /dev/null +++ b/addons/es-sii-v1.mdx @@ -0,0 +1,293 @@ +--- +title: Spain SII V1.x +--- + +Key: es-sii-v1 + +## Sources +- [Suministro Inmediato de Información (SII) at AEAT portal](https://sede.agenciatributaria.gob.es/Sede/iva/suministro-inmediato-informacion.html) + +## Correction Definitions + +Auto-generation of corrective invoices or credit and debit notes is +supported. + +### Extension Keys + +One or all of the following extensions may be required as part of the correction +options. See the [Extensions](#extensions) section for possible values. +- es-sii-doc-type + +## Extensions +### Invoice Type + +Code used to identify the type of invoice being sent or received. This will be determined +automatically by GOBL during normalization according to the scenario definitions. + +The following codes are not covered by GOBL's scenarios and will need to be set manually if +needed: `F4`, `F5`, `F6`, `R2`, `R3`, `R4`, `AJ`, `LC`. + +Maps to the `TipoFactura` field. Values correspond to the L2_EMI (issued invoices) and +L2_RECI (received invoices) lists. + + + +| Code | Name | +| ---- | ---- | +| F1 | Invoice (Article 6, 7.2 and 7.3 of RD 1619/2012) | +| F2 | Simplified invoice (Article 6.1.d) of RD 1619/2012) | +| F3 | Invoice issued as replacement of simplified invoice | +| F4 | Summary entry of invoices | +| F5 | Imports (DUA) | +| F6 | Accounting justifications | +| R1 | Rectified invoice: articles 80.1, 80.2, and 80.6 | +| R2 | Rectified invoice: article 80.3 | +| R3 | Rectified invoice: article 80.4 | +| R4 | Rectified invoice: other | +| R5 | Rectified invoice: simplified invoices | +| AJ | Profit margin adjustment | +| LC | Customs - Complementary settlement | + +### Corrective Invoice Type + +Correction type code used to identify the type of correction being made. + +Code is determined automatically according to the invoice type: + +| Invoice Type | Code | +| ------------- | ---- | +| `corrective` | `S` | +| `credit-note` | `I` | +| `debit-note` | `I` | + +Maps to the `TipoRectificativa` field. Values correspond to the L5 list. + + + +| Code | Name | +| ---- | ---- | +| S | Substitution | +| I | Differences | + +### Exemption Reason + +Exemption code used to explain why the operation is exempt from taxes. + +The follow mappings will be made automatically by GOBL during normalization: + +| Tax Key | Exemption Codes | +|-------------------|----------------------------| +| `exempt` | `E1` (default), `E6` | +| `export` | `E2` (default), `E3`, `E4` | +| `intra-community` | `E5` | + +Maps to the field `CausaExencion`. Values correspond to the L9 list. + +Note: This extension is **mutually exclusive** with `es-sii-outside-scope`. + + + +| Code | Name | +| ---- | ---- | +| E1 | Exempt pursuant to Art. 20 (internal operations). | +| E2 | Exempt pursuant to Art. 21 (exports of goods). | +| E3 | Exempt pursuant to Art. 22 (operations asimilated to exports). | +| E4 | Exempt pursuant to Art. 23 and 24 (temporary deposit, customs and fiscal regimes, and other situations). | +| E5 | Exempt pursuant to Art. 25 (delivery of goods destined to another Member State). | +| E6 | Exempt pursuant to other reasons | + +### Type of Operation Outside Scope + +Type of operation not subject to VAT. + +This extension is used to determine which tax amount field should be reported in the SII +payload: + +- `other` will set the `ImportePorArticulos7_14_Otros` field. +- `location` will set the `ImporteTAIReglasLocalizacion` field. + +GOBL will attempt to automatically assign operation type codes based on tax key: + +| Operation Type | Tax Key | +| -------------- | ------------------------- | +| `other` | `outside-scope` | +| `location` | `outside-scope` (default) | + +Doesn't map directly to any field. Used internally to determine how to report the tax amount. + +Note: This extension is **mutually exclusive** with `es-sii-exempt`. + + + +| Code | Name | +| ---- | ---- | +| other | Outside scope - Articles 7, 14, others | +| location | Outside scope - Due to location rules | + +### Special Regime or Relevance Key + +Identify the regime applied to the operation. + +The regime key must be assigned for each tax combo. If no regime key is provided, GOBL will +try to assign a code from the following tax combo contexts: + +| Combo Context | Regime Code | +| -------------- | ----------- | +| Key `standard` | `01` | +| Key `export` | `02` | + +Maps to the field `ClaveRegimenEspecialOTrascendencia`. Values correspond to the L3.1 +(issued invoices) and L3.2 (received invoices) lists. + + + +| Code | Name | +| ---- | ---- | +| 01 | General regime operation | +| 02 | Export (L3.1) / Operations for which businesses pay compensation in acquisitions from individuals under the special regime for agriculture, livestock, and fishing (L3.2) | +| 03 | Special regime for used goods, art objects, antiques and collectibles | +| 04 | Special regime for investment gold | +| 05 | Special regime for travel agencies | +| 06 | Special regime for VAT/IGIC groups (Advanced Level) | +| 07 | Special cash accounting regime | +| 08 | Operations subject to IPSI / IGIC (Tax on Production, Services and Imports / Canary Islands General Indirect Tax) | +| 09 | Billing of travel agency services acting as mediators in name and on behalf of others | +| 10 | Collection of professional fees or rights on behalf of third parties | +| 11 | Business premises rental operations | +| 12 | Business premises rental operations not subject to withholding | +| 13 | Business premises rental operations subject and not subject to withholding (L3.1) / Invoice corresponding to an import (reported without being associated with a DUA) (L3.2) | +| 14 | Invoice with pending VAT/IGIC accrual in work certifications for Public Administration (L3.1) / First half of 2017 and other invoices prior to inclusion in the SII (L3.2) | +| 15 | Invoice with pending VAT/IGIC accrual in successive tract operations | +| 16 | First half of 2017 and other invoices prior to inclusion in the SII | +| 17 | Operation covered by one of the regimes provided for in Chapter XI of Title IX (OSS and IOSS) | + +### Identification Type + +Identity code used to identify the type of identity document used by the customer. + +The regular Party Tax Identity is preferred over using a specific identity type code, and +will be mapped automatically as follows: + +- Spanish Tax IDs will be mapped to the `NIF` field. +- EU Tax IDs will be mapped to the `IDOtro\IDType` field with code `02`. +- Non-EU Tax IDs will be mapped to the `IDOtro\IDType` field with code `04`. + +SII will perform validation on both Spanish and EU Tax IDs, so it is important to provide +the correct details. + +The following identity `key` values will be mapped automatically to an extension by the +addon: + +| Identity Key | Code | +| ------------ | ---- | +| `passport` | `03` | +| `foreign` | `04` | +| `resident` | `05` | +| `other` | `06` | + +The `07` "not registered in census" code is not mapped automatically, but can be provided +directly if needed. + +Example identity of a UK passport: + +``` +{ + "identities": [ + { + "key": "passport", + "country": "GB", + "code": "123456789" + } + ] +} +``` + +Will be normalized to: + +``` +{ + "identities": [ + { + "key": "passport", + "country": "GB", + "code": "123456789", + "ext": { + "es-sii-identity-type": "03" + } + } + ] +} +``` + +Maps to the field `IDOtro\IDType`. Values correspond to the L4 list. + + + +| Code | Name | +| ---- | ---- | +| 02 | NIF-VAT Identity (VIES) | +| 03 | Passport | +| 04 | Foreign Identity Document | +| 05 | Residential Certificate | +| 06 | Other Identity Document | +| 07 | Not registered in census | + +### Simplified Invoice Art. 7.2 and 7.3, RD 1619/2012 + +This extension covers a specific use-case when the customer specifically requests that the +invoice includes their fiscal details, but they are not registered for tax. + +Can only be true when the invoice type (`TipoFactura`) is one of: `F1`, `F3`, `R1`, `R2`, +`R3`, or `R4`. + +Maps to the `FacturaSimplificadaArticulos7.2_7.3` field. Values correspond to the L26 list. + + + +| Code | Name | +| ---- | ---- | +| S | Yes | +| N | No | + +### Issued by Third Party or Recipient + +Indicates whether the invoice is issued by a third party or by the customer themselves. + +The default value is `N` (No). + +The `self-billed` tag will automatically set this extension in the invoice to `S` (Yes). + +If the `issuer` field is set in the invoice's ordering section, then this extension will be +set to `S` (Yes) too. + +Maps to the field `EmitidaPorTercerosODestinatario`. Values correspond to the L10 list. + + + +| Code | Name | +| ---- | ---- | +| S | Yes | +| N | No | + +### Product Type + +Product type code used to differentiate between goods and services for the purpose of +reporting breakdowns in the SII format. + +This extension is used to determine the type of operation breakdown when generating the SII +report. When provided, the value will be used to generate the `DesgloseTipoOperacion` field, +selecting between `PrestacionServices` (provision of services) or `Entrega` (delivery of +goods). + +This extension is optional; if not provided, the breakdown will use `DesgloseFactura` instead +of `DesgloseTipoOperacion`. + +Doesn't map directly to any field. Used internally to structure the breakdown data. + + + +| Code | Name | +| ---- | ---- | +| goods | Delivery of goods | +| services | Provision of services | + \ No newline at end of file diff --git a/addons/es-verifactu-v1.mdx b/addons/es-verifactu-v1.mdx index bf59cab..0875802 100644 --- a/addons/es-verifactu-v1.mdx +++ b/addons/es-verifactu-v1.mdx @@ -69,14 +69,15 @@ Classification code for operations that are subject to tax and not exempt, or fo GOBL will attempt to automatically assign operation class codes based on tax key, but if your workflow requires more control, you may prefer to let users select the appropriate operation class and exemption code for each case. -Automatic mapping of tax combo keys to operation classes: +Tax keys will be normalized as described in the following table. Some keys will set a default value which can be overridden. -| Operation Class | Tax Key | -|-----------------|-------------------------| -| `S1` | `standard`, `reduced`, `super-reduced`, `zero` | -| `S2` | `reverse-charge` | -| `N1` | `outside-scope` | -| `N2` | `outside-scope` (default) | +| Tax Key | Operation Classes | +|------------------|----------------------| +| `standard` | `S1` | +| `zero` | `S1` | +| `reverse-charge` | `S2` | +| `outside-scope` | `N2` (default), `N1` | +| others | removed | This extension maps to the `CalificacionOperacion` field and must not be used together with the `es-verifactu-exempt` extension. Values correspond to the L9 list. @@ -107,6 +108,7 @@ The follow mappings will be made automatically by GOBL during normalization. | `exempt` | `E1` (default), `E6` | | `export` | `E2` (default), `E3`, `E4` | | `intra-community` | `E5` | +| others | removed | @@ -176,10 +178,12 @@ to provide the correct details. The following identity `key` values will be mapped automatically to an extension by the addon for the following keys: -- `passport`: `03` -- `foreign`: `04` -- `resident`: `05` -- `other`: `06` +| Identity Key | Extension Code | +|--------------|----------------| +| `passport` | `03` | +| `foreign` | `04` | +| `resident` | `05` | +| `other` | `06` | The `07` "not registered in census" code is not mapped automatically, but can be provided directly if needed. diff --git a/addons/fr-ctc-flow2-v1.mdx b/addons/fr-ctc-flow2-v1.mdx new file mode 100644 index 0000000..b2a5f69 --- /dev/null +++ b/addons/fr-ctc-flow2-v1.mdx @@ -0,0 +1,58 @@ +--- +title: France CTC Flow 2 +--- + +Key: fr-ctc-flow2-v1 + +Support for the French CTC (Continuous Transaction Control) Flow 2 B2B +e-invoicing requirements from the French electronic invoicing reform. + +This addon provides the necessary structures and validations to ensure compliance +with the French CTC specifications for B2B electronic invoicing. + +It requires the EN16931 addon as it extends the European standard with French-specific +requirements for the e-invoicing reform. + +This addon is required for regulated invoice. This refers to invoices between two parties +registered for VAT in France. This addon should not be used for invoices which should be reported. + +Note on currency conversion (BR-FR-CO-12): When an invoice is issued in a non-EUR +currency, the gobl.ubl library will automatically handle the conversion to EUR and +present the invoice with both the original currency and EUR equivalents for tax +amounts, ensuring compliance with French accounting requirements. + +## Sources +- [External Specifications](https://www.impots.gouv.fr/specifications-externes-b2b) + +## Extensions +### Billing Mode + +Code used to describe the billing framework of the invoice. The billing mode +indicates the nature of goods/services and the payment context. + +Code prefixes indicate the invoice nature: +- "B": Goods invoice (Biens) +- "S": Services invoice +- "M": Mixed/dual invoice (goods and services that are not accessory to each other) + +The numeric suffix indicates the payment type (1=deposit, 2=already paid, +4=final after down payment, 5=subcontractor, 6=co-contractor, 7=e-reporting). + + + +| Code | Name | +| ---- | ---- | +| B1 | Goods - Deposit invoice | +| B2 | Goods - Already paid invoice | +| B4 | Goods - Final invoice (after down payment) | +| B7 | Goods - E-reporting (VAT already collected) | +| S1 | Services - Deposit invoice | +| S2 | Services - Already paid invoice | +| S4 | Services - Final invoice (after down payment) | +| S5 | Services - Subcontractor invoice | +| S6 | Services - Co-contractor invoice | +| S7 | Services - E-reporting (VAT already collected) | +| M1 | Mixed - Deposit invoice | +| M2 | Mixed - Already paid invoice | +| M4 | Mixed - Final invoice (after down payment) | + \ No newline at end of file diff --git a/addons/gr-mydata-v1.mdx b/addons/gr-mydata-v1.mdx index 9c10ce9..9803f9c 100644 --- a/addons/gr-mydata-v1.mdx +++ b/addons/gr-mydata-v1.mdx @@ -15,7 +15,7 @@ generate the myDATA XML reporting files. ## Extensions ### VAT rate -Greece has three VAT rates: standard, reduced and super-reduced. Each of these rates are reduced by +Greece has three VAT rates: standard, reduced and super-reduced. Each of these rates are reduced by 30% on the islands of Leros, Lesbos, Kos, Samos and Chios. The tax authority identifies each rate with a specific VAT category. @@ -58,7 +58,7 @@ Please, note that GOBL will automatically set the proper `gr-mydata-vat-rate` co } ], } -``` +``` @@ -99,7 +99,7 @@ IAPR MyDATA invoice type code: | `11.3` | Simplified Invoice | `standard` | `simplified` | | `11.4` | Retail Sales Credit Note | `credit-note` | `simplified` | | `11.5` | Retail Sales Receipt on Behalf of Third Parties | `credit-note` | `goods`, `simplified`, `self-billed` | - + For example, this is how you set the IAPR invoice type explicitly: ```json @@ -242,7 +242,7 @@ Example usage: "cat": "VAT", "key": "exempt", "ext": { - "gr-mydata-exemption": "3" + "gr-mydata-exemption": "7" } } ], @@ -375,11 +375,99 @@ See the Income Classification Category for more information. | E3_598_001 | Sales of goods belonging to excise duty | | E3_598_003 | Sales on behalf of farmers through an agricultural cooperative e.t.c. | +### Tax type + +Greek invoices may contain charges or allowances for taxes and fees different from VAT. The +`gr-mydata-tax-type` extension at charge level must be used to specify the tax type. + +GOBL will attempt to automatically set the `gr-mydata-tax-type` extension. The following +table shows the mappings used: first, GOBL will check the charge's `key` field; if that +does not match, it will then check for the presence of the related extension: + +| Code | Name | GOBL Charge Key | Extension | +| ---- | ---------- | --------------- | ---------------------- | +| `2` | Fee | | `gr-mydata-fee` | +| `3` | Other Tax | `tax` | `gr-mydata-other-tax` | +| `4` | Stamp Duty | `stamp-duty` | `gr-mydata-stamp-duty` | + +For example (manual): + +```json +"charges": [ + { + "amount": "10.00", + "reason": "Stamp duty fee", + "ext": { + "gr-mydata-tax-type": "2", + "gr-mydata-fee": "13", + } + } +] +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Withholding Tax | +| 2 | Fee | +| 3 | Other Tax | +| 4 | Stamp Duty | +| 5 | Deduction | + +### Fee category + +Greek invoices may contain charges for different types of fees. In GOBL, you must use +the `gr-mydata-fee` extension at charge level to specify the specific fee category +for the charge. + +For example: + +```json +"charges": [ + { + "amount": "10.00", + "reason": "Subscription fee", + "ext": { + "gr-mydata-tax-type": "2", + "gr-mydata-fee": "13", + } + } +] +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Monthly account up to 50 euros 12% | +| 2 | Monthly account from 50.01 to 100 euros 15% | +| 3 | Monthly account from 100.01 to 150 euros 18% | +| 4 | Monthly account from 150.01 euros and above 20% | +| 5 | Mobile telephony fee based on call time value (12%) | +| 6 | Subscription television fee 10% | +| 7 | Fixed-line subscription fee 5% | +| 8 | Environmental fee & plastic bag v. 2339/2001 art. 6a 0.07 euros per item | +| 9 | Postal service contribution 2% | +| 10 | Other fees | +| 11 | Petroleum fees | +| 12 | Postal service contribution | +| 13 | Monthly account per connection (10%) | +| 14 | Mobile and mobile telephony fee based on call time value (10%) | +| 15 | Mobile and mobile telephony fee for natural persons aged 15 to 29 years (0%) | +| 16 | Environmental protection contribution for plastic products 0.04 cents per item [article 4 v. 4736/2020] | +| 17 | Recycling fee 0.08 cents per item [article 80 v. 4819/2021] | +| 18 | Accommodation fee | +| 19 | Fee on gross revenues of restaurants and related establishments | +| 20 | Fee on gross revenues of entertainment centers | +| 21 | Fee on gross revenues of casinos | +| 22 | Other fees on gross revenues | + ### Other taxes category -Certain myDATA invoice types (_e.g._, 8.2 for the accommodation tax) require a category -for other taxes to be provided. In GOBL, you can use the `gr-mydata-other-tax` extension -at charge level. +Greek invoices may contain charges for different taxes other than VAT. The +`gr-mydata-other-tax` extension at charge level must be used to specify the specific +other tax category for the charge. For example: @@ -387,8 +475,9 @@ For example: "charges": [ { "amount": "3.00", - "reason": "Accommodation tax", + "reason": "Climate Crisis Fee", "ext": { + "gr-mydata-tax-type": "3", "gr-mydata-other-tax": "8", } } @@ -399,23 +488,64 @@ For example: | Code | Name | | ---- | ---- | -| 1 | a1) 20% fire insurance premiums | -| 2 | a2) 20% fire insurance premiums | -| 3 | b) 4% life insurance premiums | -| 4 | c) 15% other insurance premiums | -| 5 | d) 0% tax-exempt insurance premiums | -| 6 | Hotels 1-2 stars 0,50 € | -| 7 | Hotels 3 stars 1,50 € | -| 8 | Hotels 4 stars 3,00 € | -| 9 | Hotels 5 stars 4,00 € | -| 10 | Rental rooms - Furnished rooms - Apartments 0,50 € | -| 11 | Special 5% tax on tv-broadcast commercials (EFTD) | -| 12 | 10% luxury tax on the taxable value of intra-community acquired goods and those imported from third countries | -| 13 | 10% luxury tax on the selling price before VAT for domestically produced goods | -| 14 | 80% Public fees on the admission ticket price for casinos | -| 15 | Fire industry insurance premiums 20% | -| 16 | Customs duties- Taxes | +| 1 | a1) fire insurance premiums 20% | +| 2 | a2) fire insurance premiums 20% | +| 3 | b) life insurance premiums 4% | +| 4 | c) insurance premiums for other branches 15% | +| 5 | d) tax-exempt insurance premiums 0% | +| 6 | Hotels 1-2 stars 0.50 € | +| 7 | Hotels 3 stars 1.50 € | +| 8 | Hotels 4 stars 3.00 € | +| 9 | Hotels 4 stars 4.00 € | +| 10 | Rented - furnished rooms - apartments 0.50 € | +| 11 | Special tax on advertisements broadcast on television (EFTD) 5% | +| 12 | 3.1 Luxury tax 10% on the taxable value for intra-Community acquisitions and imported from third countries 10% | +| 13 | 3.2 Luxury tax 10% on the selling price before VAT for domestically produced goods 10% | +| 14 | State rights on casino tickets (80% on the ticket) | +| 15 | Fire insurance premiums 20% | +| 16 | Other Customs Duties-Taxes | | 17 | Other Taxes | -| 18 | Charges of other Taxes | -| 19 | Special consumption tax | +| 18 | Charges of Other Taxes | +| 19 | EFK | +| 20 | Hotels 1-2 stars 1.50€ (per Room/Night) | +| 21 | Hotels 3 stars 3.00€ (per Room/Night) | +| 22 | Hotels 4 stars 7.00€ (per Room/Night) | +| 23 | Hotels 5 stars 10.00€ (per Room/Night) | +| 24 | Rented furnished rooms – apartments 1.50€ (per Room/Night) | +| 25 | Short-term rental properties 1.50€ | +| 26 | Short-term rental properties detached houses over 80 sq.m. 10.00€ | +| 27 | Self-catering accommodation – tourist furnished villas (villas) 10.00€ | +| 28 | Short-term rental properties 0.50€ | +| 29 | Short-term rental properties detached houses over 80 sq.m. 4.00€ | +| 30 | Self-catering accommodation – tourist furnished villas (villas) 4.00€ | + +### Stamp duty coefficient category + +Greek invoices may contain charges for stamp duty. The `gr-mydata-stamp-duty` extension +at charge level must be used to specify the specific stamp duty coefficient category +for the charge. + +For example: + +```json +"charges": [ + { + "amount": "12.00", + "reason": "Stamp duty", + "ext": { + "gr-mydata-tax-type": "4", + "gr-mydata-stamp-duty": "1" + } + } +] +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Coefficient 1.2% | +| 2 | Coefficient 2.4% | +| 3 | Coefficient 3.6% | +| 4 | Other cases | \ No newline at end of file diff --git a/addons/pl-favat-v3.mdx b/addons/pl-favat-v3.mdx new file mode 100644 index 0000000..5b9136d --- /dev/null +++ b/addons/pl-favat-v3.mdx @@ -0,0 +1,674 @@ +--- +title: Polish KSeF FA_VAT FA(3) +--- + +Key: pl-favat-v3 + +## Correction Definitions + +Auto-generation of corrective invoices or credit and debit notes is +supported. + +### Invoice Types + +The types of invoices that can be created with a preceding definition: +- credit-note + +### Stamp Keys + +Stamp keys from the previous invoice that need to be referenced: +- favat-ksef-number + +## Extensions +### Tax categories for KSeF + +The `pl-favat-tax-category` extension specifies tax categories for Polish FA_VAT/KSeF invoices. +Each category corresponds to a field in the FA_VAT XML schema (P_13_*, P_14_*, etc.). + +This extension is used at the **line tax level** (`lines[].taxes[]`) and is automatically +normalized by GOBL based on the tax combo `key` and `rate` fields. The extension is required +for all line items. + +Automatic mapping from GOBL tax combos: + +| GOBL Tax Key | GOBL Rate | FA_VAT Category | VAT % | +| --------------------- | ---------------- | --------------- | ----- | +| `standard` | `general` | 1 | 23% | +| `standard` | `reduced` | 2 | 8% | +| `standard` | `super-reduced` | 3 | 5% | +| `zero` | - | 6.1 | 0% | +| `intra-community` | - | 6.2 | 0% | +| `export` | - | 6.3 | 0% | +| `exempt` | - | 7 | - | +| `outside-scope` | - | 8 | - | +| `reverse-charge` | - | 9 | - | + +Example: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + // ... + "lines": [ + { + // ... + "taxes": [ + { + "cat": "VAT", + "key": "standard", + "rate": "general", + "percent": "23.0%", + // Extension automatically set to "1" + "ext": { + "pl-favat-tax-category": "1" + } + } + ] + } + ] +} +``` + +The ones that are not automatically mapped can be set manually. + + + +| Code | Name | +| ---- | ---- | +| 1 | Base rate | +| 2 | First reduced rate | +| 3 | Second reduced rate | +| 4 | Taxi Rate | +| 5 | OSS (one stop shop) | +| 6.1 | 0% VAT | +| 6.2 | 0% VAT for intra-community supply of goods | +| 6.3 | 0% VAT for export | +| 7 | Exempt | +| 8 | Foreign sales outside scope of Polish VAT | +| 9 | EU Reverse Charge | +| 10 | Domestic Reverse charge | +| 11 | Margin scheme | + +### Invoice type code for KSeF + +The `pl-favat-invoice-type` extension specifies the type of invoice for Polish FA_VAT/KSeF. +This extension is used in the **invoice tax section** (`tax.ext`) and is automatically +normalized by GOBL based on the invoice type and tags during the `scenarios` normalization step. + +Automatic mapping from GOBL invoice structure: + +| Tags | GOBL invoice type | Code | Description | +|--------------|-------------------|---------|----------------------| +| - | `standard` | VAT | Regular invoice | +| `partial` | `standard` | ZAL | Advance invoice | +| `settlement` | `standard` | ROZ | Settlement invoice | +| `simplified` | `standard` | UPR | Simplified invoice | +| - | `credit-note` | KOR | Credit note | +| `partial` | `credit-note` | KOR_ZAL | Advance credit note | +| `settlement` | `credit-note` | KOR_ROZ | Settlement credit note | + +Example of an advance invoice: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + "$addons": ["pl-favat-v3"], + "$tags": ["partial"], + "type": "standard", + // ... + "tax": { + // Extension automatically set to "ZAL" + "ext": { + "pl-favat-invoice-type": "ZAL" + } + } +} +``` + + + +| Code | Name | +| ---- | ---- | +| VAT | Regular Invoice | +| ZAL | Advance Invoice | +| ROZ | Settlement Invoice | +| UPR | Simplified Invoice | +| KOR | Credit note | +| KOR_ZAL | advance credit note | +| KOR_ROZ | Settlement credit note | + +### Cash accounting flag for KSeF + +The `pl-favat-cash-accounting` extension indicates whether an invoice uses cash accounting +for VAT purposes (kasowa metoda rozliczenia VAT). This extension is used in the **invoice +tax section** (`tax.ext`). + +This extension is **not normalized automatically** and must be set manually by the user +when the cash accounting method applies. According to Polish VAT law (Article 19a sec. 5 +item 1 or Article 21 sec. 1), certain small businesses may account for VAT on a cash +basis rather than accrual basis. + +Values: +- "1": Cash accounting applies +- "2": Normal accounting (accrual basis) - default + +Example with cash accounting: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + "$addons": ["pl-favat-v3"], + // ... + "tax": { + "ext": { + "pl-favat-cash-accounting": "1" + } + } +} +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Cash accounting | +| 2 | No cash accounting | + +### Self-invoicing flag for KSeF + +The `pl-favat-self-billing` extension indicates whether an invoice is self-billed +(samofakturowanie), where the buyer issues the invoice on behalf of the supplier. +This extension is used in the **invoice tax section** (`tax.ext`). + +This extension is **automatically normalized** by GOBL: +- When the invoice has the `self-billed` tag, the value is set to "1" +- Otherwise, the value defaults to "2" + +Self-billing is permitted under Article 106d sec. 1 of the Polish VAT Act when +there is a prior agreement between the parties. + +Values: +- "1": Self-billed invoice +- "2": Regular invoice - default + +Example of a self-billed invoice: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + "$addons": ["pl-favat-v3"], + "$tags": ["self-billed"], + // ... + "tax": { + // Extension automatically set to "1" + "ext": { + "pl-favat-self-billing": "1" + } + } +} +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Self-invoicing | +| 2 | Not self-invoicing | + +### Reverse charge code for KSeF + +The `pl-favat-reverse-charge` extension indicates whether the reverse charge mechanism +applies to an invoice. This extension is used in the **invoice tax section** (`tax.ext`). + +This extension is **automatically normalized** by GOBL: +- When the invoice has the `reverse-charge` tag, the value is set to "1" +- Otherwise, the value defaults to "2" + +Under the reverse charge mechanism (odwrotne obciążenie), the buyer rather than the +seller is responsible for accounting for the VAT. This applies to: +- EU intra-community services (B2B cross-border services) +- Domestic reverse charge for specific goods and services listed in Polish VAT law +- Imports of services from outside the EU + +When using reverse charge, the line items should use the `reverse-charge` tax key, +which automatically sets the tax category to "9" (EU Reverse Charge) or "10" +(Domestic Reverse Charge) depending on the scenario. + +Values: +- "1": Reverse charge applies +- "2": Normal charge - default + +Example of an EU reverse charge invoice: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + "$addons": ["pl-favat-v3"], + "$tags": ["reverse-charge"], + // ... + "lines": [ + { + // ... + "taxes": [ + { + "cat": "VAT", + "key": "reverse-charge" + } + ] + } + ], + "tax": { + // Extension automatically set to "1" + "ext": { + "pl-favat-reverse-charge": "1" + } + } +} +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Reverse charge | +| 2 | No reverse charge | + +### Split payment mechanism flag for KSeF + +The `pl-favat-split-payment-mechanism` extension indicates whether the mandatory split +payment mechanism (mechanizm podzielonej płatności, MPP) applies to an invoice. +This extension is used in the **invoice tax section** (`tax.ext`). + +This extension is **not normalized automatically** and must be set manually when the +split payment mechanism applies. + +According to Polish VAT law, split payment is mandatory when ALL of the following +conditions are met: +- The invoice amount exceeds PLN 15,000 (or equivalent in foreign currency) +- The invoice covers goods or services listed in Annex 15 to the VAT Act +- The transaction is B2B (business to business) +- The invoice bears the note "split payment mechanism" + +Under split payment, the buyer pays the VAT portion to a separate VAT account rather +than to the seller directly. + +Values: +- "1": Split payment mechanism applies +- "2": Normal payment - default + +Example: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + "$addons": ["pl-favat-v3"], + // ... + "tax": { + "ext": { + "pl-favat-split-payment-mechanism": "1" + } + }, + "notes": [ + { + "key": "general", + "text": "Mechanizm podzielonej płatności" + } + ] +} +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Split payment mechanism | +| 2 | No split payment mechanism | + +### Tax exemption code for KSeF + +Extension used to indicate the type of reason for tax exemption code for KSeF. When the `exempt` tag +is used in the invoice, having `ext` map's `pl-favat-exemption` property is required. Also, it is +required to add descriptive text for the legal basis for exemption. To do this in GOBL, add a note +to the invoice with the exemption reason, in the following format: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + // ... + + "tax": { + "ext": { + "pl-favat-exemption": "A" + // ... + } + }, + "notes": [ + { + "key": "legal", + "code": "A", + "src": "pl-favat-exemption", + "text": "Art. 25a ust. 1 pkt 9 ustawy o VAT" + } + ] +} +``` + +In notes, code must match the code from the extension. + + + +| Code | Name | +| ---- | ---- | +| A | Law or act issued under the Polish law | +| B | Directive 2006/112/EC | +| C | Other legal basis | + +### Margin scheme code for KSeF + +The `pl-favat-margin-scheme` extension specifies the type of margin scheme (procedura +marży) applied to an invoice. This extension is used in the **invoice tax section** +(`tax.ext`). + +This extension is **not normalized automatically** and must be set manually when a +margin scheme applies. + +Under margin schemes, VAT is calculated only on the seller's margin (profit) rather +than on the full sale price. This applies to specific business sectors in Poland: +- Travel agencies (tour operators) +- Sales of second-hand goods +- Sales of works of art +- Sales of collector's items and antiques + +When using a margin scheme, the tax category should typically be set to "11" +(Margin scheme) in line items. + +Example for a travel agency: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + "$addons": ["pl-favat-v3"], + // ... + "tax": { + "ext": { + "pl-favat-margin-scheme": "2" + } + } +} +``` + + + +| Code | Name | +| ---- | ---- | +| 2 | Travel agency | +| 3.1 | Second-hand goods | +| 3.2 | Works of art | +| 3.3 | Antiques and collectibles | + +### Payment method code for KSeF + +The `pl-favat-payment-means` extension specifies the payment method used in an invoice. +This extension is used in **payment instructions** (`payment.instructions.ext`) or +**payment advances** (`payment.advances[].ext`). + +This extension is **automatically normalized** by GOBL based on the payment means key. +The following table shows the mapping: + +| Code | FA_VAT Name | GOBL Payment Means Key | +| ---- | --------------- | ------------------------- | +| 1 | Cash | `cash` | +| 2 | Card | `card` | +| 3 | Voucher | `other+voucher` | +| 4 | Cheque | `cheque` | +| 5 | Credit/Loan | `other+credit` | +| 6 | Credit Transfer | `credit-transfer` | +| 7 | Mobile | `online` | + +Example with bank transfer payment: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + "$addons": ["pl-favat-v3"], + // ... + "payment": { + "instructions": { + "key": "credit-transfer", + // Extension automatically set to "6" + "ext": { + "pl-favat-payment-means": "6" + }, + "credit_transfer": [ + { + "iban": "PL61109010140000071219812874", + "name": "Company Name" + } + ] + } + } +} +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Cash | +| 2 | Card | +| 3 | Coupon | +| 4 | Cheque | +| 5 | Loan | +| 6 | Wire Transfer | +| 7 | Mobile | + +### Subordinate Local Government Unit flag + +The `pl-favat-jst` extension indicates whether the customer is a Subordinate Local +Government Unit (Jednostka Samorządu Terytorialnego - JST). This extension is used +in the **customer party section** (`customer.ext`). + +This extension is **not normalized automatically** and must be set manually. + +When this extension is set to "1" (customer is JST), GOBL validates that the customer +has an identity with role "8" (Local Government Unit - recipient) in the `customer.identities` +array. This identity must include a `code` field with the JST identifier. + +Values: +- "1": Customer is a Subordinate Local Government Unit +- "2": Customer is not a JST - default + +Example: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + "$addons": ["pl-favat-v3"], + // ... + "customer": { + "name": "Gmina Warszawa", + "tax_id": { + "country": "PL", + "code": "5252548806" + }, + "ext": { + "pl-favat-jst": "1" + }, + "identities": [ + { + "code": "146501", + "ext": { + "pl-favat-third-party-role": "8" + } + } + ] + } +} +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Customer is a Subordinate Local Government Unit | +| 2 | Customer is not a Subordinate Local Government Unit | + +### Group VAT member flag + +The `pl-favat-group-vat` extension indicates whether the customer is a member of a VAT +group (Grupa VAT - GV). This extension is used in the **customer party section** +(`customer.ext`). + +This extension is **not normalized automatically** and must be set manually. + +VAT groups in Poland allow multiple legal entities to be treated as a single taxpayer +for VAT purposes. When this extension is set to "1" (customer is a GV member), GOBL +validates that the customer has an identity with role "10" (GV member - recipient) in +the `customer.identities` array. This identity must include a `code` field with the +VAT group member identifier. + +Values: +- "1": Customer is a VAT Group member +- "2": Customer is not a VAT Group member - default + +Example: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + "$addons": ["pl-favat-v3"], + // ... + "customer": { + "name": "Member Company Ltd.", + "tax_id": { + "country": "PL", + "code": "1234567890" + }, + "ext": { + "pl-favat-group-vat": "1" + }, + "identities": [ + { + "code": "GV-12345", + "ext": { + "pl-favat-third-party-role": "10" + } + } + ] + } +} +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Customer is a Group VAT member | +| 2 | Customer is not a Group VAT member | + +### Third party role + +The `pl-favat-third-party-role` extension specifies the role of a third party or +additional entity in an invoice transaction. This extension is used in **party +identities** (`customer.identities[].ext`, `supplier.identities[].ext`, or in +additional parties). + +This extension is **not normalized automatically** and must be set manually based on +the role of the entity in the transaction. + +Common use cases: +- Role "8": Required when customer has `pl-favat-jst` = "1" (Local Government Unit) +- Role "10": Required when customer has `pl-favat-group-vat` = "1" (VAT Group member) +- Role "5": When invoice is issued by an entity on behalf of the taxpayer +- Other roles: For factoring, recipients, payers, etc. + +Each identity with this extension should also include a `code` field with the +identifier of the third party. + +Example with JST customer: + +```js +{ + "customer": { + // ... + "ext": { + "pl-favat-jst": "1" + }, + "identities": [ + { + "code": "146501", + "ext": { + "pl-favat-third-party-role": "8" + } + } + ] + } +} +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Factor | +| 2 | Recipient | +| 3 | Original entity | +| 4 | Additional Purchaser | +| 5 | Invoice Issuer | +| 6 | Payer | +| 7 | Local Government Unit (LGU) - issuer | +| 8 | Local Government Unit (LGU) - recipient | +| 9 | GV member - issuer | +| 10 | GV member - recipient | +| 11 | Employee | + +### Effective date code + +The `pl-favat-effective-date` extension specifies when a correction invoice (credit note) +becomes effective for VAT purposes. This extension is used in **credit note tax section** +(`tax.ext`) when `type` is `credit-note`. + +This extension is **not normalized automatically** and it is not mandatory. It can be set manually for credit +notes based on when the correction should take effect. + +According to Polish VAT regulations, a correction invoice can be effective: +- On the date of the original invoice (code "1") +- On the date of the correction invoice itself (code "2") +- On another specific date, or different dates for different line items (code "3") + +Values: +- "1": Effective according to original invoice date +- "2": Effective according to correction date +- "3": Effective on another date (or multiple dates) + +Example of a credit note effective on correction date: + +```js +{ + "$schema": "https://gobl.org/draft-0/bill/invoice", + "$addons": ["pl-favat-v3"], + "type": "credit-note", + // ... + "tax": { + "ext": { + "pl-favat-invoice-type": "KOR", + "pl-favat-effective-date": "2" + } + }, + "preceding": [ + { + "code": "INVOICE-001", + "issue_date": "2025-01-15" + } + ] +} +``` + + + +| Code | Name | +| ---- | ---- | +| 1 | Original | +| 2 | Correction | +| 3 | Other | + \ No newline at end of file diff --git a/addons/pt-saft-v1.mdx b/addons/pt-saft-v1.mdx index b4b56a8..3b19251 100644 --- a/addons/pt-saft-v1.mdx +++ b/addons/pt-saft-v1.mdx @@ -204,6 +204,9 @@ the reason as follows: | M41 | Article 8 No. 3 of the RITI | | M42 | Decree-Law No. 21/2007 of 29th January | | M43 | Decree-Law No. 362/99 of 16th September | +| M44 | Article 6.º of the CIVA – Specific rules | +| M45 | Art 58º-A of the CIVA (IVA - cross-border exemption regime) | +| M46 | Decree-Law No. 19/2017, of February 14 | | M99 | Not subject to tax or not taxed | ### Product Type diff --git a/catalogues/untdid.mdx b/catalogues/untdid.mdx index 4c03b57..b058f56 100644 --- a/catalogues/untdid.mdx +++ b/catalogues/untdid.mdx @@ -50,6 +50,13 @@ Other tax regimes and addons may use their own subset of codes. | 394 | Lease invoice | | 395 | Consignment invoice | | 396 | Factored credit note | +| 471 | Request for payment with prepaid amount deducted | +| 472 | Self-billed request for payment with prepaid amount deducted | +| 473 | Standalone credit note | +| 500 | Self-billed prepayment invoice | +| 501 | Final invoice after prepayments | +| 502 | Self-billed corrected invoice | +| 503 | Self-billed credit note for claim | | 420 | Optical Character Reading (OCR) payment credit note | | 456 | Debit advice | | 457 | Reversal of debit | diff --git a/regimes/ae.mdx b/regimes/ae.mdx index 7a2ca98..f2ae56e 100644 --- a/regimes/ae.mdx +++ b/regimes/ae.mdx @@ -1,6 +1,19 @@ --- title: United Arab Emirates --- +The UAE tax system is administered by the Federal Tax Authority (FTA). +VAT was introduced on January 1, 2018, with standard, zero, and +exempt rate categories. + +Businesses must register for VAT if taxable supplies and imports +exceed AED 375,000 in a 12-month period, with voluntary registration +available above AED 187,500. Registered businesses receive a Tax +Registration Number (TRN) which must be included on all tax invoices. + +Simplified VAT invoices may be used when the recipient is not VAT +registered, or when the transaction value does not exceed AED 10,000 +for VAT-registered recipients. Credit notes are supported for +correcting invoices. ## Base Details diff --git a/regimes/ar.mdx b/regimes/ar.mdx index b4a47f4..7f3774c 100644 --- a/regimes/ar.mdx +++ b/regimes/ar.mdx @@ -1,19 +1,36 @@ --- title: Argentina --- -Argentina's tax system is administered by ARCA (Agencia de Recaudación y Control Aduanero), which oversees the collection of IVA (Impuesto al Valor Agregado), the country's value-added tax. - -Taxpayers are identified using three main types of tax identification numbers: CUIT (Clave Única de Identificación Tributaria) - 11 digits (XX-XXXXXXXX-X) used by companies and legal entities with prefixes 30, 33 (conflict resolution), and 34 (foreign entities); CUIL (Clave Única de Identificación Laboral) - 11 digits (XX-XXXXXXXX-X) used by individuals and employees with prefixes 20 (males), 27 (females), and 23 (conflict resolution); and CDI (Clave de Identificación) for foreign residents without CUIT/CUIL (not validated). - -IVA rates include 27% increased rate for gas, water and telecom services, 21% general rate for most goods and services, and 10.5% reduced rate for essential goods such as construction, medicine, transportation, and food products. - -Argentina applies several retention taxes: IVA Retenido (Retained VAT) with variable rates based on taxpayer category and registration status (reference: AFIP RG 2854/2010 and modifications); Ganancias (Income Tax Withholding) applied to payments for services with rates ranging from 0.5% to 35% depending on service type (reference: AFIP RG 830/2000, RG 4003/2017); and Ingresos Brutos (Gross Income Tax), a provincial tax with rates set by each jurisdiction, typically 1% to 5% depending on province and activity. - -Electronic invoicing through ARCA's system is required for most transactions. Electronic invoices must include CAE/CAI (Código de Autorización Electrónico - Electronic Authorization Code) and Point of Sale (Punto de Venta) for invoice numbering. - -Common invoice types include Tipo A (issued by Responsable Inscripto to another Responsable Inscripto), Tipo B (issued by Responsable Inscripto to Monotributista or final consumer), Tipo C (issued by Monotributista or exempt entities), Tipo E (export invoices), and Credit Notes (Notas de Crédito - corrective documents). - -Argentina has different tax regime classifications: Responsable Inscripto (registered taxpayer with full IVA obligations), Monotributo (simplified tax regime for small businesses), Exento (exempt from IVA), No Responsable (not responsible for IVA collection), and Consumidor Final (final consumer - no tax ID required). +Argentina's tax system is administered by ARCA (Agencia de Recaudación +y Control Aduanero), which oversees the collection of IVA (Impuesto al +Valor Agregado), the country's value-added tax. + +Taxpayers are identified using three main types of tax identification +numbers: CUIT (Clave Única de Identificación Tributaria), 11 digits +(XX-XXXXXXXX-X) used by companies and legal entities with prefixes 30, +33, and 34; CUIL (Clave Única de Identificación Laboral), 11 digits used +by individuals with prefixes 20, 27, and 23; and CDI (Clave de +Identificación) for foreign residents without CUIT/CUIL. + +IVA has increased, general, and reduced rates. Argentina also +applies several retention taxes: IVA Retenido (Retained VAT) with +variable rates based on taxpayer category; Ganancias (Income Tax +Withholding) applied to payments for services; and Ingresos Brutos +(Gross Income Tax), a provincial tax with rates set by each +jurisdiction. + +Electronic invoicing through ARCA is required for most transactions. +Invoices must include a CAE (Código de Autorización Electrónico) and +Point of Sale (Punto de Venta) number. + +Common invoice types include Tipo A (between Responsable Inscripto +parties), Tipo B (to Monotributista or final consumer), Tipo C (from +Monotributista or exempt entities), Tipo E (exports), and Credit Notes +(Notas de Crédito). + +Tax regime classifications include Responsable Inscripto (full IVA +obligations), Monotributo (simplified regime for small businesses), +Exento (exempt from IVA), and Consumidor Final (no tax ID required). ## Base Details diff --git a/regimes/at.mdx b/regimes/at.mdx index 9e7cb83..3ab9dc2 100644 --- a/regimes/at.mdx +++ b/regimes/at.mdx @@ -1,6 +1,15 @@ --- title: Austria --- +Austria's tax system is administered by the Federal Ministry of +Finance (Bundesministerium für Finanzen). As an EU member state, +Austria follows the EU VAT Directive with standard, reduced, and +intermediate rates. + +VAT (Umsatzsteuer, USt) applies to most goods and services. +Businesses are identified by their UID-Nummer (VAT identification +number) in the format ATU followed by 8 digits. Austria supports +credit notes for invoice corrections. ## Base Details diff --git a/regimes/be.mdx b/regimes/be.mdx index b486674..ea3c081 100644 --- a/regimes/be.mdx +++ b/regimes/be.mdx @@ -1,6 +1,19 @@ --- title: Belgium --- +Belgium's tax system is administered by the Federal Public Service Finance +(Service Public Fédéral Finances / Federale Overheidsdienst Financiën). +As an EU member state, Belgium follows the EU VAT Directive. + +VAT (Taxe sur la Valeur Ajoutée, TVA / Belasting over de Toegevoegde Waarde, +BTW) applies at standard, intermediate, and reduced rates. The intermediate +rate covers certain goods including social housing, restaurant services, and +some food products, while the reduced rate applies to basic necessities such +as food, water, pharmaceuticals, books, and passenger transport. + +Businesses are identified by their VAT number (Numéro de TVA / BTW-nummer) +in the format BE followed by 10 digits. Belgium supports credit notes for +invoice corrections. ## Base Details diff --git a/regimes/br.mdx b/regimes/br.mdx index 19dd7df..9729b9d 100644 --- a/regimes/br.mdx +++ b/regimes/br.mdx @@ -1,7 +1,25 @@ --- title: Brazil --- -Tax identification in Brazil is provided either through a CNPJ for businesses or a CPF for individuals. Both types are valid for the issuance of NFS-e (electronic service invoices). +Brazil uses Notas Fiscais Eletrônicas (electronic fiscal notes) such as NFSe, +NFe, and NFCe for reporting tax information to municipal, state, and federal +authorities. The tax system is administered by the Receita Federal (Federal +Revenue Service). + +Tax identification is provided through a CNPJ (Cadastro Nacional da Pessoa +Jurídica) for businesses, consisting of 14 digits, or a CPF (Cadastro de Pessoas +Físicas) for individuals, consisting of 11 digits. Both types are valid for the +issuance of NFS-e (electronic service invoices). + +Brazilian addresses have three subdivisions relevant for tax purposes: bairro +(neighbourhood), município (municipality), and estado (state). Municipality codes +follow the IBGE coding system. + +Service notes (NFSe) let service providers document and report taxes such as +ISS (Imposto Sobre Serviços) related to the services they provide. Municipal +governments regulate them. Special tax regimes include Simples Nacional for +simplified taxation of micro and small enterprises, and MEI (Micro-Empreendedor +Individual) for individual micro-entrepreneurs. ## Base Details @@ -25,6 +43,8 @@ Tax identification in Brazil is provided either through a CNPJ for businesses or | CSLL | CSLL | Social Contribution on Net Profit | | INSS | INSS | National Social Security Institute Withholding | | IRRF | IRRF | Income Tax Withheld at Source | +| IBS | IBS | Goods and Services Tax | +| CBS | CBS | Federal Goods and Services Contribution | ## Correction Definitions diff --git a/regimes/ca.mdx b/regimes/ca.mdx index 16c6b54..89331ea 100644 --- a/regimes/ca.mdx +++ b/regimes/ca.mdx @@ -1,6 +1,22 @@ --- title: Canada --- +Canada's tax system is administered by the Canada Revenue Agency +(CRA). The country uses a multi-layered sales tax system consisting +of the federal Goods and Services Tax (GST) and various provincial +taxes. + +The Harmonized Sales Tax (HST) combines GST and provincial sales +tax in participating provinces. Non-participating provinces levy a +separate Provincial Sales Tax (PST) at varying rates. Zero-rated +supplies include basic groceries, agricultural products, and +exports. Exempt supplies include certain financial services, +educational services, and healthcare services. + +Businesses with annual taxable revenues exceeding CAD 30,000 must +register for GST/HST. Tax identification is through the Business +Number (BN) assigned by the CRA. Canada supports both credit notes +and debit notes for invoice corrections. ## Base Details diff --git a/regimes/ch.mdx b/regimes/ch.mdx index 9b0787a..118687f 100644 --- a/regimes/ch.mdx +++ b/regimes/ch.mdx @@ -1,6 +1,21 @@ --- title: Switzerland --- +Switzerland's tax system is administered by the Federal Tax Administration +(Eidgenössische Steuerverwaltung, ESTV). Although not an EU member, Switzerland +operates its own VAT system (Mehrwertsteuer, MWST). + +VAT applies at standard, reduced, and special rates. The reduced rate covers +everyday goods such as food, non-alcoholic beverages, books, newspapers, and +medicines, while a special rate applies to accommodation services. + +Businesses with annual taxable revenues exceeding CHF 100,000 must register +for VAT. Tax identification uses the UID (Unternehmens-Identifikationsnummer) +in the format CHE-XXX.XXX.XXX followed by "MWST" for VAT purposes. + +Switzerland supports credit notes for invoice corrections. E-invoicing is not +mandatory but is increasingly used, particularly in business-to-government (B2G) +transactions. ## Base Details diff --git a/regimes/co.mdx b/regimes/co.mdx index d038a01..9f606ef 100644 --- a/regimes/co.mdx +++ b/regimes/co.mdx @@ -1,6 +1,26 @@ --- title: Colombia --- +Colombia's tax system is administered by the DIAN (Dirección de Impuestos y +Aduanas Nacionales). Electronic invoicing is mandatory for most businesses +through the DIAN's e-invoicing platform. + +Businesses are identified by their NIT (Número de Identificación Tributaria), +which includes a check digit. For B2C transactions (using the simplified tag), +customers may be identified using various document types including Registro +civil, Tarjeta de identidad, Cédula de ciudadanía, Tarjeta de extranjería, +Cédula de extranjería, Pasaporte, PEP, or NUIP. If no customer identity is +provided for simplified invoices, the reserved final consumer code is used +automatically. + +IVA (Impuesto sobre el Valor Agregado) applies at general, reduced, and zero +rates. Some goods and services are excluded or exempt from IVA. + +Invoice series must be pre-registered with the DIAN. Municipality codes are +required for addresses. Both credit notes and debit notes are supported for +invoice corrections, each requiring a specific correction cause code from the +DIAN (e.g. partial refund, revoked, discount, adjustment for credit notes; +interest, pending charges, change in value for debit notes). ## Base Details diff --git a/regimes/de.mdx b/regimes/de.mdx index 92e9c1a..a567141 100644 --- a/regimes/de.mdx +++ b/regimes/de.mdx @@ -1,6 +1,20 @@ --- title: Germany --- +Germany's tax system is administered by the Federal Central Tax Office +(Bundeszentralamt für Steuern, BZSt). As an EU member state, Germany follows +the EU VAT Directive with locally adapted rates. + +VAT (Umsatzsteuer, USt) applies at standard and reduced rates. The reduced +rate covers food, books, newspapers, public transport, and cultural events. + +Businesses are identified by their Umsatzsteuer-Identifikationsnummer (USt-IdNr) +in the format DE followed by 9 digits for cross-border transactions, and by +their Steuernummer (tax number) in regional formats for domestic purposes. + +Germany supports credit notes for invoice corrections. E-invoicing is +progressively becoming mandatory, with XRechnung as the standard for B2G +transactions and ZUGFeRD/Factur-X widely used for B2B. ## Base Details diff --git a/regimes/dk.mdx b/regimes/dk.mdx new file mode 100644 index 0000000..310b77a --- /dev/null +++ b/regimes/dk.mdx @@ -0,0 +1,46 @@ +--- +title: Denmark +--- +Denmark's tax system is administered by the Danish Tax Agency (Skattestyrelsen). +As an EU member state, Denmark follows the EU VAT Directive. + +VAT (Moms, short for Merværdiafgift) applies at a single standard rate on +most goods and services. Unlike many other EU countries, Denmark does not +have reduced VAT rates, making it one of the simplest VAT systems in Europe. +Certain supplies are zero-rated (e.g. exports, newspapers) or exempt (e.g. +healthcare, education, financial services). + +Businesses are identified by their CVR number (Det Centrale Virksomhedsregister), +an 8-digit number. The Danish VAT number uses the format DK followed by the +8-digit CVR number. E-invoicing via the NemHandel/PEPPOL network is mandatory +for all B2G transactions. + +## Base Details + +| Key | Value | +| --- | ----- | +| Tax Country Code | DK | +| Currency | DKK | +| Base Time Zone | Europe/Copenhagen | + +## Tax Categories + +| Code | Name | Title | +| ---- | ---- | ----- | +| VAT | VAT | Value Added Tax | + +### VAT Rates + +| Rate | Keys | Name | Percents | Description | +| ---- | ---- | ---- | -------- | ----------- | +| general | standard | General Rate | 25.0% | | + +## Correction Definitions + +Auto-generation of corrective invoices or credit and debit notes is +supported. + +### Invoice Types + +The types of invoices that can be created with a preceding definition: +- credit-note \ No newline at end of file diff --git a/regimes/el.mdx b/regimes/el.mdx index b7e28e7..0039d7d 100644 --- a/regimes/el.mdx +++ b/regimes/el.mdx @@ -1,6 +1,23 @@ --- title: Greece --- +Greece's tax system is administered by the Independent Authority for Public +Revenue (IAPR / AADE). As an EU member state, Greece follows the EU VAT +Directive with locally adapted rates. + +FPA (Fóros Prostithémenis Axías) applies at standard, reduced, and +super-reduced rates. The islands of Leros, Lesbos, Kos, Samos, and Chios +benefit from a reduction on all standard rates. + +Businesses are identified by their AFM (Arithmós Forologikoú Mitróou), a +9-digit tax identification number. The Greek VAT number uses the format EL +followed by the 9-digit AFM. + +Greece uses the myDATA platform for tax reporting, where invoices must be +classified with specific invoice type codes, VAT category codes, income +classifications, and exemption codes. Payment method codes must also be +reported. PEPPOL BIS Billing 3.0 is used for B2G e-invoicing. Credit notes +are supported for invoice corrections. ## Base Details diff --git a/regimes/es.mdx b/regimes/es.mdx index f65b8b9..eda9631 100644 --- a/regimes/es.mdx +++ b/regimes/es.mdx @@ -1,6 +1,26 @@ --- title: Spain --- +Spain's tax system is administered by the Agencia Tributaria (AEAT). As an +EU member state, Spain follows the EU VAT Directive with locally adapted rates. + +IVA (Impuesto sobre el Valor Añadido) applies at general, reduced, and +super-reduced rates. The Canary Islands use IGIC (Impuesto General Indirecto +Canario) instead of IVA, while Ceuta and Melilla use IPSI (Impuesto sobre la +Producción, los Servicios y la Importación). + +Businesses are identified by their NIF (Número de Identificación Fiscal) or +CIF for companies. IRPF (Impuesto sobre la Renta de las Personas Físicas) +retention taxes apply to freelancer invoices at varying rates. + +According to Real Decreto 1619/2012, only rectified (rectificativa) invoices +are recognized in Spanish law. GOBL maps corrective invoices to "rectificación +modelo íntegro" (complete replacement) and credit notes to "rectificación por +diferencias" (correction by differences, with quantities inverted during +conversion). The FacturaE format is used for B2G e-invoicing, with TicketBAI +required in the Basque Country, VeriFactu being rolled out nationally, and the +SII (Suministro Inmediato de Información) system providing near-real-time +reporting of invoicing data to the AEAT. ## Base Details diff --git a/regimes/fr.mdx b/regimes/fr.mdx index ef36cda..c5e42dd 100644 --- a/regimes/fr.mdx +++ b/regimes/fr.mdx @@ -1,7 +1,24 @@ --- title: France --- -The French tax regime covers the basics. +France's tax system is administered by the Direction Générale des Finances +Publiques (DGFiP). As an EU member state, France follows the EU VAT Directive +with locally adapted rates. + +TVA (Taxe sur la Valeur Ajoutée) applies at standard, intermediate, reduced, +and super-reduced rates covering various categories of goods and services. + +Businesses are identified by three closely related numbers: the VAT code +(numéro de TVA intracommunautaire), an 11-digit number starting with a +2-digit checksum followed by the 9-digit SIREN; the SIREN itself, a 9-digit +company identifier from the national register (Répertoire SIRENE); and the +SIRET, which extends the SIREN with a 5-digit establishment number to form +a 14-digit code. + +France supports both corrective invoices and credit notes for invoice +corrections. E-invoicing via the Chorus Pro platform is mandatory for B2G +transactions, with B2B e-invoicing being progressively mandated through the +CTC (Continuous Transaction Controls) framework. ## Base Details diff --git a/regimes/gb.mdx b/regimes/gb.mdx index c94d16a..ca2e74b 100644 --- a/regimes/gb.mdx +++ b/regimes/gb.mdx @@ -1,6 +1,21 @@ --- title: United Kingdom --- +The United Kingdom's tax system is administered by His Majesty's Revenue and +Customs (HMRC). Following Brexit, the UK operates its own VAT system +independently of the EU VAT Directive. + +VAT applies at standard, reduced, and zero rates. Zero-rated supplies include +food, children's clothing, books, and newspapers. Some supplies are exempt +from VAT, including financial services, education, and healthcare. +Companies are identified by their VAT Registration Number (VRN) in the format +GB followed by 9 digits, and optionally by their Company Registration Number +(CRN) from Companies House. + +Northern Ireland (country code XI) has special arrangements for goods under +the Windsor Framework, remaining aligned with EU VAT rules for goods while +following UK rules for services. Credit notes are supported for invoice +corrections. ## Base Details diff --git a/regimes/ie.mdx b/regimes/ie.mdx index 5570342..e92adb0 100644 --- a/regimes/ie.mdx +++ b/regimes/ie.mdx @@ -1,6 +1,19 @@ --- title: Ireland --- +Ireland's tax system is administered by the Revenue Commissioners (Na +Coimisinéirí Ioncaim). As an EU member state, Ireland follows the EU VAT +Directive with locally adapted rates. + +VAT applies at standard, reduced, second reduced, livestock, and zero rates. +Zero-rated supplies include food, children's clothing, oral medicines, and +exports. + +Businesses are identified by their VAT registration number in the format IE +followed by 7 digits and 1-2 letters. + +Ireland supports credit notes for invoice corrections. E-invoicing via +PEPPOL is supported for B2G transactions. ## Base Details diff --git a/regimes/in.mdx b/regimes/in.mdx index f93c824..1e9168d 100644 --- a/regimes/in.mdx +++ b/regimes/in.mdx @@ -1,6 +1,26 @@ --- title: India --- +India follows a dual GST (Goods and Services Tax) model, where both the Central +and State Governments levy taxes. CGST (Central GST) is levied by the Central +Government, SGST/UTGST (State/Union Territory GST) by state governments, and +IGST (Integrated GST) on interstate supplies and imports. + +For intrastate supplies, CGST and SGST/UTGST apply in equal proportions. For +interstate supplies and imports, IGST applies at a rate equivalent to CGST plus +SGST. A Compensation Cess may apply on luxury and sin goods. Due to the dual +model, tax rate allocations between central and state must be managed at the +application level. + +GST rates vary by goods and services across multiple rate slabs. Exports and +supplies to Special Economic Zones are zero-rated. Exempt supplies include +fresh fruits and vegetables, educational services, and public road tolls. + +Businesses are identified by their GSTIN (Goods and Services Tax Identification +Number), a unique 15-digit identifier with format and checksum validation. +Items on invoices must include HSN (Harmonized System of Nomenclature) codes +for goods classification. India supports both credit notes and debit notes for +invoice corrections. ## Base Details diff --git a/regimes/it.mdx b/regimes/it.mdx index 5df9ac9..4d9d697 100644 --- a/regimes/it.mdx +++ b/regimes/it.mdx @@ -1,6 +1,26 @@ --- title: Italy --- +Italy's tax system is administered by the Agenzia delle Entrate (Revenue +Agency). All invoices must comply with the FatturaPA electronic format, +transmitted through the Sistema di Interscambio (SDI). + +IVA (Imposta sul Valore Aggiunto) applies at standard, reduced, intermediate, +and minimum rates covering various categories of goods and services. + +Businesses are identified by their Partita IVA (VAT number), an 11-digit code, +and by the Codice Fiscale (fiscal code) for individuals and entities. The +FatturaPA format requires a Codice Destinatario (recipient code) or PEC +(certified email) for invoice routing. Every supplier must declare a fiscal +regime (Regime Fiscale, e.g. RF01 Ordinary, RF19 Flat rate) in their invoices. + +The FatturaPA format supports an extensive set of document types (TD01-TD28) +covering standard invoices, self-billed invoices, and various special cases. +Line items may require Nature (Natura) codes to explain VAT exemptions or +reverse charge situations. Stamp duty (Imposta di bollo) applies to certain +exempt invoices. Withholding taxes (IRPEF, IRES, INPS, ENASARCO, ENPAM) can +be applied alongside VAT. Both credit notes and debit notes are supported for +corrections. ## Base Details diff --git a/regimes/mx.mdx b/regimes/mx.mdx index 191639e..0e18187 100644 --- a/regimes/mx.mdx +++ b/regimes/mx.mdx @@ -1,6 +1,27 @@ --- title: Mexico --- +Mexico's tax system is administered by the SAT (Servicio de Administración +Tributaria). Electronic invoicing through CFDI (Comprobante Fiscal Digital por +Internet) version 4.0 is mandatory for all businesses. + +IVA (Impuesto al Valor Agregado) applies at general, zero, and exempt rates. +Zero-rated supplies include food, medicine, and exports, while educational +and medical services are exempt. + +Businesses are identified by their RFC (Registro Federal de Contribuyentes), +a 12-character code for companies or 13-character code for individuals, which +includes a date component and check digits. Every supplier and customer must +be associated with a fiscal regime code (RegimenFiscal). + +CFDI invoices require specific fields including issue place (LugarExpedicion), +CFDI use (UsoCFDI), payment method (MetodoPago distinguishing between fully +paid PUE and pending PPD invoices), payment means (FormaPago), and +product/service codes (ClaveProdServ) from the SAT catalog. For B2C sales, +the simplified tag triggers use of the generic RFC code for final consumers. +For foreign customers, their country and local tax code are mapped +automatically. Invoices can include complements for fuel account balances and +food vouchers among others. ## Base Details diff --git a/regimes/nl.mdx b/regimes/nl.mdx index f1c04d6..d01d74e 100644 --- a/regimes/nl.mdx +++ b/regimes/nl.mdx @@ -1,6 +1,22 @@ --- title: The Netherlands --- +The Netherlands' tax system is administered by the Belastingdienst (Tax and +Customs Administration). As an EU member state, the Netherlands follows the +EU VAT Directive with locally adapted rates. + +BTW (Belasting over de Toegevoegde Waarde) applies at standard and reduced +rates. The reduced rate covers food, water, pharmaceuticals, books, passenger +transport, hotel accommodation, and cultural and sporting events. + +Businesses are identified by their BTW-nummer (VAT number) in the format NL +followed by 9 digits, the letter B, and 2 check digits (e.g. +NL123456789B01). The KVK (Kamer van Koophandel) number is the commercial +register number. + +The Netherlands supports credit notes for invoice corrections. E-invoicing +via PEPPOL is commonly used, and is mandatory for B2G transactions with the +central government. ## Base Details diff --git a/regimes/pl.mdx b/regimes/pl.mdx index f3f45b2..41e4370 100644 --- a/regimes/pl.mdx +++ b/regimes/pl.mdx @@ -1,6 +1,21 @@ --- title: Poland --- +Poland's tax system is administered by the Krajowa Administracja Skarbowa +(National Revenue Administration, KAS). As an EU member state, Poland follows +the EU VAT Directive with locally adapted rates. + +VAT (Podatek od towarów i usług, PTU) applies at standard, reduced, and +super-reduced rates. Zero-rated supplies include exports and intra-community +supplies. + +Businesses are identified by their NIP (Numer Identyfikacji Podatkowej), a +10-digit tax identification number. The Polish VAT number uses the format PL +followed by the 10-digit NIP. + +Poland has implemented the KSeF (Krajowy System e-Faktur) national e-invoicing +system, which is progressively becoming mandatory for B2B transactions. +E-invoicing via PEPPOL is used for cross-border and B2G transactions. ## Base Details diff --git a/regimes/pt.mdx b/regimes/pt.mdx index 95622bf..fe16421 100644 --- a/regimes/pt.mdx +++ b/regimes/pt.mdx @@ -1,6 +1,23 @@ --- title: Portugal --- +Portugal's tax system is administered by the Autoridade Tributária e Aduaneira +(AT). As an EU member state, Portugal follows the EU VAT Directive with +locally adapted rates that vary by region. + +IVA (Imposto sobre o Valor Acrescentado) applies at standard, intermediate, +and reduced rates on the mainland. The autonomous regions of Açores and +Madeira apply their own reduced rates. + +Businesses are identified by their NIF (Número de Identificação Fiscal), a +9-digit number. The Portuguese VAT number uses the format PT followed by the +NIF. + +Portugal requires all invoicing software to be certified by the AT and +invoices must include a unique document identifier (ATCUD) and a hash chain +linking sequential documents. The SAF-T (Standard Audit File for Tax Purposes) +format is used for tax reporting. Both credit notes and debit notes are +supported for invoice corrections. ## Base Details diff --git a/regimes/se.mdx b/regimes/se.mdx index 21cce7c..dd0dcb6 100644 --- a/regimes/se.mdx +++ b/regimes/se.mdx @@ -1,6 +1,27 @@ --- title: Sweden --- +Sweden's tax system is administered by the Swedish Tax Agency +(Skatteverket). As an EU member state, Sweden follows the EU VAT Directive +with locally adapted rates. + +Moms (Mervärdesskatt) applies at standard, reduced, and heavily reduced +rates. Exports and certain financial and healthcare services are exempt. + +Businesses are identified by their Organisationsnummer (organization number), +a 10-digit number validated with the Luhn algorithm. The Swedish VAT number +uses the format SE followed by the 10-digit organization number plus "01" as +check digits. Individuals may be identified by their Personnummer (personal +identity number, format YYMMDD-XXXX) or Samordningsnummer (coordination +number for non-residents, where the day component is offset by 60). Sole +proprietorships use the owner's personal number as their organization number. + +E-invoicing via PEPPOL BIS Billing 3.0 is mandatory for all B2G transactions +since April 2019. F-tax (F-skatt) registration indicates that a business +handles its own tax payments, exempting customers from withholding obligations. +Reverse charge applies in specific sectors (construction, metals, waste) and +for cross-border transactions within the EU. Simplified invoices may be used +for transactions up to 4000 SEK. ## Base Details diff --git a/regimes/sg.mdx b/regimes/sg.mdx index e7ef387..6bc5923 100644 --- a/regimes/sg.mdx +++ b/regimes/sg.mdx @@ -1,21 +1,22 @@ --- title: Singapore --- -Singapore offers a simple GST model with a standard rate along with a few exceptions. GST is handled by the Inland Revenue Authority of Singapore ([IRAS](https://www.iras.gov.sg/taxes/goods-services-tax-(gst))) - -For GST to be chargeable on a supply of goods and services, the following four conditions must be satisfied: - -1. The supply must be made in Singapore -2. The supply is a taxable supply -3. The supply is made by a taxable person -4. The supply is made in the course of furtherance of any business carried on by the taxable person, i.e, GST is not chargeable on personal transactions - -GST is chargeable on all imported goods (whether for domestic consumption, sale, or re-export), regardless of whether the importer is GST-registered or not. The importer is required to take up the appropriate import permit and pay GST upon importation of the goods into Singapore. Import GST is not chargeable under the following circumstances: - -1. Importation of investment precious metals. -2. Importation of goods that are specifically given GST reliefs5 under the GST Act. -3. Importation of goods into Zero-GST/Licensed warehouses administered by Singapore Customs. -4. Importation of goods by GST-registered businesses that are under Major Exporter Scheme or other approved schemes. +Singapore's tax system includes a Goods and Services Tax (GST) administered +by the Inland Revenue Authority of Singapore (IRAS). Zero-rated supplies apply +to international services and exports. Exempt supplies include financial +services, sale and lease of residential properties, digital payment tokens, +and investment precious metals. + +Businesses are identified by their Unique Entity Number (UEN). GST-registered +suppliers must display their GST Registration Number on all tax invoices, +which in most cases is the same as the UEN. + +Three invoicing methods are supported: tax invoices (standard, requiring full +supplier and customer details), simplified tax invoices (for transactions +up to 1000 SGD inclusive of GST), and receipts (for non-GST-registered +customers). Credit notes are supported for correcting invoices; debit notes +in Singapore are used for requesting payment on non-GST transactions, not +for invoice corrections. ## Base Details diff --git a/regimes/us.mdx b/regimes/us.mdx index 4384104..416ea56 100644 --- a/regimes/us.mdx +++ b/regimes/us.mdx @@ -1,6 +1,22 @@ --- title: United States of America --- +The United States does not have a federal value-added tax (VAT) or goods and +services tax (GST). Instead, sales taxes are levied at the state and local +level, with rates and rules varying significantly across jurisdictions. + +Sales tax rates vary significantly by jurisdiction, with some states having +no sales tax at all (e.g. Oregon, Montana, Delaware, New Hampshire). Sales +tax is generally collected by the seller at the point of sale and remitted to +the relevant state tax authority. + +Businesses are identified by their EIN (Employer Identification Number), a +9-digit number assigned by the IRS (Internal Revenue Service) in the format +XX-XXXXXXX. State-level tax registration is separate and varies by +jurisdiction. + +There is no federal e-invoicing mandate. Both credit notes and debit notes +are supported for invoice corrections. ## Base Details From a6a3ec92c6f0c3952c7ea75182230f752c46a407 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Olivi=C3=A9?= Date: Mon, 2 Mar 2026 18:18:50 +0000 Subject: [PATCH 5/5] Fix and extend EN16931 terms mappings Correct field paths to match actual library implementations: - BT-9/20: fix payment terms paths - BT-17/18: separate tender vs object identifier correctly - BT-25/26: use specific series+code paths for preceding reference - BT-29/30/32/46/47/60/61: clarify scope and ext usage - BT-71: delivery location identifiers - BT-81/82: payment means code uses ext, not key - BT-87/88: card last4 and holder field names - BT-105/128/156: charge reason code, line object ID, buyer item ID - BT-115/116-121: payable field and rates[] level in VAT breakdown - BT-124: url not uri for attachment location - BT-158/159: item classification via identity label - BG-32: fix typo from BR-32 - Add missing BT-125, BT-147-150 entries - Remove BT-4 (withdrawn from standard) --- terms/en16931.yaml | 198 ++++++++++++++++++++++++++++++--------------- 1 file changed, 132 insertions(+), 66 deletions(-) diff --git a/terms/en16931.yaml b/terms/en16931.yaml index a9062bc..b818a92 100644 --- a/terms/en16931.yaml +++ b/terms/en16931.yaml @@ -65,7 +65,7 @@ terms: - id: "BT-9" name: "Payment due date" paths: - - $.doc.payment.terms[*].due_dates + - $.doc.payment.terms.due_dates[*].date notes: |- Forms part of the general payment details. @@ -73,10 +73,6 @@ terms: name: "Buyer reference" paths: - $.doc.ordering.code - - $.doc.ordering.identities[*].code - notes: |- - Additional codes defined with types or keys are available in the ordering identities - array. - id: "BT-11" name: "Project reference" @@ -115,14 +111,12 @@ terms: - id: "BT-18" name: "Invoiced object identifier" - path: - - $.doc.ordering.code + paths: - $.doc.ordering.identities[*].code - $.doc.ordering.identities[*].ext['untdid-reference'] notes: |- - GOBL supports multiple identifiers. If schema is important for the identifier - and the regular code cannot be used, assume the **first** identifier should be mapped - to the `BT-18` term. + Mapped to the first ordering identity. The scheme identifier (BT-18-1) is + stored in the `untdid-reference` extension when present. - id: "BT-19" name: "Buyer accounting reference" @@ -133,7 +127,7 @@ terms: - id: "BT-20" name: "Payment terms" paths: - - $.doc.payment.terms + - $.doc.payment.terms.notes - id: "BG-1" name: "INVOICE NOTE" @@ -179,7 +173,8 @@ terms: - id: "BT-25" name: "Preceding invoice reference" paths: - - $.doc.preceding + - $.doc.preceding[*].series + - $.doc.preceding[*].code - id: "BT-26" name: "Preceding invoice issue date" @@ -214,17 +209,22 @@ terms: - id: "BT-29" name: "Seller identifier" paths: - - $.doc.supplier.uuid - - $.doc.supplier.identities + - $.doc.supplier.identities[*].code + - $.doc.supplier.identities[*].ext['iso-scheme-id'] notes: |- - Supplier UUID is designed for use with internal systems of the document issuer. - dentifier schemes may be defined using extensions according to the standard - in use. + Identities without a scope and without `ext['iso-scheme-id']` map to the + plain party identifier. Identities with `ext['iso-scheme-id']` but no scope + map to the global identifier with a scheme. - id: "BT-30" name: "Seller legal registration identifier" paths: - - $.doc.supplier.identities + - $.doc.supplier.identities[*].code + - $.doc.supplier.identities[*].scope + - $.doc.supplier.identities[*].ext['iso-scheme-id'] + notes: |- + Uses identities where `scope` is `"legal"`. The scheme identifier is + stored in `ext['iso-scheme-id']` when present. - id: "BT-31" name: "Seller VAT identifier" @@ -234,9 +234,11 @@ terms: - id: "BT-32" name: "Seller tax registration identifier" paths: - - $.doc.supplier.identities + - $.doc.supplier.identities[*].code + - $.doc.supplier.identities[*].scope notes: |- - All non-VAT tax registration details can be defined in the `identities` array. + Uses identities where `scope` is `"tax"`. The tax scheme type is + stored in the identity `type` field. - id: "BT-33" name: "Seller additional legal information" @@ -343,17 +345,22 @@ terms: - id: "BT-46" name: "Buyer identifier" paths: - - $.doc.customer.uuid - - $.doc.customer.identities + - $.doc.customer.identities[*].code + - $.doc.customer.identities[*].ext['iso-scheme-id'] notes: |- - Customer UUID is designed for use with internal systems of the document issuer. - Identifier schemes may be defined using extensions according to the standard - in use. + Identities without a scope and without `ext['iso-scheme-id']` map to the + plain party identifier. Identities with `ext['iso-scheme-id']` but no scope + map to the global identifier with a scheme. - id: "BT-47" name: "Buyer legal registration identifier" paths: - - $.doc.customer.identities + - $.doc.customer.identities[*].code + - $.doc.customer.identities[*].scope + - $.doc.customer.identities[*].ext['iso-scheme-id'] + notes: |- + Uses identities where `scope` is `"legal"`. The scheme identifier is + stored in `ext['iso-scheme-id']` when present. - id: "BT-48" name: "Buyer VAT identifier" @@ -453,20 +460,21 @@ terms: - id: "BT-60" name: "Payee identifier" paths: - - $.doc.payment.payee.uuid - - $.doc.payment.payee.identities + - $.doc.payment.payee.identities[*].code + - $.doc.payment.payee.identities[*].ext['iso-scheme-id'] notes: |- - Payee UUID is designed for use with internal systems of the document issuer. - Identifier schemes may be defined using extensions according to the standard - in use. + Identities without a scope map to the payee identifier. The scheme + identifier is stored in `ext['iso-scheme-id']` when present. - id: "BT-61" name: "Payee legal registration identifier" paths: - - $.doc.payment.payee.tax_id - - $.doc.payment.payee.identities + - $.doc.payment.payee.identities[*].code + - $.doc.payment.payee.identities[*].scope + - $.doc.payment.payee.identities[*].ext['iso-scheme-id'] notes: |- - The payee's VAT ID may be provided as the primary legal registration identifier. + Uses identities where `scope` is `"legal"`. The scheme identifier is + stored in `ext['iso-scheme-id']` when present. - id: "BG-11" name: "SELLER TAX REPRESENTATIVE PARTY" @@ -543,11 +551,9 @@ terms: - id: BT-71 name: Deliver to location identifier paths: - - $.doc.delivery.receiver.uuid - - $.doc.delivery.receiver.identities - - $.doc.delivery.receiver.tax_id + - $.doc.delivery.identities notes: |- - Extensions in identities may be used to determine the scheme identifier if required. + Delivery location identifiers are stored in the delivery identities array, not on the receiver party. The identity label holds the scheme identifier if present. - id: BT-72 name: "Actual delivery date" paths: @@ -570,7 +576,7 @@ terms: - id: BG-15 name: DELIVER TO ADDRESS paths: - - $.doc.delivery.address + - $.doc.delivery.receiver.addresses terms: - id: BT-75 name: Deliver to address line 1 @@ -584,7 +590,7 @@ terms: - id: BT-76 name: Deliver to address line 2 paths: - - $.doc.delivery.reveiver.addresses[0].street_extra + - $.doc.delivery.receiver.addresses[0].street_extra - id: BT-165 name: Deliver to address line 3 paths: [] @@ -597,7 +603,7 @@ terms: - id: BT-78 name: Deliver to postal code paths: - - $.doc.delivery.reveiver.addresses[0].code + - $.doc.delivery.receiver.addresses[0].code - id: BT-79 name: Deliver to country subdivision paths: @@ -615,20 +621,19 @@ terms: - id: BT-81 name: Payment means type code paths: - - $.doc.payment.instructions.key + - $.doc.payment.instructions.ext["untdid-payment-means"] notes: |- - Mapping of GOBL payment means key to UNTDID 4461 codes is provided - in library will update extensions. + The UNTDID 4461 payment means code is stored in the extension. + The GOBL payment instructions key (e.g. "credit-transfer") is + mapped bidirectionally to the code by the libraries. - id: BT-82 name: Payment means text paths: - - $.doc.payment.instructions.key - $.doc.payment.instructions.detail notes: |- - In GOBL, payment means keys are self-descriptive, but if additional - details are required, they can be provided in the detail or description - fields provided. + The libraries map the detail field directly to the payment means + text/information field in CII and UBL. - id: BT-83 name: Remittance information @@ -656,9 +661,11 @@ terms: name: Payment account name paths: - $.doc.payment.instructions.credit_transfer[*].name + notes: |- + CII conversion intentionally omits the account name output. - id: BT-86 - name: Payment serivce provider identifier + name: Payment service provider identifier paths: - $.doc.payment.instructions.credit_transfer[*].bic @@ -670,15 +677,15 @@ terms: - id: BT-87 name: Payment card primary account number paths: - - $.doc.payment.instructions.card.first6 - $.doc.payment.instructions.card.last4 notes: |- - The first 6 and last 4 digits of the card number are split between two - fields to ensure that the full number is not stored in a single location. + Only the last 4 digits are mapped. The libraries extract the + last 4 digits when parsing a full PAN from XML. + - id: BT-88 name: Payment card holder name paths: - - $.doc.payment.instructions.card.name + - $.doc.payment.instructions.card.holder - id: BG-19 name: DIRECT DEBIT @@ -693,6 +700,9 @@ terms: name: Bank assigned creditor identifier paths: - $.doc.payment.instructions.direct_debit.creditor + notes: |- + In UBL, this is stored as a SEPA PartyIdentification on + the payee party (or supplier if no payee exists). - id: BT-91 name: Debited account identifier paths: @@ -862,7 +872,10 @@ terms: - id: "BT-115" name: "Amount due for payment" paths: + - $.doc.totals.payable - $.doc.totals.due + notes: |- + Libraries use `payable` by default, overridden by `due` if present. - id: "BG-23" name: "VAT BREAKDOWN" @@ -872,15 +885,15 @@ terms: - id: "BT-116" name: "VAT category taxable amount" paths: - - $.doc.totals.taxes.categories[code='VAT'].base + - $.doc.totals.taxes.categories[code='VAT'].rates[*].base - id: "BT-117" name: "VAT category tax amount" paths: - - $.doc.totals.taxes.categories[code='VAT'].amount + - $.doc.totals.taxes.categories[code='VAT'].rates[*].amount - id: "BT-118" name: "VAT category code" paths: - - $.doc.totals.taxes.categories[code='VAT'].ext['untdid-tax-category'] + - $.doc.totals.taxes.categories[code='VAT'].rates[*].ext['untdid-tax-category'] notes: |- Specific tax category codes can be added in the extensions using the `untdid-tax-category` extension key defined in the @@ -888,18 +901,15 @@ terms: - id: BT-119 name: "VAT category rate" paths: - - $.doc.totals.taxes.categories[code='VAT'].percent + - $.doc.totals.taxes.categories[code='VAT'].rates[*].percent - id: "BT-120" name: "VAT exemption reason text" - paths: - - $.doc.notes[key='legal'].text notes: |- - Exemption reasons are added to the list of legal notes included in the - invoice as opposed to being stored in the tax breakdown. + Mapping may change in the future. - id: "BT-121" name: "VAT exemption reason code" paths: - - $.doc.totals.taxes.categories[code='VAT'].ext['cef-vatex'] + - $.doc.totals.taxes.categories[code='VAT'].rates[*].ext['cef-vatex'] notes: |- Specific exemption codes can be added in the extensions using the `cef-vatex` extension key defined in the @@ -921,7 +931,12 @@ terms: - id: BT-124 name: "External document location" paths: - - $.doc.attachments[*].uri + - $.doc.attachments[*].url + - id: BT-125 + name: "Attached document" + notes: |- + Binary content is handled via the AddBinaryAttachment and + ExtractBinaryAttachments API methods in both CII and UBL. - id: BG-25 name: "INVOICE LINE" @@ -932,6 +947,8 @@ terms: name: "Invoice line identifier" paths: - $.doc.lines[*].i + notes: |- + Auto-generated from the line index. Not user-provided. - id: BT-127 name: "Invoice line note" paths: @@ -941,9 +958,11 @@ terms: - id: BT-128 name: "Invoice line object identifier" paths: - - $.doc.lines[*].identifier + - $.doc.lines[*].identifier.code + - $.doc.lines[*].identifier.ext['untdid-reference'] notes: |- - Use the `untdid-reference` extension if required for greater precision. + The reference type code (UNTDID 1153) is stored in the + untdid-reference extension when present. - id: BT-129 name: "Invoiced Quantity" paths: @@ -1063,6 +1082,34 @@ terms: paths: - $.doc.lines[*].item.price + - id: BT-147 + name: "Item price discount" + paths: [] + notes: |- + Not directly supported. GOBL stores net prices only. + + - id: BT-148 + name: "Item gross price" + paths: [] + notes: |- + Not directly supported. GOBL stores net prices only. + When parsing, the gross price is used to derive the net price. + + - id: BT-149 + name: "Item price base quantity" + paths: + - $.doc.lines[*].item.price + notes: |- + When parsing, the base quantity is used to normalize the unit price + by dividing. The original base quantity value is not preserved. + + - id: BT-150 + name: "Item price base quantity unit of measure code" + paths: + - $.doc.lines[*].item.unit + notes: |- + Same unit as the invoiced quantity. Not separately stored. + - id: BG-30 name: "LINE VAT INFORMATION" paths: @@ -1102,12 +1149,31 @@ terms: name: "Item Buyer's identifier" paths: - $.doc.lines[*].item.identities[*].code + notes: |- + Identity without ext['iso-scheme-id'] or label. First + plain identity is used as the buyer's item identifier. - id: BT-157 name: "Item standard identifier" paths: - $.doc.lines[*].item.identities[*].code - $.doc.lines[*].item.identities[*].ext['iso-scheme-id'] - - id: BR-32 + + - id: BT-158 + name: "Item classification identifier" + paths: + - $.doc.lines[*].item.identities[*].code + - $.doc.lines[*].item.identities[*].label + notes: |- + Classification identifiers use the identity label to store the + scheme identifier (listID). This distinguishes them from standard + identifiers which use ext['iso-scheme-id']. + + - id: BT-159 + name: "Item classification identifier scheme identifier" + paths: + - $.doc.lines[*].item.identities[*].label + + - id: BG-32 name: "ITEM ATTRIBUTES" paths: - $.doc.lines[*].item.meta