Fiscal catalogue / tax engine
Versioned catalogue of jurisdictions and taxes. It is distinct from billing/charges.
Concepts
- Seed jurisdictions:
ES, DE, FR, IT, PT, NL, BE, IE, AT, SE, FI, DK, PL, CY, MT+US(manual) +OTROS(tenant custom). A starting point, not a closed set — the super admin can add more countries. - Pluggable providers: when adding or refreshing a
catalog_managedcountry, the system queries the preferred provider (TEDB VatRetrievalService by default for the EU; Avalara / Stripe Tax when configured;fakeonly in tests /TAX_RATE_PROVIDER=fake) and materializes rates into the internal catalogue. If the preferred provider cannot serve the country, the operation fails without falling back to synthetic rates. TEDB/fake accept open ISO-3166-1 alpha-2 codes — there is no product allowlist forcing a redeploy. - Seeding never invents percentages: if the provider fails during seed/incorporate, the jurisdiction stays
failed/pending(a refresh is required); hardcoded rates are never auto-activated as if they were TEDB. - Versioning: every publication, refresh or override creates a new version. Issued documents keep a snapshot (jurisdiction code, rate, percentage) that is never recalculated.
- US: no automatic sales tax. OTROS: OWNER/ADMIN define their own percentages.
- AI:
proposeddrafts only; it never publishes to the production catalogue. - VIES: optional VAT-number validation; it is not a rate source.
Endpoints
| Method | Route | Who | Notes |
|---|---|---|---|
| GET | /tax/jurisdictions | Authenticated | Seeds + published version |
| GET | /tax/jurisdictions/:code | Authenticated | Detail + published rates |
| GET | /tax/jurisdictions/:code/rates | Authenticated | Rates in force for invoicing |
| GET | /tax/jurisdictions/:code/versions | Super admin | Version history |
| GET | /tax/jurisdictions/:code/audits | Super admin | Provider vs override audit trail |
| POST | /tax/jurisdictions | Super admin | Add a country |
| POST | /tax/jurisdictions/:code/refresh | Super admin | Provider refresh |
| POST | /tax/jurisdictions/:code/versions/:versionId/publish | Super admin | Publish a proposal (human gate) |
| PATCH | /tax/jurisdictions/:code/rates/:rateId | Super admin | Override |
| POST | /tax/jurisdictions/:code/ai-proposals | Super admin | AI draft (proposed only) |
| POST | /tax/snapshots | Authenticated | Snapshot |
| POST | /tax/vies/validate | Authenticated | Optional VIES |
| GET/POST/PATCH/DELETE | /tax/custom-rates | OWNER/ADMIN (writes) | OTROS |
Environment variables
TAX_RATE_PROVIDER, TEDB_VAT_RETRIEVAL_URL, AVALARA_ACCOUNT_ID, AVALARA_LICENSE_KEY, AVALARA_BASE_URL, STRIPE_TAX_ENABLED, STRIPE_TAX_SECRET_KEY, STRIPE_TAX_CODE, TAX_CATALOG_AUTO_PUBLISH, VIES_ENABLED, VIES_CHECK_VAT_URL — see the configuration documentation.