Motor híbrido de impuesto sobre las ventas de EE. UU. para Odoo: resuelve la tasa combinada de estado + condado + ciudad + distrito para un código ZIP, la aplica a los pedidos de venta y a las facturas, y mantiene un registro de auditoría completo de cada cálculo.
Orden de resolución: primero la base de datos de tasas local, los proveedores de API externos como respaldo (configurados de forma independiente en sus propios módulos l10n_us_sales_tax_provider_* — este módulo nunca importa su código directamente). Realiza un seguimiento del nexus por estado, de la gravabilidad por categoría de producto, y almacena en caché las respuestas de las API externas para controlar el volumen de llamadas.
Traducción automática al español (DeepSeek) de la descripción original de OCA, que está en inglés.
auto_awesome Qué hace este módulo
Generado por IA a partir del código · Odoo 18.0Calcula el impuesto sobre las ventas de EE. UU. (estado, condado, ciudad y distrito) para pedidos de venta y facturas basándose en el código postal del cliente, utilizando primero una base de datos local de tarifas y proveedores externos como respaldo, con un registro de auditoría completo.
Este módulo añade un motor híbrido de impuestos de ventas de EE. UU. a Odoo. Cuando se activa en los ajustes de Contabilidad, calcula automáticamente la tasa combinada de estado, condado, ciudad y distrito para el código postal de un cliente y la aplica a los pedidos de venta y a las facturas/abonos de cliente.
- En los pedidos de venta, el impuesto se recalcula automáticamente cuando se confirma el pedido, y existe una acción manual "Calculate US Tax". Una casilla decide si se usa la dirección de envío o la de facturación.
- En las facturas, el impuesto se recalcula automáticamente cuando se publica la factura, además de una acción manual.
- Los clientes se pueden marcar como exentos del impuesto de EE. UU. con un código de exención y un número de certificado; los productos obtienen una categoría fiscal de EE. UU. (p. ej. TANGIBLE, SERVICE, FOOD).
- Las pantallas de configuración permiten activar el motor, elegir el modo (solo local, solo API, híbrido), establecer la política de fallo de la API, la duración de la caché y el umbral de confianza del ZIP.
- Los datos maestros abarcan jurisdicciones, tasas versionadas, asignaciones de ZIP a jurisdicción, reglas de gravabilidad por estado/categoría, nexus por estado y proveedores externos con límites mensuales de llamadas y advertencias.
- Cada cálculo se escribe en un registro de auditoría inmutable; las respuestas caducadas de la API se purgan mediante una tarea programada, y los contadores de llamadas de los proveedores se restablecen mensualmente.
- Un asistente importa archivos de tasas (Florida DOR, Texas Open Data, CSV genérico) con vista previa y reversión.
Depende de
Lo necesitan otros módulos
Menús que añade
Modelos y campos (17)
- sale.order · amplía un modelo existenteus_tax_source (Tax Source), us_tax_calculated_at (Tax Calculated At), us_tax_based_on_shipping (Tax Based on Shipping Address)
- res.partner · amplía un modelo existenteus_tax_exempt (US Tax Exempt), us_tax_exemption_code (Exemption Code), us_tax_exemption_number (Exemption Certificate #)
- us.tax.rate · modelo nuevonotes, active, source, end_date, state_id, city_rate, source_url (Source URL), state_rate, total_rate, county_rate, district_rate, effective_date, import_batch_id, jurisdiction_id, product_tax_category_id
- us.tax.rule · modelo nuevoactive, taxable, end_date, state_id, rate_override, effective_date, exemption_reason, product_tax_category_id
- account.move · amplía un modelo existenteus_tax_source (Tax Source), us_tax_calculated_at (Tax Calculated At)
- us.tax.nexus · modelo nuevonotes, active, state_id, company_id, start_date, threshold_amount, threshold_transactions
- us.tax.provider · modelo nuevocode, name, active, is_paid, timeout, priority, description, limit_status, sandbox_mode, api_key_param, limit_usage_pct, account_id_param, calls_this_month, limit_alert_sent, monthly_call_limit, supports_zip_level, supports_address_level
- product.template · amplía un modelo existenteus_tax_category_id (US Tax Category)
- us.tax.api.cache · modelo nuevozip, active, state_id, cached_at, city_rate, expires_at, state_rate, total_rate, county_rate, provider_id, source_date, address_hash, district_rate, request_payload, response_payload
- us.tax.zip.mapping · modelo nuevozip (ZIP Code), city, zip4 (ZIP+4), county, source, state_id, confidence, imported_at, import_batch_id, jurisdiction_id
- res.config.settings · amplía un modelo existenteus_tax_engine_mode (Engine Mode), us_tax_fail_policy (API Failure Policy), us_tax_engine_active (Enable US Sales Tax Engine), us_tax_cache_ttl_hours (Cache TTL (hours)), us_tax_confidence_threshold (ZIP Confidence Threshold)
- us.tax.import.batch · modelo nuevoname, source, status, state_id (State Covered), error_log, file_name, started_at, finished_at, imported_by, can_rollback, effective_date, records_created, records_skipped, records_updated
- us.tax.jurisdiction · modelo nuevocity, name, type, active, county, rate_ids, state_id, child_ids, parent_id (Parent Jurisdiction), parent_path, complete_name, district_code, zip_mapping_ids
- us.tax.import.wizard · modelo nuevosource, state_id, delimiter, file_data (File), file_name, preview_html, effective_date
- us.tax.engine.service · modelo nuevo
- us.tax.calculation.log · modelo nuevores_id, source, status, city_rate, res_model, partner_id, state_rate, tax_amount, total_rate, county_rate, currency_id, provider_id, document_ref, full_address, shipping_zip, calculated_at, calculated_by, district_rate, error_message, nexus_applied, shipping_city, taxable_amount, request_payload, shipping_county, response_payload, shipping_state_id, product_category_id
- us.tax.product.category · modelo nuevocode, name, active, description, default_taxable
Texto generado por IA (DeepSeek) al leer el código de la versión 18.0 en GitHub; puede contener errores, así que verifícalo en el código antes de decidir. El módulo es muy grande y solo se ha leído una parte del código. Ver el código en GitHub
Disponibilidad por versión
Revisado: 2026-11-03Estado de confirmación: 1 confirmada, 8 sin información de 9 versiones.
Fuentes · Odoo 18.0
Confirmado el 2026-11-03 en la rama 18.0 de OCA/l10n-usa.
terminal Instalación y uso
Documentación de OCA · Odoo 18.0Carga de datos de tasas locales
El proveedor local necesita tres cosas antes de poder resolver una tasa de impuesto para un código ZIP: una Jurisdiction (condado/ciudad), un ZIP Mapping que apunte ese ZIP a la jurisdicción, y un Tax Rate en esa jurisdicción. Ninguno de estos se carga previamente — solo las categorías de producto y el registro del proveedor se siembran en la instalación.
Asistente Import Tax Rates
US Sales Tax → Rate Database → Import Rates siempre requiere subir un archivo — no hay opción de "instantáneo, sin archivo" en el asistente.
- Florida DOR: sube el CSV oficial Master Address List desde https://pointmatch.floridarevenue.com/General/AddressFiles.aspx (selecciona un condado y una fecha de vigencia, luego descarga). Esto crea la jurisdicción, la tasa y el mapeo ZIP para cada fila — resolución completa a nivel de ZIP.
- CSV genérico (cualquier estado): cualquier archivo con
ZIP,COUNTY/CITY, y una columna de tasa funciona de la misma manera.
Configuración manual (prueba rápida, un solo ZIP)
Para probar un solo ZIP sin descargar un archivo, crea los tres registros a mano en US Sales Tax → Rate Database:
- Jurisdictions — nombre, tipo (condado/ciudad), estado.
- ZIP Mappings — el código ZIP, apuntando a esa jurisdicción.
- Tax Rates — los valores de tasa reales en esa jurisdicción.
El Nexus es independiente de los datos de tasas
Crear un registro Nexus (US Sales Tax → Configuration → Nexus) solo marca que la empresa tiene una obligación legal de recaudar impuestos en ese estado — no crea ni requiere ninguna jurisdicción, mapeo ZIP o tasa. Ambos son necesarios de forma independiente antes de que un pedido de venta calcule un impuesto local distinto de cero.
Las líneas con impuesto cero siempre llevan un impuesto explícito, nunca un campo de impuesto vacío
Cuando una línea termina con un impuesto del 0%, el motor siempre asigna un registro account.tax real en lugar de dejar la línea sin impuesto:
- Categoría de producto exenta o sin nexus en ese estado — se le asigna el impuesto compartido
US Sales Tax - Exempt (0%)(un impuesto para ambos motivos, en todos los estados). - Un estado con una tasa combinada genuina del 0% (p. ej. Oregon, Montana — estados sin ningún impuesto sobre las ventas) — se le asigna
US Sales Tax {state} 0%, el mismo impuesto por estado y tasa que se usa para cualquier otra tasa.
Esto es deliberado: un tax_id vacío es indistinguible de "el impuesto nunca se calculó" en una factura o en un informe de impuestos filtrado/agrupado por account.tax/account.tax.group. Un registro de impuesto explícito del 0% muestra que la línea fue evaluada y que se tomó una determinación deliberada de "no se debe impuesto" — el tipo de rastro de auditoría que una línea exenta de impuesto sobre las ventas debería dejar.
El motivo específico de una línea al 0% (qué categoría de producto, qué estado, nexus o sin nexus) no está codificado en el nombre del impuesto — ese nivel de detalle ya vive en us.tax.calculation.log, un registro por cálculo. El impuesto en sí solo necesita responder "¿se evaluó esto, y es gravable?" de un vistazo.
Nota de migración: si tenías informes ad-hoc que filtraban líneas sin ningún tax_id/tax_ids para señalar casos de "impuesto faltante", esas líneas dejarán de coincidir una vez que lleven el impuesto explícito del 0% — este es el efecto previsto de este cambio, no una regresión.
Traducción automática al español (DeepSeek) de la documentación original de OCA; los comandos y el código no se traducen. Sin información verificada en OCA: Instalación, Configuración.
Las instrucciones de instalación, el paquete de distribución, las dependencias y los pasos de configuración no se muestran porque todavía no se han verificado en la documentación del módulo para ninguna versión.
Datos importados de GitHub: esta ficha refleja la última revisión del catálogo, no una consulta en directo. Verifica siempre en la documentación del módulo y en staging antes de instalar en producción.