arancel-mx

Datos arancelarios de México, reproducibles, auditables y trazables

Herramientas abiertas en Python para capturar, normalizar, reconciliar y publicar datos arancelarios de México con procedencia verificable.

Español · English

Instalación · CLI · Python · Datos · Fuentes · Automatización · Certificación · Contribuir

Captura · Reconcilia · Normaliza · Valida · Publica

Alcance

arancel-mx es un proyecto público enfocado en construir una capa de datos abierta, reproducible y auditable para la LIGIE, NICO y sus fuentes oficiales. El núcleo público prioriza datos, procedencia documental, validación, DuckDB y artefactos reproducibles; no pretende reemplazar un sistema comercial completo de comercio exterior.

Licencia del proyecto: Apache-2.0.

[!IMPORTANT] arancel-mx es una herramienta técnica y de datos. No constituye asesoría legal. Para decisiones de clasificación arancelaria, cumplimiento regulatorio, importación o exportación deben consultarse las fuentes oficiales aplicables y, cuando corresponda, profesionales especializados.

Resumen rápido

• Captura snapshots registrados de Diputados, DOF y SNICE con SHA256 y retrieved_at real.
• Reconcilia evidencia legal antes de permitir que un candidato sea publicable.
• Normaliza HS2, HS4, HS6, fracción MX de 8 dígitos y NICO de 10 dígitos.
• Materializa un warehouse DuckDB y exporta CSV, JSON y manifest schema v2.
• Detecta no_change sin crear releases redundantes.
• Ejecuta una revisión diaria automatizada y hace publicación automática sólo cuando el dataset cambió y todos los gates pasaron.
• Abre o actualiza un GitHub Issue cuando cualquier stage de producción falla.
• Usa releases data-YYYY.MM.DD y un contrato exacto de seis assets verificables.
• Mantiene una certificación manual aislada para probar permisos de release/Issue y verificar rollback sin tocar releases data-*.

Por qué es diferente

De HS a fracción MX y NICO

HS 2
  ↓
HS 4
  ↓
HS 6
  ↓
Fracción MX 8 dígitos
  ↓
NICO 10 dígitos

La base valida relaciones padre-hijo para evitar que una fracción quede sin HS6 o que un NICO quede sin su fracción vigente.

Arquitectura

fuentes oficiales → captura → reconciliación legal → parseo → validación
→ sin cambios: termina en verde
→ cambio válido: release inmutable verificado
→ cualquier fallo: bloquea la publicación + GitHub Issue

En términos de componentes:

Diputados / DOF / SNICE
          ↓
 source_registry + discovery
          ↓
 capture + source_capture.json
          ↓
 SHA256 + retrieved_at
          ↓
 reconciliación legal
          ↓
 parsers offline XLS/XLSX/PDF
          ↓
 normalización + validación
          ↓
 DuckDB canónico
    ↙       ↓       ↘
  CSV      JSON    manifest.json
          ↓
 six-asset verified bundle
          ↓
 GitHub Release data-YYYY.MM.DD

Instalación

Requiere Python 3.11 o superior.

Consumo del dataset publicado

La distribución pública está preparada para instalarse desde PyPI con el siguiente contrato cuando se publique el paquete:

pip install arancel-mx
arancel-mx --version
arancel-mx doctor

El paquete y los datasets se versionan por separado. arancel-mx --version muestra la versión del paquete Python; cada dataset usa una release inmutable data-YYYY.MM.DD.

Desarrollo del repositorio

Para contribuir o ejecutar el pipeline desde el checkout:

python -m venv .venv
# PowerShell: .\.venv\Scripts\Activate.ps1
# macOS/Linux: source .venv/bin/activate
python -m pip install -e ".[dev]"
python -m arancel_mx --help

Los builds oficiales y CI usan el entorno reproducible definido por requirements/production-build.txt:

python -m pip install pip==26.2.1
python -m pip install -c requirements/production-build.txt -e ".[dev]"

Uso rápido CLI

El flujo para consumidores parte del dataset publicado y no requiere clonar el repositorio:

arancel-mx doctor
arancel-mx data download
arancel-mx lookup 01012101
arancel-mx ficha 01012101
arancel-mx chapters
arancel-mx search "refrigeradores"
arancel-mx data verify

Después de descargar y verificar una release, las consultas pueden operar en modo offline estricto:

arancel-mx lookup 01012101 --offline --format json
arancel-mx data verify --offline --format json

También se puede fijar una release exacta con --dataset data-YYYY.MM.DD. Consulta docs/consumer-cli.md para data status/list/update/path/verify, formatos JSON/CSV, variables de entorno, integridad del cache y el contrato de doctor.

Comandos para consumidores

Comandos de mantenimiento del repositorio

Los mantenedores conservan los comandos de construcción y publicación:

# exportar artefactos desde una base DuckDB validada
python -m arancel_mx build --database data/arancel.duckdb --output-dir out/release

# revisar el ledger oficial y escribir un reporte de cambios
python -m arancel_mx check-updates --state-path data/update_state/ligie.json --report-path out/update.json

# reconciliar evidencia
python -m arancel_mx reconcile --ledger-json ledger.json --dof-json dof.json --snice-json snice.json

# verificar y preparar un bundle local
python -m arancel_mx release --release-dir out/release --source-dir data/raw/release --latest-dir out/latest

Durante la serie 0.x, update permanece como alias de compatibilidad de sólo lectura para check-updates; la documentación nueva usa check-updates como nombre preferido.

Uso desde Python

from arancel_mx import Dataset

dataset = Dataset.latest()
card = dataset.ficha("01012101")
print(card.formatted_code, card.record.description, card.record.igi_text)
for chapter in dataset.chapters():
    print(chapter.code, chapter.description)

Dataset.open("arancel_mx.duckdb") abre un archivo local ya validado estructuralmente. ficha y chapters usan el dataset oficial verificado; no scrapean SIICEX-CAAAREM ni dumps como tigies-mx.

Modelo de datos

DuckDB separa clasificación, tasas, vigencia y procedencia. Las tablas principales incluyen source_registry, source_document, hs_code, tariff_fraction, nico, tariff_rate, canonical_record, record_provenance y dataset_release.

El manifest de release usa schema v2 y conserva, entre otros, registry_sha256, git_commit_sha, github_run_id, github_run_attempt, github_workflow_ref y github_artifact_name.

Consulta docs/data-model.md para la semántica de retrieved_at, generated_at y dataset_release.release_metadata_json.

Artefactos y reproducibilidad

Una release pública válida contiene exactamente:

release/
├── arancel_mx.duckdb
├── arancel_mx.csv
├── arancel_mx.json
├── manifest.json
├── SHA256SUMS
└── official-sources.tar.gz

manifest.json conserva versión, procedencia, reconciliación, conteos y hashes. SHA256SUMS cubre los otros cinco assets. official-sources.tar.gz conserva los bytes oficiales capturados y su source_capture.json.

La representación lógica es reproducible. El archivo físico DuckDB se verifica por SHA256 para esa construcción concreta, sin asumir que dos archivos DuckDB creados por procesos distintos sean byte a byte idénticos.

Construcción end-to-end de dataset oficial

El entrypoint público sigue disponible:

python scripts/build_official_dataset.py \
  --work-dir data/embedded/official-build \
  --output-dir out/release \
  --effective-as-of 2026-08-10 \
  --dataset-version 2026.08.10

Para producción, scripts/run_official_pipeline.py añade comparación contra el manifest anterior, diagnóstico estructurado y semántica no_change.

Pipeline oficial autónomo

El workflow Official data pipeline está definido en .github/workflows/official-data-pipeline.yml.

• Schedule: 17 11 * * *, una revisión diaria automatizada en UTC.
• workflow_dispatch: disponible para dry-run y ejecución mantenida; publish=false es el valor manual por defecto.
• Build: contents: read y tests offline antes de tocar la red.
• Publish: contents: write sólo si main produjo built y la ejecución está autorizada para mutar.
• Notify: issues: write únicamente para el lifecycle de alertas.

La publicación automática ocurre sólo para un cambio válido y verificado. Cualquier falla bloquea la publicación. Si no hubo cambios, no_change termina en verde y el publisher queda skipped.

Antes de publicar, el bundle se verifica localmente, se vuelve a verificar después de descargar el artifact y se sube a una release draft. Los seis assets remotos se comprueban antes de hacer pública la release. Un tag data-YYYY.MM.DD existente nunca se sobrescribe.

Consulta docs/release-process.md para el contrato exacto y docs/production-certification.md para el runbook de certificación de permisos y rollback.

Fuentes oficiales

El registro versionado vive en src/arancel_mx/sources/source_registry.json.

Fuentes principales:

• Diputados, LIGIE: https://www.diputados.gob.mx/LeyesBiblio/ref/ligie_2022.htm
• SNICE, LIGIE: https://www.snice.gob.mx/cs/avi/snice/ligie.info22.html
• SNICE, NICO y propuestas NICO: https://www.snice.gob.mx/cs/avi/snice/ligie.nico2022.html
• SNICE, notas nacionales: https://www.snice.gob.mx/cs/avi/snice/ligie.notasnac22.html
• SNICE, indicadores: https://www.snice.gob.mx/cs/avi/snice/ligie.indicaranc22.html
• Diario Oficial de la Federación, publicación relacionada: https://www.dof.gob.mx/nota_detalle.php?codigo=5656249&fecha=27/06/2022

docs/sources.md explica cómo el ledger registrado de Diputados se usa como ancla y cómo la evidencia DOF participa como gate antes de publicar. SIICEX-CAAAREM y dumps como tigies-mx no son fuentes oficiales.

Proceso y calendario visual

Calendario DOF, parte 1

Calendario DOF, parte 2

Flujo NICO / DOF

Estas imágenes son contexto documental y no un indicador dinámico del estado del dataset.

Estructura del repositorio

.github/
├── workflows/
│   ├── ci.yml
│   ├── official-data-pipeline.yml
│   ├── production-certification.yml
│   └── generate-demo.yml
└── dependabot.yml
requirements/
└── production-build.txt
src/arancel_mx/
├── certification/
├── pipeline/
├── release/
├── sources/
│   └── source_registry.json
└── storage/
scripts/
├── build_official_dataset.py
├── run_official_pipeline.py
├── certify_package_install.py
├── check_duckdb_compat.py
├── certify_github_release.py
├── certify_github_issue.py
├── fetch_previous_release.py
├── publish_release.py
└── data_alert.py
docs/
tests/
LICENSE
NOTICE

El repositorio conserva documentación de ingeniería en docs/superpowers/ y pruebas de distribución que buscan credenciales y rutas privadas. Los datos generados, snapshots, DuckDB locales y tokens permanecen fuera de Git.

Pruebas

python -m pytest -q
python -m build
git diff --check

El workflow se muestra como CI y el contexto exacto requerido por el ruleset de main es test. Un PR normal no hace live-update de fuentes ni publica releases.

La certificación live de permisos GitHub se ejecuta aparte mediante el workflow manual Production certification. El run 31450616908 sobre a14c57ee3aeeb982e6aa7077ae1b34582585db8b terminó verde y dejó cero drafts/tags de certificación; consulta docs/production-certification.md.

Seguridad y supply chain

• Actions externas fijadas por SHA completo.
• Dependencias de producción restringidas por requirements/production-build.txt.
• Dependabot abre PRs semanales para Python y GitHub Actions.
• El pipeline de producción usa permisos por job, no write-all.
• No usa PAT para releases.
• La automatización de demos abre PR en vez de empujar a main.
• La certificación de write-boundaries usa namespaces certification-* y [CERTIFICATION ALERT], separados de producción.

El runbook de configuración de producción está en docs/operations/github-settings.md. Ahí se documentan release immutability, el ruleset de main, el required check test, permisos de Actions y controles de Advanced Security que deben verificarse en la UI.

Ver SECURITY.md, CONTRIBUTING.md y docs/production-certification.md.

Estado del proyecto

Contribución

Las contribuciones de la comunidad de código abierto son bienvenidas. Consulta CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, LICENSE y NOTICE antes de enviar cambios.

Para cambios de fuentes, parsers, reconciliación o release contract, agrega fixtures/pruebas offline del caso esperado. Para cambios del build oficial, actualiza el lock/constraints en el mismo PR cuando corresponda.

Notas de procedencia

El proyecto conserva capture manifests y hashes para que una release pueda relacionarse con los snapshots observados. La presencia de una fuente o registro en el dataset describe evidencia técnica observada; no sustituye la publicación oficial ni una interpretación jurídica especializada.