Read regime, exemption, and identity-type from es-tbai-* extensions

Wires the converter to read three new gobl tbai-addon extensions and
folds the existing legacy paths into fallbacks:

- es-tbai-regime: per-combo `ClaveRegimenIvaOpTrascendencia` value. The
  addon now normalizes this from per-combo signals (export, surcharge,
  simplified-scheme) or to 01 by default; explicit values are preserved.
  Legacy inference in `collectRegimeCodes` is kept as fallback for
  documents not run through the addon.
- es-tbai-exemption: with the addon's S2 mapping for reverse-charge,
  the breakdown dispatcher now routes S2 to Sujeta/NoExenta/TipoNoExenta
  instead of CausaExencion. VT/IE join OT/RL in NoSujeta. The tag-based
  reverse-charge fallback is preserved.
- es-tbai-identity-type: read on customer identities to select the L7
  IDType in IDOtro; falls back to the existing key->code map when the
  extension is absent.

Bumps gobl to the pseudo-version that ships both extensions in the
tbai addon. Regenerates test/data and test/data/out fixtures so the
extension values are present where normalization sets them.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: pmenendz

README.md

@@ -224,6 +224,10 @@ The following extension can be applied to each line tax:
 
 _(\*) As noted elsewhere, `RL` will be set automatically set in invoices using the `customer-rates` tax tag. It can also be set explicitly using the `es-tbai-exemption` extension in invoices not using that tag._
 
+- `es-tbai-regime` - sets the `ClaveRegimenIvaOpTrascendencia` field per VAT/IGIC tax combo. Codes follow the TicketBAI XSD list (`01`–`17`, `51`–`53`). If not provided, GOBL fills it in during normalization from per-combo signals — `tax.KeyExport` → `02`, equivalence-surcharge rate → `51`, the invoice-level `simplified-scheme` tag → `52`, otherwise `01`. Set it explicitly when none of those defaults applies (e.g. travel agencies → `05`, cash accounting → `07`, OSS/IOSS → `17`); explicit values are always preserved.
+
+- `es-tbai-identity-type` - sets the `IDType` value under `IDOtro` for the customer's identity (L7 list, codes `02`–`06`). Normalization maps `org.IdentityKeyPassport` → `03`, `IdentityKeyForeign` → `04`, `IdentityKeyResident` → `05`, `IdentityKeyOther` → `06`. Set it explicitly on an identity with no key (or to override). Spanish NIFs use the `NIF` field directly, and EU/non-EU tax IDs map to `IDOtro/IDType` `02`/`04` automatically.
+
 ### Use-Cases
 
 Under what situations should the TicketBAI system be expected to function:

convert/breakdown.go

@@ -145,7 +145,7 @@ func newDesgloseFactura(taxInfo taxInfo, rates []*tax.RateTotal) *DesgloseFactur
 			})
 		} else {
 			dne := df.Sujeta.NoExenta.appendDetalle(&DetalleNoExenta{
-				TipoNoExenta: taxInfo.nonExemptedType(),
+				TipoNoExenta: taxInfo.nonExemptedType(rate),
 				DesgloseIVA:  &DesgloseIVA{},
 			})
 
@@ -219,9 +219,13 @@ func (di *DesgloseIVA) appendDetalle(d *DetalleIVA) *DetalleIVA {
 }
 
 func newDetalleIVA(taxInfo taxInfo, rate *tax.RateTotal) *DetalleIVA {
+	percent := num.PercentageZero // S2 reverse-charge rates have no percent
+	if rate.Percent != nil {
+		percent = *rate.Percent
+	}
 	diva := &DetalleIVA{
 		BaseImponible:  rate.Base.Rescale(2).String(),
-		TipoImpositivo: formatPercent(*rate.Percent),
+		TipoImpositivo: formatPercent(percent),
 		CuotaImpuesto:  rate.Amount.Rescale(2).String(),
 	}
 
@@ -254,16 +258,28 @@ func newTaxInfo(gobl *bill.Invoice) taxInfo {
 	}
 }
 
-func (t taxInfo) nonExemptedType() string {
-	if t.reverseCharge {
+// notSubjectExemptionCodes are the es-tbai-exemption values that the
+// es-tbai-v1 addon assigns to "outside-scope" tax combos; they map to
+// DetalleNoSujeta/Causa in the TicketBAI XML.
+var notSubjectExemptionCodes = []cbc.Code{"OT", "RL", "VT", "IE"}
+
+// reverseChargeExemptionCodes are the es-tbai-exemption values that map
+// to DetalleNoExenta/TipoNoExenta = S2 (subject to VAT with reverse
+// charge) in the TicketBAI XML.
+var reverseChargeExemptionCodes = []cbc.Code{"S2"}
+
+// nonExemptedType returns the TBAI TipoNoExenta value for a "subject and
+// non-exempt" tax rate. The new path consults the es-tbai-exemption
+// extension set by the es-tbai-v1 addon normalizer; the legacy fallback
+// relies on the invoice-wide reverse-charge tag for callers that have
+// not been normalized through the addon.
+func (t taxInfo) nonExemptedType(r *tax.RateTotal) string {
+	if t.reverseCharge || r.Ext.Get(tbai.ExtKeyExempt).In(reverseChargeExemptionCodes...) {
 		return "S2"
 	}
-
 	return "S1"
 }
 
-var notSubjectExemptionCodes = []cbc.Code{"OT", "RL"}
-
 func (t taxInfo) isNoSujeta(r *tax.RateTotal) bool {
 	if t.customerRates {
 		return true
@@ -279,5 +295,8 @@ func (t taxInfo) causaNoSujeta(r *tax.RateTotal) string {
 }
 
 func (taxInfo) isExenta(r *tax.RateTotal) bool {
-	return r.Percent == nil && !r.Ext.Get(tbai.ExtKeyExempt).In(notSubjectExemptionCodes...)
+	code := r.Ext.Get(tbai.ExtKeyExempt)
+	return r.Percent == nil &&
+		!code.In(notSubjectExemptionCodes...) &&
+		!code.In(reverseChargeExemptionCodes...)
 }

convert/breakdown_test.go

@@ -195,7 +195,9 @@ func TestDesgloseConversion(t *testing.T) {
 				&tax.Combo{Category: es.TaxCategoryIRPF, Rate: "pro"},
 				&tax.Combo{
 					Category: tax.CategoryVAT,
-					Ext:      tax.MakeExtensions().Set(tbai.ExtKeyExempt, "OT"),
+					Ext: tax.ExtensionsOf(cbc.CodeMap{
+						tbai.ExtKeyExempt: "OT",
+					}),
 				},
 			},
 		}}
@@ -217,7 +219,7 @@ func TestDesgloseConversion(t *testing.T) {
 			Taxes: tax.Set{
 				&tax.Combo{
 					Category: tax.CategoryVAT,
-					Ext:      tax.MakeExtensions().Set(tbai.ExtKeyExempt, "RL"),
+					Ext:      tax.ExtensionsOf(cbc.CodeMap{tbai.ExtKeyExempt: "RL"}),
 				},
 			},
 		}}
@@ -239,7 +241,7 @@ func TestDesgloseConversion(t *testing.T) {
 			Taxes: tax.Set{
 				&tax.Combo{
 					Category: tax.CategoryVAT,
-					Ext:      tax.MakeExtensions().Set(tbai.ExtKeyExempt, "RL"),
+					Ext:      tax.ExtensionsOf(cbc.CodeMap{tbai.ExtKeyExempt: "RL"}),
 				},
 			},
 		}}
@@ -347,7 +349,7 @@ func TestDesgloseConversion(t *testing.T) {
 					&tax.Combo{
 						Category: tax.CategoryVAT,
 						Rate:     "general",
-						Ext:      tax.MakeExtensions().Set(tbai.ExtKeyProduct, "resale"),
+						Ext:      tax.ExtensionsOf(cbc.CodeMap{tbai.ExtKeyProduct: "resale"}),
 					},
 				},
 			},
@@ -374,7 +376,7 @@ func TestDesgloseConversion(t *testing.T) {
 				&tax.Combo{
 					Category: tax.CategoryVAT,
 					Key:      tax.KeyExempt,
-					Ext:      tax.MakeExtensions().Set(tbai.ExtKeyExempt, "E1"),
+					Ext:      tax.ExtensionsOf(cbc.CodeMap{tbai.ExtKeyExempt: "E1"}),
 				},
 			},
 		}}
@@ -465,6 +467,92 @@ func TestDesgloseConversion(t *testing.T) {
 		desglose := invoice.Factura.TipoDesglose.DesgloseFactura
 		assert.Equal(t, "S2", desglose.Sujeta.NoExenta.DetalleNoExenta[0].TipoNoExenta)
 	})
+
+	t.Run("should route es-tbai-exemption=S2 to Sujeta.NoExenta with TipoNoExenta=S2", func(t *testing.T) {
+		goblInvoice := invoiceFromCountry("ES")
+		goblInvoice.Lines = []*bill.Line{{
+			Index:    1,
+			Quantity: num.MakeAmount(100, 0),
+			Item:     &org.Item{Name: "A", Price: num.NewAmount(10, 0)},
+			Taxes: tax.Set{
+				&tax.Combo{
+					Category: tax.CategoryVAT,
+					Key:      tax.KeyReverseCharge,
+				},
+			},
+		}}
+		_ = goblInvoice.Calculate()
+
+		invoice, _ := convert.NewTicketBAI(goblInvoice, ts, role, convert.ZoneBI)
+
+		desglose := invoice.Factura.TipoDesglose.DesgloseFactura
+		require.NotNil(t, desglose.Sujeta)
+		require.NotNil(t, desglose.Sujeta.NoExenta)
+		require.Len(t, desglose.Sujeta.NoExenta.DetalleNoExenta, 1)
+		detalle := desglose.Sujeta.NoExenta.DetalleNoExenta[0]
+		assert.Equal(t, "S2", detalle.TipoNoExenta)
+		require.Len(t, detalle.DesgloseIVA.DetalleIVA, 1)
+		diva := detalle.DesgloseIVA.DetalleIVA[0]
+		assert.Equal(t, "1000.00", diva.BaseImponible)
+		assert.Equal(t, "0.00", diva.TipoImpositivo)
+		assert.Equal(t, "0.00", diva.CuotaImpuesto)
+		assert.Nil(t, desglose.Sujeta.Exenta, "S2 must not appear under Sujeta.Exenta")
+		assert.Nil(t, desglose.NoSujeta, "S2 must not appear under NoSujeta")
+	})
+
+	t.Run("should route es-tbai-exemption=S2 set via extension only to Sujeta.NoExenta", func(t *testing.T) {
+		// Caller sets the exemption code directly via the extension;
+		// the es-tbai-v1 addon normalizer maps it back to KeyReverseCharge.
+		goblInvoice := invoiceFromCountry("ES")
+		goblInvoice.Lines = []*bill.Line{{
+			Index:    1,
+			Quantity: num.MakeAmount(100, 0),
+			Item:     &org.Item{Name: "A", Price: num.NewAmount(10, 0)},
+			Taxes: tax.Set{
+				&tax.Combo{
+					Category: tax.CategoryVAT,
+					Ext:      tax.MakeExtensions().Set(tbai.ExtKeyExempt, "S2"),
+				},
+			},
+		}}
+		_ = goblInvoice.Calculate()
+
+		invoice, _ := convert.NewTicketBAI(goblInvoice, ts, role, convert.ZoneBI)
+
+		desglose := invoice.Factura.TipoDesglose.DesgloseFactura
+		require.NotNil(t, desglose.Sujeta)
+		require.NotNil(t, desglose.Sujeta.NoExenta)
+		assert.Equal(t, "S2", desglose.Sujeta.NoExenta.DetalleNoExenta[0].TipoNoExenta)
+	})
+
+	t.Run("should route es-tbai-exemption=VT and IE to NoSujeta", func(t *testing.T) {
+		for _, code := range []cbc.Code{"VT", "IE"} {
+			t.Run(string(code), func(t *testing.T) {
+				goblInvoice := invoiceFromCountry("ES")
+				goblInvoice.Lines = []*bill.Line{{
+					Index:    1,
+					Quantity: num.MakeAmount(100, 0),
+					Item:     &org.Item{Name: "A", Price: num.NewAmount(10, 0)},
+					Taxes: tax.Set{
+						&tax.Combo{
+							Category: tax.CategoryVAT,
+							Key:      tax.KeyOutsideScope,
+							Ext:      tax.MakeExtensions().Set(tbai.ExtKeyExempt, code),
+						},
+					},
+				}}
+				_ = goblInvoice.Calculate()
+
+				invoice, _ := convert.NewTicketBAI(goblInvoice, ts, role, convert.ZoneBI)
+
+				desglose := invoice.Factura.TipoDesglose.DesgloseFactura
+				require.NotNil(t, desglose.NoSujeta)
+				require.Len(t, desglose.NoSujeta.DetalleNoSujeta, 1)
+				assert.Equal(t, string(code), desglose.NoSujeta.DetalleNoSujeta[0].Causa)
+				assert.Nil(t, desglose.Sujeta, "%s must not appear under Sujeta", code)
+			})
+		}
+	})
 }
 
 func invoiceFromCountry(countryCode l10n.TaxCountryCode) *bill.Invoice {

convert/doc_test.go

@@ -73,16 +73,32 @@ func TestInvoiceConversion(t *testing.T) {
 		assert.Contains(t, invoice.Sujetos.Destinatarios.IDDestinatario[0].Direccion, "PO-745")
 	})
 
-	t.Run("should contain the right id for abroad customers", func(t *testing.T) {
+	t.Run("EU customer tax ID is emitted as NIF-VAT (IDType 02)", func(t *testing.T) {
 		goblInvoice := test.LoadInvoice("sample-invoice.json")
-		goblInvoice.Customer.TaxID = &tax.Identity{Country: "GB", Code: "PP-123456-S"}
+		goblInvoice.Customer.TaxID = &tax.Identity{Country: "DE", Code: "DE123456789"}
+		goblInvoice.Customer.Name = "EU Co GmbH"
+
+		invoice, _ := convert.NewTicketBAI(goblInvoice, ts, role, convert.ZoneBI)
+
+		assert.Equal(t, "DE", invoice.Sujetos.Destinatarios.IDDestinatario[0].IDOtro.CodigoPais)
+		assert.Equal(t, "DE123456789", invoice.Sujetos.Destinatarios.IDDestinatario[0].IDOtro.ID)
+		assert.Equal(t, "02", invoice.Sujetos.Destinatarios.IDDestinatario[0].IDOtro.IDType)
+		assert.Equal(t, "EU Co GmbH", invoice.Sujetos.Destinatarios.IDDestinatario[0].ApellidosNombreRazonSocial)
+	})
+
+	t.Run("non-EU customer tax ID is emitted as Foreign Identity (IDType 04)", func(t *testing.T) {
+		// The TicketBAI gateway rejects non-EU tax IDs sent as NIF-VAT
+		// with B4_2000013; they must be reported as foreign identity
+		// documents (IDType 04) instead. GB qualifies since 2020-01-31.
+		goblInvoice := test.LoadInvoice("sample-invoice.json")
+		goblInvoice.Customer.TaxID = &tax.Identity{Country: "GB", Code: "GB123456789"}
 		goblInvoice.Customer.Name = "Abroad Co LLC"
 
 		invoice, _ := convert.NewTicketBAI(goblInvoice, ts, role, convert.ZoneBI)
 
 		assert.Equal(t, "GB", invoice.Sujetos.Destinatarios.IDDestinatario[0].IDOtro.CodigoPais)
-		assert.Equal(t, "PP-123456-S", invoice.Sujetos.Destinatarios.IDDestinatario[0].IDOtro.ID)
-		assert.Equal(t, "02", invoice.Sujetos.Destinatarios.IDDestinatario[0].IDOtro.IDType)
+		assert.Equal(t, "GB123456789", invoice.Sujetos.Destinatarios.IDDestinatario[0].IDOtro.ID)
+		assert.Equal(t, "04", invoice.Sujetos.Destinatarios.IDDestinatario[0].IDOtro.IDType)
 		assert.Equal(t, "Abroad Co LLC", invoice.Sujetos.Destinatarios.IDDestinatario[0].ApellidosNombreRazonSocial)
 	})
 

convert/invoice.go

@@ -147,6 +147,51 @@ func newRetencionSoportada(inv *bill.Invoice) string {
 }
 
 func newClaves(inv *bill.Invoice) []IDClave {
+	// Preferred: collect unique codes from the es-tbai-regime extension
+	// set per VAT tax combo by the es-tbai-v1 addon normalizer. This is
+	// the path that respects an explicit ClaveRegimenIvaOpTrascendencia
+	// the caller may have set.
+	if codes := collectRegimeCodes(inv); len(codes) > 0 {
+		claves := make([]IDClave, 0, len(codes))
+		for _, c := range codes {
+			claves = append(claves, IDClave{ClaveRegimenIvaOpTrascendencia: c})
+		}
+		return claves
+	}
+
+	return legacyClaves(inv)
+}
+
+// collectRegimeCodes returns the distinct ClaveRegimenIvaOpTrascendencia
+// codes carried by the invoice's VAT rate totals via the es-tbai-regime
+// extension, preserving the order of first appearance.
+func collectRegimeCodes(inv *bill.Invoice) []string {
+	if inv.Totals == nil || inv.Totals.Taxes == nil {
+		return nil
+	}
+	vat := inv.Totals.Taxes.Category(tax.CategoryVAT)
+	if vat == nil {
+		return nil
+	}
+	seen := make(map[string]bool, len(vat.Rates))
+	codes := make([]string, 0, len(vat.Rates))
+	for _, rate := range vat.Rates {
+		c := rate.Ext.Get(tbai.ExtKeyRegime).String()
+		if c == "" || seen[c] {
+			continue
+		}
+		seen[c] = true
+		codes = append(codes, c)
+	}
+	return codes
+}
+
+// legacyClaves is the original invoice-level inference of
+// ClaveRegimenIvaOpTrascendencia, kept as a fallback for callers that
+// build TicketBAI documents from GOBL invoices that have not been
+// normalized by the es-tbai-v1 addon. New code should rely on the
+// es-tbai-regime extension instead.
+func legacyClaves(inv *bill.Invoice) []IDClave {
 	claves := []IDClave{}
 
 	if inv.Customer != nil && partyCountry(inv.Customer) != "ES" {
@@ -207,6 +252,9 @@ func newFacturasRectificadasSustituidas(inv *bill.Invoice) *FacturasRectificadas
 	}
 }
 
+// hasSurchargedLines is part of the legacy ClaveRegimenIvaOpTrascendencia
+// inference. Detection now happens at addon-normalization time and is
+// reflected in the es-tbai-regime extension; see legacyClaves.
 func hasSurchargedLines(inv *bill.Invoice) bool {
 	if inv.Totals == nil || inv.Totals.Taxes == nil {
 		return false
@@ -225,6 +273,8 @@ func hasSurchargedLines(inv *bill.Invoice) bool {
 	return false
 }
 
+// underSimplifiedRegime is part of the legacy regime inference; see
+// legacyClaves.
 func underSimplifiedRegime(inv *bill.Invoice) bool {
 	return inv.HasTags(es.TagSimplifiedScheme)
 }