Skip to content

Catálogo fiscal / motor de impuestos ​

Catálogo versionado de jurisdicciones e impuestos. Distinto de billing/cobros.

Conceptos ​

  • Jurisdicciones seed: ES, DE, FR, IT, PT, NL, BE, IE, AT, SE, FI, DK, PL, CY, MT + US (manual) + OTROS (custom tenant). Arranque, no cierre — el super admin puede incorporar más países.
  • Providers pluggables: al incorporar/refrescar un país catalog_managed, el sistema consulta el provider preferido (TEDB VatRetrievalService por defecto para UE; Avalara / Stripe Tax cuando están configurados — 2; fake solo en tests / TAX_RATE_PROVIDER=fake) y materializa tasas en el catálogo interno. Si el preferred no puede servir el país, falla sin caer a tasas sintéticas. TEDB/fake aceptan ISO-3166-1 alpha-2 abiertos no hay allowlist de producto que exija redeploy.
  • Semilla sin inventar %: si el provider falla en seed/incorporate, la jurisdicción queda failed/pending (requiere refresh); nunca se auto-activan tasas hardcodeadas como si fueran TEDB.
  • Versionado: cada publicación/refresco/override crea una nueva versión. Los documentos emitidos guardan un snapshot (código jurisdicción, tasa, %) que no se recalcula.
  • US: sin sales tax automático. OTROS: OWNER/ADMIN definen porcentajes propios.
  • IA: solo propuestas proposed; nunca publica al catálogo productivo.
  • VIES: validación opcional de NIF-IVA; no es fuente de tasas.

Endpoints ​

MétodoRutaQuiénNotas
GET/tax/jurisdictionsAutenticadoSemillas + versión publicada
GET/tax/jurisdictions/:codeAutenticadoDetalle + tasas publicadas
GET/tax/jurisdictions/:code/ratesAutenticadoTasas vigentes para facturar
GET/tax/jurisdictions/:code/versionsSuper adminHistorial de versiones
GET/tax/jurisdictions/:code/auditsSuper adminAuditoría provider vs override
POST/tax/jurisdictionsSuper adminIncorporar país
POST/tax/jurisdictions/:code/refreshSuper adminRefresco provider
POST/tax/jurisdictions/:code/versions/:versionId/publishSuper adminPublicar propuesta (gate humano)
PATCH/tax/jurisdictions/:code/rates/:rateIdSuper adminOverride
POST/tax/jurisdictions/:code/ai-proposalsSuper adminBorrador IA (proposed only)
POST/tax/snapshotsAutenticadoSnapshot
POST/tax/vies/validateAutenticadoVIES opcional
GET/POST/PATCH/DELETE/tax/custom-ratesOWNER/ADMIN (escritura)OTROS

Variables de entorno ​

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 — ver la documentación de configuración.