Skip to content

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_managed country, the system queries the preferred provider (TEDB VatRetrievalService by default for the EU; Avalara / Stripe Tax when configured; fake only 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: proposed drafts only; it never publishes to the production catalogue.
  • VIES: optional VAT-number validation; it is not a rate source.

Endpoints ​

MethodRouteWhoNotes
GET/tax/jurisdictionsAuthenticatedSeeds + published version
GET/tax/jurisdictions/:codeAuthenticatedDetail + published rates
GET/tax/jurisdictions/:code/ratesAuthenticatedRates in force for invoicing
GET/tax/jurisdictions/:code/versionsSuper adminVersion history
GET/tax/jurisdictions/:code/auditsSuper adminProvider vs override audit trail
POST/tax/jurisdictionsSuper adminAdd a country
POST/tax/jurisdictions/:code/refreshSuper adminProvider refresh
POST/tax/jurisdictions/:code/versions/:versionId/publishSuper adminPublish a proposal (human gate)
PATCH/tax/jurisdictions/:code/rates/:rateIdSuper adminOverride
POST/tax/jurisdictions/:code/ai-proposalsSuper adminAI draft (proposed only)
POST/tax/snapshotsAuthenticatedSnapshot
POST/tax/vies/validateAuthenticatedOptional VIES
GET/POST/PATCH/DELETE/tax/custom-ratesOWNER/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.