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;fakesolo 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étodo | Ruta | Quién | Notas |
|---|---|---|---|
| GET | /tax/jurisdictions | Autenticado | Semillas + versión publicada |
| GET | /tax/jurisdictions/:code | Autenticado | Detalle + tasas publicadas |
| GET | /tax/jurisdictions/:code/rates | Autenticado | Tasas vigentes para facturar |
| GET | /tax/jurisdictions/:code/versions | Super admin | Historial de versiones |
| GET | /tax/jurisdictions/:code/audits | Super admin | Auditoría provider vs override |
| POST | /tax/jurisdictions | Super admin | Incorporar país |
| POST | /tax/jurisdictions/:code/refresh | Super admin | Refresco provider |
| POST | /tax/jurisdictions/:code/versions/:versionId/publish | Super admin | Publicar propuesta (gate humano) |
| PATCH | /tax/jurisdictions/:code/rates/:rateId | Super admin | Override |
| POST | /tax/jurisdictions/:code/ai-proposals | Super admin | Borrador IA (proposed only) |
| POST | /tax/snapshots | Autenticado | Snapshot |
| POST | /tax/vies/validate | Autenticado | VIES opcional |
| GET/POST/PATCH/DELETE | /tax/custom-rates | OWNER/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.