feat(crm): rediseño profesional del PDF de cotización

Banda de encabezado, logo + emisor, título con regla, panel de datos, barras de
sección en color, tabla de costos con encabezado y filas alternadas, caja de
totales, y pie con banda. Fix: elipsis "…" -> "..." (evita "?" en latin-1);
oculta secciones sin datos; color por defecto navy.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

backend/alembic/versions/a0b1c2d3e4f5_quote_settings_and_pdf.py

@@ -0,0 +1,60 @@
+"""crm quote_settings (marca por tenant) + quotes.pdf_file_key
+
+Revision ID: a0b1c2d3e4f5
+Revises: f8a9b0c1d2e3
+Create Date: 2026-07-29 00:00:00.000000
+
+PDF de cotización con formato maestro + branding por tenant + envío por correo.
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "a0b1c2d3e4f5"
+down_revision: Union[str, None] = "f8a9b0c1d2e3"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+SCHEMA = "crm"
+
+
+def upgrade() -> None:
+    op.add_column("quotes", sa.Column("pdf_file_key", sa.String(length=512), nullable=True), schema=SCHEMA)
+
+    op.create_table(
+        "quote_settings",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("emitter_name", sa.String(length=255), nullable=True),
+        sa.Column("emitter_rfc", sa.String(length=13), nullable=True),
+        sa.Column("emitter_address", sa.Text(), nullable=True),
+        sa.Column("emitter_phone", sa.String(length=60), nullable=True),
+        sa.Column("emitter_email", sa.String(length=255), nullable=True),
+        sa.Column("emitter_website", sa.String(length=255), nullable=True),
+        sa.Column("logo_file_key", sa.String(length=512), nullable=True),
+        sa.Column("accent_color", sa.String(length=9), nullable=True, server_default=sa.text("'#2f6bf0'")),
+        sa.Column("quote_prefix", sa.String(length=12), nullable=True, server_default=sa.text("'COT'")),
+        sa.Column("default_terms", sa.Text(), nullable=True),
+        sa.Column("footer_note", sa.Text(), nullable=True),
+        sa.Column("tenant_id", sa.Integer(), nullable=False),
+        sa.Column("company_id", sa.Integer(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.text("now()")),
+        sa.Column("deleted_at", sa.DateTime(), nullable=True),
+        sa.PrimaryKeyConstraint("id"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["core.tenants.id"]),
+        schema=SCHEMA,
+    )
+    op.create_index("ix_crm_quote_settings_id", "quote_settings", ["id"], schema=SCHEMA)
+    op.create_index("ix_crm_quote_settings_tenant_id", "quote_settings", ["tenant_id"], schema=SCHEMA)
+    op.create_index("ix_crm_quote_settings_company_id", "quote_settings", ["company_id"], schema=SCHEMA)
+    # Una configuración por compañía
+    op.create_index(
+        "uq_crm_quote_settings_company", "quote_settings", ["tenant_id", "company_id"],
+        unique=True, schema=SCHEMA, postgresql_where=sa.text("deleted_at IS NULL"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("quote_settings", schema=SCHEMA)
+    op.drop_column("quotes", "pdf_file_key", schema=SCHEMA)

backend/alembic/versions/e6f7a8b9c0d1_crm_catalog_items.py

@@ -0,0 +1,90 @@
+"""crm catalog_items (catálogos de referencia) + columnas nuevas accounts/suppliers
+
+Revision ID: e6f7a8b9c0d1
+Revises: d5e6f7a8b9c0
+Create Date: 2026-07-22 00:00:00.000000
+
+Soporta T2026-07-081 (Clientes/Prospectos) y T2026-07-082 (Proveedores):
+catálogos de referencia SAT/ISO + propios del cliente, y campos faltantes
+(observaciones comerciales, "otro" de medio de contacto y de clasificación).
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "e6f7a8b9c0d1"
+down_revision: Union[str, None] = "d5e6f7a8b9c0"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+SCHEMA = "crm"
+
+
+def upgrade() -> None:
+    # ----- crm.catalog_items -----
+    op.create_table(
+        "catalog_items",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("catalog", sa.String(length=60), nullable=False),
+        sa.Column("code", sa.String(length=64), nullable=False),
+        sa.Column("label", sa.String(length=255), nullable=False),
+        sa.Column("parent_catalog", sa.String(length=60), nullable=True),
+        sa.Column("parent_code", sa.String(length=64), nullable=True),
+        # NULL = catálogo global (Aduanasoft); con valor = catálogo del tenant.
+        sa.Column("tenant_id", sa.Integer(), nullable=True),
+        sa.Column("sort_order", sa.Integer(), nullable=False, server_default=sa.text("0")),
+        sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.text("true")),
+        sa.Column("is_system", sa.Boolean(), nullable=False, server_default=sa.text("false")),
+        sa.Column("extra", sa.JSON(), nullable=True),
+        sa.Column("created_by", sa.String(length=64), nullable=True),
+        sa.Column("updated_by", sa.String(length=64), nullable=True),
+        sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.text("now()")),
+        sa.PrimaryKeyConstraint("id"),
+        schema=SCHEMA,
+    )
+    op.create_index("ix_crm_catalog_items_id", "catalog_items", ["id"], schema=SCHEMA)
+    op.create_index("ix_crm_catalog_items_catalog", "catalog_items", ["catalog"], schema=SCHEMA)
+    op.create_index("ix_crm_catalog_items_tenant_id", "catalog_items", ["tenant_id"], schema=SCHEMA)
+    op.create_index(
+        "ix_crm_catalog_items_lookup", "catalog_items", ["catalog", "tenant_id", "is_active"], schema=SCHEMA
+    )
+    # Unicidad de clave por catálogo: global (tenant NULL) y por tenant, separadas.
+    op.create_index(
+        "uq_crm_catalog_items_global",
+        "catalog_items",
+        ["catalog", "code"],
+        unique=True,
+        schema=SCHEMA,
+        postgresql_where=sa.text("tenant_id IS NULL"),
+    )
+    op.create_index(
+        "uq_crm_catalog_items_tenant",
+        "catalog_items",
+        ["catalog", "code", "tenant_id"],
+        unique=True,
+        schema=SCHEMA,
+        postgresql_where=sa.text("tenant_id IS NOT NULL"),
+    )
+
+    # ----- columnas nuevas -----
+    # Clientes/Prospectos: observaciones comerciales + "otro" del medio de contacto.
+    op.add_column("accounts", sa.Column("commercial_observations", sa.Text(), nullable=True), schema=SCHEMA)
+    op.add_column("accounts", sa.Column("preferred_contact_other", sa.String(length=120), nullable=True), schema=SCHEMA)
+    # Proveedores: "otro" de la clasificación múltiple.
+    op.add_column("suppliers", sa.Column("classification_other", sa.String(length=120), nullable=True), schema=SCHEMA)
+
+
+def downgrade() -> None:
+    op.drop_column("suppliers", "classification_other", schema=SCHEMA)
+    op.drop_column("accounts", "preferred_contact_other", schema=SCHEMA)
+    op.drop_column("accounts", "commercial_observations", schema=SCHEMA)
+
+    op.drop_index("uq_crm_catalog_items_tenant", table_name="catalog_items", schema=SCHEMA)
+    op.drop_index("uq_crm_catalog_items_global", table_name="catalog_items", schema=SCHEMA)
+    op.drop_index("ix_crm_catalog_items_lookup", table_name="catalog_items", schema=SCHEMA)
+    op.drop_index("ix_crm_catalog_items_tenant_id", table_name="catalog_items", schema=SCHEMA)
+    op.drop_index("ix_crm_catalog_items_catalog", table_name="catalog_items", schema=SCHEMA)
+    op.drop_index("ix_crm_catalog_items_id", table_name="catalog_items", schema=SCHEMA)
+    op.drop_table("catalog_items", schema=SCHEMA)

backend/alembic/versions/e6f7a8b9c0d1_fin_sat_catalogs_concepts_issuer.py

@@ -1,269 +0,0 @@
-"""Catálogos SAT (schema sat), conceptos de facturación, datos fiscales del emisor
-y amarre de facturas y partidas a los catálogos.
-
-Revision ID: e6f7a8b9c0d1
-Revises: d5e6f7a8b9c0
-Create Date: 2026-08-07 00:00:00.000000
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-from api.v1.modules.fin.catalogs.seed_data import sync_catalogs
-
-revision: str = "e6f7a8b9c0d1"
-down_revision: Union[str, None] = "d5e6f7a8b9c0"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-# Índices únicos parciales: la baja lógica (deleted_at) libera la clave.
-_ALIVE = "deleted_at IS NULL"
-
-# Catálogos del SAT: (tabla, longitud de code, columnas propias del catálogo).
-_SAT_CATALOGS: list[tuple[str, int, list[sa.Column]]] = [
-    ("tax_regimes", 3, [
-        sa.Column("applies_to_individual", sa.Boolean(), nullable=False, server_default=sa.text("false")),
-        sa.Column("applies_to_legal_entity", sa.Boolean(), nullable=False, server_default=sa.text("false")),
-    ]),
-    ("taxes", 3, [
-        sa.Column("is_withholding", sa.Boolean(), nullable=False, server_default=sa.text("false")),
-        sa.Column("is_transferred", sa.Boolean(), nullable=False, server_default=sa.text("false")),
-        sa.Column("is_local", sa.Boolean(), nullable=False, server_default=sa.text("false")),
-    ]),
-    ("payment_forms", 2, []),
-    ("units_of_measure", 20, [
-        sa.Column("name", sa.String(length=255), nullable=False),
-        sa.Column("symbol", sa.String(length=20), nullable=True),
-    ]),
-    ("products_services", 8, []),
-    ("voucher_types", 1, []),
-    ("payment_methods", 3, []),
-    ("tax_objects", 2, []),
-]
-
-# units_of_measure guarda el nombre corto aparte, así que su description es opcional.
-_NULLABLE_DESCRIPTION = {"units_of_measure"}
-
-
-def _timestamp_columns(with_soft_delete: bool) -> list[sa.Column]:
-    columns = [
-        sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.text("now()")),
-        sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.text("now()")),
-    ]
-    if with_soft_delete:
-        columns.append(sa.Column("deleted_at", sa.DateTime(), nullable=True))
-    return columns
-
-
-def upgrade() -> None:
-    # ---------- Schema y catálogos globales del SAT ----------
-    op.execute("CREATE SCHEMA IF NOT EXISTS sat")
-
-    for table, code_length, extra_columns in _SAT_CATALOGS:
-        op.create_table(
-            table,
-            sa.Column("id", sa.Integer(), nullable=False),
-            sa.Column("code", sa.String(length=code_length), nullable=False),
-            sa.Column(
-                "description",
-                sa.String(length=500),
-                nullable=table in _NULLABLE_DESCRIPTION,
-            ),
-            sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.text("true")),
-            *extra_columns,
-            *_timestamp_columns(with_soft_delete=False),
-            sa.PrimaryKeyConstraint("id"),
-            schema="sat",
-        )
-        op.create_index(f"ix_sat_{table}_id", table, ["id"], schema="sat")
-        # La clave oficial del SAT es única dentro de su catálogo.
-        op.create_index(f"ix_sat_{table}_code", table, ["code"], unique=True, schema="sat")
-
-    # Semillas de los catálogos (idempotente: puede volver a correrse sin duplicar).
-    sync_catalogs(op.get_bind())
-
-    # ---------- fin.concepts ----------
-    op.create_table(
-        "concepts",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("tenant_id", sa.Integer(), nullable=False),
-        sa.Column("company_id", sa.Integer(), nullable=False),
-        sa.Column("code", sa.String(length=40), nullable=False),
-        sa.Column("description", sa.String(length=500), nullable=False),
-        sa.Column("product_service_id", sa.Integer(), nullable=False),
-        sa.Column("unit_of_measure_id", sa.Integer(), nullable=True),
-        sa.Column("tax_object_id", sa.Integer(), nullable=True),
-        sa.Column("unit_price", sa.Numeric(precision=14, scale=2), nullable=True),
-        sa.Column("currency", sa.String(length=3), nullable=False, server_default=sa.text("'MXN'")),
-        sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.text("true")),
-        sa.Column("notes", sa.Text(), nullable=True),
-        sa.Column("created_by", sa.String(length=64), nullable=True),
-        sa.Column("updated_by", sa.String(length=64), nullable=True),
-        *_timestamp_columns(with_soft_delete=True),
-        sa.PrimaryKeyConstraint("id"),
-        sa.ForeignKeyConstraint(["tenant_id"], ["core.tenants.id"], name="fk_fin_concepts_tenant_id"),
-        sa.ForeignKeyConstraint(
-            ["product_service_id"], ["sat.products_services.id"], name="fk_fin_concepts_product_service_id"
-        ),
-        sa.ForeignKeyConstraint(
-            ["unit_of_measure_id"], ["sat.units_of_measure.id"], name="fk_fin_concepts_unit_of_measure_id"
-        ),
-        sa.ForeignKeyConstraint(
-            ["tax_object_id"], ["sat.tax_objects.id"], name="fk_fin_concepts_tax_object_id"
-        ),
-        schema="fin",
-    )
-    op.create_index("ix_fin_concepts_id", "concepts", ["id"], schema="fin")
-    op.create_index("ix_fin_concepts_tenant_id", "concepts", ["tenant_id"], schema="fin")
-    op.create_index("ix_fin_concepts_company_id", "concepts", ["company_id"], schema="fin")
-    op.create_index("ix_fin_concepts_product_service_id", "concepts", ["product_service_id"], schema="fin")
-    # La clave interna del concepto es única por empresa.
-    op.create_index(
-        "uq_fin_concepts_code", "concepts", ["tenant_id", "company_id", "code"],
-        unique=True, schema="fin", postgresql_where=sa.text(_ALIVE),
-    )
-    # Relación 1:1 con c_ClaveProdServ: una clave del SAT no puede repetirse entre
-    # los conceptos vigentes de la misma empresa.
-    op.create_index(
-        "uq_fin_concepts_product_service", "concepts", ["tenant_id", "company_id", "product_service_id"],
-        unique=True, schema="fin", postgresql_where=sa.text(_ALIVE),
-    )
-
-    # ---------- fin.issuer_settings ----------
-    op.create_table(
-        "issuer_settings",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("tenant_id", sa.Integer(), nullable=False),
-        sa.Column("company_id", sa.Integer(), nullable=False),
-        sa.Column("legal_name", sa.String(length=255), nullable=False),
-        sa.Column("rfc", sa.String(length=13), nullable=False),
-        sa.Column("tax_regime_id", sa.Integer(), nullable=False),
-        sa.Column("zip_code", sa.String(length=5), nullable=True),
-        sa.Column("updated_by", sa.String(length=64), nullable=True),
-        *_timestamp_columns(with_soft_delete=True),
-        sa.PrimaryKeyConstraint("id"),
-        sa.ForeignKeyConstraint(["tenant_id"], ["core.tenants.id"], name="fk_fin_issuer_settings_tenant_id"),
-        sa.ForeignKeyConstraint(
-            ["tax_regime_id"], ["sat.tax_regimes.id"], name="fk_fin_issuer_settings_tax_regime_id"
-        ),
-        schema="fin",
-    )
-    op.create_index("ix_fin_issuer_settings_id", "issuer_settings", ["id"], schema="fin")
-    op.create_index("ix_fin_issuer_settings_tenant_id", "issuer_settings", ["tenant_id"], schema="fin")
-    op.create_index("ix_fin_issuer_settings_company_id", "issuer_settings", ["company_id"], schema="fin")
-    op.create_index("ix_fin_issuer_settings_tax_regime_id", "issuer_settings", ["tax_regime_id"], schema="fin")
-    # Una sola configuración fiscal vigente por empresa.
-    op.create_index(
-        "uq_fin_issuer_settings_company", "issuer_settings", ["tenant_id", "company_id"],
-        unique=True, schema="fin", postgresql_where=sa.text(_ALIVE),
-    )
-
-    # ---------- fin.invoice_item_taxes ----------
-    op.create_table(
-        "invoice_item_taxes",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("tenant_id", sa.Integer(), nullable=False),
-        sa.Column("company_id", sa.Integer(), nullable=False),
-        sa.Column("invoice_item_id", sa.Integer(), nullable=False),
-        sa.Column("tax_id", sa.Integer(), nullable=False),
-        sa.Column("is_withholding", sa.Boolean(), nullable=False, server_default=sa.text("false")),
-        sa.Column("rate", sa.Numeric(precision=8, scale=6), nullable=True),
-        sa.Column("amount", sa.Numeric(precision=14, scale=2), nullable=False, server_default=sa.text("0")),
-        *_timestamp_columns(with_soft_delete=True),
-        sa.PrimaryKeyConstraint("id"),
-        sa.ForeignKeyConstraint(["tenant_id"], ["core.tenants.id"], name="fk_fin_invoice_item_taxes_tenant_id"),
-        sa.ForeignKeyConstraint(
-            ["invoice_item_id"], ["fin.invoice_items.id"], name="fk_fin_invoice_item_taxes_invoice_item_id"
-        ),
-        sa.ForeignKeyConstraint(["tax_id"], ["sat.taxes.id"], name="fk_fin_invoice_item_taxes_tax_id"),
-        schema="fin",
-    )
-    op.create_index("ix_fin_invoice_item_taxes_id", "invoice_item_taxes", ["id"], schema="fin")
-    op.create_index("ix_fin_invoice_item_taxes_tenant_id", "invoice_item_taxes", ["tenant_id"], schema="fin")
-    op.create_index("ix_fin_invoice_item_taxes_company_id", "invoice_item_taxes", ["company_id"], schema="fin")
-    op.create_index(
-        "ix_fin_invoice_item_taxes_invoice_item_id", "invoice_item_taxes", ["invoice_item_id"], schema="fin"
-    )
-    # Un mismo impuesto no puede declararse dos veces con el mismo rol en la partida.
-    op.create_index(
-        "uq_fin_invoice_item_taxes", "invoice_item_taxes", ["invoice_item_id", "tax_id", "is_withholding"],
-        unique=True, schema="fin", postgresql_where=sa.text(_ALIVE),
-    )
-
-    # ---------- fin.invoices: claves fiscales del comprobante ----------
-    # Todas nullable: las facturas ya emitidas no tienen estos datos.
-    op.add_column("invoices", sa.Column("voucher_type_id", sa.Integer(), nullable=True), schema="fin")
-    op.add_column("invoices", sa.Column("payment_form_id", sa.Integer(), nullable=True), schema="fin")
-    op.add_column("invoices", sa.Column("payment_method_id", sa.Integer(), nullable=True), schema="fin")
-    op.add_column("invoices", sa.Column("expedition_zip_code", sa.String(length=5), nullable=True), schema="fin")
-    op.create_foreign_key(
-        "fk_fin_invoices_voucher_type_id", "invoices", "voucher_types",
-        ["voucher_type_id"], ["id"], source_schema="fin", referent_schema="sat",
-    )
-    op.create_foreign_key(
-        "fk_fin_invoices_payment_form_id", "invoices", "payment_forms",
-        ["payment_form_id"], ["id"], source_schema="fin", referent_schema="sat",
-    )
-    op.create_foreign_key(
-        "fk_fin_invoices_payment_method_id", "invoices", "payment_methods",
-        ["payment_method_id"], ["id"], source_schema="fin", referent_schema="sat",
-    )
-
-    # ---------- fin.invoice_items: claves fiscales de la partida ----------
-    # La columna de texto libre `concept` se conserva intacta y obligatoria: la usa el
-    # PDF actual de la factura.
-    op.add_column("invoice_items", sa.Column("concept_id", sa.Integer(), nullable=True), schema="fin")
-    op.add_column("invoice_items", sa.Column("product_service_id", sa.Integer(), nullable=True), schema="fin")
-    op.add_column("invoice_items", sa.Column("unit_of_measure_id", sa.Integer(), nullable=True), schema="fin")
-    op.add_column("invoice_items", sa.Column("tax_object_id", sa.Integer(), nullable=True), schema="fin")
-    op.create_index("ix_fin_invoice_items_concept_id", "invoice_items", ["concept_id"], schema="fin")
-    op.create_foreign_key(
-        "fk_fin_invoice_items_concept_id", "invoice_items", "concepts",
-        ["concept_id"], ["id"], source_schema="fin", referent_schema="fin",
-    )
-    op.create_foreign_key(
-        "fk_fin_invoice_items_product_service_id", "invoice_items", "products_services",
-        ["product_service_id"], ["id"], source_schema="fin", referent_schema="sat",
-    )
-    op.create_foreign_key(
-        "fk_fin_invoice_items_unit_of_measure_id", "invoice_items", "units_of_measure",
-        ["unit_of_measure_id"], ["id"], source_schema="fin", referent_schema="sat",
-    )
-    op.create_foreign_key(
-        "fk_fin_invoice_items_tax_object_id", "invoice_items", "tax_objects",
-        ["tax_object_id"], ["id"], source_schema="fin", referent_schema="sat",
-    )
-
-
-def downgrade() -> None:
-    # fin.invoice_items
-    for constraint in (
-        "fk_fin_invoice_items_tax_object_id",
-        "fk_fin_invoice_items_unit_of_measure_id",
-        "fk_fin_invoice_items_product_service_id",
-        "fk_fin_invoice_items_concept_id",
-    ):
-        op.drop_constraint(constraint, "invoice_items", schema="fin", type_="foreignkey")
-    op.drop_index("ix_fin_invoice_items_concept_id", table_name="invoice_items", schema="fin")
-    for column in ("tax_object_id", "unit_of_measure_id", "product_service_id", "concept_id"):
-        op.drop_column("invoice_items", column, schema="fin")
-
-    # fin.invoices
-    for constraint in (
-        "fk_fin_invoices_payment_method_id",
-        "fk_fin_invoices_payment_form_id",
-        "fk_fin_invoices_voucher_type_id",
-    ):
-        op.drop_constraint(constraint, "invoices", schema="fin", type_="foreignkey")
-    for column in ("expedition_zip_code", "payment_method_id", "payment_form_id", "voucher_type_id"):
-        op.drop_column("invoices", column, schema="fin")
-
-    # Tablas nuevas (los índices caen con la tabla).
-    op.drop_table("invoice_item_taxes", schema="fin")
-    op.drop_table("issuer_settings", schema="fin")
-    op.drop_table("concepts", schema="fin")
-
-    # Catálogos del SAT: se va el schema completo.
-    op.execute("DROP SCHEMA IF EXISTS sat CASCADE")

backend/alembic/versions/e7f8a9b0c1d2_widen_address_country.py

@@ -0,0 +1,44 @@
+"""ampliar crm.addresses.country a 3 (país ISO alfa-3 del catálogo)
+
+Revision ID: e7f8a9b0c1d2
+Revises: e6f7a8b9c0d1
+Create Date: 2026-07-22 00:30:00.000000
+
+El catálogo de País usa códigos ISO 3166 alfa-3 (MEX, USA, …). La columna
+addresses.country era String(2); se amplía a String(3) para almacenarlos.
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "e7f8a9b0c1d2"
+down_revision: Union[str, None] = "e6f7a8b9c0d1"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+SCHEMA = "crm"
+
+
+def upgrade() -> None:
+    op.alter_column(
+        "addresses", "country",
+        type_=sa.String(length=3),
+        existing_type=sa.String(length=2),
+        existing_nullable=True,
+        server_default=sa.text("'MEX'"),
+        schema=SCHEMA,
+    )
+
+
+def downgrade() -> None:
+    # Trunca a 2 chars por si hay códigos alfa-3 guardados (rollback de dev).
+    op.execute("UPDATE crm.addresses SET country = left(country, 2) WHERE length(country) > 2")
+    op.alter_column(
+        "addresses", "country",
+        type_=sa.String(length=2),
+        existing_type=sa.String(length=3),
+        existing_nullable=True,
+        server_default=sa.text("'MX'"),
+        schema=SCHEMA,
+    )

backend/alembic/versions/f7a8b9c0d1e2_sat_cfdi_uses_and_account_fiscal_fks.py

@@ -1,84 +0,0 @@
-"""Catálogo c_UsoCFDI y claves fiscales del receptor en crm.accounts.
-
-Cierra las decisiones pendientes 1 y 5 del ticket de catálogos SAT: agrega
-``sat.cfdi_uses`` y amarra el régimen fiscal y el uso de CFDI de la cuenta a los
-catálogos, conservando las columnas de texto libre que ya existían.
-
-Revision ID: f7a8b9c0d1e2
-Revises: e6f7a8b9c0d1
-Create Date: 2026-08-07 00:00:00.000000
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-from api.v1.modules.fin.catalogs.seed_data import sync_catalogs
-
-revision: str = "f7a8b9c0d1e2"
-down_revision: Union[str, None] = "e6f7a8b9c0d1"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # ---------- sat.cfdi_uses ----------
-    op.create_table(
-        "cfdi_uses",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("code", sa.String(length=4), nullable=False),
-        sa.Column("description", sa.String(length=500), nullable=False),
-        sa.Column("is_active", sa.Boolean(), nullable=False, server_default=sa.text("true")),
-        sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.text("now()")),
-        sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.text("now()")),
-        sa.PrimaryKeyConstraint("id"),
-        schema="sat",
-    )
-    op.create_index("ix_sat_cfdi_uses_id", "cfdi_uses", ["id"], schema="sat")
-    op.create_index("ix_sat_cfdi_uses_code", "cfdi_uses", ["code"], unique=True, schema="sat")
-
-    # sync_catalogs es idempotente: siembra c_UsoCFDI y deja intactos los catálogos
-    # que ya sembró la migración anterior.
-    sync_catalogs(op.get_bind())
-
-    # ---------- crm.accounts: claves fiscales del receptor ----------
-    # Nullables: las cuentas existentes solo tienen el texto libre.
-    op.add_column("accounts", sa.Column("tax_regime_id", sa.Integer(), nullable=True), schema="crm")
-    op.add_column("accounts", sa.Column("cfdi_use_id", sa.Integer(), nullable=True), schema="crm")
-    op.create_foreign_key(
-        "fk_crm_accounts_tax_regime_id", "accounts", "tax_regimes",
-        ["tax_regime_id"], ["id"], source_schema="crm", referent_schema="sat",
-    )
-    op.create_foreign_key(
-        "fk_crm_accounts_cfdi_use_id", "accounts", "cfdi_uses",
-        ["cfdi_use_id"], ["id"], source_schema="crm", referent_schema="sat",
-    )
-
-    # Backfill conservador: solo resuelve lo inequívoco. Se compara el texto libre
-    # contra la clave del catálogo (p. ej. "601", "G03") y contra la descripción
-    # exacta, sin distinguir mayúsculas ni espacios sobrantes. Lo que no case así se
-    # queda en NULL para que lo revise el usuario: adivinar el régimen de un receptor
-    # a partir de texto libre provoca CFDI rechazados.
-    for column, catalog in [("tax_regime", "tax_regimes"), ("cfdi_use", "cfdi_uses")]:
-        op.execute(
-            f"""
-            UPDATE crm.accounts AS a
-               SET {column}_id = c.id
-              FROM sat.{catalog} AS c
-             WHERE a.{column}_id IS NULL
-               AND a.{column} IS NOT NULL
-               AND (
-                     upper(btrim(a.{column})) = upper(c.code)
-                  OR upper(btrim(a.{column})) = upper(c.description)
-               )
-            """
-        )
-
-
-def downgrade() -> None:
-    op.drop_constraint("fk_crm_accounts_cfdi_use_id", "accounts", schema="crm", type_="foreignkey")
-    op.drop_constraint("fk_crm_accounts_tax_regime_id", "accounts", schema="crm", type_="foreignkey")
-    op.drop_column("accounts", "cfdi_use_id", schema="crm")
-    op.drop_column("accounts", "tax_regime_id", schema="crm")
-    op.drop_table("cfdi_uses", schema="sat")

backend/alembic/versions/f8a9b0c1d2e3_crm_rates.py

@@ -0,0 +1,131 @@
+"""crm rates: tarifarios (rate_sheets/lanes/breaks/charges)
+
+Revision ID: f8a9b0c1d2e3
+Revises: e7f8a9b0c1d2
+Create Date: 2026-07-27 00:00:00.000000
+
+Módulo Tarifario: base de costos para Cotizaciones (import por Excel + motor de costeo).
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "f8a9b0c1d2e3"
+down_revision: Union[str, None] = "e7f8a9b0c1d2"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+SCHEMA = "crm"
+
+
+def _scoped() -> list[sa.Column]:
+    return [
+        sa.Column("tenant_id", sa.Integer(), nullable=False),
+        sa.Column("company_id", sa.Integer(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.text("now()")),
+        sa.Column("updated_at", sa.DateTime(), nullable=False, server_default=sa.text("now()")),
+        sa.Column("deleted_at", sa.DateTime(), nullable=True),
+    ]
+
+
+def _idx(table: str) -> None:
+    op.create_index(f"ix_{SCHEMA}_{table}_id", table, ["id"], schema=SCHEMA)
+    op.create_index(f"ix_{SCHEMA}_{table}_tenant_id", table, ["tenant_id"], schema=SCHEMA)
+    op.create_index(f"ix_{SCHEMA}_{table}_company_id", table, ["company_id"], schema=SCHEMA)
+
+
+def upgrade() -> None:
+    # ----- rate_sheets -----
+    op.create_table(
+        "rate_sheets",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("supplier_id", sa.Integer(), nullable=True),
+        sa.Column("mode", sa.String(length=20), nullable=False),
+        sa.Column("name", sa.String(length=255), nullable=False),
+        sa.Column("currency", sa.String(length=3), nullable=True, server_default=sa.text("'USD'")),
+        sa.Column("valid_from", sa.Date(), nullable=True),
+        sa.Column("valid_to", sa.Date(), nullable=True),
+        sa.Column("default_origin", sa.String(length=20), nullable=True),
+        sa.Column("status", sa.String(length=20), nullable=False, server_default=sa.text("'borrador'")),
+        sa.Column("source_file", sa.String(length=512), nullable=True),
+        sa.Column("source_url", sa.String(length=1024), nullable=True),
+        sa.Column("notes", sa.Text(), nullable=True),
+        sa.Column("created_by", sa.String(length=64), nullable=True),
+        sa.Column("updated_by", sa.String(length=64), nullable=True),
+        *_scoped(),
+        sa.PrimaryKeyConstraint("id"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["core.tenants.id"]),
+        sa.ForeignKeyConstraint(["supplier_id"], [f"{SCHEMA}.suppliers.id"]),
+        schema=SCHEMA,
+    )
+    _idx("rate_sheets")
+    op.create_index("ix_crm_rate_sheets_mode", "rate_sheets", ["mode"], schema=SCHEMA)
+    op.create_index("ix_crm_rate_sheets_supplier_id", "rate_sheets", ["supplier_id"], schema=SCHEMA)
+
+    # ----- rate_lanes -----
+    op.create_table(
+        "rate_lanes",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("rate_sheet_id", sa.Integer(), nullable=False),
+        sa.Column("origin", sa.String(length=20), nullable=True),
+        sa.Column("destination", sa.String(length=20), nullable=True),
+        sa.Column("region", sa.String(length=60), nullable=True),
+        sa.Column("equipment_type", sa.String(length=20), nullable=True),
+        sa.Column("rate_unit", sa.String(length=20), nullable=True),
+        sa.Column("min_charge", sa.Numeric(precision=14, scale=4), nullable=True),
+        sa.Column("flat_rate", sa.Numeric(precision=14, scale=4), nullable=True),
+        sa.Column("transit_days", sa.Integer(), nullable=True),
+        sa.Column("notes", sa.Text(), nullable=True),
+        *_scoped(),
+        sa.PrimaryKeyConstraint("id"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["core.tenants.id"]),
+        sa.ForeignKeyConstraint(["rate_sheet_id"], [f"{SCHEMA}.rate_sheets.id"]),
+        schema=SCHEMA,
+    )
+    _idx("rate_lanes")
+    op.create_index("ix_crm_rate_lanes_rate_sheet_id", "rate_lanes", ["rate_sheet_id"], schema=SCHEMA)
+    op.create_index("ix_crm_rate_lanes_origin", "rate_lanes", ["origin"], schema=SCHEMA)
+    op.create_index("ix_crm_rate_lanes_destination", "rate_lanes", ["destination"], schema=SCHEMA)
+
+    # ----- rate_breaks -----
+    op.create_table(
+        "rate_breaks",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("rate_lane_id", sa.Integer(), nullable=False),
+        sa.Column("from_qty", sa.Numeric(precision=12, scale=3), nullable=False, server_default=sa.text("0")),
+        sa.Column("rate", sa.Numeric(precision=14, scale=4), nullable=False, server_default=sa.text("0")),
+        *_scoped(),
+        sa.PrimaryKeyConstraint("id"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["core.tenants.id"]),
+        sa.ForeignKeyConstraint(["rate_lane_id"], [f"{SCHEMA}.rate_lanes.id"]),
+        schema=SCHEMA,
+    )
+    _idx("rate_breaks")
+    op.create_index("ix_crm_rate_breaks_rate_lane_id", "rate_breaks", ["rate_lane_id"], schema=SCHEMA)
+
+    # ----- rate_charges -----
+    op.create_table(
+        "rate_charges",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("rate_sheet_id", sa.Integer(), nullable=True),
+        sa.Column("rate_lane_id", sa.Integer(), nullable=True),
+        sa.Column("concept", sa.String(length=60), nullable=False),
+        sa.Column("charge_type", sa.String(length=20), nullable=False, server_default=sa.text("'fijo'")),
+        sa.Column("value", sa.Numeric(precision=14, scale=4), nullable=True),
+        sa.Column("condition", sa.Text(), nullable=True),
+        *_scoped(),
+        sa.PrimaryKeyConstraint("id"),
+        sa.ForeignKeyConstraint(["tenant_id"], ["core.tenants.id"]),
+        sa.ForeignKeyConstraint(["rate_sheet_id"], [f"{SCHEMA}.rate_sheets.id"]),
+        sa.ForeignKeyConstraint(["rate_lane_id"], [f"{SCHEMA}.rate_lanes.id"]),
+        schema=SCHEMA,
+    )
+    _idx("rate_charges")
+
+
+def downgrade() -> None:
+    op.drop_table("rate_charges", schema=SCHEMA)
+    op.drop_table("rate_breaks", schema=SCHEMA)
+    op.drop_table("rate_lanes", schema=SCHEMA)
+    op.drop_table("rate_sheets", schema=SCHEMA)

backend/api/v1/modules/core/auth/dto.py

@@ -36,6 +36,12 @@ class TokenResponseDTO(BaseModel):
     tenant: Optional["TenantInfoDTO"] = None
     tenant_id: Optional[int] = None
     tenant_slug: Optional[str] = None
+    # Sesión local del CRM (patrón SIWEB) — presente solo con SESSION_STORE_ENABLED.
+    # Es un JWT propio (HS256) que la app usa como bearer para el backend del CRM y
+    # que sobrevive aunque el refresh del token KC contra el Hub falle. El access_token
+    # de arriba sigue siendo el de Keycloak (para llamadas al Hub).
+    session_token: Optional[str] = None
+    session_id: Optional[str] = None
 
     class Config:
         json_schema_extra = {
@@ -52,6 +58,12 @@ class RefreshTokenRequestDTO(BaseModel):
     """DTO para solicitud de refresh token"""
 
     refresh_token: str = Field(..., description="Refresh token")
+    # Sesión local actual del CRM (patrón SIWEB). Si se envía, el backend preserva el
+    # inicio de sesión (cap absoluto) y puede re-emitirla como fallback cuando el
+    # refresh del token KC contra el Hub falla ("Token is not active" del relay).
+    session_token: Optional[str] = Field(None, description="Sesión local actual del CRM (opcional)")
+    # session_id opaco de la sesión en valkey (guarda los tokens KC fuera del browser).
+    session_id: Optional[str] = Field(None, description="ID de sesión en valkey (opcional)")
 
 
 class UserInfoResponseDTO(BaseModel):

backend/api/v1/modules/core/auth/routes.py

@@ -24,6 +24,12 @@ from .dto import (
 )
 from .service import AuthService
 
+import logging
+from typing import Optional
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
 router = APIRouter(prefix="/auth", tags=["Authentication"])
 security = HTTPBearer()
 
@@ -402,10 +408,16 @@ async def dev_login():
 @router.get("/my-companies")
 async def get_my_companies(
     current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
 ):
     """
     Retorna las compañías accesibles para el usuario actual.
-    STUB: implementa con tu modelo de compañías.
+
+    Modelo del CRM: una compañía por tenant (1:1) — el ``company_id`` coincide con
+    el ``tenant_id``. Cada agente de carga (tenant) opera como una empresa. Se
+    garantiza el vínculo usuario↔tenant↔company; los permisos de la empresa se
+    resuelven en ``/permissions/me`` (bootstrap de super_admin al primer usuario).
+
     En dev-local retorna una compañía ficticia para que el dashboard funcione.
     """
     from core.config import settings
@@ -415,8 +427,239 @@ async def get_my_companies(
             "id": settings.DEV_LOCAL_AUTH_COMPANY_ID,
             "name": "Empresa Dev Local",
             "tenant_id": settings.DEV_LOCAL_AUTH_TENANT_ID,
+            "rfc": None,
+            "logo": None,
             "is_active": True,
         }]
 
-    # Implementa aquí la consulta real a tu tabla de compañías.
+    from core.security import (
+        resolve_effective_tenant_id_from_user,
+        _ensure_user_tenant_for_company,
+    )
+    from api.v1.modules.core.tenants.models import Tenant
+    from sqlalchemy import text
+
+    user_id = current_user.get("sub") or current_user.get("id")
+    tenant_id = resolve_effective_tenant_id_from_user(current_user)
+
+    # 1) Usuario CON tenant en el token (flujo normal): autocrea una compañía por
+    #    defecto en el primer acceso y AUTO-LIGA al usuario a TODAS las compañías de
+    #    su tenant. Así cualquier usuario del mismo tenant (misma organización del
+    #    Workspace) entra y ve la(s) compañía(s) sin gestión manual. El ROL no se
+    #    asigna aquí: es solo membresía; los permisos se otorgan aparte (un admin
+    #    asigna el rol; el primer usuario recibe super_admin vía /permissions/me).
+    if tenant_id:
+        tenant_id = int(tenant_id)
+        company_ids = [
+            int(r[0])
+            for r in db.execute(
+                text("SELECT id FROM a76.company WHERE tenant_id = :tid ORDER BY id"),
+                {"tid": tenant_id},
+            ).fetchall()
+        ]
+        if not company_ids:
+            tenant = db.query(Tenant).filter(Tenant.id == tenant_id).first()
+            default_name = (
+                (tenant.name if tenant else None)
+                or current_user.get("tenant_slug")
+                or "Mi empresa"
+            )
+            created = db.execute(
+                text("INSERT INTO a76.company (tenant_id, name) VALUES (:tid, :name) RETURNING id"),
+                {"tid": tenant_id, "name": default_name},
+            ).fetchone()
+            db.execute(text("SELECT setval('a76.company_id_seq', (SELECT MAX(id) FROM a76.company))"))
+            db.commit()
+            company_ids = [int(created[0])]
+            logger.info("Compañía por defecto creada para tenant=%s: id=%s", tenant_id, created[0])
+
+        # Auto-ligado por tenant (solo membresía, sin rol).
+        if user_id:
+            for cid in company_ids:
+                try:
+                    _ensure_user_tenant_for_company(db, str(user_id), tenant_id, cid)
+                except Exception as exc:
+                    logger.warning("auto-ligado de compañía %s falló (no bloquea): %s", cid, exc)
+
+    # 2) Compañías por MEMBRESÍA (user_tenants ∪ user_company_roles) → funciona
+    #    también para hub_admin sin tenant en el token: verá las compañías que creó
+    #    o a las que fue asignado. La membresía la determina el CRM, no el Hub.
+    if not user_id:
+        return []
+    rows = db.execute(
+        text(
+            """
+            SELECT c.id, c.name, c.rfc, c.logo, c.tenant_id, t.name, t.slug
+            FROM a76.company c
+            LEFT JOIN core.tenants t ON t.id = c.tenant_id
+            WHERE c.id IN (
+                SELECT company_id FROM core.user_tenants
+                    WHERE keycloak_user_id = :uid AND is_active AND company_id IS NOT NULL
+                UNION
+                SELECT company_id FROM core.user_company_roles
+                    WHERE user_id = :uid AND is_active
+            )
+            ORDER BY c.id
+            """
+        ),
+        {"uid": str(user_id)},
+    ).fetchall()
+
+    return [
+        {
+            "id": int(r[0]),
+            "name": r[1] or "Empresa",
+            "tenant_id": int(r[4]),
+            "tenant_name": r[5],
+            "tenant_slug": r[6],
+            "rfc": r[2],
+            "logo": r[3],
+            "is_active": True,
+        }
+        for r in rows
+    ]
+
+
+class _CreateCompanyDTO(BaseModel):
+    name: str
+    tenant_id: int
+    rfc: Optional[str] = None
+
+
+async def _sync_tenants_from_hub(request: Request, db: Session) -> None:
+    """
+    Auto-sync Workspace→CRM: trae los tenants del Workspace (Hub GET /hub/tenants) y
+    los da de alta/actualiza en core.tenants con su MISMO ID del Workspace. Así los
+    tenants creados en el Workspace aparecen solos en el CRM para asignarles compañías.
+    Best-effort: usa el token KC de la sesión (valkey); si no está fresco o el Hub no
+    responde, no bloquea (se devuelven los tenants ya sincronizados).
+    """
+    import httpx
+    from sqlalchemy import text as _text
+    from core.config import settings
+    from core import session_store
+    from api.v1.modules.core.tenants.models import Tenant, TenantType
+
+    sid = request.cookies.get("crm_sid") if request else None
+    kc_token = None
+    if sid:
+        sess = session_store.get_session(sid)
+        kc_token = (sess or {}).get("access_token")
+    if not kc_token:
+        return
+
+    try:
+        async with httpx.AsyncClient(timeout=8.0) as client:
+            r = await client.get(
+                f"{settings.HUB_URL}api/v1/hub/tenants",
+                headers={"Authorization": f"Bearer {kc_token}"},
+            )
+        if r.status_code != 200:
+            logger.info("sync-tenants: Hub devolvió %s — sin sincronizar", r.status_code)
+            return
+        payload = r.json()
+        items = payload.get("tenants", []) if isinstance(payload, dict) else (payload or [])
+        for t in items:
+            tid = t.get("id")
+            if tid is None:
+                continue
+            name = t.get("name") or t.get("display_name") or t.get("slug")
+            slug = t.get("slug") or f"tenant-{tid}"
+            existing = db.query(Tenant).filter(Tenant.id == int(tid)).first()
+            if existing:
+                if name and existing.name != name:
+                    existing.name = name
+            else:
+                db.add(Tenant(
+                    id=int(tid), name=name or slug, slug=slug,
+                    keycloak_realm=slug, type=TenantType.SHARED, is_active=True,
+                ))
+        db.commit()
+        db.execute(_text("SELECT setval('core.tenants_id_seq', (SELECT MAX(id) FROM core.tenants))"))
+        db.commit()
+    except Exception as exc:
+        logger.warning("sync-tenants desde Hub falló (no bloquea): %s", exc)
+        try:
+            db.rollback()
+        except Exception:
+            pass
+
+
+@router.get("/assignable-tenants")
+async def assignable_tenants(
+    request: Request,
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    """
+    Tenants disponibles para asignar una compañía. El tenant lo crea el Workspace;
+    aquí solo se elige. hub_admin ve TODOS (auto-sincronizados del Hub); un usuario
+    con tenant ve el suyo.
+    """
+    from api.v1.modules.core.tenants.models import Tenant
+    from core.security import resolve_effective_tenant_id_from_user, is_hub_admin
+
+    if is_hub_admin(current_user):
+        # Sincroniza automáticamente los tenants del Workspace antes de listar.
+        await _sync_tenants_from_hub(request, db)
+        rows = db.query(Tenant).filter(Tenant.is_active == True).order_by(Tenant.id).all()  # noqa: E712
+        return [{"id": t.id, "name": t.name, "slug": t.slug} for t in rows]
+
+    tid = resolve_effective_tenant_id_from_user(current_user)
+    if tid:
+        t = db.query(Tenant).filter(Tenant.id == int(tid), Tenant.is_active == True).first()  # noqa: E712
+        return [{"id": t.id, "name": t.name, "slug": t.slug}] if t else []
     return []
+
+
+@router.post("/companies", status_code=201)
+async def create_company(
+    data: _CreateCompanyDTO,
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    """
+    Da de alta una compañía (a76.company) bajo un tenant del Workspace y asigna al
+    usuario como miembro. hub_admin puede crear en cualquier tenant; un usuario con
+    tenant solo en el suyo. El rol super_admin se otorga al seleccionarla (/permissions/me).
+    """
+    from sqlalchemy import text as _text
+    from api.v1.modules.core.tenants.models import Tenant
+    from core.security import (
+        resolve_effective_tenant_id_from_user,
+        is_hub_admin,
+        _ensure_user_tenant_for_company,
+    )
+
+    name = (data.name or "").strip()
+    if len(name) < 2:
+        raise HTTPException(status_code=422, detail="El nombre de la compañía es obligatorio.")
+
+    tid = int(data.tenant_id)
+    tenant = db.query(Tenant).filter(Tenant.id == tid, Tenant.is_active == True).first()  # noqa: E712
+    if not tenant:
+        raise HTTPException(status_code=404, detail="Tenant no encontrado.")
+
+    # Autorización: hub_admin (atestado por el Hub) puede crear en cualquier tenant;
+    # un usuario ligado a un tenant, solo en el suyo.
+    if not is_hub_admin(current_user):
+        own = resolve_effective_tenant_id_from_user(current_user)
+        if own is None or int(own) != tid:
+            raise HTTPException(status_code=403, detail="No puedes crear compañías en ese tenant.")
+
+    created = db.execute(
+        _text("INSERT INTO a76.company (tenant_id, name, rfc) VALUES (:t, :n, :r) RETURNING id"),
+        {"t": tid, "n": name, "r": (data.rfc or None)},
+    ).fetchone()
+    db.execute(_text("SELECT setval('a76.company_id_seq', (SELECT MAX(id) FROM a76.company))"))
+    db.commit()
+    cid = int(created[0])
+
+    user_id = current_user.get("sub") or current_user.get("id")
+    if user_id:
+        try:
+            _ensure_user_tenant_for_company(db, str(user_id), tid, cid)
+        except Exception as exc:
+            logger.warning("create_company: no se pudo asegurar membresía (no bloquea): %s", exc)
+
+    return {"id": cid, "name": name, "tenant_id": tid, "rfc": data.rfc, "logo": None, "is_active": True}

backend/api/v1/modules/core/auth/service.py

@@ -213,55 +213,160 @@ class AuthService:
             logger.error(f"Unexpected login error: {str(e)}")
             raise HTTPException(status_code=500, detail="Authentication error")
 
+    def _decode_local_session(self, session_token: Optional[str]) -> Optional[Dict[str, Any]]:
+        """
+        Decodifica una sesión local del CRM (HS256) verificando la firma pero
+        SIN exigir exp — para poder re-emitirla en el refresh. Retorna los claims
+        o None si la firma no valida o no es una sesión local del CRM.
+        """
+        if not session_token:
+            return None
+        try:
+            claims = jwt.decode(
+                session_token,
+                settings.SECRET_KEY,
+                algorithms=["HS256"],
+                options={"verify_exp": False},
+            )
+        except JWTError:
+            return None
+        if not claims.get("crm_session") or claims.get("source") != "local":
+            return None
+        return claims
+
+    def _session_claims_from_kc(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Construye los claims de la sesión local a partir del token KC (decode)."""
+        kc_claims = self._decode_kc_user_from_token(data.get("access_token", ""))
+        claims: Dict[str, Any] = dict(kc_claims)
+        # tenant_id/tenant_slug explícitos del Hub tienen precedencia sobre el token
+        if data.get("tenant_id") is not None:
+            claims["tenant_id"] = data.get("tenant_id")
+        if data.get("tenant_slug") is not None:
+            claims["tenant_slug"] = data.get("tenant_slug")
+        return claims
+
+    async def _session_claims(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Claims AUTORITATIVOS para la sesión local: se prefiere /auth/me del Hub (trae
+        is_hub_admin, roles, etc. que el token KC crudo no incluye). Si el Hub no
+        responde, se cae al decode del token KC. Así la sesión local sabe si el
+        usuario es hub_admin sin volver a consultar al Hub en cada request.
+        """
+        from core.security import verify_token
+
+        claims: Dict[str, Any] = {}
+        try:
+            info = await verify_token(data.get("access_token", ""))
+            if isinstance(info, dict):
+                claims = dict(info)
+        except Exception as exc:
+            logger.warning("session_claims: /auth/me no disponible, uso decode KC: %s", exc)
+
+        if not claims:
+            return self._session_claims_from_kc(data)
+
+        # tenant_id/tenant_slug explícitos del Hub tienen precedencia.
+        if data.get("tenant_id") is not None:
+            claims["tenant_id"] = data.get("tenant_id")
+        if data.get("tenant_slug") is not None:
+            claims["tenant_slug"] = data.get("tenant_slug")
+        return claims
+
     async def refresh_token(self, refresh_data: RefreshTokenRequestDTO) -> TokenResponseDTO:
         """
-        Refresca el access token usando el Hub
+        Refresca la sesión.
+
+        - Intenta el refresh del token KC contra el Hub (comportamiento histórico).
+        - Con SESSION_STORE_ENABLED, además emite/actualiza la sesión local del CRM
+          (patrón SIWEB) que la app usa como bearer y que dura por inactividad, de
+          modo que el refresh KC solo se intenta al expirar esa sesión (no cada ~60s).
+        - Si el Hub RECHAZA el refresh se devuelve 401 y la sesión termina: se
+          RESPETA la revocación central de Keycloak (sin re-emisión de fallback).
         """
+        from datetime import datetime, timezone
+
+        session_enabled = bool(getattr(settings, "SESSION_STORE_ENABLED", False))
+        prev_claims = self._decode_local_session(refresh_data.session_token) if session_enabled else None
+        prev_sst = prev_claims.get("sst") if prev_claims else None
+        prev_session_id = refresh_data.session_id if session_enabled else None
+
+        # Fuente del refresh KC: valkey (sesión) tiene precedencia sobre lo que
+        # mande el cliente (puede estar desactualizado). Fail-silent.
+        kc_refresh = refresh_data.refresh_token
+        if session_enabled and prev_session_id:
+            from core import session_store
+
+            sess = session_store.get_session(prev_session_id)
+            if sess and sess.get("refresh_token"):
+                kc_refresh = sess["refresh_token"]
+
+        # ── Intento de refresh del token KC contra el Hub ────────────────────────
+        kc_ok = False
+        data: Optional[Dict[str, Any]] = None
         try:
             async with httpx.AsyncClient(timeout=10.0) as client:
                 response = await client.post(
                     f"{settings.HUB_URL}api/v1/auth/refresh",
-                    json=refresh_data.model_dump()
+                    json={"refresh_token": kc_refresh},
                 )
-
-            if response.status_code == 200:
+            kc_ok = response.status_code == 200
+            if kc_ok:
                 data = response.json()
-                from core.workspace_profile_sync import sync_workspace_profile_for_user
-                from core.workspace_profile_client import WorkspaceProfileClient
+            else:
+                logger.warning("Hub rechazó el refresh (status %s)", response.status_code)
+        except Exception as exc:
+            logger.warning("Hub inalcanzable en refresh: %s", exc)
+            kc_ok = False
 
-                workspace_profile = None
-                try:
-                    workspace_profile = await WorkspaceProfileClient().get_me(
-                        data.get("access_token", "")
-                    )
-                except Exception as exc:
-                    logger.warning(
-                        "workspace_profile_sync_failed",
-                        extra={
-                            "event": "workspace_profile_sync_failed",
-                            "phase": "refresh",
-                            "error": str(exc),
-                        },
-                    )
-                    workspace_profile = None
+        # ── Camino feliz: el Hub renovó el token KC ──────────────────────────────
+        if kc_ok and data is not None:
+            from core.workspace_profile_sync import sync_workspace_profile_for_user
+            from core.workspace_profile_client import WorkspaceProfileClient
 
-                await sync_workspace_profile_for_user(
-                    self.db,
-                    access_token=data.get("access_token"),
-                    keycloak_user_id=(workspace_profile or {}).get("sub")
-                    or data.get("sub")
-                    or data.get("user_id"),
-                    tenant_id=data.get("tenant_id"),
-                    workspace_profile=workspace_profile,
-                    force=True,
+            workspace_profile = None
+            try:
+                workspace_profile = await WorkspaceProfileClient().get_me(data.get("access_token", ""))
+            except Exception as exc:
+                logger.warning(
+                    "workspace_profile_sync_failed",
+                    extra={"event": "workspace_profile_sync_failed", "phase": "refresh", "error": str(exc)},
                 )
-                return TokenResponseDTO(**data)
-            
-            raise HTTPException(status_code=401, detail="Invalid or expired refresh token")
+                workspace_profile = None
 
-        except Exception as e:
-            logger.error(f"Token refresh error: {str(e)}")
-            raise HTTPException(status_code=500, detail="Token refresh error")
+            await sync_workspace_profile_for_user(
+                self.db,
+                access_token=data.get("access_token"),
+                keycloak_user_id=(workspace_profile or {}).get("sub") or data.get("sub") or data.get("user_id"),
+                tenant_id=data.get("tenant_id"),
+                workspace_profile=workspace_profile,
+                force=True,
+            )
+
+            resp = TokenResponseDTO(**data)
+
+            if session_enabled:
+                from core import local_session, session_store
+
+                start = int(prev_sst) if prev_sst else int(datetime.now(timezone.utc).timestamp())
+                claims = await self._session_claims(data)
+                new_access = data.get("access_token", "")
+                new_refresh = data.get("refresh_token", "")
+                # Reutiliza la sesión de valkey si ya existía; si no, la crea.
+                if prev_session_id and session_store.get_session(prev_session_id):
+                    session_store.update_session_tokens(prev_session_id, new_access, new_refresh)
+                    resp.session_id = prev_session_id
+                else:
+                    resp.session_id = session_store.create_session(new_access, new_refresh, start)
+                resp.session_token = local_session.mint_session_token(claims, session_start=start)
+
+            return resp
+
+        # El Hub rechazó el refresh: la sesión termina y se RESPETA la revocación
+        # central de Keycloak (no hay re-emisión local de fallback). El usuario
+        # re-entra por el App Launcher. La sesión local de larga duración evita el
+        # bucle: el refresh solo se intenta al expirar la sesión local por
+        # inactividad (idle), no cada ~60s como con el token KC crudo.
+        raise HTTPException(status_code=401, detail="Invalid or expired refresh token")
 
     async def get_user_info(self, access_token: str) -> UserInfoResponseDTO:
         """

backend/api/v1/modules/core/invites/routes.py

@@ -37,13 +37,33 @@ async def create_invite(
         required_permissions=["user.create"],
     )
 
+    # tenant_slug: del token si viene; si el usuario es hub_admin (sin tenant en el
+    # token), se resuelve desde la compañía destino (a76.company → core.tenants).
     tenant_slug: str = current_user.get("tenant_slug") or ""
+    if not tenant_slug:
+        from sqlalchemy import text as _text
+        row = db.execute(
+            _text(
+                "SELECT t.slug FROM a76.company c "
+                "JOIN core.tenants t ON t.id = c.tenant_id WHERE c.id = :c"
+            ),
+            {"c": data.company_id},
+        ).first()
+        if row and row[0]:
+            tenant_slug = row[0]
+
     created_by: str = current_user.get("sub") or ""
 
+    # El invite se crea en el Hub: se necesita el token KC (la sesión local no la
+    # acepta el Hub). Se toma de la sesión (valkey) y se refresca si hace falta.
+    from core.hub_token import get_hub_access_token
+
+    kc_token = await get_hub_access_token(request)
+
     service = InviteService(db)
     return await service.create_invite(
         data=data,
         created_by=created_by,
         tenant_slug=tenant_slug,
-        user_access_token=credentials.credentials,
+        user_access_token=kc_token or credentials.credentials,
     )

backend/api/v1/modules/core/users/routes.py

@@ -53,12 +53,17 @@ async def get_user_statistics(
     """
     tenant_id = validate_access_to_resource(db, company_id, current_user, required_permissions=["user.view"])
     service = UserService(db, tenant_id, company_id, is_hub_admin=is_hub_admin(current_user))
+    from core.hub_token import get_hub_access_token
+
     auth_header = request.headers.get("Authorization") or ""
     token = (
         auth_header[7:].strip()
         if auth_header.lower().startswith("bearer ")
         else auth_header.strip()
     )
+    kc_token = await get_hub_access_token(request)
+    if kc_token:
+        token = kc_token
     hub_tid = resolve_hub_tenant_id_for_api(
         tenant_id, request.headers.get("X-Tenant-Override")
     )
@@ -84,12 +89,19 @@ async def list_users(
     """
     tenant_id = validate_access_to_resource(db, company_id, current_user, required_permissions=["user.view"])
     service = UserService(db, tenant_id, company_id, is_hub_admin=is_hub_admin(current_user))
+    # El Bearer de la app puede ser la sesión local (SIWEB), que el Hub no acepta.
+    # Para listar usuarios del tenant se usa el token KC de la sesión (valkey), refrescado.
+    from core.hub_token import get_hub_access_token
+
     auth_header = request.headers.get("Authorization") or ""
     token = (
         auth_header[7:].strip()
         if auth_header.lower().startswith("bearer ")
         else auth_header.strip()
     )
+    kc_token = await get_hub_access_token(request)
+    if kc_token:
+        token = kc_token
     hub_tid = resolve_hub_tenant_id_for_api(
         tenant_id, request.headers.get("X-Tenant-Override")
     )

backend/api/v1/modules/crm/accounts/dto.py

@@ -18,16 +18,15 @@ class AccountBase(BaseModel):
     # Comercial
     commercial_classification: str | None = Field(None, max_length=20)
     preferred_contact_method: str | None = Field(None, max_length=20)
+    preferred_contact_other: str | None = Field(None, max_length=120)
     language: str | None = Field(None, max_length=40)
     email: EmailStr | None = None
     phone: str | None = Field(None, max_length=40)
     website: str | None = Field(None, max_length=255)
+    commercial_observations: str | None = None  # observaciones generales
     # Fiscal
     tax_regime: str | None = Field(None, max_length=120)
     cfdi_use: str | None = Field(None, max_length=60)
-    # Claves contra los catálogos del SAT; sustituyen al texto libre de arriba al timbrar.
-    tax_regime_id: int | None = Field(None, description="c_RegimenFiscal del receptor")
-    cfdi_use_id: int | None = Field(None, description="c_UsoCFDI del receptor")
     payment_method: str | None = Field(None, max_length=60)
     payment_form: str | None = Field(None, max_length=60)
     currency: str | None = Field(None, max_length=3)
@@ -62,14 +61,14 @@ class AccountUpdate(BaseModel):
     status: str | None = Field(None, max_length=20)
     commercial_classification: str | None = Field(None, max_length=20)
     preferred_contact_method: str | None = Field(None, max_length=20)
+    preferred_contact_other: str | None = Field(None, max_length=120)
     language: str | None = Field(None, max_length=40)
     email: EmailStr | None = None
     phone: str | None = Field(None, max_length=40)
     website: str | None = Field(None, max_length=255)
+    commercial_observations: str | None = None
     tax_regime: str | None = Field(None, max_length=120)
     cfdi_use: str | None = Field(None, max_length=60)
-    tax_regime_id: int | None = None
-    cfdi_use_id: int | None = None
     payment_method: str | None = Field(None, max_length=60)
     payment_form: str | None = Field(None, max_length=60)
     currency: str | None = Field(None, max_length=3)

backend/api/v1/modules/crm/accounts/models.py

@@ -1,10 +1,9 @@
 from decimal import Decimal
 
-from sqlalchemy import ForeignKey, Integer, Numeric, String, Text, text
+from sqlalchemy import Integer, Numeric, String, Text, text
 from sqlalchemy.orm import Mapped, mapped_column
 
 from api.v1.common.base_models import TenantScopedMixin, TimestampMixin
-from api.v1.modules.fin.catalogs.models import CfdiUse, TaxRegime  # noqa: F401  (resuelve las FK)
 from core.database import Base
 
 
@@ -40,25 +39,19 @@ class Account(Base, TenantScopedMixin, TimestampMixin):
     # ----- Información comercial -----
     # Clasificación: importador | exportador | ambos
     commercial_classification: Mapped[str | None] = mapped_column(String(20), nullable=True)
-    # Medio de contacto preferido: llamada | correo | videollamada | whatsapp | otro
+    # Medio de contacto preferido: llamada | correo | videoconferencia | whatsapp | otro
     preferred_contact_method: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    # Texto libre cuando el medio de contacto es "otro"
+    preferred_contact_other: Mapped[str | None] = mapped_column(String(120), nullable=True)
     language: Mapped[str | None] = mapped_column(String(40), nullable=True)
     email: Mapped[str | None] = mapped_column(String(255), nullable=True)
     phone: Mapped[str | None] = mapped_column(String(40), nullable=True)
     website: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    commercial_observations: Mapped[str | None] = mapped_column(Text, nullable=True)  # observaciones generales
 
     # ----- Información fiscal -----
-    # Régimen fiscal y uso de CFDI en texto libre: se conservan como capturó el usuario
-    # para no perder lo ya registrado, pero lo que vale al timbrar son las FK de abajo.
     tax_regime: Mapped[str | None] = mapped_column(String(120), nullable=True)  # régimen fiscal
     cfdi_use: Mapped[str | None] = mapped_column(String(60), nullable=True)  # uso de CFDI
-    # Claves del receptor contra los catálogos del SAT (c_RegimenFiscal y c_UsoCFDI).
-    tax_regime_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("sat.tax_regimes.id"), nullable=True
-    )
-    cfdi_use_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("sat.cfdi_uses.id"), nullable=True
-    )
     payment_method: Mapped[str | None] = mapped_column(String(60), nullable=True)  # método de pago
     payment_form: Mapped[str | None] = mapped_column(String(60), nullable=True)  # forma de pago
     currency: Mapped[str | None] = mapped_column(String(3), nullable=True)  # moneda

backend/api/v1/modules/crm/accounts/service.py

@@ -3,24 +3,10 @@ from datetime import datetime, timezone
 from fastapi import HTTPException, status
 from sqlalchemy.orm import Session
 
-from api.v1.modules.fin.catalogs.models import CfdiUse, TaxRegime
-
 from .dto import AccountCreate, AccountUpdate
 from .models import Account
 
 
-def _validate_sat_refs(db: Session, data: dict) -> None:
-    """Verifica las claves del SAT del receptor antes de guardar la cuenta."""
-    for field, model, msg in [
-        ("tax_regime_id", TaxRegime, "El régimen fiscal indicado no existe en el catálogo del SAT"),
-        ("cfdi_use_id", CfdiUse, "El uso de CFDI indicado no existe en el catálogo del SAT"),
-    ]:
-        value = data.get(field)
-        if field in data and value is not None:
-            if db.query(model.id).filter(model.id == value).first() is None:
-                raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=msg)
-
-
 def get_accounts(
     db: Session,
     tenant_id: int,
@@ -67,10 +53,8 @@ def get_account(db: Session, account_id: int, tenant_id: int, company_id: int) -
 def create_account(
     db: Session, payload: AccountCreate, tenant_id: int, company_id: int, user_id: str | None = None
 ) -> Account:
-    data = payload.model_dump()
-    _validate_sat_refs(db, data)
     account = Account(
-        **data,
+        **payload.model_dump(),
         tenant_id=tenant_id,
         company_id=company_id,
         created_by=user_id,
@@ -91,9 +75,7 @@ def update_account(
     user_id: str | None = None,
 ) -> Account:
     account = get_account(db, account_id, tenant_id, company_id)
-    data = payload.model_dump(exclude_unset=True)
-    _validate_sat_refs(db, data)
-    for field, value in data.items():
+    for field, value in payload.model_dump(exclude_unset=True).items():
         setattr(account, field, value)
     account.updated_by = user_id
     db.commit()

backend/api/v1/modules/crm/addresses/models.py

@@ -29,7 +29,8 @@ class Address(Base, TenantScopedMixin, TimestampMixin):
     neighborhood: Mapped[str | None] = mapped_column(String(120), nullable=True)  # colonia
     postal_code: Mapped[str | None] = mapped_column(String(10), nullable=True)  # código postal
     city: Mapped[str | None] = mapped_column(String(120), nullable=True)  # municipio
-    state: Mapped[str | None] = mapped_column(String(120), nullable=True)  # estado
-    country: Mapped[str | None] = mapped_column(String(2), nullable=True, server_default=text("'MX'"))
+    state: Mapped[str | None] = mapped_column(String(120), nullable=True)  # estado (código catálogo)
+    # País como código ISO 3166 alfa-3 del catálogo (p. ej. MEX). Ampliado de 2→3.
+    country: Mapped[str | None] = mapped_column(String(3), nullable=True, server_default=text("'MEX'"))
     reference_notes: Mapped[str | None] = mapped_column(Text, nullable=True)  # referencias
     is_primary: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))

backend/api/v1/modules/crm/catalogs/dto.py

@@ -0,0 +1,46 @@
+"""Schemas (DTOs) de los catálogos de referencia del CRM."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CatalogItemBase(BaseModel):
+    code: str = Field(..., max_length=64)
+    label: str = Field(..., max_length=255)
+    parent_catalog: str | None = Field(None, max_length=60)
+    parent_code: str | None = Field(None, max_length=64)
+    sort_order: int = 0
+    is_active: bool = True
+
+
+class CatalogItemCreate(CatalogItemBase):
+    pass
+
+
+class CatalogItemUpdate(BaseModel):
+    """PATCH: todos los campos opcionales."""
+
+    code: str | None = Field(None, max_length=64)
+    label: str | None = Field(None, max_length=255)
+    parent_code: str | None = Field(None, max_length=64)
+    sort_order: int | None = None
+    is_active: bool | None = None
+
+
+class CatalogItemResponse(CatalogItemBase):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    catalog: str
+    tenant_id: int | None
+    is_system: bool
+    extra: dict | None = None  # metadata (ej. dimensiones de un tipo de equipo)
+
+
+class CatalogMeta(BaseModel):
+    """Metadata de un catálogo para la pantalla de administración."""
+
+    catalog: str
+    label: str
+    scope: str  # 'global' | 'tenant'
+    is_system: bool
+    count: int

backend/api/v1/modules/crm/catalogs/models.py

@@ -0,0 +1,54 @@
+"""Modelo de catálogos de referencia del CRM (T2026-07-081/082).
+
+Un único modelo genérico ``CatalogItem`` respalda todos los catálogos
+(SAT/ISO y los propios del cliente). Cada fila pertenece a un catálogo
+(``catalog``) e identifica una opción por ``code`` (clave) + ``label``
+(descripción que se visualiza).
+
+Alcance:
+- ``tenant_id IS NULL`` → catálogo GLOBAL (Aduanasoft), compartido por todos.
+- ``tenant_id`` con valor → catálogo del CLIENTE (ese tenant lo administra).
+
+Los catálogos dependientes (p. ej. Estado depende de País) usan
+``parent_catalog`` + ``parent_code`` para filtrarse.
+"""
+
+from datetime import datetime
+
+from sqlalchemy import JSON, Boolean, DateTime, Integer, String, text
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy.sql import func
+
+from core.database import Base
+
+
+class CatalogItem(Base):
+    __tablename__ = "catalog_items"
+    __table_args__ = {"schema": "crm"}
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+
+    catalog: Mapped[str] = mapped_column(String(60), nullable=False, index=True)
+    code: Mapped[str] = mapped_column(String(64), nullable=False)
+    label: Mapped[str] = mapped_column(String(255), nullable=False)
+
+    # Dependencia (Estado→País, Municipio→Estado, …)
+    parent_catalog: Mapped[str | None] = mapped_column(String(60), nullable=True)
+    parent_code: Mapped[str | None] = mapped_column(String(64), nullable=True)
+
+    # NULL = global (Aduanasoft); con valor = catálogo propio del tenant (cliente).
+    tenant_id: Mapped[int | None] = mapped_column(Integer, nullable=True, index=True)
+
+    sort_order: Mapped[int] = mapped_column(Integer, nullable=False, server_default=text("0"))
+    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("true"))
+    # Catálogos base SAT/ISO: no se pueden borrar (solo activar/desactivar).
+    is_system: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
+
+    extra: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+
+    created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False, server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime, nullable=False, server_default=func.now(), onupdate=func.now()
+    )

backend/api/v1/modules/crm/catalogs/routes.py

@@ -1,6 +1,10 @@
-"""Endpoints de catálogos de referencia y participantes del proceso (R-T-01, R-T-10)."""
+"""Endpoints de catálogos de referencia y participantes del proceso (R-T-01, R-T-10).
 
-from fastapi import APIRouter, Depends, Query
+Incluye el CRUD de catálogos de referencia (T2026-07-081/082): SAT/ISO globales
+(Aduanasoft) y catálogos propios de cada cliente (tenant).
+"""
+
+from fastapi import APIRouter, Depends, Query, status
 from sqlalchemy.orm import Session
 
 from core.database import get_core_db
@@ -8,7 +12,9 @@ from core.security import get_current_user
 
 from ..accounts.models import Account
 from ..suppliers.models import Supplier
+from . import service as catalog_service
 from .data import INCOTERMS, PARTICIPANT_ROLES
+from .dto import CatalogItemCreate, CatalogItemResponse, CatalogItemUpdate, CatalogMeta
 
 router = APIRouter()
 
@@ -31,6 +37,76 @@ def list_participant_roles(
     return PARTICIPANT_ROLES
 
 
+# ----------------------------------------------------------------------------
+# Catálogos de referencia (CRUD) — T2026-07-081/082
+# ----------------------------------------------------------------------------
+
+
+@router.get("/catalogs", response_model=list[CatalogMeta])
+def list_catalog_meta(
+    company_id: int = Query(..., description="Company ID"),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    """Lista los catálogos disponibles (global + del tenant) con su conteo."""
+    return catalog_service.list_meta(db, current_user["tenant_id"])
+
+
+@router.get("/catalogs/{catalog}", response_model=list[CatalogItemResponse])
+def list_catalog_items(
+    catalog: str,
+    company_id: int = Query(..., description="Company ID"),
+    parent_code: str | None = Query(None, description="Filtra dependientes (ej. Estado por País)"),
+    include_inactive: bool = Query(False),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    """Opciones de un catálogo (global + del tenant), activas y ordenadas."""
+    return catalog_service.list_items(
+        db, catalog, current_user["tenant_id"], parent_code=parent_code, include_inactive=include_inactive
+    )
+
+
+@router.post(
+    "/catalogs/{catalog}", response_model=CatalogItemResponse, status_code=status.HTTP_201_CREATED
+)
+def create_catalog_item(
+    catalog: str,
+    data: CatalogItemCreate,
+    company_id: int = Query(..., description="Company ID"),
+    scope: str | None = Query("tenant", description="'tenant' (cliente) o 'global' (Aduanasoft, hub_admin)"),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    """Inserta una opción en un catálogo."""
+    return catalog_service.create_item(db, catalog, data, current_user, scope=scope)
+
+
+@router.patch("/catalogs/{catalog}/{item_id}", response_model=CatalogItemResponse)
+def update_catalog_item(
+    catalog: str,
+    item_id: int,
+    data: CatalogItemUpdate,
+    company_id: int = Query(..., description="Company ID"),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    """Edita una opción de catálogo."""
+    return catalog_service.update_item(db, catalog, item_id, data, current_user)
+
+
+@router.delete("/catalogs/{catalog}/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_catalog_item(
+    catalog: str,
+    item_id: int,
+    company_id: int = Query(..., description="Company ID"),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    """Borra una opción de catálogo (los catálogos base del sistema no se borran)."""
+    catalog_service.delete_item(db, catalog, item_id, current_user)
+
+
 @router.get("/participants")
 def list_participants(
     company_id: int = Query(..., description="Company ID"),

backend/api/v1/modules/crm/catalogs/seed.py

@@ -0,0 +1,69 @@
+"""Siembra de catálogos globales (Aduanasoft) del CRM.
+
+Idempotente: inserta solo las claves que aún no existen (tenant_id NULL). Se
+puede correr múltiples veces sin duplicar. Para ejecutarlo en un entorno:
+
+    docker compose exec backend python -m api.v1.modules.crm.catalogs.seed
+"""
+
+import logging
+
+from sqlalchemy.orm import Session
+
+from .models import CatalogItem
+from .seed_data import GLOBAL_CATALOGS
+
+logger = logging.getLogger(__name__)
+
+
+def seed_global_catalogs(db: Session) -> dict:
+    """Inserta los catálogos globales que falten. Devuelve un resumen {catalog: nuevos}."""
+    summary: dict[str, int] = {}
+    for catalog, meta in GLOBAL_CATALOGS.items():
+        is_system = bool(meta.get("is_system", False))
+        existing = {
+            row.code
+            for row in db.query(CatalogItem.code).filter(
+                CatalogItem.catalog == catalog, CatalogItem.tenant_id.is_(None)
+            )
+        }
+        added = 0
+        for order, item in enumerate(meta["items"]):
+            if item["code"] in existing:
+                continue
+            db.add(
+                CatalogItem(
+                    catalog=catalog,
+                    code=item["code"],
+                    label=item["label"],
+                    parent_catalog=item.get("parent_catalog"),
+                    parent_code=item.get("parent_code"),
+                    extra=item.get("extra"),
+                    tenant_id=None,
+                    sort_order=order,
+                    is_active=True,
+                    is_system=is_system,
+                )
+            )
+            added += 1
+        if added:
+            summary[catalog] = added
+    db.commit()
+    total = sum(summary.values())
+    logger.info("seed_global_catalogs: %s nuevas filas en %s catálogos", total, len(summary))
+    return summary
+
+
+def _run() -> None:
+    from core.database import CoreSessionLocal
+
+    db = CoreSessionLocal()
+    try:
+        result = seed_global_catalogs(db)
+        print("Catálogos sembrados (nuevos):", result or "0 (ya estaban todos)")
+    finally:
+        db.close()
+
+
+if __name__ == "__main__":
+    _run()

backend/api/v1/modules/crm/catalogs/seed_data.py

@@ -0,0 +1,768 @@
+"""Datos semilla de los catálogos de referencia del CRM.
+
+SAT/ISO + estándar + Medidas de Equipos (tipo_equipo con dimensiones en extra)
++ catálogos del módulo Tarifario. Globales con tenant_id NULL.
+"""
+
+GLOBAL_CATALOGS = {'tipo_registro': {'label': 'Tipo de registro',
+                   'is_system': True,
+                   'items': [{'code': 'cliente', 'label': 'Cliente'}, {'code': 'prospecto', 'label': 'Prospecto'}]},
+ 'tipo_persona': {'label': 'Tipo de persona',
+                  'is_system': True,
+                  'items': [{'code': 'fisica', 'label': 'Persona física'},
+                            {'code': 'moral', 'label': 'Persona moral'}]},
+ 'estatus': {'label': 'Estatus',
+             'is_system': True,
+             'items': [{'code': 'active', 'label': 'Activo'}, {'code': 'inactive', 'label': 'Inactivo'}]},
+ 'giro': {'label': 'Giro o industria',
+          'is_system': False,
+          'items': [{'code': 'importadora', 'label': 'Importadora'},
+                    {'code': 'exportadora', 'label': 'Exportadora'},
+                    {'code': 'manufactura', 'label': 'Manufactura'},
+                    {'code': 'comercializadora', 'label': 'Comercializadora'},
+                    {'code': 'logistica', 'label': 'Logística y transporte'},
+                    {'code': 'agencia_aduanal', 'label': 'Agencia aduanal'},
+                    {'code': 'maquiladora', 'label': 'Maquiladora / IMMEX'},
+                    {'code': 'servicios', 'label': 'Servicios'},
+                    {'code': 'otro', 'label': 'Otro'}]},
+ 'clasificacion_cliente': {'label': 'Clasificación del cliente',
+                           'is_system': False,
+                           'items': [{'code': 'importador', 'label': 'Importador'},
+                                     {'code': 'exportador', 'label': 'Exportador'},
+                                     {'code': 'importador_exportador', 'label': 'Importador/Exportador'}]},
+ 'medio_contacto': {'label': 'Medio de contacto preferido',
+                    'is_system': False,
+                    'items': [{'code': 'llamada', 'label': 'Llamada telefónica'},
+                              {'code': 'correo', 'label': 'Correo electrónico'},
+                              {'code': 'videoconferencia', 'label': 'Videoconferencia'},
+                              {'code': 'whatsapp', 'label': 'WhatsApp'},
+                              {'code': 'otro', 'label': 'Otro'}]},
+ 'idioma': {'label': 'Idioma',
+            'is_system': False,
+            'items': [{'code': 'es', 'label': 'Español'},
+                      {'code': 'en', 'label': 'Inglés'},
+                      {'code': 'zh', 'label': 'Chino (mandarín)'},
+                      {'code': 'pt', 'label': 'Portugués'},
+                      {'code': 'fr', 'label': 'Francés'},
+                      {'code': 'de', 'label': 'Alemán'},
+                      {'code': 'ja', 'label': 'Japonés'},
+                      {'code': 'ko', 'label': 'Coreano'},
+                      {'code': 'it', 'label': 'Italiano'},
+                      {'code': 'otro', 'label': 'Otro'}]},
+ 'regimen_fiscal': {'label': 'Régimen fiscal',
+                    'is_system': False,
+                    'items': [{'code': 'fisica', 'label': 'Persona física'},
+                              {'code': 'moral', 'label': 'Persona moral'}]},
+ 'uso_cfdi': {'label': 'Uso de CFDI (SAT)',
+              'is_system': True,
+              'items': [{'code': 'G01', 'label': 'Adquisición de mercancías'},
+                        {'code': 'G02', 'label': 'Devoluciones, descuentos o bonificaciones'},
+                        {'code': 'G03', 'label': 'Gastos en general'},
+                        {'code': 'I01', 'label': 'Construcciones'},
+                        {'code': 'I02', 'label': 'Mobiliario y equipo de oficina por inversiones'},
+                        {'code': 'I03', 'label': 'Equipo de transporte'},
+                        {'code': 'I04', 'label': 'Equipo de cómputo y accesorios'},
+                        {'code': 'I05', 'label': 'Dados, troqueles, moldes, matrices y herramental'},
+                        {'code': 'I06', 'label': 'Comunicaciones telefónicas'},
+                        {'code': 'I07', 'label': 'Comunicaciones satelitales'},
+                        {'code': 'I08', 'label': 'Otra maquinaria y equipo'},
+                        {'code': 'D01', 'label': 'Honorarios médicos, dentales y gastos hospitalarios'},
+                        {'code': 'D02', 'label': 'Gastos médicos por incapacidad o discapacidad'},
+                        {'code': 'D03', 'label': 'Gastos funerales'},
+                        {'code': 'D04', 'label': 'Donativos'},
+                        {'code': 'D05', 'label': 'Intereses por créditos hipotecarios'},
+                        {'code': 'D06', 'label': 'Aportaciones voluntarias al SAR'},
+                        {'code': 'D07', 'label': 'Primas por seguros de gastos médicos'},
+                        {'code': 'D08', 'label': 'Gastos de transportación escolar obligatoria'},
+                        {'code': 'D09', 'label': 'Depósitos en cuentas para el ahorro'},
+                        {'code': 'D10', 'label': 'Pagos por servicios educativos (colegiaturas)'},
+                        {'code': 'S01', 'label': 'Sin efectos fiscales'},
+                        {'code': 'CP01', 'label': 'Pagos'},
+                        {'code': 'CN01', 'label': 'Nómina'},
+                        {'code': 'P01', 'label': 'Por definir'}]},
+ 'forma_pago': {'label': 'Forma de pago (SAT)',
+                'is_system': True,
+                'items': [{'code': '1', 'label': 'Efectivo'},
+                          {'code': '2', 'label': 'Cheque nominativo'},
+                          {'code': '3', 'label': 'Transferencia electrónica de fondos'},
+                          {'code': '4', 'label': 'Tarjeta de crédito'},
+                          {'code': '5', 'label': 'Monedero electrónico'},
+                          {'code': '6', 'label': 'Dinero electrónico'},
+                          {'code': '8', 'label': 'Vales de despensa'},
+                          {'code': '12', 'label': 'Dación en pago'},
+                          {'code': '13', 'label': 'Pago por subrogación'},
+                          {'code': '14', 'label': 'Pago por consignación'},
+                          {'code': '15', 'label': 'Condonación'},
+                          {'code': '17', 'label': 'Compensación'},
+                          {'code': '23', 'label': 'Novación'},
+                          {'code': '24', 'label': 'Confusión'},
+                          {'code': '25', 'label': 'Remisión de deuda'},
+                          {'code': '26', 'label': 'Prescripción o caducidad'},
+                          {'code': '27', 'label': 'A satisfacción del acreedor'},
+                          {'code': '28', 'label': 'Tarjeta de débito'},
+                          {'code': '29', 'label': 'Tarjeta de servicios'},
+                          {'code': '30', 'label': 'Aplicación de anticipos'},
+                          {'code': '31', 'label': 'Intermediario pagos'},
+                          {'code': '99', 'label': 'Por definir'}]},
+ 'metodo_pago': {'label': 'Método de pago (SAT)',
+                 'is_system': True,
+                 'items': [{'code': 'PPD', 'label': 'Pago en parcialidades o diferido'},
+                           {'code': 'PUE', 'label': 'Pago en una sola exhibición'}]},
+ 'moneda': {'label': 'Moneda (ISO 4217)',
+            'is_system': True,
+            'items': [{'code': 'CRC', 'label': 'Colón costarricense'},
+                      {'code': 'CUC', 'label': 'Peso Convertible'},
+                      {'code': 'CUP', 'label': 'Peso Cubano'},
+                      {'code': 'CVE', 'label': 'Cabo Verde Escudo'},
+                      {'code': 'CZK', 'label': 'Corona checa'},
+                      {'code': 'DJF', 'label': 'Franco de Djibouti'},
+                      {'code': 'DKK', 'label': 'Corona danesa'},
+                      {'code': 'DOP', 'label': 'Peso Dominicano'},
+                      {'code': 'DZD', 'label': 'Dinar argelino'},
+                      {'code': 'EGP', 'label': 'Libra egipcia'},
+                      {'code': 'ERN', 'label': 'Nakfa'},
+                      {'code': 'ETB', 'label': 'Birr etíope'},
+                      {'code': 'EUR', 'label': 'Euro'},
+                      {'code': 'FJD', 'label': 'Dólar de Fiji'},
+                      {'code': 'FKP', 'label': 'Libra malvinense'},
+                      {'code': 'GBP', 'label': 'Libra Esterlina'},
+                      {'code': 'GEL', 'label': 'Lari'},
+                      {'code': 'GHS', 'label': 'Cedi de Ghana'},
+                      {'code': 'GIP', 'label': 'Libra de Gibraltar'},
+                      {'code': 'GMD', 'label': 'Dalasi'},
+                      {'code': 'GNF', 'label': 'Franco guineano'},
+                      {'code': 'GTQ', 'label': 'Quetzal'},
+                      {'code': 'GYD', 'label': 'Dólar guyanés'},
+                      {'code': 'HKD', 'label': 'Dolar De Hong Kong'},
+                      {'code': 'HNL', 'label': 'Lempira'},
+                      {'code': 'HRK', 'label': 'Kuna'},
+                      {'code': 'HTG', 'label': 'Gourde'},
+                      {'code': 'HUF', 'label': 'Florín'},
+                      {'code': 'IDR', 'label': 'Rupia'},
+                      {'code': 'ILS', 'label': 'Nuevo Shekel Israelí'},
+                      {'code': 'INR', 'label': 'Rupia india'},
+                      {'code': 'IQD', 'label': 'Dinar iraquí'},
+                      {'code': 'IRR', 'label': 'Rial iraní'},
+                      {'code': 'ISK', 'label': 'Corona islandesa'},
+                      {'code': 'JMD', 'label': 'Dólar Jamaiquino'},
+                      {'code': 'JOD', 'label': 'Dinar jordano'},
+                      {'code': 'JPY', 'label': 'Yen'},
+                      {'code': 'KES', 'label': 'Chelín keniano'},
+                      {'code': 'KGS', 'label': 'Som'},
+                      {'code': 'KHR', 'label': 'Riel'},
+                      {'code': 'KMF', 'label': 'Franco Comoro'},
+                      {'code': 'KPW', 'label': 'Corea del Norte ganó'},
+                      {'code': 'KRW', 'label': 'Won'},
+                      {'code': 'KWD', 'label': 'Dinar kuwaití'},
+                      {'code': 'KYD', 'label': 'Dólar de las Islas Caimán'},
+                      {'code': 'KZT', 'label': 'Tenge'},
+                      {'code': 'LAK', 'label': 'Kip'},
+                      {'code': 'LBP', 'label': 'Libra libanesa'},
+                      {'code': 'LKR', 'label': 'Rupia de Sri Lanka'},
+                      {'code': 'LRD', 'label': 'Dólar liberiano'},
+                      {'code': 'LSL', 'label': 'Loti'},
+                      {'code': 'LYD', 'label': 'Dinar libio'},
+                      {'code': 'MAD', 'label': 'Dirham marroquí'},
+                      {'code': 'MDL', 'label': 'Leu moldavo'},
+                      {'code': 'MGA', 'label': 'Ariary malgache'},
+                      {'code': 'MKD', 'label': 'Denar'},
+                      {'code': 'MMK', 'label': 'Kyat'},
+                      {'code': 'MNT', 'label': 'Tugrik'},
+                      {'code': 'MOP', 'label': 'Pataca'},
+                      {'code': 'MRO', 'label': 'Ouguiya'},
+                      {'code': 'MUR', 'label': 'Rupia de Mauricio'},
+                      {'code': 'MVR', 'label': 'Rupia'},
+                      {'code': 'MWK', 'label': 'Kwacha'},
+                      {'code': 'MXN', 'label': 'Peso Mexicano'},
+                      {'code': 'MXV', 'label': 'México Unidad de Inversión (UDI)'},
+                      {'code': 'MYR', 'label': 'Ringgit malayo'},
+                      {'code': 'MZN', 'label': 'Mozambique Metical'},
+                      {'code': 'NAD', 'label': 'Dólar de Namibia'},
+                      {'code': 'NGN', 'label': 'Naira'},
+                      {'code': 'NIO', 'label': 'Córdoba Oro'},
+                      {'code': 'NOK', 'label': 'Corona noruega'},
+                      {'code': 'NPR', 'label': 'Rupia nepalí'},
+                      {'code': 'NZD', 'label': 'Dólar de Nueva Zelanda'},
+                      {'code': 'OMR', 'label': 'Rial omaní'},
+                      {'code': 'PAB', 'label': 'Balboa'},
+                      {'code': 'PEN', 'label': 'Nuevo Sol'},
+                      {'code': 'PGK', 'label': 'Kina'},
+                      {'code': 'PHP', 'label': 'Peso filipino'},
+                      {'code': 'PKR', 'label': 'Rupia de Pakistán'},
+                      {'code': 'PLN', 'label': 'Zloty'},
+                      {'code': 'PYG', 'label': 'Guaraní'},
+                      {'code': 'QAR', 'label': 'Qatar Rial'},
+                      {'code': 'RON', 'label': 'Leu rumano'},
+                      {'code': 'RSD', 'label': 'Dinar serbio'},
+                      {'code': 'RUB', 'label': 'Rublo ruso'},
+                      {'code': 'RWF', 'label': 'Franco ruandés'},
+                      {'code': 'SAR', 'label': 'Riyal saudí'},
+                      {'code': 'SBD', 'label': 'Dólar de las Islas Salomón'},
+                      {'code': 'SCR', 'label': 'Rupia de Seychelles'},
+                      {'code': 'SDG', 'label': 'Libra sudanesa'},
+                      {'code': 'SEK', 'label': 'Corona sueca'},
+                      {'code': 'SGD', 'label': 'Dolar De Singapur'},
+                      {'code': 'SHP', 'label': 'Libra de Santa Helena'},
+                      {'code': 'SLL', 'label': 'Leona'},
+                      {'code': 'SOS', 'label': 'Chelín somalí'},
+                      {'code': 'SRD', 'label': 'Dólar de Suriname'},
+                      {'code': 'SSP', 'label': 'Libra sudanesa Sur'},
+                      {'code': 'STD', 'label': 'Dobra'},
+                      {'code': 'SVC', 'label': 'Colon El Salvador'},
+                      {'code': 'SYP', 'label': 'Libra Siria'},
+                      {'code': 'SZL', 'label': 'Lilangeni'},
+                      {'code': 'THB', 'label': 'Baht'},
+                      {'code': 'TJS', 'label': 'Somoni'},
+                      {'code': 'TMT', 'label': 'Turkmenistán nuevo manat'},
+                      {'code': 'TND', 'label': 'Dinar tunecino'},
+                      {'code': 'TOP', 'label': "Pa'anga"},
+                      {'code': 'TRY', 'label': 'Lira turca'},
+                      {'code': 'TTD', 'label': 'Dólar de Trinidad y Tobago'},
+                      {'code': 'TWD', 'label': 'Nuevo dólar de Taiwán'},
+                      {'code': 'TZS', 'label': 'Shilling tanzano'},
+                      {'code': 'UAH', 'label': 'Hryvnia'},
+                      {'code': 'UGX', 'label': 'Shilling de Uganda'},
+                      {'code': 'USD', 'label': 'Dolar americano'},
+                      {'code': 'USN', 'label': 'Dólar estadounidense (día siguiente)'},
+                      {'code': 'UYI', 'label': 'Peso Uruguay en Unidades Indexadas (URUIURUI)'},
+                      {'code': 'UYU', 'label': 'Peso Uruguayo'},
+                      {'code': 'UZS', 'label': 'Uzbekistán Sum'},
+                      {'code': 'VEF', 'label': 'Bolívar'},
+                      {'code': 'VND', 'label': 'Dong'},
+                      {'code': 'VUV', 'label': 'Vatu'},
+                      {'code': 'WST', 'label': 'Tala'},
+                      {'code': 'XAF', 'label': 'Franco CFA BEAC'},
+                      {'code': 'XAG', 'label': 'Plata'},
+                      {'code': 'XAU', 'label': 'Oro'},
+                      {'code': 'XBA', 'label': 'Unidad de Mercados de Bonos Unidad Europea Composite (EURCO)'},
+                      {'code': 'XBB', 'label': 'Unidad Monetaria de Bonos de Mercados Unidad Europea (UEM-6)'},
+                      {'code': 'XBC', 'label': 'Mercados de Bonos Unidad Europea unidad de cuenta a 9 (UCE-9)'},
+                      {'code': 'XBD', 'label': 'Mercados de Bonos Unidad Europea unidad de cuenta a 17 (UCE-17)'},
+                      {'code': 'XCD', 'label': 'Dólar del Caribe Oriental'},
+                      {'code': 'XDR', 'label': 'DEG (Derechos Especiales de Giro)'},
+                      {'code': 'XOF', 'label': 'Franco CFA BCEAO'},
+                      {'code': 'XPD', 'label': 'Paladio'},
+                      {'code': 'XPF', 'label': 'Franco CFP'},
+                      {'code': 'XPT', 'label': 'Platino'},
+                      {'code': 'XSU', 'label': 'Sucre'},
+                      {'code': 'XTS', 'label': 'Códigos reservados específicamente para propósitos de prueba'},
+                      {'code': 'XUA', 'label': 'Unidad ADB de Cuenta'},
+                      {'code': 'XXX',
+                       'label': 'Los códigos asignados para las transacciones en que intervenga ninguna moneda'},
+                      {'code': 'YER', 'label': 'Rial yemení'},
+                      {'code': 'ZAR', 'label': 'Rand'},
+                      {'code': 'ZMW', 'label': 'Kwacha zambiano'},
+                      {'code': 'ZWL', 'label': 'Zimbabwe Dólar'},
+                      {'code': 'NULL', 'label': 'NULL'}]},
+ 'pais': {'label': 'País (ISO 3166)',
+          'is_system': True,
+          'items': [{'code': 'ABW', 'label': 'Aruba'},
+                    {'code': 'AFG', 'label': 'Afganistán'},
+                    {'code': 'AGO', 'label': 'Angola'},
+                    {'code': 'AIA', 'label': 'Anguila'},
+                    {'code': 'ALA', 'label': 'Islas Åland'},
+                    {'code': 'ALB', 'label': 'Albania'},
+                    {'code': 'AND', 'label': 'Andorra'},
+                    {'code': 'ARE', 'label': 'Emiratos Árabes Unidos (Los)'},
+                    {'code': 'ARG', 'label': 'Argentina'},
+                    {'code': 'ARM', 'label': 'Armenia'},
+                    {'code': 'ASM', 'label': 'Samoa Americana'},
+                    {'code': 'ATA', 'label': 'Antártida'},
+                    {'code': 'ATF', 'label': 'Territorios Australes Franceses (los)'},
+                    {'code': 'ATG', 'label': 'Antigua y Barbuda'},
+                    {'code': 'AUS', 'label': 'Australia'},
+                    {'code': 'AUT', 'label': 'Austria'},
+                    {'code': 'AZE', 'label': 'Azerbaiyán'},
+                    {'code': 'BDI', 'label': 'Burundi'},
+                    {'code': 'BEL', 'label': 'Bélgica'},
+                    {'code': 'BEN', 'label': 'Benín'},
+                    {'code': 'BES', 'label': 'Bonaire, San Eustaquio y Saba'},
+                    {'code': 'BFA', 'label': 'Burkina Faso'},
+                    {'code': 'BGD', 'label': 'Bangladés'},
+                    {'code': 'BGR', 'label': 'Bulgaria'},
+                    {'code': 'BHR', 'label': 'Baréin'},
+                    {'code': 'BHS', 'label': 'Bahamas (las)'},
+                    {'code': 'BIH', 'label': 'Bosnia y Herzegovina'},
+                    {'code': 'BLM', 'label': 'San Bartolomé'},
+                    {'code': 'BLR', 'label': 'Bielorrusia'},
+                    {'code': 'BLZ', 'label': 'Belice'},
+                    {'code': 'BMU', 'label': 'Bermudas'},
+                    {'code': 'BOL', 'label': 'Bolivia, Estado Plurinacional de'},
+                    {'code': 'BRA', 'label': 'Brasil'},
+                    {'code': 'BRB', 'label': 'Barbados'},
+                    {'code': 'BRN', 'label': 'Brunéi Darussalam'},
+                    {'code': 'BTN', 'label': 'Bután'},
+                    {'code': 'BVT', 'label': 'Isla Bouvet'},
+                    {'code': 'BWA', 'label': 'Botsuana'},
+                    {'code': 'CAF', 'label': 'República Centroafricana (la)'},
+                    {'code': 'CAN', 'label': 'Canadá'},
+                    {'code': 'CCK', 'label': 'Islas Cocos (Keeling)'},
+                    {'code': 'CHE', 'label': 'Suiza'},
+                    {'code': 'CHL', 'label': 'Chile'},
+                    {'code': 'CHN', 'label': 'China'},
+                    {'code': 'CIV', 'label': "Côte d'Ivoire"},
+                    {'code': 'CMR', 'label': 'Camerún'},
+                    {'code': 'COD', 'label': 'Congo (la República Democrática del)'},
+                    {'code': 'COG', 'label': 'Congo'},
+                    {'code': 'COK', 'label': 'Islas Cook (las)'},
+                    {'code': 'COL', 'label': 'Colombia'},
+                    {'code': 'COM', 'label': 'Comoras'},
+                    {'code': 'CPV', 'label': 'Cabo Verde'},
+                    {'code': 'CRI', 'label': 'Costa Rica'},
+                    {'code': 'CUB', 'label': 'Cuba'},
+                    {'code': 'CUW', 'label': 'Curaçao'},
+                    {'code': 'CXR', 'label': 'Isla de Navidad'},
+                    {'code': 'CYM', 'label': 'Islas Caimán (las)'},
+                    {'code': 'CYP', 'label': 'Chipre'},
+                    {'code': 'CZE', 'label': 'República Checa (la)'},
+                    {'code': 'DEU', 'label': 'Alemania'},
+                    {'code': 'DJI', 'label': 'Yibuti'},
+                    {'code': 'DMA', 'label': 'Dominica'},
+                    {'code': 'DNK', 'label': 'Dinamarca'},
+                    {'code': 'DOM', 'label': 'República Dominicana (la)'},
+                    {'code': 'DZA', 'label': 'Argelia'},
+                    {'code': 'ECU', 'label': 'Ecuador'},
+                    {'code': 'EGY', 'label': 'Egipto'},
+                    {'code': 'ERI', 'label': 'Eritrea'},
+                    {'code': 'ESH', 'label': 'Sahara Occidental'},
+                    {'code': 'ESP', 'label': 'España'},
+                    {'code': 'EST', 'label': 'Estonia'},
+                    {'code': 'ETH', 'label': 'Etiopía'},
+                    {'code': 'FIN', 'label': 'Finlandia'},
+                    {'code': 'FJI', 'label': 'Fiyi'},
+                    {'code': 'FLK', 'label': 'Islas Malvinas [Falkland] (las)'},
+                    {'code': 'FRA', 'label': 'Francia'},
+                    {'code': 'FRO', 'label': 'Islas Feroe (las)'},
+                    {'code': 'FSM', 'label': 'Micronesia (los Estados Federados de)'},
+                    {'code': 'GAB', 'label': 'Gabón'},
+                    {'code': 'GBR', 'label': 'Reino Unido (el)'},
+                    {'code': 'GEO', 'label': 'Georgia'},
+                    {'code': 'GGY', 'label': 'Guernsey'},
+                    {'code': 'GHA', 'label': 'Ghana'},
+                    {'code': 'GIB', 'label': 'Gibraltar'},
+                    {'code': 'GIN', 'label': 'Guinea'},
+                    {'code': 'GLP', 'label': 'Guadalupe'},
+                    {'code': 'GMB', 'label': 'Gambia (La)'},
+                    {'code': 'GNB', 'label': 'Guinea-Bisáu'},
+                    {'code': 'GNQ', 'label': 'Guinea Ecuatorial'},
+                    {'code': 'GRC', 'label': 'Grecia'},
+                    {'code': 'GRD', 'label': 'Granada'},
+                    {'code': 'GRL', 'label': 'Groenlandia'},
+                    {'code': 'GTM', 'label': 'Guatemala'},
+                    {'code': 'GUF', 'label': 'Guayana Francesa'},
+                    {'code': 'GUM', 'label': 'Guam'},
+                    {'code': 'GUY', 'label': 'Guyana'},
+                    {'code': 'HKG', 'label': 'Hong Kong'},
+                    {'code': 'HMD', 'label': 'Isla Heard e Islas McDonald'},
+                    {'code': 'HND', 'label': 'Honduras'},
+                    {'code': 'HRV', 'label': 'Croacia'},
+                    {'code': 'HTI', 'label': 'Haití'},
+                    {'code': 'HUN', 'label': 'Hungría'},
+                    {'code': 'IDN', 'label': 'Indonesia'},
+                    {'code': 'IMN', 'label': 'Isla de Man'},
+                    {'code': 'IND', 'label': 'India'},
+                    {'code': 'IOT', 'label': 'Territorio Británico del Océano Índico (el)'},
+                    {'code': 'IRL', 'label': 'Irlanda'},
+                    {'code': 'IRN', 'label': 'Irán (la República Islámica de)'},
+                    {'code': 'IRQ', 'label': 'Irak'},
+                    {'code': 'ISL', 'label': 'Islandia'},
+                    {'code': 'ISR', 'label': 'Israel'},
+                    {'code': 'ITA', 'label': 'Italia'},
+                    {'code': 'JAM', 'label': 'Jamaica'},
+                    {'code': 'JEY', 'label': 'Jersey'},
+                    {'code': 'JOR', 'label': 'Jordania'},
+                    {'code': 'JPN', 'label': 'Japón'},
+                    {'code': 'KAZ', 'label': 'Kazajistán'},
+                    {'code': 'KEN', 'label': 'Kenia'},
+                    {'code': 'KGZ', 'label': 'Kirguistán'},
+                    {'code': 'KHM', 'label': 'Camboya'},
+                    {'code': 'KIR', 'label': 'Kiribati'},
+                    {'code': 'KNA', 'label': 'San Cristóbal y Nieves'},
+                    {'code': 'KOR', 'label': 'Corea (la República de)'},
+                    {'code': 'KWT', 'label': 'Kuwait'},
+                    {'code': 'LAO', 'label': 'Lao, (la) República Democrática Popular'},
+                    {'code': 'LBN', 'label': 'Líbano'},
+                    {'code': 'LBR', 'label': 'Liberia'},
+                    {'code': 'LBY', 'label': 'Libia'},
+                    {'code': 'LCA', 'label': 'Santa Lucía'},
+                    {'code': 'LIE', 'label': 'Liechtenstein'},
+                    {'code': 'LKA', 'label': 'Sri Lanka'},
+                    {'code': 'LSO', 'label': 'Lesoto'},
+                    {'code': 'LTU', 'label': 'Lituania'},
+                    {'code': 'LUX', 'label': 'Luxemburgo'},
+                    {'code': 'LVA', 'label': 'Letonia'},
+                    {'code': 'MAC', 'label': 'Macao'},
+                    {'code': 'MAF', 'label': 'San Martín (parte francesa)'},
+                    {'code': 'MAR', 'label': 'Marruecos'},
+                    {'code': 'MCO', 'label': 'Mónaco'},
+                    {'code': 'MDA', 'label': 'Moldavia (la República de)'},
+                    {'code': 'MDG', 'label': 'Madagascar'},
+                    {'code': 'MDV', 'label': 'Maldivas'},
+                    {'code': 'MEX', 'label': 'México'},
+                    {'code': 'MHL', 'label': 'Islas Marshall (las)'},
+                    {'code': 'MKD', 'label': 'Macedonia (la antigua República Yugoslava de)'},
+                    {'code': 'MLI', 'label': 'Malí'},
+                    {'code': 'MLT', 'label': 'Malta'},
+                    {'code': 'MMR', 'label': 'Myanmar'},
+                    {'code': 'MNE', 'label': 'Montenegro'},
+                    {'code': 'MNG', 'label': 'Mongolia'},
+                    {'code': 'MNP', 'label': 'Islas Marianas del Norte (las)'},
+                    {'code': 'MOZ', 'label': 'Mozambique'},
+                    {'code': 'MRT', 'label': 'Mauritania'},
+                    {'code': 'MSR', 'label': 'Montserrat'},
+                    {'code': 'MTQ', 'label': 'Martinica'},
+                    {'code': 'MUS', 'label': 'Mauricio'},
+                    {'code': 'MWI', 'label': 'Malaui'},
+                    {'code': 'MYS', 'label': 'Malasia'},
+                    {'code': 'MYT', 'label': 'Mayotte'},
+                    {'code': 'NAM', 'label': 'Namibia'},
+                    {'code': 'NCL', 'label': 'Nueva Caledonia'},
+                    {'code': 'NER', 'label': 'Níger (el)'},
+                    {'code': 'NFK', 'label': 'Isla Norfolk'},
+                    {'code': 'NGA', 'label': 'Nigeria'},
+                    {'code': 'NIC', 'label': 'Nicaragua'},
+                    {'code': 'NIU', 'label': 'Niue'},
+                    {'code': 'NLD', 'label': 'Países Bajos (los)'},
+                    {'code': 'NOR', 'label': 'Noruega'},
+                    {'code': 'NPL', 'label': 'Nepal'},
+                    {'code': 'NRU', 'label': 'Nauru'},
+                    {'code': 'NZL', 'label': 'Nueva Zelanda'},
+                    {'code': 'OMN', 'label': 'Omán'},
+                    {'code': 'PAK', 'label': 'Pakistán'},
+                    {'code': 'PAN', 'label': 'Panamá'},
+                    {'code': 'PCN', 'label': 'Pitcairn'},
+                    {'code': 'PER', 'label': 'Perú'},
+                    {'code': 'PHL', 'label': 'Filipinas (las)'},
+                    {'code': 'PLW', 'label': 'Palaos'},
+                    {'code': 'PNG', 'label': 'Papúa Nueva Guinea'},
+                    {'code': 'POL', 'label': 'Polonia'},
+                    {'code': 'PRI', 'label': 'Puerto Rico'},
+                    {'code': 'PRK', 'label': 'Corea (la República Democrática Popular de)'},
+                    {'code': 'PRT', 'label': 'Portugal'},
+                    {'code': 'PRY', 'label': 'Paraguay'},
+                    {'code': 'PSE', 'label': 'Palestina, Estado de'},
+                    {'code': 'PYF', 'label': 'Polinesia Francesa'},
+                    {'code': 'QAT', 'label': 'Catar'},
+                    {'code': 'REU', 'label': 'Reunión'},
+                    {'code': 'ROU', 'label': 'Rumania'},
+                    {'code': 'RUS', 'label': 'Rusia, (la) Federación de'},
+                    {'code': 'RWA', 'label': 'Ruanda'},
+                    {'code': 'SAU', 'label': 'Arabia Saudita'},
+                    {'code': 'SDN', 'label': 'Sudán (el)'},
+                    {'code': 'SEN', 'label': 'Senegal'},
+                    {'code': 'SGP', 'label': 'Singapur'},
+                    {'code': 'SGS', 'label': 'Georgia del sur y las islas sandwich del sur'},
+                    {'code': 'SHN', 'label': 'Santa Helena, Ascensión y Tristán de Acuña'},
+                    {'code': 'SJM', 'label': 'Svalbard y Jan Mayen'},
+                    {'code': 'SLB', 'label': 'Islas Salomón (las)'},
+                    {'code': 'SLE', 'label': 'Sierra leona'},
+                    {'code': 'NULL', 'label': 'NULL'}]},
+ 'estado': {'label': 'Estado / Provincia',
+            'is_system': True,
+            'items': [{'code': 'AGU', 'label': 'Aguascalientes', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'BCN', 'label': 'Baja California', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'BCS', 'label': 'Baja California Sur', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'CAM', 'label': 'Campeche', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'CHP', 'label': 'Chiapas', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'CHH', 'label': 'Chihuahua', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'CMX', 'label': 'Ciudad de México', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'COA', 'label': 'Coahuila', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'COL', 'label': 'Colima', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'DUR', 'label': 'Durango', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'GUA', 'label': 'Guanajuato', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'GRO', 'label': 'Guerrero', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'HID', 'label': 'Hidalgo', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'JAL', 'label': 'Jalisco', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'MEX', 'label': 'Estado de México', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'MIC', 'label': 'Michoacán', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'MOR', 'label': 'Morelos', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'NAY', 'label': 'Nayarit', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'NLE', 'label': 'Nuevo León', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'OAX', 'label': 'Oaxaca', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'PUE', 'label': 'Puebla', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'QUE', 'label': 'Querétaro', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'ROO', 'label': 'Quintana Roo', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'SLP', 'label': 'San Luis Potosí', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'SIN', 'label': 'Sinaloa', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'SON', 'label': 'Sonora', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'TAB', 'label': 'Tabasco', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'TAM', 'label': 'Tamaulipas', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'TLA', 'label': 'Tlaxcala', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'VER', 'label': 'Veracruz', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'YUC', 'label': 'Yucatán', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
+                      {'code': 'ZAC', 'label': 'Zacatecas', 'parent_catalog': 'pais', 'parent_code': 'MEX'}]},
+ 'tipo_domicilio': {'label': 'Tipo de domicilio',
+                    'is_system': False,
+                    'items': [{'code': 'fiscal', 'label': 'Fiscal'},
+                              {'code': 'oficina', 'label': 'Oficina'},
+                              {'code': 'sucursal', 'label': 'Sucursal'},
+                              {'code': 'bodega', 'label': 'Bodega'},
+                              {'code': 'patio', 'label': 'Patio'},
+                              {'code': 'terminal', 'label': 'Terminal'},
+                              {'code': 'almacen', 'label': 'Almacén'}]},
+ 'area': {'label': 'Área / Departamento',
+          'is_system': False,
+          'items': [{'code': 'ventas', 'label': 'Ventas'},
+                    {'code': 'operaciones', 'label': 'Operaciones'},
+                    {'code': 'facturacion', 'label': 'Facturación'},
+                    {'code': 'cobranza', 'label': 'Cobranza'},
+                    {'code': 'servicio_cliente', 'label': 'Servicio al cliente'}]},
+ 'cobertura': {'label': 'Cobertura',
+               'is_system': True,
+               'items': [{'code': 'nacional', 'label': 'Nacional'},
+                         {'code': 'internacional', 'label': 'Internacional'}]},
+ 'clasificacion_proveedor': {'label': 'Clasificación del proveedor',
+                             'is_system': False,
+                             'items': [{'code': 'naviera', 'label': 'Naviera'},
+                                       {'code': 'aerolinea', 'label': 'Aerolínea'},
+                                       {'code': 'transportista_terrestre', 'label': 'Transportista Terrestre'},
+                                       {'code': 'ferrocarril', 'label': 'Ferrocarril'},
+                                       {'code': 'agente_aduanal', 'label': 'Agente Aduanal'},
+                                       {'code': 'agente_carga', 'label': 'Agente de Carga'},
+                                       {'code': 'agente_corresponsal', 'label': 'Agente Corresponsal'},
+                                       {'code': 'almacen', 'label': 'Almacén'},
+                                       {'code': 'aseguradora', 'label': 'Aseguradora'},
+                                       {'code': 'paqueteria', 'label': 'Paquetería'},
+                                       {'code': 'otro', 'label': 'Otro'}]},
+ 'tipo_equipo': {'label': 'Tipo de equipo / contenedor',
+                 'is_system': True,
+                 'items': [{'code': '40DC',
+                            'label': "40' Standard",
+                            'extra': {'modo': 'maritimo',
+                                      'largo_m': 12.035,
+                                      'ancho_m': 2.35,
+                                      'alto_m': 2.392,
+                                      'capacidad_m3': 67.7,
+                                      'tara_kg': 3700,
+                                      'carga_max_kg': 26790}},
+                           {'code': '20DC',
+                            'label': "20' Standard",
+                            'extra': {'modo': 'maritimo',
+                                      'largo_m': 5.9,
+                                      'ancho_m': 2.35,
+                                      'alto_m': 2.392,
+                                      'capacidad_m3': 33.2,
+                                      'tara_kg': 2230,
+                                      'carga_max_kg': 21770}},
+                           {'code': '20OT',
+                            'label': "20' Open Top",
+                            'extra': {'modo': 'maritimo',
+                                      'largo_m': 5.894,
+                                      'ancho_m': 2.311,
+                                      'alto_m': 2.354,
+                                      'capacidad_m3': 32.23,
+                                      'tara_kg': 2400,
+                                      'carga_max_kg': 30490}},
+                           {'code': '20FR',
+                            'label': "20' Flat Rack",
+                            'extra': {'modo': 'maritimo',
+                                      'largo_m': 5.62,
+                                      'ancho_m': 2.23,
+                                      'alto_m': 2.233,
+                                      'tara_kg': 2530,
+                                      'carga_max_kg': 21470}},
+                           {'code': '40HC',
+                            'label': "40' High Cube",
+                            'extra': {'modo': 'maritimo',
+                                      'largo_m': 12.036,
+                                      'ancho_m': 2.35,
+                                      'alto_m': 2.697,
+                                      'capacidad_m3': 76.3,
+                                      'tara_kg': 3970,
+                                      'carga_max_kg': 26510}},
+                           {'code': '20PL',
+                            'label': "20' Platform",
+                            'extra': {'modo': 'maritimo',
+                                      'largo_m': 6.058,
+                                      'ancho_m': 2.438,
+                                      'alto_m': 0.37,
+                                      'tara_kg': 2520,
+                                      'carga_max_kg': 27960}},
+                           {'code': '20FRC',
+                            'label': "20' Flat Rack Collapsible",
+                            'extra': {'modo': 'maritimo',
+                                      'largo_m': 5.618,
+                                      'ancho_m': 2.206,
+                                      'alto_m': 2.233,
+                                      'tara_kg': 2750,
+                                      'carga_max_kg': 27730}},
+                           {'code': '20BK',
+                            'label': "20' Bulk",
+                            'extra': {'modo': 'maritimo',
+                                      'largo_m': 5.93,
+                                      'ancho_m': 2.35,
+                                      'alto_m': 2.34,
+                                      'capacidad_m3': 32.0,
+                                      'tara_kg': 2450,
+                                      'carga_max_kg': 21350}},
+                           {'code': '20TK',
+                            'label': "20' Tank",
+                            'extra': {'modo': 'maritimo',
+                                      'largo_m': 6.058,
+                                      'ancho_m': 2.438,
+                                      'alto_m': 2.438,
+                                      'tara_kg': 4100,
+                                      'carga_max_kg': 26200}},
+                           {'code': 'LD2',
+                            'label': 'LD2',
+                            'extra': {'modo': 'aereo',
+                                      'capacidad_m3': 3.5,
+                                      'tara_kg': 30,
+                                      'carga_max_kg': 1225,
+                                      'nota': 'Aviones 767'}},
+                           {'code': 'LD3',
+                            'label': 'LD3',
+                            'extra': {'modo': 'aereo',
+                                      'capacidad_m3': 4.2,
+                                      'tara_kg': 80,
+                                      'carga_max_kg': 1587,
+                                      'nota': 'B747/B777/DC10/MD-11/A310/A330/A340'}},
+                           {'code': 'LBD',
+                            'label': 'LBD (Flex Door)',
+                            'extra': {'modo': 'aereo',
+                                      'capacidad_m3': 7.0,
+                                      'tara_kg': 123,
+                                      'carga_max_kg': 2449,
+                                      'nota': 'Aviones 767'}},
+                           {'code': 'LD6',
+                            'label': 'LD6',
+                            'extra': {'modo': 'aereo',
+                                      'capacidad_m3': 8.9,
+                                      'tara_kg': 175,
+                                      'carga_max_kg': 3175,
+                                      'nota': 'B747/B777/DC10/MD-11/A310/A330/A340'}},
+                           {'code': 'PAG',
+                            'label': 'PAP / PIP / PAG',
+                            'extra': {'modo': 'aereo',
+                                      'capacidad_m3': 10.0,
+                                      'tara_kg': 120,
+                                      'carga_max_kg': 6033,
+                                      'nota': 'Boeing 747/767/777/DC10'}},
+                           {'code': 'LD9',
+                            'label': 'LD9 AAP',
+                            'extra': {'modo': 'aereo',
+                                      'capacidad_m3': 10.0,
+                                      'tara_kg': 85,
+                                      'carga_max_kg': 1588,
+                                      'nota': 'Boeing 747/777/DC10'}},
+                           {'code': 'XAW',
+                            'label': 'XAW',
+                            'extra': {'modo': 'aereo',
+                                      'capacidad_m3': 14.0,
+                                      'tara_kg': 170,
+                                      'carga_max_kg': 5000,
+                                      'nota': 'Boeing 747/777/DC10'}},
+                           {'code': 'PMC',
+                            'label': 'PMC',
+                            'extra': {'modo': 'aereo',
+                                      'capacidad_m3': 12.7,
+                                      'tara_kg': 130,
+                                      'carga_max_kg': 6804,
+                                      'nota': 'Boeing 747/767/777'}},
+                           {'code': 'LD8',
+                            'label': 'LD8',
+                            'extra': {'modo': 'aereo', 'capacidad_m3': 7.2, 'tara_kg': 120, 'carga_max_kg': 2450}},
+                           {'code': 'DV48',
+                            'label': "Dry Van 48'",
+                            'extra': {'modo': 'terrestre',
+                                      'largo_m': 14.63,
+                                      'ancho_m': 2.59,
+                                      'alto_m': 2.3,
+                                      'capacidad_m3': 98.0,
+                                      'carga_max_kg': 20412,
+                                      'pallets': 22}},
+                           {'code': 'SD',
+                            'label': 'Legal Step Deck (Single Drop)',
+                            'extra': {'modo': 'terrestre',
+                                      'largo_m': 11.58,
+                                      'ancho_m': 2.59,
+                                      'alto_m': 3.05,
+                                      'carga_max_kg': 20865}},
+                           {'code': 'TANK',
+                            'label': 'Tanker',
+                            'extra': {'modo': 'terrestre',
+                                      'largo_m': 16.15,
+                                      'ancho_m': 2.59,
+                                      'alto_m': 2.3,
+                                      'capacidad_l': 22712}},
+                           {'code': 'DV53',
+                            'label': "Dry Van 53'",
+                            'extra': {'modo': 'terrestre',
+                                      'largo_m': 16.15,
+                                      'ancho_m': 2.59,
+                                      'alto_m': 2.3,
+                                      'capacidad_m3': 99.11,
+                                      'carga_max_kg': 20412,
+                                      'pallets': 26}},
+                           {'code': 'DD',
+                            'label': 'Double Drop (Low Boy)',
+                            'extra': {'modo': 'terrestre',
+                                      'largo_m': 8.53,
+                                      'ancho_m': 2.59,
+                                      'alto_m': 3.51,
+                                      'carga_max_kg': 18144}},
+                           {'code': 'RF48',
+                            'label': "48' Reefer Trailer",
+                            'extra': {'modo': 'terrestre',
+                                      'largo_m': 14.63,
+                                      'ancho_m': 2.4,
+                                      'alto_m': 2.3,
+                                      'capacidad_m3': 90.0,
+                                      'carga_max_kg': 19958,
+                                      'pallets': 20}},
+                           {'code': 'FB48',
+                            'label': "48' Legal Flatbed",
+                            'extra': {'modo': 'terrestre',
+                                      'largo_m': 14.63,
+                                      'ancho_m': 2.59,
+                                      'alto_m': 2.59,
+                                      'carga_max_kg': 21772}},
+                           {'code': 'PUP28',
+                            'label': "Pup Trailer 28'",
+                            'extra': {'modo': 'terrestre',
+                                      'largo_m': 8.53,
+                                      'ancho_m': 2.59,
+                                      'alto_m': 2.3,
+                                      'capacidad_m3': 57.45,
+                                      'carga_max_kg': 9979,
+                                      'pallets': 14}},
+                           {'code': 'IM53',
+                            'label': "Intermodal 53' Container",
+                            'extra': {'modo': 'terrestre',
+                                      'largo_m': 16.15,
+                                      'ancho_m': 2.59,
+                                      'alto_m': 2.3,
+                                      'capacidad_m3': 99.11,
+                                      'carga_max_kg': 19958,
+                                      'pallets': 24}}]},
+ 'modo_tarifario': {'label': 'Modo de tarifario',
+                    'is_system': True,
+                    'items': [{'code': 'aereo', 'label': 'Aéreo'},
+                              {'code': 'maritimo_fcl', 'label': 'Marítimo FCL'},
+                              {'code': 'maritimo_lcl', 'label': 'Marítimo LCL'},
+                              {'code': 'terrestre', 'label': 'Terrestre'}]},
+ 'unidad_tarifa': {'label': 'Unidad de tarifa',
+                   'is_system': True,
+                   'items': [{'code': 'per_kg', 'label': 'Por kg'},
+                             {'code': 'per_wm', 'label': 'Por peso/medida (W/M)'},
+                             {'code': 'per_container', 'label': 'Por contenedor'},
+                             {'code': 'flat', 'label': 'Tarifa plana'}]},
+ 'concepto_cargo': {'label': 'Concepto de cargo',
+                    'is_system': False,
+                    'items': [{'code': 'combustible', 'label': 'Combustible (BAF/FSC)'},
+                              {'code': 'dgr', 'label': 'Mercancía peligrosa (DGR)'},
+                              {'code': 'moc', 'label': 'MOC (mínimo origen)'},
+                              {'code': 'afs', 'label': 'AFS'},
+                              {'code': 'thc', 'label': 'THC (manejo en terminal)'},
+                              {'code': 'maniobras', 'label': 'Maniobras'},
+                              {'code': 'almacenaje', 'label': 'Almacenaje'},
+                              {'code': 'seguro', 'label': 'Seguro'},
+                              {'code': 'despacho', 'label': 'Despacho aduanal'},
+                              {'code': 'documentacion', 'label': 'Documentación'},
+                              {'code': 'custodia', 'label': 'Custodia'},
+                              {'code': 'otro', 'label': 'Otro'}]}}
+
+TENANT_CATALOG_LABELS = {'servicio': 'Servicios que ofrece',
+ 'puerto': 'Puertos donde opera',
+ 'aeropuerto': 'Aeropuertos donde opera',
+ 'aduana': 'Aduanas donde opera'}

backend/api/v1/modules/crm/catalogs/service.py

@@ -0,0 +1,168 @@
+"""Lógica de negocio de los catálogos de referencia del CRM."""
+
+from typing import Any
+
+from fastapi import HTTPException, status
+from sqlalchemy import and_, or_
+from sqlalchemy.orm import Session
+
+from core.security import is_hub_admin
+
+from .dto import CatalogItemCreate, CatalogItemUpdate, CatalogMeta
+from .models import CatalogItem
+from .seed_data import GLOBAL_CATALOGS, TENANT_CATALOG_LABELS
+
+# Metadata de catálogos (labels y si el cliente puede llenarlos).
+CATALOG_LABELS: dict[str, str] = {k: v["label"] for k, v in GLOBAL_CATALOGS.items()}
+CATALOG_LABELS.update(TENANT_CATALOG_LABELS)
+# Catálogos que administra el cliente (tenant). El resto son globales (Aduanasoft).
+TENANT_CATALOG_KEYS = set(TENANT_CATALOG_LABELS.keys())
+KNOWN_CATALOGS = set(CATALOG_LABELS.keys())
+
+
+def _require_known(catalog: str) -> None:
+    if catalog not in KNOWN_CATALOGS:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Catálogo '{catalog}' no existe")
+
+
+def list_meta(db: Session, tenant_id: int) -> list[CatalogMeta]:
+    """Lista todos los catálogos disponibles con su conteo (global + del tenant)."""
+    out: list[CatalogMeta] = []
+    for key, label in CATALOG_LABELS.items():
+        is_tenant = key in TENANT_CATALOG_KEYS
+        count = (
+            db.query(CatalogItem)
+            .filter(
+                CatalogItem.catalog == key,
+                or_(CatalogItem.tenant_id.is_(None), CatalogItem.tenant_id == tenant_id),
+            )
+            .count()
+        )
+        out.append(
+            CatalogMeta(
+                catalog=key,
+                label=label,
+                scope="tenant" if is_tenant else "global",
+                is_system=bool(GLOBAL_CATALOGS.get(key, {}).get("is_system", False)),
+                count=count,
+            )
+        )
+    return out
+
+
+def list_items(
+    db: Session,
+    catalog: str,
+    tenant_id: int,
+    parent_code: str | None = None,
+    include_inactive: bool = False,
+) -> list[CatalogItem]:
+    _require_known(catalog)
+    q = db.query(CatalogItem).filter(
+        CatalogItem.catalog == catalog,
+        or_(CatalogItem.tenant_id.is_(None), CatalogItem.tenant_id == tenant_id),
+    )
+    if not include_inactive:
+        q = q.filter(CatalogItem.is_active.is_(True))
+    if parent_code:
+        q = q.filter(CatalogItem.parent_code == parent_code)
+    return q.order_by(CatalogItem.sort_order, CatalogItem.label).all()
+
+
+def _resolve_write_scope(catalog: str, scope: str | None, current_user: dict) -> int | None:
+    """Devuelve el tenant_id a usar al escribir (None = global) y valida permisos.
+
+    - scope 'global' → solo hub_admin puede tocar catálogos globales (Aduanasoft).
+    - scope 'tenant' (default) → se guarda en el tenant del usuario.
+    """
+    wants_global = scope == "global"
+    if wants_global:
+        if not is_hub_admin(current_user):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Solo un administrador de Aduanasoft puede editar catálogos globales.",
+            )
+        return None
+    return int(current_user["tenant_id"])
+
+
+def create_item(
+    db: Session, catalog: str, data: CatalogItemCreate, current_user: dict, scope: str | None = None
+) -> CatalogItem:
+    _require_known(catalog)
+    target_tenant = _resolve_write_scope(catalog, scope, current_user)
+
+    # No duplicar por (catalog, code, tenant_id)
+    exists = (
+        db.query(CatalogItem)
+        .filter(
+            CatalogItem.catalog == catalog,
+            CatalogItem.code == data.code,
+            CatalogItem.tenant_id.is_(None) if target_tenant is None else CatalogItem.tenant_id == target_tenant,
+        )
+        .first()
+    )
+    if exists:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"Ya existe la clave '{data.code}' en el catálogo '{catalog}'.",
+        )
+
+    item = CatalogItem(
+        catalog=catalog,
+        code=data.code,
+        label=data.label,
+        parent_catalog=data.parent_catalog,
+        parent_code=data.parent_code,
+        tenant_id=target_tenant,
+        sort_order=data.sort_order,
+        is_active=data.is_active,
+        is_system=False,
+        created_by=current_user.get("sub"),
+        updated_by=current_user.get("sub"),
+    )
+    db.add(item)
+    db.commit()
+    db.refresh(item)
+    return item
+
+
+def _get_writable(db: Session, catalog: str, item_id: int, current_user: dict) -> CatalogItem:
+    _require_known(catalog)
+    item = db.query(CatalogItem).filter(CatalogItem.id == item_id, CatalogItem.catalog == catalog).first()
+    if not item:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Elemento no encontrado")
+    if item.tenant_id is None:
+        # Global (Aduanasoft): solo hub_admin.
+        if not is_hub_admin(current_user):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Solo un administrador de Aduanasoft puede editar este catálogo global.",
+            )
+    elif item.tenant_id != int(current_user["tenant_id"]):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Elemento no encontrado")
+    return item
+
+
+def update_item(
+    db: Session, catalog: str, item_id: int, data: CatalogItemUpdate, current_user: dict
+) -> CatalogItem:
+    item = _get_writable(db, catalog, item_id, current_user)
+    payload: dict[str, Any] = data.model_dump(exclude_unset=True)
+    for field, value in payload.items():
+        setattr(item, field, value)
+    item.updated_by = current_user.get("sub")
+    db.commit()
+    db.refresh(item)
+    return item
+
+
+def delete_item(db: Session, catalog: str, item_id: int, current_user: dict) -> None:
+    item = _get_writable(db, catalog, item_id, current_user)
+    if item.is_system:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Un catálogo base del sistema no se puede borrar; puedes desactivarlo.",
+        )
+    db.delete(item)
+    db.commit()

backend/api/v1/modules/crm/quotes/dto.py

@@ -86,6 +86,7 @@ class QuoteResponse(QuoteBase):
     status: str
     total_cost: Decimal
     total_sale: Decimal
+    pdf_file_key: str | None = None
     sent_at: datetime | None = None
     accepted_at: datetime | None = None
     rejected_at: datetime | None = None
@@ -100,3 +101,30 @@ class QuoteResponse(QuoteBase):
     @property
     def margin(self) -> Decimal:
         return (self.total_sale or Decimal(0)) - (self.total_cost or Decimal(0))
+
+
+# ----- Configuración de marca del formato de cotización -----
+
+class QuoteSettingsInput(BaseModel):
+    emitter_name: str | None = Field(None, max_length=255)
+    emitter_rfc: str | None = Field(None, max_length=13)
+    emitter_address: str | None = None
+    emitter_phone: str | None = Field(None, max_length=60)
+    emitter_email: str | None = Field(None, max_length=255)
+    emitter_website: str | None = Field(None, max_length=255)
+    accent_color: str | None = Field(None, max_length=9)
+    quote_prefix: str | None = Field(None, max_length=12)
+    default_terms: str | None = None
+    footer_note: str | None = None
+
+
+class QuoteSettingsResponse(QuoteSettingsInput):
+    model_config = ConfigDict(from_attributes=True)
+    id: int | None = None
+    logo_file_key: str | None = None
+
+
+class SendQuoteEmailRequest(BaseModel):
+    to: str | None = None
+    subject: str | None = None
+    message: str | None = None

backend/api/v1/modules/crm/quotes/models.py

@@ -34,10 +34,35 @@ class Quote(Base, TenantScopedMixin, TimestampMixin):
     notes: Mapped[str | None] = mapped_column(Text, nullable=True)
     terms: Mapped[str | None] = mapped_column(Text, nullable=True)
     owner_user_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
+    # Clave del PDF generado en MinIO (para regenerar/enviar)
+    pdf_file_key: Mapped[str | None] = mapped_column(String(512), nullable=True)
     created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
     updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
 
 
+class QuoteSettings(Base, TenantScopedMixin, TimestampMixin):
+    """Configuración de marca del formato de cotización, por compañía (tenant).
+
+    Encabezado del emisor, logo y textos por defecto que se imprimen en el PDF.
+    """
+
+    __tablename__ = "quote_settings"
+    __table_args__ = {"schema": "crm"}
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    emitter_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    emitter_rfc: Mapped[str | None] = mapped_column(String(13), nullable=True)
+    emitter_address: Mapped[str | None] = mapped_column(Text, nullable=True)
+    emitter_phone: Mapped[str | None] = mapped_column(String(60), nullable=True)
+    emitter_email: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    emitter_website: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    logo_file_key: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    accent_color: Mapped[str | None] = mapped_column(String(9), nullable=True, server_default=text("'#2f6bf0'"))
+    quote_prefix: Mapped[str | None] = mapped_column(String(12), nullable=True, server_default=text("'COT'"))
+    default_terms: Mapped[str | None] = mapped_column(Text, nullable=True)
+    footer_note: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+
 class QuoteItem(Base, TenantScopedMixin, TimestampMixin):
     """Concepto de una cotización (flete, transporte terrestre, despacho, gastos destino, otros)."""
 

backend/api/v1/modules/crm/quotes/pdf.py

@@ -0,0 +1,376 @@
+"""Generador del PDF de Cotización — diseño profesional, sin dependencias de sistema.
+
+Compone un PDF 1.4 byte a byte (Helvetica / Helvetica-Bold) con barras de sección,
+tabla de costos con bordes y filas alternadas, caja de totales y logo incrustado
+(JPEG /DCTDecode vía Pillow). El branding (emisor, color) viene de la config por tenant.
+"""
+
+from __future__ import annotations
+
+import io
+from decimal import Decimal
+
+_W = 612
+_H = 792
+_ML = 50           # margen izquierdo
+_MR = 562          # margen derecho (x)
+
+CONCEPT_LABELS = {
+    "flete_internacional": "Flete internacional",
+    "transporte_terrestre": "Transporte terrestre",
+    "despacho_aduanal": "Despacho aduanal",
+    "gastos_destino": "Gastos en destino",
+    "otros": "Otros cargos",
+}
+
+_TRANSLATE = str.maketrans({"—": "-", "–": "-", "“": '"', "”": '"', "‘": "'", "’": "'", "•": "-", "…": "...", "\t": " "})
+
+
+def _esc(text) -> str:
+    s = ("" if text is None else str(text)).translate(_TRANSLATE)
+    s = s.encode("latin-1", "replace").decode("latin-1")
+    return s.replace("\\", r"\\").replace("(", r"\(").replace(")", r"\)")
+
+
+def _money(value) -> str:
+    return f"{Decimal(str(value or 0)).quantize(Decimal('0.01')):,.2f}"
+
+
+def _num(value) -> str:
+    return f"{Decimal(str(value or 0)):,.2f}"
+
+
+# Ancho aprox de una cadena en Helvetica (para alinear a la derecha / truncar)
+def _text_w(s: str, size: float, bold: bool = False) -> float:
+    return len(s) * size * (0.56 if bold else 0.52)
+
+
+def _fit(s: str, size: float, max_w: float) -> str:
+    s = s or ""
+    if _text_w(s, size) <= max_w:
+        return s
+    while s and _text_w(s + "…", size) > max_w:
+        s = s[:-1]
+    return s + "…"
+
+
+def _wrap(text: str, width_chars: int) -> list[str]:
+    words = (text or "").split()
+    if not words:
+        return []
+    out, cur = [], ""
+    for w in words:
+        cand = f"{cur} {w}".strip()
+        if len(cand) > width_chars and cur:
+            out.append(cur)
+            cur = w
+        else:
+            cur = cand
+    if cur:
+        out.append(cur)
+    return out
+
+
+def _hex_rgb(hexs: str | None) -> tuple[float, float, float]:
+    try:
+        h = (hexs or "#12294c").lstrip("#")
+        return tuple(int(h[i : i + 2], 16) / 255 for i in (0, 2, 4))  # type: ignore[return-value]
+    except Exception:
+        return (0.07, 0.16, 0.30)
+
+
+def _prep_logo(logo_bytes: bytes | None):
+    if not logo_bytes:
+        return None
+    try:
+        from PIL import Image
+
+        im = Image.open(io.BytesIO(logo_bytes)).convert("RGB")
+        im.thumbnail((600, 300))
+        buf = io.BytesIO()
+        im.save(buf, format="JPEG", quality=88)
+        return buf.getvalue(), im.width, im.height
+    except Exception:
+        return None
+
+
+class _Canvas:
+    """Acumula operadores de contenido con paginación simple."""
+
+    def __init__(self):
+        self.pages: list[list[str]] = [[]]
+        self.y = _H
+
+    @property
+    def ops(self) -> list[str]:
+        return self.pages[-1]
+
+    def new_page(self):
+        self.pages.append([])
+        self.y = _H - 50
+
+    def ensure(self, needed: float):
+        if self.y - needed < 50:
+            self.new_page()
+
+    def rect(self, x, y, w, h, rgb):
+        r, g, b = rgb
+        self.ops.append(f"{r:.3f} {g:.3f} {b:.3f} rg {x:.1f} {y:.1f} {w:.1f} {h:.1f} re f")
+
+    def line(self, x1, y1, x2, y2, rgb, width=0.6):
+        r, g, b = rgb
+        self.ops.append(f"{width} w {r:.3f} {g:.3f} {b:.3f} RG {x1:.1f} {y1:.1f} m {x2:.1f} {y2:.1f} l S")
+
+    def text(self, x, y, s, size=10, rgb=(0, 0, 0), bold=False, right=False):
+        font = "F2" if bold else "F1"
+        r, g, b = rgb
+        tx = x - _text_w(str(s), size, bold) if right else x
+        self.ops.append(f"BT /{font} {size} Tf {r:.3f} {g:.3f} {b:.3f} rg 1 0 0 1 {tx:.1f} {y:.1f} Tm ({_esc(s)}) Tj ET")
+
+
+def build_quote_pdf(
+    *,
+    emitter: dict,
+    head: dict,
+    client: dict,
+    cargo: list[tuple[str, str]],
+    route: list[tuple[str, str]],
+    items: list[dict],
+    currency: str,
+    subtotal,
+    terms: str | None,
+    footer: str | None,
+    logo_bytes: bytes | None = None,
+    accent: str | None = "#12294c",
+) -> bytes:
+    ACC = _hex_rgb(accent)
+    INK = (0.10, 0.15, 0.24)
+    GRAY = (0.42, 0.47, 0.55)
+    LINE = (0.80, 0.84, 0.90)
+    ZEBRA = (0.955, 0.965, 0.980)
+    logo = _prep_logo(logo_bytes)
+
+    c = _Canvas()
+
+    # ---------------- Encabezado ----------------
+    c.rect(0, _H - 12, _W, 12, ACC)  # banda superior
+    logo_bottom = _H - 95
+    if logo:
+        _, lw, lh = logo
+        dw, dh = 150.0, 150.0 * lh / lw
+        if dh > 55:
+            dh, dw = 55.0, 55.0 * lw / lh
+        c.ops.append(f"q {dw:.1f} 0 0 {dh:.1f} {_ML} {logo_bottom:.1f} cm /Im0 Do Q")
+    else:
+        c.text(_ML, _H - 55, emitter.get("name") or "Emisor", 16, INK, bold=True)
+
+    # Emisor (derecha)
+    ex, ey = 320, _H - 42
+    c.text(ex, ey, emitter.get("name") or "Emisor", 12, INK, bold=True)
+    ey -= 14
+    em_lines = []
+    if emitter.get("rfc"):
+        em_lines.append(f"RFC: {emitter['rfc']}")
+    for a in (emitter.get("address") or "").splitlines():
+        if a.strip():
+            em_lines.append(a.strip())
+    contact = "   ".join([x for x in [emitter.get("phone"), emitter.get("email"), emitter.get("website")] if x])
+    if contact:
+        em_lines.append(contact)
+    for ln in em_lines[:5]:
+        c.text(ex, ey, _fit(ln, 8.5, _MR - ex), 8.5, GRAY)
+        ey -= 11
+
+    # Título + regla
+    c.text(_ML, _H - 150, "COTIZACIÓN", 26, INK, bold=True)
+    c.line(_ML, _H - 158, _ML + 190, _H - 158, ACC, 2)
+
+    # Panel de datos (derecha)
+    px, pw = 320, _MR - 320
+    py_top = _H - 128
+    ph = 74
+    c.rect(px, py_top - ph, pw, ph, ZEBRA)
+    c.line(px, py_top, px, py_top - ph, LINE)
+    hy = py_top - 15
+    info = [
+        ("No.", head.get("reference") or "-"),
+        ("Fecha", head.get("issue_date") or "-"),
+        ("Vigencia", head.get("valid_until") or "-"),
+        ("Ejecutivo", head.get("owner") or "-"),
+        ("Estatus", str(head.get("status") or "-").capitalize()),
+    ]
+    for k, v in info:
+        c.text(px + 10, hy, f"{k}:", 8.5, GRAY, bold=True)
+        c.text(px + 66, hy, _fit(str(v), 9, pw - 76), 9, INK)
+        hy -= 12.5
+
+    c.y = _H - 215
+
+    # ---------------- Helpers de sección ----------------
+    def section(title: str):
+        c.ensure(30)
+        c.rect(_ML, c.y - 18, _MR - _ML, 18, ACC)
+        c.text(_ML + 8, c.y - 13, title.upper(), 9.5, (1, 1, 1), bold=True)
+        c.y -= 26
+
+    def kv_block(pairs: list[tuple[str, str]]):
+        rows = [(k, v) for k, v in pairs if v not in (None, "", "None")]
+        if not rows:
+            return False
+        col_w = (_MR - _ML) / 2
+        i = 0
+        while i < len(rows):
+            c.ensure(16)
+            for col in range(2):
+                if i + col < len(rows):
+                    k, v = rows[i + col]
+                    x = _ML + 6 + col * col_w
+                    c.text(x, c.y - 11, f"{k}:", 9, GRAY, bold=True)
+                    c.text(x + _text_w(f"{k}: ", 9, True), c.y - 11, _fit(str(v), 9, col_w - 90), 9, INK)
+            c.y -= 16
+            i += 2
+        c.y -= 4
+        return True
+
+    # ---------------- Cliente ----------------
+    section("Cliente")
+    if not kv_block([
+        ("Cliente", client.get("name")), ("RFC", client.get("rfc")),
+        ("Correo", client.get("email")), ("Teléfono", client.get("phone")),
+    ]):
+        c.text(_ML + 6, c.y - 11, "—", 9, GRAY)
+        c.y -= 16
+
+    # ---------------- Carga / Ruta (solo si hay datos) ----------------
+    if [v for _, v in cargo if v not in (None, "", "None")]:
+        section("Información de la carga")
+        kv_block(cargo)
+    if [v for _, v in route if v not in (None, "", "None")]:
+        section("Ruta logística")
+        kv_block(route)
+
+    # ---------------- Costos ----------------
+    section("Costos cotizados")
+    x_con, x_cant, x_tar, x_imp = _ML, 372, 460, _MR - 6
+    row_h = 18
+    # encabezado de tabla
+    c.ensure(row_h)
+    c.rect(_ML, c.y - row_h, _MR - _ML, row_h, ACC)
+    c.text(x_con + 6, c.y - 13, "Concepto", 9, (1, 1, 1), bold=True)
+    c.text(x_cant, c.y - 13, "Cant.", 9, (1, 1, 1), bold=True, right=True)
+    c.text(x_tar, c.y - 13, "Tarifa", 9, (1, 1, 1), bold=True, right=True)
+    c.text(x_imp, c.y - 13, "Importe", 9, (1, 1, 1), bold=True, right=True)
+    c.y -= row_h
+    z = False
+    for it in items:
+        code = str(it.get("concept") or "")
+        label = CONCEPT_LABELS.get(code, code)
+        desc = str(it.get("description") or "")
+        if desc:
+            label = f"{label} - {desc}"
+        qty = Decimal(str(it.get("quantity") or 0))
+        unit = Decimal(str(it.get("unit_sale") or 0))
+        amount = (qty * unit).quantize(Decimal("0.01"))
+        c.ensure(row_h)
+        if z:
+            c.rect(_ML, c.y - row_h, _MR - _ML, row_h, ZEBRA)
+        c.text(x_con + 6, c.y - 13, _fit(label, 9, x_cant - x_con - 40), 9, INK)
+        c.text(x_cant, c.y - 13, _num(qty), 9, INK, right=True)
+        c.text(x_tar, c.y - 13, _money(unit), 9, INK, right=True)
+        c.text(x_imp, c.y - 13, _money(amount), 9, INK, right=True)
+        c.y -= row_h
+        z = not z
+    if not items:
+        c.text(_ML + 6, c.y - 13, "Sin conceptos.", 9, GRAY)
+        c.y -= row_h
+    # borde de la tabla
+    c.line(_ML, c.y, _MR, c.y, LINE)
+    c.y -= 12
+
+    # ---------------- Totales (caja derecha) ----------------
+    tb_x, tb_w = 360, _MR - 360
+    c.ensure(58)
+    c.rect(tb_x, c.y - 58, tb_w, 58, ZEBRA)
+    c.line(tb_x, c.y, tb_x, c.y - 58, LINE)
+    ty = c.y - 16
+    c.text(tb_x + 10, ty, "Subtotal", 9.5, GRAY, bold=True)
+    c.text(_MR - 8, ty, f"{currency} {_money(subtotal)}", 9.5, INK, right=True)
+    ty -= 15
+    c.text(tb_x + 10, ty, "IVA", 9.5, GRAY, bold=True)
+    c.text(_MR - 8, ty, "según aplique", 9, GRAY, right=True)
+    ty -= 6
+    c.rect(tb_x, ty - 20, tb_w, 20, ACC)
+    c.text(tb_x + 10, ty - 14, "TOTAL", 10, (1, 1, 1), bold=True)
+    c.text(_MR - 8, ty - 14, f"{currency} {_money(subtotal)} + IVA", 10, (1, 1, 1), bold=True, right=True)
+    c.y -= 70
+
+    # ---------------- Condiciones ----------------
+    if terms:
+        section("Condiciones comerciales")
+        for para in terms.splitlines():
+            for ln in (_wrap(para, 108) or [""]):
+                c.ensure(13)
+                c.text(_ML + 6, c.y - 10, ln, 8.8, GRAY)
+                c.y -= 12
+        c.y -= 4
+
+    # pie en todas las páginas
+    for ops in c.pages:
+        if footer:
+            r, g, b = GRAY
+            ops.append(f"BT /F1 8 Tf {r:.3f} {g:.3f} {b:.3f} rg 1 0 0 1 {_ML} 34 Tm ({_esc(_fit(footer, 8, _MR - _ML))}) Tj ET")
+        ops.append(f"{ACC[0]:.3f} {ACC[1]:.3f} {ACC[2]:.3f} rg 0 0 {_W} 6 re f")
+
+    # ---------------- Ensamblado ----------------
+    streams = ["\n".join(ops).encode("latin-1", "replace") for ops in c.pages]
+    objects: list[bytes] = []
+
+    def add(obj: bytes):
+        objects.append(obj)
+
+    n_pages = len(c.pages)
+    has_img = 1 if logo else 0
+    # numeración: 1 catalog, 2 pages, 3 F1, 4 F2, [5 img], luego páginas y streams
+    img_num = 5 if has_img else None
+    base = 6 if has_img else 5
+    page_nums = list(range(base, base + n_pages))
+    content_nums = list(range(base + n_pages, base + 2 * n_pages))
+
+    kids = " ".join(f"{n} 0 R" for n in page_nums)
+    add(b"<< /Type /Catalog /Pages 2 0 R >>")
+    add(f"<< /Type /Pages /Kids [{kids}] /Count {n_pages} >>".encode("latin-1"))
+    add(b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>")
+    add(b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding >>")
+    if logo:
+        jpeg, lw, lh = logo
+        add(
+            (
+                f"<< /Type /XObject /Subtype /Image /Width {lw} /Height {lh} "
+                f"/ColorSpace /DeviceRGB /BitsPerComponent 8 /Filter /DCTDecode /Length {len(jpeg)} >>\n"
+            ).encode("latin-1") + b"stream\n" + jpeg + b"\nendstream"
+        )
+    for i in range(n_pages):
+        res = "/Font << /F1 3 0 R /F2 4 0 R >>"
+        if has_img and i == 0:
+            res += f" /XObject << /Im0 {img_num} 0 R >>"
+        add(
+            (
+                f"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 {_W} {_H}] "
+                f"/Resources << {res} >> /Contents {content_nums[i]} 0 R >>"
+            ).encode("latin-1")
+        )
+    for stream in streams:
+        add(b"<< /Length " + str(len(stream)).encode() + b" >>\nstream\n" + stream + b"\nendstream")
+
+    out = bytearray(b"%PDF-1.4\n%\xe2\xe3\xcf\xd3\n")
+    offsets = []
+    for i, obj in enumerate(objects, start=1):
+        offsets.append(len(out))
+        out += f"{i} 0 obj\n".encode("latin-1") + obj + b"\nendobj\n"
+    xref_pos = len(out)
+    total = len(objects) + 1
+    out += f"xref\n0 {total}\n".encode("latin-1") + b"0000000000 65535 f \n"
+    for off in offsets:
+        out += f"{off:010d} 00000 n \n".encode("latin-1")
+    out += f"trailer\n<< /Size {total} /Root 1 0 R >>\nstartxref\n{xref_pos}\n%%EOF".encode("latin-1")
+    return bytes(out)

backend/api/v1/modules/crm/quotes/pdf_service.py

@@ -0,0 +1,241 @@
+"""PDF de cotización, configuración de marca por tenant y envío por correo."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+
+from fastapi import HTTPException, status
+from sqlalchemy import text
+from sqlalchemy.orm import Session
+
+from ..accounts.models import Account
+from ..service_requests.models import ServiceRequest
+from .models import Quote, QuoteItem, QuoteSettings
+from .pdf import build_quote_pdf
+from .service import get_quote
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TERMS = (
+    "Tarifas sujetas a disponibilidad de espacio.\n"
+    "Cualquier variación en peso o volumen generará ajuste tarifario.\n"
+    "No incluye cargos extraordinarios, maniobras especiales o servicios no especificados.\n"
+    "Tarifas sujetas a revisión por parte de la línea transportista y autoridades correspondientes."
+)
+
+
+# ---------------- Configuración de marca ----------------
+def get_settings(db: Session, tenant_id: int, company_id: int) -> QuoteSettings | None:
+    return (
+        db.query(QuoteSettings)
+        .filter(QuoteSettings.tenant_id == tenant_id, QuoteSettings.company_id == company_id,
+                QuoteSettings.deleted_at.is_(None))
+        .first()
+    )
+
+
+def upsert_settings(db: Session, tenant_id: int, company_id: int, data: dict) -> QuoteSettings:
+    obj = get_settings(db, tenant_id, company_id)
+    if obj is None:
+        obj = QuoteSettings(tenant_id=tenant_id, company_id=company_id)
+        db.add(obj)
+    for field, value in data.items():
+        if value is not None:
+            setattr(obj, field, value)
+    db.commit()
+    db.refresh(obj)
+    return obj
+
+
+def set_logo_key(db: Session, tenant_id: int, company_id: int, file_key: str) -> QuoteSettings:
+    obj = get_settings(db, tenant_id, company_id)
+    if obj is None:
+        obj = QuoteSettings(tenant_id=tenant_id, company_id=company_id)
+        db.add(obj)
+    obj.logo_file_key = file_key
+    db.commit()
+    db.refresh(obj)
+    return obj
+
+
+def _company_row(db: Session, company_id: int) -> dict:
+    try:
+        row = db.execute(
+            text("SELECT name, rfc, logo FROM a76.company WHERE id = :c"), {"c": company_id}
+        ).first()
+        if row:
+            return {"name": row[0], "rfc": row[1], "logo": row[2]}
+    except Exception:
+        pass
+    return {}
+
+
+# ---------------- Construcción del PDF ----------------
+def build_pdf_bytes(db: Session, quote: Quote, tenant_id: int, company_id: int) -> bytes:
+    items = (
+        db.query(QuoteItem)
+        .filter(QuoteItem.quote_id == quote.id, QuoteItem.deleted_at.is_(None))
+        .order_by(QuoteItem.id.asc())
+        .all()
+    )
+    account = (
+        db.query(Account).filter(Account.id == quote.account_id).first() if quote.account_id else None
+    )
+    sr = (
+        db.query(ServiceRequest).filter(ServiceRequest.id == quote.service_request_id).first()
+        if quote.service_request_id else None
+    )
+    settings = get_settings(db, tenant_id, company_id)
+    company = _company_row(db, company_id)
+
+    # Emisor: config del tenant con respaldo en a76.company
+    emitter = {
+        "name": (settings.emitter_name if settings else None) or company.get("name") or "Emisor",
+        "rfc": (settings.emitter_rfc if settings else None) or company.get("rfc"),
+        "address": settings.emitter_address if settings else None,
+        "phone": settings.emitter_phone if settings else None,
+        "email": settings.emitter_email if settings else None,
+        "website": settings.emitter_website if settings else None,
+    }
+    accent = (settings.accent_color if settings else None) or "#12294c"
+    prefix = (settings.quote_prefix if settings else None) or "COT"
+    terms = quote.terms or (settings.default_terms if settings else None) or DEFAULT_TERMS
+    footer = settings.footer_note if settings else None
+
+    # Logo (MinIO)
+    logo_bytes = None
+    logo_key = settings.logo_file_key if settings else None
+    if logo_key:
+        try:
+            from core.storage_s3 import get_object_bytes
+            logo_bytes = get_object_bytes(logo_key)
+        except Exception as exc:
+            logger.warning("No se pudo leer el logo del tarifario: %s", exc)
+
+    reference = quote.reference or f"{prefix}-{datetime.now().strftime('%Y%m%d')}-{quote.id:03d}"
+    head = {
+        "reference": reference,
+        "issue_date": quote.issue_date.isoformat() if quote.issue_date else None,
+        "valid_until": quote.valid_until.isoformat() if quote.valid_until else None,
+        "owner": quote.owner_user_id or "-",
+        "status": quote.status,
+    }
+    client = {
+        "name": account.name if account else None,
+        "rfc": account.rfc if account else None,
+        "email": account.email if account else None,
+        "phone": account.phone if account else None,
+    }
+    cargo = []
+    route = []
+    if sr:
+        cargo = [
+            ("Tipo de mercancía", sr.cargo_type), ("Descripción", sr.commodity),
+            ("Peso", str(sr.weight) if sr.weight is not None else None),
+            ("Volumen", str(sr.volume) if sr.volume is not None else None),
+            ("Tipo de carga", sr.load_type), ("Equipo", sr.container_equipment),
+        ]
+        route = [
+            ("Operación", sr.operation_type), ("Modo", sr.transport_mode),
+            ("Servicio", sr.service_type), ("Incoterm", sr.incoterm),
+            ("Origen", sr.origin), ("Destino", sr.destination),
+            ("Fecha requerida", sr.required_date.isoformat() if sr.required_date else None),
+        ]
+
+    return build_quote_pdf(
+        emitter=emitter, head=head, client=client, cargo=cargo, route=route,
+        items=[{"concept": i.concept, "description": i.description, "quantity": i.quantity, "unit_sale": i.unit_sale} for i in items],
+        currency=quote.currency, subtotal=quote.total_sale, terms=terms, footer=footer,
+        logo_bytes=logo_bytes, accent=accent,
+    )
+
+
+def _store_pdf(db: Session, quote: Quote, tenant_id: int, company_id: int, pdf_bytes: bytes) -> str:
+    from core.storage_s3 import put_object_bytes
+    ref = (quote.reference or f"cot-{quote.id}").replace("/", "-")
+    key = f"tenants/{tenant_id}/companies/{company_id}/crm-quotes/{quote.id}/cotizacion-{ref}.pdf"
+    put_object_bytes(key, pdf_bytes, content_type="application/pdf")
+    quote.pdf_file_key = key
+    db.commit()
+    return key
+
+
+def get_pdf_url(db: Session, quote_id: int, tenant_id: int, company_id: int) -> str:
+    from core.storage_s3 import presigned_get_url
+    quote = get_quote(db, quote_id, tenant_id, company_id)
+    pdf_bytes = build_pdf_bytes(db, quote, tenant_id, company_id)
+    key = _store_pdf(db, quote, tenant_id, company_id, pdf_bytes)
+    return presigned_get_url(key)
+
+
+# ---------------- Envío por correo ----------------
+async def send_quote_email(
+    db: Session, quote_id: int, tenant_id: int, company_id: int,
+    to: str | None, subject: str | None, message: str | None,
+) -> dict:
+    import ssl
+    from email import encoders
+    from email.mime.base import MIMEBase
+    from email.mime.multipart import MIMEMultipart
+    from email.mime.text import MIMEText
+
+    import aiosmtplib
+
+    from core.config import settings as cfg
+
+    quote = get_quote(db, quote_id, tenant_id, company_id)
+    account = db.query(Account).filter(Account.id == quote.account_id).first() if quote.account_id else None
+    recipient = to or (account.email if account else None)
+    if not recipient:
+        raise HTTPException(status_code=400, detail="No hay correo destino (captura uno o pon el correo del cliente).")
+
+    pdf_bytes = build_pdf_bytes(db, quote, tenant_id, company_id)
+    _store_pdf(db, quote, tenant_id, company_id, pdf_bytes)
+    ref = quote.reference or f"COT-{quote.id}"
+
+    msg = MIMEMultipart()
+    msg["From"] = f"{cfg.SMTP_FROM_NAME} <{cfg.SMTP_USER}>"
+    msg["To"] = recipient
+    msg["Subject"] = subject or f"Cotización {ref}"
+    html = (
+        "<div style='font-family:Arial,sans-serif;color:#333;max-width:600px'>"
+        f"<p>{(message or 'Adjunto la cotización solicitada. Quedamos atentos.').replace(chr(10), '<br>')}</p>"
+        f"<p style='color:#6b7280;font-size:12px'>Cotización {ref}</p></div>"
+    )
+    msg.attach(MIMEText(html, "html"))
+    part = MIMEBase("application", "pdf")
+    part.set_payload(pdf_bytes)
+    encoders.encode_base64(part)
+    part.add_header("Content-Disposition", f'attachment; filename="cotizacion-{ref}.pdf"')
+    msg.attach(part)
+
+    if not (cfg.SMTP_USER and cfg.SMTP_PASSWORD):
+        raise HTTPException(status_code=503, detail="El correo saliente (SMTP) no está configurado en el servidor.")
+    ctx = ssl.create_default_context()
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_NONE
+    try:
+        # Puerto 465 = SSL implícito; los demás (587/2525/…) = STARTTLS.
+        await aiosmtplib.send(
+            msg,
+            hostname=cfg.SMTP_HOST,
+            port=cfg.SMTP_PORT,
+            username=cfg.SMTP_USER,
+            password=cfg.SMTP_PASSWORD,
+            use_tls=(cfg.SMTP_PORT == 465),
+            start_tls=(cfg.SMTP_PORT != 465),
+            tls_context=ctx,
+            validate_certs=False,
+            timeout=30,
+        )
+    except Exception as exc:
+        logger.error("Error enviando cotización %s: %s", quote_id, exc)
+        raise HTTPException(status_code=502, detail=f"No se pudo enviar el correo: {exc}")
+
+    # Marca como enviada
+    if quote.status == "borrador":
+        quote.status = "enviada"
+    quote.sent_at = datetime.now(timezone.utc)
+    db.commit()
+    return {"sent_to": recipient, "reference": ref}

backend/api/v1/modules/crm/quotes/routes.py

@@ -1,22 +1,76 @@
-from fastapi import APIRouter, Depends, Query, status
+from fastapi import APIRouter, Depends, File, Query, Response, UploadFile, status
 from sqlalchemy.orm import Session
 
 from core.database import get_core_db
 from core.security import get_current_user
 
-from . import service
+from . import pdf_service, service
 from .dto import (
     QuoteCreate,
     QuoteItemCreate,
     QuoteItemResponse,
     QuoteItemUpdate,
     QuoteResponse,
+    QuoteSettingsInput,
+    QuoteSettingsResponse,
     QuoteUpdate,
+    SendQuoteEmailRequest,
 )
 
 router = APIRouter()
 
 
+# ----- Configuración de marca del formato de cotización -----
+
+@router.get("/quote-settings", response_model=QuoteSettingsResponse)
+def get_quote_settings(
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    obj = pdf_service.get_settings(db, current_user["tenant_id"], company_id)
+    return obj or QuoteSettingsResponse()
+
+
+@router.put("/quote-settings", response_model=QuoteSettingsResponse)
+def save_quote_settings(
+    payload: QuoteSettingsInput,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    return pdf_service.upsert_settings(db, current_user["tenant_id"], company_id, payload.model_dump(exclude_unset=True))
+
+
+@router.post("/quote-settings/logo", response_model=QuoteSettingsResponse)
+async def upload_quote_logo(
+    company_id: int = Query(...),
+    file: UploadFile = File(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    from core.storage_s3 import put_object_bytes
+    tenant_id = current_user["tenant_id"]
+    content = await file.read()
+    safe = (file.filename or "logo").replace("/", "-")
+    key = f"tenants/{tenant_id}/companies/{company_id}/crm-quote-logo/{safe}"
+    put_object_bytes(key, content, content_type=file.content_type or "image/png")
+    return pdf_service.set_logo_key(db, tenant_id, company_id, key)
+
+
+@router.get("/quote-settings/logo-url")
+def get_logo_url(
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    from core.storage_s3 import presigned_get_url
+    obj = pdf_service.get_settings(db, current_user["tenant_id"], company_id)
+    if not obj or not obj.logo_file_key:
+        return {"url": None}
+    return {"url": presigned_get_url(obj.logo_file_key)}
+
+
 def _user_id(current_user: dict) -> str | None:
     return current_user.get("sub") or current_user.get("id")
 
@@ -98,6 +152,39 @@ def reject_quote(
     return service.reject_quote(db, quote_id, current_user["tenant_id"], company_id)
 
 
+@router.get("/quotes/{quote_id}/pdf")
+def quote_pdf(
+    quote_id: int,
+    company_id: int = Query(..., description="Company ID"),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    """Devuelve el PDF de la cotización directamente (vía backend, sin exponer MinIO)."""
+    tenant_id = current_user["tenant_id"]
+    quote = service.get_quote(db, quote_id, tenant_id, company_id)
+    pdf_bytes = pdf_service.build_pdf_bytes(db, quote, tenant_id, company_id)
+    ref = (quote.reference or f"cot-{quote.id}").replace("/", "-")
+    return Response(
+        content=pdf_bytes,
+        media_type="application/pdf",
+        headers={"Content-Disposition": f'inline; filename="cotizacion-{ref}.pdf"'},
+    )
+
+
+@router.post("/quotes/{quote_id}/send-email")
+async def quote_send_email(
+    quote_id: int,
+    payload: SendQuoteEmailRequest,
+    company_id: int = Query(..., description="Company ID"),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    """Genera el PDF y lo envía por correo (al cliente o al destinatario indicado)."""
+    return await pdf_service.send_quote_email(
+        db, quote_id, current_user["tenant_id"], company_id, payload.to, payload.subject, payload.message
+    )
+
+
 @router.post("/quotes/{quote_id}/clone", response_model=QuoteResponse, status_code=status.HTTP_201_CREATED)
 def clone_quote(
     quote_id: int,

backend/api/v1/modules/crm/rates/dto.py

@@ -0,0 +1,174 @@
+"""Schemas del módulo Tarifario."""
+
+from datetime import date, datetime
+from decimal import Decimal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# ---------- Quiebres y cargos ----------
+class RateBreakDTO(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    from_qty: Decimal = Field(0)
+    rate: Decimal = Field(0)
+
+
+class RateChargeDTO(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    concept: str = Field(..., max_length=60)
+    charge_type: str = Field("fijo", max_length=20)
+    value: Decimal | None = None
+    condition: str | None = None
+
+
+class RateChargeCreate(BaseModel):
+    concept: str = Field(..., max_length=60)
+    charge_type: str = Field("fijo", max_length=20)
+    value: Decimal | None = None
+    condition: str | None = None
+    rate_lane_id: int | None = None
+
+
+class RateChargeUpdate(BaseModel):
+    concept: str | None = Field(None, max_length=60)
+    charge_type: str | None = Field(None, max_length=20)
+    value: Decimal | None = None
+    condition: str | None = None
+
+
+class RateChargeResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    rate_sheet_id: int | None
+    rate_lane_id: int | None
+    concept: str
+    charge_type: str
+    value: Decimal | None
+    condition: str | None
+
+
+# ---------- Rutas ----------
+class RateLaneBase(BaseModel):
+    origin: str | None = Field(None, max_length=20)
+    destination: str | None = Field(None, max_length=20)
+    region: str | None = Field(None, max_length=60)
+    equipment_type: str | None = Field(None, max_length=20)
+    rate_unit: str | None = Field(None, max_length=20)
+    min_charge: Decimal | None = None
+    flat_rate: Decimal | None = None
+    transit_days: int | None = None
+    notes: str | None = None
+
+
+class RateLaneCreate(RateLaneBase):
+    breaks: list[RateBreakDTO] = Field(default_factory=list)
+
+
+class RateLaneUpdate(RateLaneBase):
+    breaks: list[RateBreakDTO] | None = None
+
+
+class RateLaneResponse(RateLaneBase):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    rate_sheet_id: int
+    breaks: list[RateBreakDTO] = Field(default_factory=list)
+
+
+# ---------- Tarifario (cabecera) ----------
+class RateSheetBase(BaseModel):
+    supplier_id: int | None = None
+    mode: str = Field(..., max_length=20)
+    name: str = Field(..., min_length=1, max_length=255)
+    currency: str | None = Field("USD", max_length=3)
+    valid_from: date | None = None
+    valid_to: date | None = None
+    default_origin: str | None = Field(None, max_length=20)
+    status: str = Field("borrador", max_length=20)
+    notes: str | None = None
+
+
+class RateSheetCreate(RateSheetBase):
+    pass
+
+
+class RateSheetUpdate(BaseModel):
+    supplier_id: int | None = None
+    mode: str | None = Field(None, max_length=20)
+    name: str | None = Field(None, max_length=255)
+    currency: str | None = Field(None, max_length=3)
+    valid_from: date | None = None
+    valid_to: date | None = None
+    default_origin: str | None = Field(None, max_length=20)
+    status: str | None = Field(None, max_length=20)
+    notes: str | None = None
+
+
+class RateSheetResponse(RateSheetBase):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+    tenant_id: int
+    company_id: int
+    source_file: str | None = None
+    created_by: str | None = None
+    updated_by: str | None = None
+    created_at: datetime
+    updated_at: datetime
+    lane_count: int | None = None
+
+
+# ---------- Importación ----------
+class ImportPreviewRow(BaseModel):
+    row: int
+    data: dict
+    ok: bool
+    warnings: list[str] = Field(default_factory=list)
+    errors: list[str] = Field(default_factory=list)
+
+
+class ImportPreview(BaseModel):
+    mode: str
+    total: int
+    valid: int
+    rows: list[ImportPreviewRow]
+    columns: list[str]
+
+
+class ImportConfirm(RateSheetCreate):
+    lanes: list[RateLaneCreate]
+
+
+# ---------- Costeo ----------
+class CostRequest(BaseModel):
+    mode: str
+    origin: str | None = None
+    destination: str | None = None
+    on_date: date | None = None
+    gross_weight_kg: Decimal | None = None
+    volume_m3: Decimal | None = None
+    equipment_type: str | None = None
+    quantity: int = 1
+    dangerous: bool = False
+
+
+class CostChargeLine(BaseModel):
+    concept: str
+    amount: Decimal
+
+
+class CostOption(BaseModel):
+    rate_sheet_id: int
+    rate_sheet_name: str
+    supplier_id: int | None
+    currency: str | None
+    chargeable: Decimal | None = None  # peso/wm facturable usado
+    base_cost: Decimal
+    charges: list[CostChargeLine] = Field(default_factory=list)
+    total_cost: Decimal
+    transit_days: int | None = None
+    detail: str | None = None
+
+
+class CostResult(BaseModel):
+    request: CostRequest
+    options: list[CostOption]

backend/api/v1/modules/crm/rates/models.py

@@ -0,0 +1,93 @@
+"""Modelos del módulo Tarifario (base de costos para Cotizaciones).
+
+Un ``RateSheet`` (tarifario) pertenece a un proveedor y agrupa muchas
+``RateLane`` (rutas origen→destino). Cada ruta tiene, según el modo:
+- Aéreo / LCL: varios ``RateBreak`` (quiebres de peso/volumen con su tarifa).
+- FCL / terrestre: una tarifa plana por contenedor/unidad (``flat_rate``).
+Los ``RateCharge`` son cargos adicionales a nivel tarifario o ruta.
+"""
+
+from datetime import date
+from decimal import Decimal
+
+from sqlalchemy import Date, ForeignKey, Integer, Numeric, String, Text, text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from api.v1.common.base_models import TenantScopedMixin, TimestampMixin
+from core.database import Base
+
+
+class RateSheet(Base, TenantScopedMixin, TimestampMixin):
+    __tablename__ = "rate_sheets"
+    __table_args__ = {"schema": "crm"}
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    supplier_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("crm.suppliers.id"), nullable=True, index=True
+    )
+    # aereo | maritimo_fcl | maritimo_lcl | terrestre
+    mode: Mapped[str] = mapped_column(String(20), nullable=False, index=True)
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    currency: Mapped[str | None] = mapped_column(String(3), nullable=True, server_default=text("'USD'"))
+    valid_from: Mapped[date | None] = mapped_column(Date, nullable=True)
+    valid_to: Mapped[date | None] = mapped_column(Date, nullable=True)
+    default_origin: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    # borrador | activo | vencido | reemplazado
+    status: Mapped[str] = mapped_column(String(20), nullable=False, server_default=text("'borrador'"))
+    source_file: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    source_url: Mapped[str | None] = mapped_column(String(1024), nullable=True)
+    notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
+
+
+class RateLane(Base, TenantScopedMixin, TimestampMixin):
+    __tablename__ = "rate_lanes"
+    __table_args__ = {"schema": "crm"}
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    rate_sheet_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("crm.rate_sheets.id"), nullable=False, index=True
+    )
+    origin: Mapped[str | None] = mapped_column(String(20), nullable=True, index=True)
+    destination: Mapped[str | None] = mapped_column(String(20), nullable=True, index=True)
+    region: Mapped[str | None] = mapped_column(String(60), nullable=True)
+    # Solo FCL/terrestre (código del catálogo tipo_equipo). Nulo en aéreo/LCL.
+    equipment_type: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    # per_kg | per_wm | per_container | flat
+    rate_unit: Mapped[str | None] = mapped_column(String(20), nullable=True)
+    min_charge: Mapped[Decimal | None] = mapped_column(Numeric(14, 4), nullable=True)
+    flat_rate: Mapped[Decimal | None] = mapped_column(Numeric(14, 4), nullable=True)
+    transit_days: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+
+class RateBreak(Base, TenantScopedMixin, TimestampMixin):
+    __tablename__ = "rate_breaks"
+    __table_args__ = {"schema": "crm"}
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    rate_lane_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("crm.rate_lanes.id"), nullable=False, index=True
+    )
+    # Umbral del quiebre (kg en aéreo; W/M en LCL)
+    from_qty: Mapped[Decimal] = mapped_column(Numeric(12, 3), nullable=False, server_default=text("0"))
+    rate: Mapped[Decimal] = mapped_column(Numeric(14, 4), nullable=False, server_default=text("0"))
+
+
+class RateCharge(Base, TenantScopedMixin, TimestampMixin):
+    __tablename__ = "rate_charges"
+    __table_args__ = {"schema": "crm"}
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    rate_sheet_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("crm.rate_sheets.id"), nullable=True, index=True
+    )
+    rate_lane_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("crm.rate_lanes.id"), nullable=True, index=True
+    )
+    concept: Mapped[str] = mapped_column(String(60), nullable=False)
+    # fijo | por_kg | por_guia | por_contenedor | porcentaje
+    charge_type: Mapped[str] = mapped_column(String(20), nullable=False, server_default=text("'fijo'"))
+    value: Mapped[Decimal | None] = mapped_column(Numeric(14, 4), nullable=True)
+    condition: Mapped[str | None] = mapped_column(Text, nullable=True)

backend/api/v1/modules/crm/rates/routes.py

@@ -0,0 +1,257 @@
+"""Endpoints del módulo Tarifario."""
+
+from datetime import date
+
+from fastapi import APIRouter, Depends, File, Form, Query, Response, UploadFile, status
+from sqlalchemy.orm import Session
+
+from core.database import get_core_db
+from core.security import get_current_user
+
+from . import service
+from .dto import (
+    CostRequest,
+    CostResult,
+    ImportPreview,
+    RateBreakDTO,
+    RateChargeCreate,
+    RateChargeResponse,
+    RateChargeUpdate,
+    RateLaneCreate,
+    RateLaneResponse,
+    RateSheetCreate,
+    RateSheetResponse,
+    RateSheetUpdate,
+)
+
+router = APIRouter(prefix="/rate-sheets", tags=["Tarifario"])
+
+
+def _ctx(current_user: dict):
+    return current_user["tenant_id"], current_user.get("sub") or current_user.get("id")
+
+
+def _sheet_out(db: Session, tenant_id: int, sheet) -> RateSheetResponse:
+    out = RateSheetResponse.model_validate(sheet)
+    out.lane_count = service.lane_count(db, tenant_id, sheet.id)
+    return out
+
+
+def _lane_out(db: Session, lane) -> RateLaneResponse:
+    out = RateLaneResponse.model_validate(lane)
+    out.breaks = [RateBreakDTO.model_validate(b) for b in service.breaks_of(db, lane.id)]
+    return out
+
+
+# ---------------- Tarifarios ----------------
+@router.get("", response_model=list[RateSheetResponse])
+def list_sheets(
+    company_id: int = Query(...),
+    mode: str | None = Query(None),
+    supplier_id: int | None = Query(None),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, _ = _ctx(current_user)
+    sheets = service.list_sheets(db, tenant_id, company_id, mode=mode, supplier_id=supplier_id)
+    return [_sheet_out(db, tenant_id, s) for s in sheets]
+
+
+@router.post("", response_model=RateSheetResponse, status_code=status.HTTP_201_CREATED)
+def create_sheet(
+    data: RateSheetCreate,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, user_id = _ctx(current_user)
+    sheet = service.create_sheet(db, tenant_id, company_id, data, user_id)
+    return _sheet_out(db, tenant_id, sheet)
+
+
+@router.get("/template")
+def download_template(
+    mode: str = Query(..., description="aereo | maritimo_fcl | maritimo_lcl | terrestre"),
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+):
+    content = service.build_template(mode)
+    return Response(
+        content=content,
+        media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        headers={"Content-Disposition": f'attachment; filename="plantilla_tarifario_{mode}.xlsx"'},
+    )
+
+
+@router.post("/import/preview", response_model=ImportPreview)
+async def import_preview(
+    company_id: int = Query(...),
+    mode: str = Form(...),
+    file: UploadFile = File(...),
+    current_user: dict = Depends(get_current_user),
+):
+    content = await file.read()
+    return service.parse_excel(mode, content)
+
+
+@router.post("/import", response_model=RateSheetResponse, status_code=status.HTTP_201_CREATED)
+async def import_sheet(
+    company_id: int = Query(...),
+    mode: str = Form(...),
+    name: str = Form(...),
+    supplier_id: int | None = Form(None),
+    currency: str = Form("USD"),
+    valid_from: date | None = Form(None),
+    valid_to: date | None = Form(None),
+    default_origin: str | None = Form(None),
+    file: UploadFile = File(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, user_id = _ctx(current_user)
+    content = await file.read()
+    header = RateSheetCreate(
+        mode=mode, name=name, supplier_id=supplier_id, currency=currency,
+        valid_from=valid_from, valid_to=valid_to, default_origin=default_origin,
+    )
+    sheet = service.import_from_excel(db, tenant_id, company_id, mode, content, header, user_id)
+    return _sheet_out(db, tenant_id, sheet)
+
+
+@router.get("/{sheet_id}", response_model=RateSheetResponse)
+def get_sheet(
+    sheet_id: int,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, _ = _ctx(current_user)
+    return _sheet_out(db, tenant_id, service.get_sheet(db, tenant_id, company_id, sheet_id))
+
+
+@router.patch("/{sheet_id}", response_model=RateSheetResponse)
+def update_sheet(
+    sheet_id: int,
+    data: RateSheetUpdate,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, user_id = _ctx(current_user)
+    return _sheet_out(db, tenant_id, service.update_sheet(db, tenant_id, company_id, sheet_id, data, user_id))
+
+
+@router.delete("/{sheet_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_sheet(
+    sheet_id: int,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, _ = _ctx(current_user)
+    service.delete_sheet(db, tenant_id, company_id, sheet_id)
+
+
+# ---------------- Rutas (lanes) ----------------
+@router.get("/{sheet_id}/lanes", response_model=list[RateLaneResponse])
+def list_lanes(
+    sheet_id: int,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, _ = _ctx(current_user)
+    service.get_sheet(db, tenant_id, company_id, sheet_id)
+    return [_lane_out(db, lane) for lane in service.list_lanes(db, tenant_id, sheet_id)]
+
+
+@router.post("/{sheet_id}/lanes", response_model=RateLaneResponse, status_code=status.HTTP_201_CREATED)
+def create_lane(
+    sheet_id: int,
+    data: RateLaneCreate,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, _ = _ctx(current_user)
+    lane = service.create_lane(db, tenant_id, company_id, sheet_id, data)
+    return _lane_out(db, lane)
+
+
+@router.delete("/{sheet_id}/lanes/{lane_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_lane(
+    sheet_id: int,
+    lane_id: int,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, _ = _ctx(current_user)
+    service.delete_lane(db, tenant_id, sheet_id, lane_id)
+
+
+# ---------------- Cargos adicionales ----------------
+@router.get("/{sheet_id}/charges", response_model=list[RateChargeResponse])
+def list_charges(
+    sheet_id: int,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, _ = _ctx(current_user)
+    service.get_sheet(db, tenant_id, company_id, sheet_id)
+    return service.list_charges(db, tenant_id, sheet_id)
+
+
+@router.post("/{sheet_id}/charges", response_model=RateChargeResponse, status_code=status.HTTP_201_CREATED)
+def create_charge(
+    sheet_id: int,
+    data: RateChargeCreate,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, _ = _ctx(current_user)
+    return service.create_charge(db, tenant_id, company_id, sheet_id, data)
+
+
+@router.patch("/{sheet_id}/charges/{charge_id}", response_model=RateChargeResponse)
+def update_charge(
+    sheet_id: int,
+    charge_id: int,
+    data: RateChargeUpdate,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, _ = _ctx(current_user)
+    return service.update_charge(db, tenant_id, sheet_id, charge_id, data)
+
+
+@router.delete("/{sheet_id}/charges/{charge_id}", status_code=status.HTTP_204_NO_CONTENT)
+def delete_charge(
+    sheet_id: int,
+    charge_id: int,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    tenant_id, _ = _ctx(current_user)
+    service.delete_charge(db, tenant_id, sheet_id, charge_id)
+
+
+# ---------------- Motor de costeo ----------------
+cost_router = APIRouter(tags=["Tarifario"])
+
+
+@cost_router.post("/rate-quote", response_model=CostResult)
+def rate_quote(
+    req: CostRequest,
+    company_id: int = Query(...),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    """Calcula opciones de costo (por proveedor) para una ruta/carga."""
+    tenant_id, _ = _ctx(current_user)
+    options = service.quote_cost(db, tenant_id, company_id, req)
+    return CostResult(request=req, options=options)

backend/api/v1/modules/crm/rates/service.py

@@ -0,0 +1,535 @@
+"""Lógica del módulo Tarifario: CRUD, importación por Excel y motor de costeo."""
+
+import io
+from datetime import date
+from decimal import Decimal
+from typing import Any
+
+from fastapi import HTTPException, status
+from sqlalchemy import and_, or_
+from sqlalchemy.orm import Session
+
+from .dto import (
+    CostChargeLine,
+    CostOption,
+    CostRequest,
+    ImportConfirm,
+    ImportPreview,
+    ImportPreviewRow,
+    RateLaneCreate,
+    RateSheetCreate,
+    RateSheetUpdate,
+)
+from .models import RateBreak, RateCharge, RateLane, RateSheet
+
+# Factor volumétrico aéreo: 1 m³ = 167 kg (equivale a 6000 cm³/kg).
+AIR_VOLUMETRIC_FACTOR = Decimal("167")
+
+
+# ============================================================ CRUD tarifarios
+def _sheet_query(db: Session, tenant_id: int, company_id: int):
+    return db.query(RateSheet).filter(
+        RateSheet.tenant_id == tenant_id,
+        RateSheet.company_id == company_id,
+        RateSheet.deleted_at.is_(None),
+    )
+
+
+def list_sheets(db: Session, tenant_id: int, company_id: int, mode: str | None = None,
+                supplier_id: int | None = None) -> list[RateSheet]:
+    q = _sheet_query(db, tenant_id, company_id)
+    if mode:
+        q = q.filter(RateSheet.mode == mode)
+    if supplier_id:
+        q = q.filter(RateSheet.supplier_id == supplier_id)
+    return q.order_by(RateSheet.created_at.desc()).all()
+
+
+def lane_count(db: Session, tenant_id: int, sheet_id: int) -> int:
+    return (
+        db.query(RateLane)
+        .filter(RateLane.rate_sheet_id == sheet_id, RateLane.tenant_id == tenant_id,
+                RateLane.deleted_at.is_(None))
+        .count()
+    )
+
+
+def get_sheet(db: Session, tenant_id: int, company_id: int, sheet_id: int) -> RateSheet:
+    sheet = _sheet_query(db, tenant_id, company_id).filter(RateSheet.id == sheet_id).first()
+    if not sheet:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Tarifario no encontrado")
+    return sheet
+
+
+def create_sheet(db: Session, tenant_id: int, company_id: int, data: RateSheetCreate,
+                 user_id: str | None) -> RateSheet:
+    sheet = RateSheet(
+        tenant_id=tenant_id, company_id=company_id,
+        **data.model_dump(),
+        created_by=user_id, updated_by=user_id,
+    )
+    db.add(sheet)
+    db.commit()
+    db.refresh(sheet)
+    return sheet
+
+
+def update_sheet(db: Session, tenant_id: int, company_id: int, sheet_id: int,
+                 data: RateSheetUpdate, user_id: str | None) -> RateSheet:
+    sheet = get_sheet(db, tenant_id, company_id, sheet_id)
+    for field, value in data.model_dump(exclude_unset=True).items():
+        setattr(sheet, field, value)
+    sheet.updated_by = user_id
+    db.commit()
+    db.refresh(sheet)
+    return sheet
+
+
+def delete_sheet(db: Session, tenant_id: int, company_id: int, sheet_id: int) -> None:
+    from sqlalchemy import func
+    sheet = get_sheet(db, tenant_id, company_id, sheet_id)
+    sheet.deleted_at = func.now()
+    db.commit()
+
+
+# ============================================================ Rutas (lanes)
+def list_lanes(db: Session, tenant_id: int, sheet_id: int) -> list[RateLane]:
+    return (
+        db.query(RateLane)
+        .filter(RateLane.rate_sheet_id == sheet_id, RateLane.tenant_id == tenant_id,
+                RateLane.deleted_at.is_(None))
+        .order_by(RateLane.region, RateLane.destination)
+        .all()
+    )
+
+
+def breaks_of(db: Session, lane_id: int) -> list[RateBreak]:
+    return (
+        db.query(RateBreak)
+        .filter(RateBreak.rate_lane_id == lane_id, RateBreak.deleted_at.is_(None))
+        .order_by(RateBreak.from_qty)
+        .all()
+    )
+
+
+def _add_lane(db: Session, tenant_id: int, company_id: int, sheet_id: int,
+              lane_data: RateLaneCreate) -> RateLane:
+    payload = lane_data.model_dump(exclude={"breaks"})
+    lane = RateLane(tenant_id=tenant_id, company_id=company_id, rate_sheet_id=sheet_id, **payload)
+    db.add(lane)
+    db.flush()  # id
+    for br in lane_data.breaks:
+        db.add(RateBreak(
+            tenant_id=tenant_id, company_id=company_id, rate_lane_id=lane.id,
+            from_qty=br.from_qty, rate=br.rate,
+        ))
+    return lane
+
+
+def create_lane(db: Session, tenant_id: int, company_id: int, sheet_id: int,
+                lane_data: RateLaneCreate) -> RateLane:
+    get_sheet(db, tenant_id, company_id, sheet_id)  # valida pertenencia
+    lane = _add_lane(db, tenant_id, company_id, sheet_id, lane_data)
+    db.commit()
+    db.refresh(lane)
+    return lane
+
+
+def delete_lane(db: Session, tenant_id: int, sheet_id: int, lane_id: int) -> None:
+    from sqlalchemy import func
+    lane = (
+        db.query(RateLane)
+        .filter(RateLane.id == lane_id, RateLane.rate_sheet_id == sheet_id,
+                RateLane.tenant_id == tenant_id)
+        .first()
+    )
+    if not lane:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Ruta no encontrada")
+    lane.deleted_at = func.now()
+    db.commit()
+
+
+# ============================================================ Cargos adicionales
+def list_charges(db: Session, tenant_id: int, sheet_id: int) -> list[RateCharge]:
+    return (
+        db.query(RateCharge)
+        .filter(RateCharge.rate_sheet_id == sheet_id, RateCharge.tenant_id == tenant_id,
+                RateCharge.deleted_at.is_(None))
+        .order_by(RateCharge.concept)
+        .all()
+    )
+
+
+def create_charge(db: Session, tenant_id: int, company_id: int, sheet_id: int, data) -> RateCharge:
+    get_sheet(db, tenant_id, company_id, sheet_id)
+    ch = RateCharge(
+        tenant_id=tenant_id, company_id=company_id, rate_sheet_id=sheet_id,
+        rate_lane_id=data.rate_lane_id, concept=data.concept, charge_type=data.charge_type,
+        value=data.value, condition=data.condition,
+    )
+    db.add(ch)
+    db.commit()
+    db.refresh(ch)
+    return ch
+
+
+def update_charge(db: Session, tenant_id: int, sheet_id: int, charge_id: int, data) -> RateCharge:
+    ch = (
+        db.query(RateCharge)
+        .filter(RateCharge.id == charge_id, RateCharge.rate_sheet_id == sheet_id,
+                RateCharge.tenant_id == tenant_id)
+        .first()
+    )
+    if not ch:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Cargo no encontrado")
+    for field, value in data.model_dump(exclude_unset=True).items():
+        setattr(ch, field, value)
+    db.commit()
+    db.refresh(ch)
+    return ch
+
+
+def delete_charge(db: Session, tenant_id: int, sheet_id: int, charge_id: int) -> None:
+    from sqlalchemy import func
+    ch = (
+        db.query(RateCharge)
+        .filter(RateCharge.id == charge_id, RateCharge.rate_sheet_id == sheet_id,
+                RateCharge.tenant_id == tenant_id)
+        .first()
+    )
+    if not ch:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Cargo no encontrado")
+    ch.deleted_at = func.now()
+    db.commit()
+
+
+# ============================================================ Importación Excel
+# Plantillas por modo: encabezados esperados (orden libre, se detectan por nombre).
+TEMPLATES: dict[str, list[str]] = {
+    "aereo": ["Region", "Origen", "Destino", "IATA", "Min", "100", "300", "500", "1000"],
+    "maritimo_fcl": ["Origen", "Destino", "Tipo contenedor", "Tarifa", "Transito", "Notas"],
+    "maritimo_lcl": ["Origen", "Destino", "Tarifa W/M", "Minimo", "Notas"],
+    "terrestre": ["Origen", "Destino", "Tarifa", "Transito", "Notas"],
+}
+
+
+def build_template(mode: str) -> bytes:
+    """Genera un .xlsx con los encabezados del modo + una fila de ejemplo."""
+    import openpyxl
+
+    if mode not in TEMPLATES:
+        raise HTTPException(status_code=400, detail=f"Modo '{mode}' no válido")
+    wb = openpyxl.Workbook()
+    ws = wb.active
+    ws.title = mode
+    headers = TEMPLATES[mode]
+    ws.append(headers)
+    examples = {
+        "aereo": ["EUROPA", "NLU", "Frankfurt", "FRA", 190, 1.00, 1.00, 0.95, 0.90],
+        "maritimo_fcl": ["MXZLO", "CNSHA", "40HC", 2500, 28, "THC no incluido"],
+        "maritimo_lcl": ["MXZLO", "USLAX", 45, 80, "1 W/M = 1 ton o 1 m3"],
+        "terrestre": ["Monterrey", "Laredo", 850, 1, ""],
+    }
+    ws.append(examples[mode])
+    buf = io.BytesIO()
+    wb.save(buf)
+    return buf.getvalue()
+
+
+def _num(v: Any) -> Decimal | None:
+    if v is None or v == "":
+        return None
+    try:
+        return Decimal(str(v).replace("$", "").replace(",", "").strip())
+    except Exception:
+        return None
+
+
+def parse_excel(mode: str, content: bytes) -> ImportPreview:
+    """Lee el Excel y devuelve una vista previa con validaciones (no persiste)."""
+    import openpyxl
+
+    if mode not in TEMPLATES:
+        raise HTTPException(status_code=400, detail=f"Modo '{mode}' no válido")
+    try:
+        wb = openpyxl.load_workbook(io.BytesIO(content), data_only=True, read_only=True)
+    except Exception:
+        raise HTTPException(status_code=400, detail="No se pudo leer el archivo Excel")
+    ws = wb.active
+    rows_iter = ws.iter_rows(values_only=True)
+    header = next(rows_iter, None)
+    if not header:
+        raise HTTPException(status_code=400, detail="El archivo está vacío")
+    cols = [str(c).strip() if c is not None else "" for c in header]
+    idx = {name.lower(): i for i, name in enumerate(cols)}
+
+    def cell(row, name):
+        i = idx.get(name.lower())
+        return row[i] if i is not None and i < len(row) else None
+
+    preview_rows: list[ImportPreviewRow] = []
+    valid = 0
+    for n, row in enumerate(rows_iter, start=2):
+        if row is None or all(c is None or str(c).strip() == "" for c in row):
+            continue
+        errors: list[str] = []
+        warnings: list[str] = []
+        data: dict = {}
+        if mode == "aereo":
+            data = {
+                "region": cell(row, "Region"),
+                "origin": cell(row, "Origen"),
+                "destination": cell(row, "Destino") or cell(row, "IATA"),
+                "iata": cell(row, "IATA"),
+                "min_charge": _num(cell(row, "Min")),
+                "breaks": {b: _num(cell(row, b)) for b in ("100", "300", "500", "1000")},
+            }
+            if not data["destination"]:
+                errors.append("Falta destino/IATA")
+            if not any(v is not None for v in data["breaks"].values()):
+                errors.append("Sin tarifas por quiebre")
+        elif mode == "maritimo_fcl":
+            data = {
+                "origin": cell(row, "Origen"),
+                "destination": cell(row, "Destino"),
+                "equipment_type": cell(row, "Tipo contenedor"),
+                "flat_rate": _num(cell(row, "Tarifa")),
+                "transit_days": _num(cell(row, "Transito")),
+                "notes": cell(row, "Notas"),
+            }
+            if data["flat_rate"] is None:
+                errors.append("Falta la tarifa")
+            if not data["equipment_type"]:
+                warnings.append("Sin tipo de contenedor")
+        elif mode == "maritimo_lcl":
+            data = {
+                "origin": cell(row, "Origen"),
+                "destination": cell(row, "Destino"),
+                "wm_rate": _num(cell(row, "Tarifa W/M")),
+                "min_charge": _num(cell(row, "Minimo")),
+                "notes": cell(row, "Notas"),
+            }
+            if data["wm_rate"] is None:
+                errors.append("Falta la tarifa W/M")
+        else:  # terrestre
+            data = {
+                "origin": cell(row, "Origen"),
+                "destination": cell(row, "Destino"),
+                "flat_rate": _num(cell(row, "Tarifa")),
+                "transit_days": _num(cell(row, "Transito")),
+                "notes": cell(row, "Notas"),
+            }
+            if data["flat_rate"] is None:
+                errors.append("Falta la tarifa")
+        if not data.get("destination"):
+            errors.append("Falta destino")
+        ok = not errors
+        if ok:
+            valid += 1
+        preview_rows.append(ImportPreviewRow(row=n, data=_jsonable(data), ok=ok,
+                                             warnings=warnings, errors=errors))
+    return ImportPreview(mode=mode, total=len(preview_rows), valid=valid,
+                         rows=preview_rows, columns=cols)
+
+
+def _jsonable(d: dict) -> dict:
+    out = {}
+    for k, v in d.items():
+        if isinstance(v, Decimal):
+            out[k] = float(v)
+        elif isinstance(v, dict):
+            out[k] = {kk: (float(vv) if isinstance(vv, Decimal) else vv) for kk, vv in v.items()}
+        else:
+            out[k] = v
+    return out
+
+
+def _rows_to_lanes(mode: str, rows: list[ImportPreviewRow], default_origin: str | None) -> list[RateLaneCreate]:
+    lanes: list[RateLaneCreate] = []
+    for r in rows:
+        if not r.ok:
+            continue
+        d = r.data
+        origin = d.get("origin") or default_origin
+        if mode == "aereo":
+            breaks = [
+                {"from_qty": Decimal(b), "rate": Decimal(str(v))}
+                for b, v in (d.get("breaks") or {}).items() if v is not None
+            ]
+            lanes.append(RateLaneCreate(
+                origin=str(origin) if origin else None,
+                destination=str(d.get("destination")),
+                region=d.get("region"), rate_unit="per_kg",
+                min_charge=_num(d.get("min_charge")),
+                breaks=breaks,  # type: ignore[arg-type]
+            ))
+        elif mode == "maritimo_fcl":
+            lanes.append(RateLaneCreate(
+                origin=str(origin) if origin else None, destination=str(d.get("destination")),
+                equipment_type=d.get("equipment_type"), rate_unit="per_container",
+                flat_rate=_num(d.get("flat_rate")),
+                transit_days=int(d["transit_days"]) if d.get("transit_days") else None,
+                notes=d.get("notes"),
+            ))
+        elif mode == "maritimo_lcl":
+            lanes.append(RateLaneCreate(
+                origin=str(origin) if origin else None, destination=str(d.get("destination")),
+                rate_unit="per_wm", min_charge=_num(d.get("min_charge")),
+                breaks=[{"from_qty": Decimal(0), "rate": Decimal(str(d["wm_rate"]))}],  # type: ignore[arg-type]
+                notes=d.get("notes"),
+            ))
+        else:
+            lanes.append(RateLaneCreate(
+                origin=str(origin) if origin else None, destination=str(d.get("destination")),
+                rate_unit="flat", flat_rate=_num(d.get("flat_rate")),
+                transit_days=int(d["transit_days"]) if d.get("transit_days") else None,
+                notes=d.get("notes"),
+            ))
+    return lanes
+
+
+def confirm_import(db: Session, tenant_id: int, company_id: int, data: ImportConfirm,
+                   user_id: str | None) -> RateSheet:
+    """Crea el tarifario + rutas a partir de la vista previa confirmada."""
+    sheet = RateSheet(
+        tenant_id=tenant_id, company_id=company_id,
+        supplier_id=data.supplier_id, mode=data.mode, name=data.name,
+        currency=data.currency, valid_from=data.valid_from, valid_to=data.valid_to,
+        default_origin=data.default_origin, status=data.status or "borrador",
+        notes=data.notes, created_by=user_id, updated_by=user_id,
+    )
+    db.add(sheet)
+    db.flush()
+    for lane in data.lanes:
+        _add_lane(db, tenant_id, company_id, sheet.id, lane)
+    db.commit()
+    db.refresh(sheet)
+    return sheet
+
+
+def import_from_excel(db: Session, tenant_id: int, company_id: int, mode: str,
+                      content: bytes, header: RateSheetCreate, user_id: str | None) -> RateSheet:
+    """Atajo: parsea el Excel y crea el tarifario en un solo paso."""
+    preview = parse_excel(mode, content)
+    lanes = _rows_to_lanes(mode, preview.rows, header.default_origin)
+    return confirm_import(
+        db, tenant_id, company_id,
+        ImportConfirm(**header.model_dump(), lanes=lanes), user_id,
+    )
+
+
+# ============================================================ Motor de costeo
+def _volumetric_kg(volume_m3: Decimal | None) -> Decimal:
+    return (volume_m3 or Decimal(0)) * AIR_VOLUMETRIC_FACTOR
+
+
+def _rate_for(breaks: list[RateBreak], qty: Decimal) -> Decimal | None:
+    """Tarifa aplicable al peso/wm 'qty' (mayor quiebre cuyo umbral <= qty)."""
+    if not breaks:
+        return None
+    applicable = None
+    for b in breaks:
+        if b.from_qty <= qty:
+            applicable = b.rate
+    if applicable is None:
+        applicable = breaks[0].rate  # por debajo del primer quiebre → tarifa base (gobierna el mínimo)
+    return applicable
+
+
+def _best_break_cost(breaks: list[RateBreak], qty: Decimal) -> Decimal:
+    """Costo base con optimización de quiebre (declarar peso mayor si conviene)."""
+    base_rate = _rate_for(breaks, qty)
+    base = (qty * base_rate) if base_rate is not None else Decimal(0)
+    for b in breaks:
+        if b.from_qty > qty:
+            candidate = b.from_qty * b.rate
+            if candidate < base:
+                base = candidate
+    return base
+
+
+def _apply_charges(db: Session, sheet: RateSheet, lane: RateLane, base: Decimal,
+                   chargeable: Decimal, quantity: int, dangerous: bool) -> list[CostChargeLine]:
+    charges = (
+        db.query(RateCharge)
+        .filter(
+            RateCharge.deleted_at.is_(None),
+            or_(RateCharge.rate_sheet_id == sheet.id, RateCharge.rate_lane_id == lane.id),
+        )
+        .all()
+    )
+    lines: list[CostChargeLine] = []
+    for c in charges:
+        if c.concept == "dgr" and not dangerous:
+            continue
+        v = c.value or Decimal(0)
+        if c.charge_type == "fijo" or c.charge_type == "por_guia":
+            amt = v
+        elif c.charge_type == "por_kg":
+            amt = v * chargeable
+        elif c.charge_type == "por_contenedor":
+            amt = v * quantity
+        elif c.charge_type == "porcentaje":
+            amt = base * v / Decimal(100)
+        else:
+            amt = v
+        lines.append(CostChargeLine(concept=c.concept, amount=amt))
+    return lines
+
+
+def quote_cost(db: Session, tenant_id: int, company_id: int, req: CostRequest) -> list[CostOption]:
+    on_date = req.on_date or date.today()
+    sheets = _sheet_query(db, tenant_id, company_id).filter(
+        RateSheet.mode == req.mode,
+        RateSheet.status == "activo",
+        or_(RateSheet.valid_from.is_(None), RateSheet.valid_from <= on_date),
+        or_(RateSheet.valid_to.is_(None), RateSheet.valid_to >= on_date),
+    ).all()
+
+    gross = req.gross_weight_kg or Decimal(0)
+    options: list[CostOption] = []
+    for sheet in sheets:
+        lanes_q = db.query(RateLane).filter(
+            RateLane.rate_sheet_id == sheet.id, RateLane.deleted_at.is_(None),
+        )
+        if req.destination:
+            lanes_q = lanes_q.filter(RateLane.destination == req.destination)
+        for lane in lanes_q.all():
+            # Origen: match exacto o el default del tarifario.
+            lane_origin = lane.origin or sheet.default_origin
+            if req.origin and lane_origin and lane_origin != req.origin:
+                continue
+            if req.mode == "maritimo_fcl":
+                if req.equipment_type and lane.equipment_type and lane.equipment_type != req.equipment_type:
+                    continue
+                chargeable = Decimal(req.quantity)
+                base = (lane.flat_rate or Decimal(0)) * req.quantity
+                detail = f"{req.quantity} x {lane.equipment_type or 'contenedor'}"
+            elif req.mode == "terrestre":
+                chargeable = Decimal(req.quantity)
+                base = (lane.flat_rate or Decimal(0)) * req.quantity
+                detail = "tarifa por ruta"
+            elif req.mode == "maritimo_lcl":
+                tons = gross / Decimal(1000)
+                wm = max(tons, req.volume_m3 or Decimal(0))
+                brks = breaks_of(db, lane.id)
+                base = _best_break_cost(brks, wm) if brks else Decimal(0)
+                chargeable = wm
+                base = max(base, lane.min_charge or Decimal(0))
+                detail = f"W/M {wm.quantize(Decimal('0.01'))}"
+            else:  # aereo
+                chargeable = max(gross, _volumetric_kg(req.volume_m3))
+                brks = breaks_of(db, lane.id)
+                base = _best_break_cost(brks, chargeable)
+                base = max(base, lane.min_charge or Decimal(0))
+                detail = f"facturable {chargeable.quantize(Decimal('0.01'))} kg"
+
+            charge_lines = _apply_charges(db, sheet, lane, base, chargeable, req.quantity, req.dangerous)
+            total = base + sum((c.amount for c in charge_lines), Decimal(0))
+            options.append(CostOption(
+                rate_sheet_id=sheet.id, rate_sheet_name=sheet.name, supplier_id=sheet.supplier_id,
+                currency=sheet.currency, chargeable=chargeable, base_cost=base,
+                charges=charge_lines, total_cost=total, transit_days=lane.transit_days, detail=detail,
+            ))
+    options.sort(key=lambda o: o.total_cost)
+    return options

backend/api/v1/modules/crm/router.py

@@ -21,6 +21,8 @@ from .metrics.routes import router as metrics_router
 from .opportunities.routes import router as opportunities_router
 from .pipelines.routes import router as pipelines_router
 from .quotes.routes import router as quotes_router
+from .rates.routes import cost_router as rates_cost_router
+from .rates.routes import router as rates_router
 from .service_requests.routes import router as service_requests_router
 from .suppliers.routes import router as suppliers_router
 from .uploads.routes import router as uploads_router
@@ -44,3 +46,5 @@ router.include_router(activities_router)
 router.include_router(metrics_router)
 router.include_router(catalogs_router)
 router.include_router(uploads_router)
+router.include_router(rates_router)
+router.include_router(rates_cost_router)

backend/api/v1/modules/crm/suppliers/dto.py

@@ -13,6 +13,7 @@ class SupplierBase(BaseModel):
     person_type: str | None = Field(None, max_length=10)
     status: str = Field("active", max_length=20)
     classifications: list[str] = Field(default_factory=list)
+    classification_other: str | None = Field(None, max_length=120)
     # Comercial
     services_offered: str | None = None
     coverage: str | None = Field(None, max_length=20)
@@ -52,6 +53,7 @@ class SupplierUpdate(BaseModel):
     person_type: str | None = Field(None, max_length=10)
     status: str | None = Field(None, max_length=20)
     classifications: list[str] | None = None
+    classification_other: str | None = Field(None, max_length=120)
     services_offered: str | None = None
     coverage: str | None = Field(None, max_length=20)
     countries: list[str] | None = None

backend/api/v1/modules/crm/suppliers/models.py

@@ -30,6 +30,8 @@ class Supplier(Base, TenantScopedMixin, TimestampMixin):
     # Clasificación (múltiple): naviera, aerolinea, transportista_terrestre, ferrocarril,
     # agente_aduanal, agente_carga, agente_corresponsal, almacen, aseguradora, paqueteria, otro
     classifications: Mapped[list | None] = mapped_column(JSON, nullable=True, default=list)
+    # Texto libre cuando la clasificación incluye "otro"
+    classification_other: Mapped[str | None] = mapped_column(String(120), nullable=True)
 
     # ----- Información comercial -----
     services_offered: Mapped[str | None] = mapped_column(Text, nullable=True)

backend/api/v1/modules/fin/catalogs/__init__.py

@@ -1 +0,0 @@
-"""Catálogos oficiales del SAT (schema ``sat``): globales y de solo lectura."""

backend/api/v1/modules/fin/catalogs/dto.py

@@ -1,61 +0,0 @@
-"""Esquemas de respuesta de los catálogos del SAT (solo lectura)."""
-
-from pydantic import BaseModel, ConfigDict
-
-
-class SatCatalogItem(BaseModel):
-    """Forma común de todo catálogo del SAT: clave + descripción."""
-
-    model_config = ConfigDict(from_attributes=True)
-
-    id: int
-    code: str
-    description: str
-    is_active: bool
-
-
-class TaxRegimeResponse(SatCatalogItem):
-    """``c_RegimenFiscal``: incluye a qué tipo de persona aplica el régimen."""
-
-    applies_to_individual: bool  # persona física
-    applies_to_legal_entity: bool  # persona moral
-
-
-class TaxResponse(SatCatalogItem):
-    """``c_Impuesto``: indica si el impuesto puede retenerse o trasladarse."""
-
-    is_withholding: bool
-    is_transferred: bool
-    is_local: bool
-
-
-class UnitOfMeasureResponse(SatCatalogItem):
-    """``c_ClaveUnidad``: nombre corto, símbolo y nota larga del catálogo."""
-
-    description: str | None = None
-    name: str
-    symbol: str | None = None
-
-
-class PaymentFormResponse(SatCatalogItem):
-    """``c_FormaPago``."""
-
-
-class ProductServiceResponse(SatCatalogItem):
-    """``c_ClaveProdServ``."""
-
-
-class VoucherTypeResponse(SatCatalogItem):
-    """``c_TipoDeComprobante``."""
-
-
-class PaymentMethodResponse(SatCatalogItem):
-    """``c_MetodoPago``."""
-
-
-class TaxObjectResponse(SatCatalogItem):
-    """``c_ObjetoImp``."""
-
-
-class CfdiUseResponse(SatCatalogItem):
-    """``c_UsoCFDI``."""

backend/api/v1/modules/fin/catalogs/models.py

@@ -1,143 +0,0 @@
-"""Modelos de los catálogos oficiales del SAT — schema ``sat``.
-
-Son catálogos **globales**: los publica el SAT, valen igual para cualquier tenant y
-compañía, por eso no heredan ``TenantScopedMixin``. Tampoco se borran: cuando el SAT
-retira una clave, el registro se marca ``is_active = false`` para que las facturas
-históricas que la usan sigan resolviendo su descripción (de ahí que se use
-``BaseTimestampMixin``, sin ``deleted_at``).
-
-La API los expone únicamente en modo lectura; el alta y la actualización pasan por
-``seed_data.sync_catalogs()``.
-"""
-
-from sqlalchemy import Boolean, Integer, String, text
-from sqlalchemy.orm import Mapped, mapped_column
-
-from api.v1.common.base_models import BaseTimestampMixin
-from core.database import Base
-
-
-class SatCatalogMixin(BaseTimestampMixin):
-    """Campos comunes a todo catálogo del SAT.
-
-    ``code`` (la clave oficial) se declara en cada modelo porque su longitud
-    cambia de catálogo en catálogo.
-    """
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
-    description: Mapped[str] = mapped_column(String(500), nullable=False)
-    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("true"))
-
-
-class TaxRegime(Base, SatCatalogMixin):
-    """``c_RegimenFiscal`` — régimen fiscal del emisor y del receptor del CFDI.
-
-    Las banderas indican a qué tipo de persona aplica el régimen: una persona física
-    no puede declararse en el 601 (General de Ley Personas Morales) y viceversa.
-    """
-
-    __tablename__ = "tax_regimes"
-    __table_args__ = {"schema": "sat"}
-
-    code: Mapped[str] = mapped_column(String(3), nullable=False, unique=True, index=True)
-    applies_to_individual: Mapped[bool] = mapped_column(  # persona física
-        Boolean, nullable=False, server_default=text("false")
-    )
-    applies_to_legal_entity: Mapped[bool] = mapped_column(  # persona moral
-        Boolean, nullable=False, server_default=text("false")
-    )
-
-
-class Tax(Base, SatCatalogMixin):
-    """``c_Impuesto`` — impuestos federales que pueden trasladarse o retenerse."""
-
-    __tablename__ = "taxes"
-    __table_args__ = {"schema": "sat"}
-
-    code: Mapped[str] = mapped_column(String(3), nullable=False, unique=True, index=True)
-    is_withholding: Mapped[bool] = mapped_column(  # puede retenerse
-        Boolean, nullable=False, server_default=text("false")
-    )
-    is_transferred: Mapped[bool] = mapped_column(  # puede trasladarse
-        Boolean, nullable=False, server_default=text("false")
-    )
-    # Los impuestos locales (ISH y similares) viajan en el complemento "Impuestos
-    # Locales" con claves ajenas a c_Impuesto; la bandera queda disponible para
-    # cuando el negocio defina ese catálogo.
-    is_local: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
-
-
-class PaymentForm(Base, SatCatalogMixin):
-    """``c_FormaPago`` — con qué se pagó (efectivo, transferencia, tarjeta…)."""
-
-    __tablename__ = "payment_forms"
-    __table_args__ = {"schema": "sat"}
-
-    code: Mapped[str] = mapped_column(String(2), nullable=False, unique=True, index=True)
-
-
-class UnitOfMeasure(Base, SatCatalogMixin):
-    """``c_ClaveUnidad`` — unidad de medida de la partida.
-
-    Único catálogo que separa nombre corto y definición: ``name`` es lo que se
-    muestra al capturar y ``description`` la nota larga del SAT, que puede venir
-    vacía.
-    """
-
-    __tablename__ = "units_of_measure"
-    __table_args__ = {"schema": "sat"}
-
-    code: Mapped[str] = mapped_column(String(20), nullable=False, unique=True, index=True)
-    name: Mapped[str] = mapped_column(String(255), nullable=False)
-    symbol: Mapped[str | None] = mapped_column(String(20), nullable=True)
-    # Se redeclara para permitir NULL: aquí la descripción es la nota del catálogo.
-    description: Mapped[str | None] = mapped_column(String(500), nullable=True)
-
-
-class ProductService(Base, SatCatalogMixin):
-    """``c_ClaveProdServ`` — clave de producto o servicio de la partida."""
-
-    __tablename__ = "products_services"
-    __table_args__ = {"schema": "sat"}
-
-    code: Mapped[str] = mapped_column(String(8), nullable=False, unique=True, index=True)
-
-
-class VoucherType(Base, SatCatalogMixin):
-    """``c_TipoDeComprobante`` — I ingreso, E egreso, T traslado, N nómina, P pago."""
-
-    __tablename__ = "voucher_types"
-    __table_args__ = {"schema": "sat"}
-
-    code: Mapped[str] = mapped_column(String(1), nullable=False, unique=True, index=True)
-
-
-class PaymentMethod(Base, SatCatalogMixin):
-    """``c_MetodoPago`` — PUE (una sola exhibición) o PPD (parcialidades/diferido)."""
-
-    __tablename__ = "payment_methods"
-    __table_args__ = {"schema": "sat"}
-
-    code: Mapped[str] = mapped_column(String(3), nullable=False, unique=True, index=True)
-
-
-class TaxObject(Base, SatCatalogMixin):
-    """``c_ObjetoImp`` — si la partida es o no objeto de impuesto."""
-
-    __tablename__ = "tax_objects"
-    __table_args__ = {"schema": "sat"}
-
-    code: Mapped[str] = mapped_column(String(2), nullable=False, unique=True, index=True)
-
-
-class CfdiUse(Base, SatCatalogMixin):
-    """``c_UsoCFDI`` — uso que el receptor le dará al comprobante.
-
-    Lo declara el receptor, no el emisor, y el SAT lo valida contra su régimen
-    fiscal: por eso vive en la ficha del cliente (``crm.accounts.cfdi_use_id``).
-    """
-
-    __tablename__ = "cfdi_uses"
-    __table_args__ = {"schema": "sat"}
-
-    code: Mapped[str] = mapped_column(String(4), nullable=False, unique=True, index=True)

backend/api/v1/modules/fin/catalogs/routes.py

@@ -1,138 +0,0 @@
-"""Endpoints de los catálogos del SAT — **solo lectura**.
-
-No se exponen POST/PUT/PATCH/DELETE a propósito: son catálogos fijos publicados por
-el SAT y se mantienen con ``seed_data.sync_catalogs()``, no por API.
-
-Nota: aunque los catálogos son globales, el router del módulo exige ``fin.access``,
-permiso que se resuelve sobre una compañía; por eso las peticiones siguen llevando
-``company_id`` en la query string.
-"""
-
-from typing import Literal
-
-from fastapi import APIRouter, Depends, Query
-from sqlalchemy.orm import Session
-
-from core.database import get_core_db
-from core.security import get_current_user
-
-from . import service
-from .dto import (
-    CfdiUseResponse,
-    PaymentFormResponse,
-    PaymentMethodResponse,
-    ProductServiceResponse,
-    TaxObjectResponse,
-    TaxRegimeResponse,
-    TaxResponse,
-    UnitOfMeasureResponse,
-    VoucherTypeResponse,
-)
-
-router = APIRouter()
-
-_SEARCH = Query(None, description="Búsqueda por clave o descripción")
-_ACTIVE_ONLY = Query(True, description="Solo claves vigentes")
-
-
-@router.get("/catalogs/tax-regimes", response_model=list[TaxRegimeResponse])
-def list_tax_regimes(
-    search: str | None = _SEARCH,
-    active_only: bool = _ACTIVE_ONLY,
-    person_type: Literal["fisica", "moral"] | None = Query(
-        None, description="Acota al régimen de persona física o moral"
-    ),
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """``c_RegimenFiscal`` — régimen fiscal del emisor/receptor del CFDI."""
-    return service.get_tax_regimes(db, search, active_only, person_type)
-
-
-@router.get("/catalogs/taxes", response_model=list[TaxResponse])
-def list_taxes(
-    search: str | None = _SEARCH,
-    active_only: bool = _ACTIVE_ONLY,
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """``c_Impuesto`` — impuestos federales trasladados y retenidos."""
-    return service.get_taxes(db, search, active_only)
-
-
-@router.get("/catalogs/payment-forms", response_model=list[PaymentFormResponse])
-def list_payment_forms(
-    search: str | None = _SEARCH,
-    active_only: bool = _ACTIVE_ONLY,
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """``c_FormaPago`` — medio con el que se liquidó el comprobante."""
-    return service.get_payment_forms(db, search, active_only)
-
-
-@router.get("/catalogs/units-of-measure", response_model=list[UnitOfMeasureResponse])
-def list_units_of_measure(
-    search: str | None = _SEARCH,
-    active_only: bool = _ACTIVE_ONLY,
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """``c_ClaveUnidad`` — unidad de medida de la partida."""
-    return service.get_units_of_measure(db, search, active_only)
-
-
-@router.get("/catalogs/products-services", response_model=list[ProductServiceResponse])
-def list_products_services(
-    search: str | None = _SEARCH,
-    active_only: bool = _ACTIVE_ONLY,
-    limit: int = Query(50, ge=1, le=200, description="Máximo de claves devueltas"),
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """``c_ClaveProdServ`` — clave de producto/servicio; pensado para autocompletado."""
-    return service.get_products_services(db, search, active_only, limit)
-
-
-@router.get("/catalogs/voucher-types", response_model=list[VoucherTypeResponse])
-def list_voucher_types(
-    search: str | None = _SEARCH,
-    active_only: bool = _ACTIVE_ONLY,
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """``c_TipoDeComprobante`` — ingreso, egreso, traslado, nómina o pago."""
-    return service.get_voucher_types(db, search, active_only)
-
-
-@router.get("/catalogs/payment-methods", response_model=list[PaymentMethodResponse])
-def list_payment_methods(
-    search: str | None = _SEARCH,
-    active_only: bool = _ACTIVE_ONLY,
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """``c_MetodoPago`` — PUE o PPD."""
-    return service.get_payment_methods(db, search, active_only)
-
-
-@router.get("/catalogs/tax-objects", response_model=list[TaxObjectResponse])
-def list_tax_objects(
-    search: str | None = _SEARCH,
-    active_only: bool = _ACTIVE_ONLY,
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """``c_ObjetoImp`` — si la partida es objeto de impuesto."""
-    return service.get_tax_objects(db, search, active_only)
-
-
-@router.get("/catalogs/cfdi-uses", response_model=list[CfdiUseResponse])
-def list_cfdi_uses(
-    search: str | None = _SEARCH,
-    active_only: bool = _ACTIVE_ONLY,
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """``c_UsoCFDI`` — uso que el receptor le dará al comprobante."""
-    return service.get_cfdi_uses(db, search, active_only)

backend/api/v1/modules/fin/catalogs/seed_data.py

@@ -1,336 +0,0 @@
-"""Datos semilla de los catálogos del SAT y su sincronización idempotente.
-
-Los catálogos viven aquí y no dentro de una migración concreta a propósito: cuando el
-SAT corrige una descripción o publica una clave nueva, basta editar estas listas y
-volver a correr :func:`sync_catalogs`, sin escribir una migración de esquema.
-
-Las tablas se describen con ``sa.Table`` ligeros sobre un ``MetaData`` propio (no con
-los modelos ORM) para que la migración pueda importar este módulo sin acoplarse a la
-definición ORM, que sigue evolucionando.
-"""
-
-import sqlalchemy as sa
-
-_metadata = sa.MetaData()
-
-
-def _catalog_table(name: str, *extra_columns: sa.Column) -> sa.Table:
-    """Tabla mínima de catálogo: las columnas que toca el upsert, nada más."""
-    return sa.Table(
-        name,
-        _metadata,
-        sa.Column("id", sa.Integer, primary_key=True),
-        sa.Column("code", sa.String, nullable=False),
-        sa.Column("description", sa.String),
-        sa.Column("is_active", sa.Boolean),
-        *extra_columns,
-        schema="sat",
-    )
-
-
-tax_regimes_table = _catalog_table(
-    "tax_regimes",
-    sa.Column("applies_to_individual", sa.Boolean),
-    sa.Column("applies_to_legal_entity", sa.Boolean),
-)
-taxes_table = _catalog_table(
-    "taxes",
-    sa.Column("is_withholding", sa.Boolean),
-    sa.Column("is_transferred", sa.Boolean),
-    sa.Column("is_local", sa.Boolean),
-)
-payment_forms_table = _catalog_table("payment_forms")
-units_of_measure_table = _catalog_table(
-    "units_of_measure",
-    sa.Column("name", sa.String),
-    sa.Column("symbol", sa.String),
-)
-products_services_table = _catalog_table("products_services")
-voucher_types_table = _catalog_table("voucher_types")
-payment_methods_table = _catalog_table("payment_methods")
-tax_objects_table = _catalog_table("tax_objects")
-cfdi_uses_table = _catalog_table("cfdi_uses")
-
-
-# ---------------------------------------------------------------------------
-# c_RegimenFiscal (CFDI 4.0)
-# ---------------------------------------------------------------------------
-
-def _regime(code: str, description: str, individual: bool, legal_entity: bool) -> dict:
-    return {
-        "code": code,
-        "description": description,
-        "applies_to_individual": individual,
-        "applies_to_legal_entity": legal_entity,
-        "is_active": True,
-    }
-
-
-TAX_REGIMES: list[dict] = [
-    _regime("601", "General de Ley Personas Morales", False, True),
-    _regime("603", "Personas Morales con Fines no Lucrativos", False, True),
-    _regime("605", "Sueldos y Salarios e Ingresos Asimilados a Salarios", True, False),
-    _regime("606", "Arrendamiento", True, False),
-    _regime("607", "Régimen de Enajenación o Adquisición de Bienes", True, False),
-    _regime("608", "Demás ingresos", True, False),
-    _regime("610", "Residentes en el Extranjero sin Establecimiento Permanente en México", True, True),
-    _regime("611", "Ingresos por Dividendos (socios y accionistas)", True, False),
-    _regime("612", "Personas Físicas con Actividades Empresariales y Profesionales", True, False),
-    _regime("614", "Ingresos por intereses", True, False),
-    _regime("615", "Régimen de los ingresos por obtención de premios", True, False),
-    _regime("616", "Sin obligaciones fiscales", True, False),
-    _regime("620", "Sociedades Cooperativas de Producción que optan por diferir sus ingresos", False, True),
-    _regime("621", "Incorporación Fiscal", True, False),
-    _regime("622", "Actividades Agrícolas, Ganaderas, Silvícolas y Pesqueras", False, True),
-    _regime("623", "Opcional para Grupos de Sociedades", False, True),
-    _regime("624", "Coordinados", False, True),
-    _regime("625", "Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas", True, False),
-    _regime("626", "Régimen Simplificado de Confianza", True, True),
-]
-
-
-# ---------------------------------------------------------------------------
-# c_Impuesto
-# ---------------------------------------------------------------------------
-# is_local queda en false para los tres: los impuestos locales (ISH y similares)
-# se declaran en el complemento "Impuestos Locales" con claves que no pertenecen
-# a c_Impuesto. No se siembran registros locales inventados.
-
-TAXES: list[dict] = [
-    {"code": "001", "description": "ISR", "is_withholding": True, "is_transferred": False, "is_local": False, "is_active": True},
-    {"code": "002", "description": "IVA", "is_withholding": True, "is_transferred": True, "is_local": False, "is_active": True},
-    {"code": "003", "description": "IEPS", "is_withholding": True, "is_transferred": True, "is_local": False, "is_active": True},
-]
-
-
-# ---------------------------------------------------------------------------
-# c_FormaPago
-# ---------------------------------------------------------------------------
-
-PAYMENT_FORMS: list[dict] = [
-    {"code": code, "description": description, "is_active": True}
-    for code, description in [
-        ("01", "Efectivo"),
-        ("02", "Cheque nominativo"),
-        ("03", "Transferencia electrónica de fondos"),
-        ("04", "Tarjeta de crédito"),
-        ("05", "Monedero electrónico"),
-        ("06", "Dinero electrónico"),
-        ("08", "Vales de despensa"),
-        ("12", "Dación en pago"),
-        ("13", "Pago por subrogación"),
-        ("14", "Pago por consignación"),
-        ("15", "Condonación"),
-        ("17", "Compensación"),
-        ("23", "Novación"),
-        ("24", "Confusión"),
-        ("25", "Remisión de deuda"),
-        ("26", "Prescripción o caducidad"),
-        ("27", "A satisfacción del acreedor"),
-        ("28", "Tarjeta de débito"),
-        ("29", "Tarjeta de servicios"),
-        ("30", "Aplicación de anticipos"),
-        ("31", "Intermediario pagos"),
-        ("99", "Por definir"),
-    ]
-]
-
-
-# ---------------------------------------------------------------------------
-# c_TipoDeComprobante
-# ---------------------------------------------------------------------------
-
-VOUCHER_TYPES: list[dict] = [
-    {"code": code, "description": description, "is_active": True}
-    for code, description in [
-        ("I", "Ingreso"),
-        ("E", "Egreso"),
-        ("T", "Traslado"),
-        ("N", "Nómina"),
-        ("P", "Pago"),
-    ]
-]
-
-
-# ---------------------------------------------------------------------------
-# c_MetodoPago
-# ---------------------------------------------------------------------------
-
-PAYMENT_METHODS: list[dict] = [
-    {"code": "PUE", "description": "Pago en una sola exhibición", "is_active": True},
-    {"code": "PPD", "description": "Pago en parcialidades o diferido", "is_active": True},
-]
-
-
-# ---------------------------------------------------------------------------
-# c_ObjetoImp
-# ---------------------------------------------------------------------------
-# Versiones posteriores del catálogo incorporan las claves 05–07; no se siembran
-# hasta que el área Fiscal confirme la versión vigente (ver PENDIENTE DECISIÓN).
-
-TAX_OBJECTS: list[dict] = [
-    {"code": "01", "description": "No objeto de impuesto", "is_active": True},
-    {"code": "02", "description": "Sí objeto de impuesto", "is_active": True},
-    {"code": "03", "description": "Sí objeto del impuesto y no obligado al desglose", "is_active": True},
-    {"code": "04", "description": "Sí objeto del impuesto y no causa impuesto", "is_active": True},
-]
-
-
-# ---------------------------------------------------------------------------
-# c_ClaveUnidad — subset operativo
-# ---------------------------------------------------------------------------
-# description queda en NULL: es la nota larga del catálogo, que aquí no aporta.
-
-UNITS_OF_MEASURE: list[dict] = [
-    {"code": code, "name": name, "symbol": symbol, "description": None, "is_active": True}
-    for code, name, symbol in [
-        ("H87", "Pieza", "pz"),
-        ("E48", "Unidad de servicio", None),
-        ("ACT", "Actividad", None),
-        ("C62", "Uno", None),
-        ("KGM", "Kilogramo", "kg"),
-        ("TNE", "Tonelada métrica", "t"),
-        ("GRM", "Gramo", "g"),
-        ("LTR", "Litro", "l"),
-        ("MTR", "Metro", "m"),
-        ("MTK", "Metro cuadrado", "m²"),
-        ("MTQ", "Metro cúbico", "m³"),
-        ("KMT", "Kilómetro", "km"),
-        ("CMT", "Centímetro", "cm"),
-        ("DAY", "Día", "d"),
-        ("HUR", "Hora", "h"),
-        ("MON", "Mes", None),
-        ("XBX", "Caja", None),
-        ("XPK", "Paquete", None),
-        ("XPX", "Paleta / tarima", None),
-        ("XLT", "Lote", None),
-        ("E51", "Trabajo", None),
-    ]
-]
-
-
-# ---------------------------------------------------------------------------
-# c_ClaveProdServ — subset de logística
-# ---------------------------------------------------------------------------
-# Subset inicial de c_ClaveProdServ para agente de carga — pendiente validación con
-# área Fiscal antes de producción. El catálogo completo son ~52,000 claves; aquí solo
-# se siembran las del giro. Si falta una clave para un caso de uso, se documenta como
-# PENDIENTE DECISIÓN: no se deduce ni se inventa.
-
-PRODUCTS_SERVICES: list[dict] = [
-    {"code": code, "description": description, "is_active": True}
-    for code, description in [
-        ("78101500", "Transporte de carga por carretera"),
-        ("78101600", "Transporte de carga marítimo"),
-        ("78101700", "Transporte de carga por ferrocarril"),
-        ("78101800", "Transporte de carga aérea"),
-        ("78102200", "Servicios postales de paqueteo y courrier"),
-        ("78121600", "Embalaje"),
-        ("78131600", "Almacenaje"),
-        ("78141500", "Servicios de planificación logística"),
-        ("78141600", "Servicios de expedición de fletes"),
-        ("84131500", "Seguros de vida, salud y accidentes / seguros de carga"),
-        ("80101500", "Servicios de consultoría de negocios y administración corporativa"),
-    ]
-]
-
-
-# ---------------------------------------------------------------------------
-# c_UsoCFDI
-# ---------------------------------------------------------------------------
-# Catálogo del uso que el receptor da al comprobante. Se siembran clave y
-# descripción; **no** se cargan las banderas de persona física/moral ni la
-# compatibilidad por régimen fiscal, porque esa matriz cambia entre versiones del
-# catálogo y equivocarla provoca rechazos al timbrar.
-#
-# Pendiente validación con área Fiscal antes de producción, igual que el subset de
-# c_ClaveProdServ.
-
-CFDI_USES: list[dict] = [
-    {"code": code, "description": description, "is_active": True}
-    for code, description in [
-        ("G01", "Adquisición de mercancías"),
-        ("G02", "Devoluciones, descuentos o bonificaciones"),
-        ("G03", "Gastos en general"),
-        ("I01", "Construcciones"),
-        ("I02", "Mobiliario y equipo de oficina por inversiones"),
-        ("I03", "Equipo de transporte"),
-        ("I04", "Equipo de cómputo y accesorios"),
-        ("I05", "Dados, troqueles, moldes, matrices y herramental"),
-        ("I06", "Comunicaciones telefónicas"),
-        ("I07", "Comunicaciones satelitales"),
-        ("I08", "Otra maquinaria y equipo"),
-        ("D01", "Honorarios médicos, dentales y gastos hospitalarios"),
-        ("D02", "Gastos médicos por incapacidad o discapacidad"),
-        ("D03", "Gastos funerales"),
-        ("D04", "Donativos"),
-        ("D05", "Intereses reales efectivamente pagados por créditos hipotecarios (casa habitación)"),
-        ("D06", "Aportaciones voluntarias al SAR"),
-        ("D07", "Primas por seguros de gastos médicos"),
-        ("D08", "Gastos de transportación escolar obligatoria"),
-        ("D09", "Depósitos en cuentas para el ahorro, primas que tengan como base planes de pensiones"),
-        ("D10", "Pagos por servicios educativos (colegiaturas)"),
-        ("S01", "Sin efectos fiscales"),
-        ("CP01", "Pagos"),
-        ("CN01", "Nómina"),
-    ]
-]
-
-
-# Orden estable de sincronización: (tabla, filas).
-CATALOGS: list[tuple[sa.Table, list[dict]]] = [
-    (tax_regimes_table, TAX_REGIMES),
-    (taxes_table, TAXES),
-    (payment_forms_table, PAYMENT_FORMS),
-    (units_of_measure_table, UNITS_OF_MEASURE),
-    (products_services_table, PRODUCTS_SERVICES),
-    (voucher_types_table, VOUCHER_TYPES),
-    (payment_methods_table, PAYMENT_METHODS),
-    (tax_objects_table, TAX_OBJECTS),
-    (cfdi_uses_table, CFDI_USES),
-]
-
-
-def sync_catalogs(connection) -> dict[str, int]:
-    """Sincroniza los catálogos del SAT contra la base, de forma idempotente.
-
-    Inserta las claves que faltan y actualiza descripción y banderas de las que ya
-    existen. **Nunca borra**: una clave retirada por el SAT se desactiva a mano para
-    no romper los CFDI históricos que la referencian.
-
-    Devuelve un resumen ``{"sat.tabla": filas_insertadas}`` útil para la bitácora de
-    la migración.
-
-    Los catálogos cuya tabla todavía no existe se omiten: al correr el historial de
-    migraciones desde cero, una migración antigua invoca esta misma función cuando los
-    catálogos agregados después aún no se han creado. Cada uno se siembra en la
-    migración que lo crea.
-
-    Se usa contra el ``connection`` que da ``op.get_bind()`` en Alembic, o contra la
-    conexión de una sesión en pruebas.
-    """
-    inspector = sa.inspect(connection)
-    # La inspección no aplica el schema_translate_map (las pruebas mapean sat -> None
-    # sobre SQLite), así que se resuelve el schema efectivo a mano.
-    schema_map = connection.get_execution_options().get("schema_translate_map") or {}
-
-    inserted: dict[str, int] = {}
-    for table, rows in CATALOGS:
-        effective_schema = schema_map.get(table.schema, table.schema)
-        if not inspector.has_table(table.name, schema=effective_schema):
-            continue
-        key = f"sat.{table.name}"
-        inserted[key] = 0
-        for row in rows:
-            existing = connection.execute(
-                sa.select(table.c.id).where(table.c.code == row["code"])
-            ).scalar()
-            values = {k: v for k, v in row.items() if k != "code"}
-            if existing is None:
-                connection.execute(table.insert().values(code=row["code"], **values))
-                inserted[key] += 1
-            else:
-                connection.execute(
-                    table.update().where(table.c.id == existing).values(**values)
-                )
-    return inserted

backend/api/v1/modules/fin/catalogs/service.py

@@ -1,106 +0,0 @@
-"""Consultas de los catálogos del SAT.
-
-Son globales (sin tenant_id / company_id) y de solo lectura: aquí no hay altas,
-cambios ni bajas, únicamente búsqueda para llenar los selectores de captura.
-"""
-
-from sqlalchemy import or_
-from sqlalchemy.orm import Session
-
-from .models import (
-    CfdiUse,
-    PaymentForm,
-    PaymentMethod,
-    ProductService,
-    Tax,
-    TaxObject,
-    TaxRegime,
-    UnitOfMeasure,
-    VoucherType,
-)
-
-# Catálogos que además del código y la descripción buscan por nombre corto.
-_SEARCHABLE_EXTRA_FIELDS = {UnitOfMeasure: ("name",)}
-
-
-def search_catalog(
-    db: Session,
-    model,
-    search: str | None = None,
-    active_only: bool = True,
-    limit: int | None = None,
-) -> list:
-    """Devuelve las claves de un catálogo, filtradas por texto libre.
-
-    ``search`` compara contra la clave o la descripción sin distinguir mayúsculas.
-    """
-    q = db.query(model)
-    if active_only:
-        q = q.filter(model.is_active.is_(True))
-    if search:
-        term = f"%{search.strip()}%"
-        fields = [model.code, model.description]
-        for extra in _SEARCHABLE_EXTRA_FIELDS.get(model, ()):
-            fields.append(getattr(model, extra))
-        q = q.filter(or_(*[f.ilike(term) for f in fields]))
-    q = q.order_by(model.code.asc())
-    if limit is not None:
-        q = q.limit(limit)
-    return q.all()
-
-
-def get_tax_regimes(
-    db: Session,
-    search: str | None = None,
-    active_only: bool = True,
-    person_type: str | None = None,
-) -> list[TaxRegime]:
-    """``c_RegimenFiscal``, opcionalmente acotado al tipo de persona.
-
-    ``person_type='fisica'`` deja solo los regímenes que puede usar una persona
-    física; ``'moral'``, los de persona moral.
-    """
-    q = db.query(TaxRegime)
-    if active_only:
-        q = q.filter(TaxRegime.is_active.is_(True))
-    if search:
-        term = f"%{search.strip()}%"
-        q = q.filter(or_(TaxRegime.code.ilike(term), TaxRegime.description.ilike(term)))
-    if person_type == "fisica":
-        q = q.filter(TaxRegime.applies_to_individual.is_(True))
-    elif person_type == "moral":
-        q = q.filter(TaxRegime.applies_to_legal_entity.is_(True))
-    return q.order_by(TaxRegime.code.asc()).all()
-
-
-def get_taxes(db: Session, search=None, active_only=True) -> list[Tax]:
-    return search_catalog(db, Tax, search, active_only)
-
-
-def get_payment_forms(db: Session, search=None, active_only=True) -> list[PaymentForm]:
-    return search_catalog(db, PaymentForm, search, active_only)
-
-
-def get_units_of_measure(db: Session, search=None, active_only=True) -> list[UnitOfMeasure]:
-    return search_catalog(db, UnitOfMeasure, search, active_only)
-
-
-def get_products_services(db: Session, search=None, active_only=True, limit=50) -> list[ProductService]:
-    """``c_ClaveProdServ``. Va paginado porque alimenta un autocompletado."""
-    return search_catalog(db, ProductService, search, active_only, limit=limit)
-
-
-def get_voucher_types(db: Session, search=None, active_only=True) -> list[VoucherType]:
-    return search_catalog(db, VoucherType, search, active_only)
-
-
-def get_payment_methods(db: Session, search=None, active_only=True) -> list[PaymentMethod]:
-    return search_catalog(db, PaymentMethod, search, active_only)
-
-
-def get_tax_objects(db: Session, search=None, active_only=True) -> list[TaxObject]:
-    return search_catalog(db, TaxObject, search, active_only)
-
-
-def get_cfdi_uses(db: Session, search=None, active_only=True) -> list[CfdiUse]:
-    return search_catalog(db, CfdiUse, search, active_only)

backend/api/v1/modules/fin/concepts/__init__.py

@@ -1 +0,0 @@
-"""Catálogo de conceptos de facturación por empresa."""

backend/api/v1/modules/fin/concepts/dto.py

@@ -1,55 +0,0 @@
-"""Esquemas del catálogo de conceptos de facturación."""
-
-from datetime import datetime
-from decimal import Decimal
-
-from pydantic import BaseModel, ConfigDict, Field
-
-from ..catalogs.dto import ProductServiceResponse, TaxObjectResponse, UnitOfMeasureResponse
-
-
-class ConceptBase(BaseModel):
-    code: str = Field(..., min_length=1, max_length=40, description="Clave interna del concepto")
-    description: str = Field(..., min_length=1, max_length=500)
-    product_service_id: int = Field(..., description="Clave ProdServ del SAT (1:1 por empresa)")
-    unit_of_measure_id: int | None = None
-    tax_object_id: int | None = None
-    unit_price: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=2)
-    currency: str = Field("MXN", min_length=3, max_length=3)
-    is_active: bool = True
-    notes: str | None = None
-
-
-class ConceptCreate(ConceptBase):
-    pass
-
-
-class ConceptUpdate(BaseModel):
-    """Actualización parcial: solo se tocan los campos enviados."""
-
-    code: str | None = Field(None, min_length=1, max_length=40)
-    description: str | None = Field(None, min_length=1, max_length=500)
-    product_service_id: int | None = None
-    unit_of_measure_id: int | None = None
-    tax_object_id: int | None = None
-    unit_price: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=2)
-    currency: str | None = Field(None, min_length=3, max_length=3)
-    is_active: bool | None = None
-    notes: str | None = None
-
-
-class ConceptResponse(ConceptBase):
-    """Incluye los objetos del catálogo del SAT ya resueltos, para evitar N+1 en la UI."""
-
-    model_config = ConfigDict(from_attributes=True)
-
-    id: int
-    tenant_id: int
-    company_id: int
-    product_service: ProductServiceResponse | None = None
-    unit_of_measure: UnitOfMeasureResponse | None = None
-    tax_object: TaxObjectResponse | None = None
-    created_by: str | None = None
-    updated_by: str | None = None
-    created_at: datetime
-    updated_at: datetime

backend/api/v1/modules/fin/concepts/models.py

@@ -1,67 +0,0 @@
-"""Catálogo de conceptos de facturación — ``fin.concepts``.
-
-A diferencia de los catálogos del SAT, este es **propio de cada empresa**: cada
-concepto que la empresa factura (flete internacional, despacho, almacenaje…) se
-registra una vez y queda amarrado a la clave de producto/servicio del SAT que le
-corresponde.
-
-La relación con ``sat.products_services`` es **1:1 por empresa**: si dos conceptos
-compartieran la misma clave ProdServ, al timbrar no habría forma de saber cuál
-descripción corresponde a la clave, así que la unicidad se garantiza por índice y se
-valida además en el service para devolver un 409 con mensaje entendible.
-"""
-
-from sqlalchemy import Boolean, ForeignKey, Index, Integer, Numeric, String, Text, text
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-
-from api.v1.common.base_models import TenantScopedMixin, TimestampMixin
-from core.database import Base
-
-from ..catalogs.models import ProductService, TaxObject, UnitOfMeasure  # noqa: F401  (resuelve las relaciones)
-
-# Los índices son parciales (``WHERE deleted_at IS NULL``): un concepto dado de baja
-# lógica libera su clave y su código para uno nuevo.
-_ALIVE = text("deleted_at IS NULL")
-
-
-class Concept(Base, TenantScopedMixin, TimestampMixin):
-    """Concepto facturable de una empresa, ligado a una clave ProdServ del SAT."""
-
-    __tablename__ = "concepts"
-    __table_args__ = (
-        Index(
-            "uq_fin_concepts_code",
-            "tenant_id", "company_id", "code",
-            unique=True, postgresql_where=_ALIVE, sqlite_where=_ALIVE,
-        ),
-        Index(
-            "uq_fin_concepts_product_service",
-            "tenant_id", "company_id", "product_service_id",
-            unique=True, postgresql_where=_ALIVE, sqlite_where=_ALIVE,
-        ),
-        {"schema": "fin"},
-    )
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
-    code: Mapped[str] = mapped_column(String(40), nullable=False)  # clave interna del concepto
-    description: Mapped[str] = mapped_column(String(500), nullable=False)
-    product_service_id: Mapped[int] = mapped_column(
-        Integer, ForeignKey("sat.products_services.id"), nullable=False, index=True
-    )
-    unit_of_measure_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("sat.units_of_measure.id"), nullable=True
-    )
-    tax_object_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("sat.tax_objects.id"), nullable=True
-    )
-    unit_price: Mapped[float | None] = mapped_column(Numeric(14, 2), nullable=True)
-    currency: Mapped[str] = mapped_column(String(3), nullable=False, server_default=text("'MXN'"))
-    is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("true"))
-    notes: Mapped[str | None] = mapped_column(Text, nullable=True)
-    created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
-    updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
-
-    # Cargadas con selectinload para que el listado no dispare N+1 consultas.
-    product_service: Mapped["ProductService"] = relationship("ProductService", lazy="selectin")
-    unit_of_measure: Mapped["UnitOfMeasure | None"] = relationship("UnitOfMeasure", lazy="selectin")
-    tax_object: Mapped["TaxObject | None"] = relationship("TaxObject", lazy="selectin")

backend/api/v1/modules/fin/concepts/routes.py

@@ -1,96 +0,0 @@
-"""Endpoints del catálogo de conceptos de facturación (CRUD por empresa)."""
-
-from fastapi import APIRouter, Depends, Query, status
-from sqlalchemy.orm import Session
-
-from api.v1.modules.core.permissions.dependencies import PermissionChecker
-from core.database import get_core_db
-from core.security import get_current_user
-
-from . import service
-from .dto import ConceptCreate, ConceptResponse, ConceptUpdate
-
-router = APIRouter()
-
-
-def _uid(current_user: dict) -> str | None:
-    return current_user.get("sub") or current_user.get("id")
-
-
-@router.get(
-    "/concepts",
-    response_model=list[ConceptResponse],
-    dependencies=[Depends(PermissionChecker(["fin.concept.view"]))],
-)
-def list_concepts(
-    company_id: int = Query(..., description="Company ID"),
-    search: str | None = Query(None, description="Búsqueda por clave o descripción"),
-    active_only: bool | None = Query(None, description="Filtra por conceptos activos o inactivos"),
-    product_service_id: int | None = Query(None, description="Filtra por clave ProdServ del SAT"),
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    return service.get_concepts(
-        db, current_user["tenant_id"], company_id, search, active_only, product_service_id
-    )
-
-
-@router.get(
-    "/concepts/{concept_id}",
-    response_model=ConceptResponse,
-    dependencies=[Depends(PermissionChecker(["fin.concept.view"]))],
-)
-def get_concept(
-    concept_id: int,
-    company_id: int = Query(..., description="Company ID"),
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    return service.get_concept(db, concept_id, current_user["tenant_id"], company_id)
-
-
-@router.post(
-    "/concepts",
-    response_model=ConceptResponse,
-    status_code=status.HTTP_201_CREATED,
-    dependencies=[Depends(PermissionChecker(["fin.concept.create"]))],
-)
-def create_concept(
-    payload: ConceptCreate,
-    company_id: int = Query(..., description="Company ID"),
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    return service.create_concept(db, payload, current_user["tenant_id"], company_id, _uid(current_user))
-
-
-@router.patch(
-    "/concepts/{concept_id}",
-    response_model=ConceptResponse,
-    dependencies=[Depends(PermissionChecker(["fin.concept.edit"]))],
-)
-def update_concept(
-    concept_id: int,
-    payload: ConceptUpdate,
-    company_id: int = Query(..., description="Company ID"),
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    return service.update_concept(
-        db, concept_id, payload, current_user["tenant_id"], company_id, _uid(current_user)
-    )
-
-
-@router.delete(
-    "/concepts/{concept_id}",
-    status_code=status.HTTP_204_NO_CONTENT,
-    dependencies=[Depends(PermissionChecker(["fin.concept.delete"]))],
-)
-def delete_concept(
-    concept_id: int,
-    company_id: int = Query(..., description="Company ID"),
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """Baja lógica del concepto (``deleted_at``)."""
-    service.delete_concept(db, concept_id, current_user["tenant_id"], company_id)

backend/api/v1/modules/fin/concepts/service.py

@@ -1,146 +0,0 @@
-"""Lógica del catálogo de conceptos de facturación.
-
-Todas las consultas filtran por ``tenant_id``, ``company_id`` y ``deleted_at IS NULL``:
-el catálogo es privado de cada empresa dentro de cada tenant.
-"""
-
-from datetime import datetime, timezone
-
-from fastapi import HTTPException, status
-from sqlalchemy import or_
-from sqlalchemy.orm import Session
-
-from ..catalogs.models import ProductService, TaxObject, UnitOfMeasure
-from .dto import ConceptCreate, ConceptUpdate
-from .models import Concept
-
-
-def _check_sat_refs(db: Session, data: dict) -> None:
-    """Verifica que las claves del SAT referidas existan antes de guardar."""
-    for field, model, msg in [
-        ("product_service_id", ProductService, "La clave de producto/servicio del SAT no existe"),
-        ("unit_of_measure_id", UnitOfMeasure, "La unidad de medida del SAT no existe"),
-        ("tax_object_id", TaxObject, "El objeto de impuesto del SAT no existe"),
-    ]:
-        value = data.get(field)
-        if field in data and value is not None:
-            if db.query(model.id).filter(model.id == value).first() is None:
-                raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail=msg)
-
-
-def _check_unique(
-    db: Session,
-    tenant_id: int,
-    company_id: int,
-    code: str | None,
-    product_service_id: int | None,
-    exclude_id: int | None = None,
-) -> None:
-    """Aplica en el service las mismas reglas que los índices únicos parciales.
-
-    Sin esto el conflicto llegaría al cliente como un IntegrityError crudo; aquí se
-    traduce a un 409 con mensaje en español.
-    """
-    base = db.query(Concept).filter(
-        Concept.tenant_id == tenant_id,
-        Concept.company_id == company_id,
-        Concept.deleted_at.is_(None),
-    )
-    if exclude_id is not None:
-        base = base.filter(Concept.id != exclude_id)
-
-    if code is not None and base.filter(Concept.code == code).first() is not None:
-        raise HTTPException(
-            status_code=status.HTTP_409_CONFLICT,
-            detail=f"Ya existe un concepto con la clave '{code}' en esta empresa",
-        )
-    # Regla 1:1 — una clave ProdServ no puede repetirse entre conceptos de la empresa.
-    if product_service_id is not None and base.filter(
-        Concept.product_service_id == product_service_id
-    ).first() is not None:
-        raise HTTPException(
-            status_code=status.HTTP_409_CONFLICT,
-            detail="La clave de producto/servicio del SAT ya está asignada a otro concepto de esta empresa",
-        )
-
-
-def get_concepts(
-    db: Session,
-    tenant_id: int,
-    company_id: int,
-    search: str | None = None,
-    active_only: bool | None = None,
-    product_service_id: int | None = None,
-) -> list[Concept]:
-    q = db.query(Concept).filter(
-        Concept.tenant_id == tenant_id,
-        Concept.company_id == company_id,
-        Concept.deleted_at.is_(None),
-    )
-    if active_only is not None:
-        q = q.filter(Concept.is_active.is_(active_only))
-    if product_service_id is not None:
-        q = q.filter(Concept.product_service_id == product_service_id)
-    if search:
-        term = f"%{search.strip()}%"
-        q = q.filter(or_(Concept.code.ilike(term), Concept.description.ilike(term)))
-    return q.order_by(Concept.code.asc()).all()
-
-
-def get_concept(db: Session, concept_id: int, tenant_id: int, company_id: int) -> Concept:
-    obj = db.query(Concept).filter(
-        Concept.id == concept_id,
-        Concept.tenant_id == tenant_id,
-        Concept.company_id == company_id,
-        Concept.deleted_at.is_(None),
-    ).first()
-    if not obj:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Concepto no encontrado")
-    return obj
-
-
-def create_concept(
-    db: Session, payload: ConceptCreate, tenant_id: int, company_id: int, user_id: str | None = None
-) -> Concept:
-    data = payload.model_dump()
-    _check_sat_refs(db, data)
-    _check_unique(db, tenant_id, company_id, data["code"], data["product_service_id"])
-    obj = Concept(**data, tenant_id=tenant_id, company_id=company_id, created_by=user_id, updated_by=user_id)
-    db.add(obj)
-    db.commit()
-    db.refresh(obj)
-    return obj
-
-
-def update_concept(
-    db: Session,
-    concept_id: int,
-    payload: ConceptUpdate,
-    tenant_id: int,
-    company_id: int,
-    user_id: str | None = None,
-) -> Concept:
-    obj = get_concept(db, concept_id, tenant_id, company_id)
-    data = payload.model_dump(exclude_unset=True)
-    _check_sat_refs(db, data)
-    _check_unique(
-        db,
-        tenant_id,
-        company_id,
-        data.get("code"),
-        data.get("product_service_id"),
-        exclude_id=obj.id,
-    )
-    for field, value in data.items():
-        setattr(obj, field, value)
-    obj.updated_by = user_id
-    db.commit()
-    db.refresh(obj)
-    return obj
-
-
-def delete_concept(db: Session, concept_id: int, tenant_id: int, company_id: int) -> None:
-    """Baja lógica: libera la clave ProdServ y el código para un concepto nuevo."""
-    obj = get_concept(db, concept_id, tenant_id, company_id)
-    obj.deleted_at = datetime.now(timezone.utc)
-    db.commit()

backend/api/v1/modules/fin/invoices/dto.py

@@ -10,16 +10,7 @@ class InvoiceClientReviewInput(BaseModel):
     notes: str | None = None
 
 
-class InvoiceItemSatFields(BaseModel):
-    """Claves fiscales de la partida. Opcionales: las facturas previas no las tienen."""
-
-    concept_id: int | None = None
-    product_service_id: int | None = None
-    unit_of_measure_id: int | None = None
-    tax_object_id: int | None = None
-
-
-class InvoiceItemBase(InvoiceItemSatFields):
+class InvoiceItemBase(BaseModel):
     concept: str = Field(..., max_length=60)
     description: str | None = Field(None, max_length=255)
     quantity: Decimal = Field(Decimal(1), ge=0, max_digits=12, decimal_places=2)
@@ -28,11 +19,9 @@ class InvoiceItemBase(InvoiceItemSatFields):
 
 class InvoiceItemCreate(InvoiceItemBase):
     invoice_id: int
-    # Opcional solo si viene concept_id: el service copia la descripción del concepto.
-    concept: str | None = Field(None, max_length=60)
 
 
-class InvoiceItemUpdate(InvoiceItemSatFields):
+class InvoiceItemUpdate(BaseModel):
     concept: str | None = Field(None, max_length=60)
     description: str | None = Field(None, max_length=255)
     quantity: Decimal | None = Field(None, ge=0, max_digits=12, decimal_places=2)
@@ -87,11 +76,6 @@ class InvoiceBase(BaseModel):
     bank_info: str | None = None
     notes: str | None = None
     owner_user_id: str | None = Field(None, max_length=64)
-    # ----- Claves fiscales del CFDI (opcionales mientras no se timbre) -----
-    voucher_type_id: int | None = None
-    payment_form_id: int | None = None
-    payment_method_id: int | None = None
-    expedition_zip_code: str | None = Field(None, max_length=5)
 
 
 class InvoiceCreate(InvoiceBase):
@@ -110,10 +94,6 @@ class InvoiceUpdate(BaseModel):
     bank_info: str | None = None
     notes: str | None = None
     owner_user_id: str | None = Field(None, max_length=64)
-    voucher_type_id: int | None = None
-    payment_form_id: int | None = None
-    payment_method_id: int | None = None
-    expedition_zip_code: str | None = Field(None, max_length=5)
 
 
 class InvoiceResponse(InvoiceBase):

backend/api/v1/modules/fin/invoices/models.py

@@ -1,22 +1,11 @@
 from datetime import date, datetime
 
-from sqlalchemy import Boolean, Date, DateTime, ForeignKey, Index, Integer, Numeric, String, Text, text
+from sqlalchemy import Boolean, Date, DateTime, ForeignKey, Integer, Numeric, String, Text, text
 from sqlalchemy.orm import Mapped, mapped_column
 
 from api.v1.common.base_models import TenantScopedMixin, TimestampMixin
 from core.database import Base
 
-from ..catalogs.models import (  # noqa: F401  (registra los catálogos SAT referidos por las FK)
-    PaymentForm,
-    PaymentMethod,
-    ProductService,
-    Tax,
-    TaxObject,
-    UnitOfMeasure,
-    VoucherType,
-)
-from ..concepts.models import Concept  # noqa: F401
-
 
 class Invoice(Base, TenantScopedMixin, TimestampMixin):
     """Factura (Diagrama 4). Integra los costos de la operación para cobro al cliente."""
@@ -61,18 +50,6 @@ class Invoice(Base, TenantScopedMixin, TimestampMixin):
     owner_user_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
     created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
     updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
-    # ----- Datos fiscales del CFDI (catálogos SAT) -----
-    # Nullables: las facturas emitidas antes de existir los catálogos no los tienen.
-    voucher_type_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("sat.voucher_types.id"), nullable=True
-    )
-    payment_form_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("sat.payment_forms.id"), nullable=True
-    )
-    payment_method_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("sat.payment_methods.id"), nullable=True
-    )
-    expedition_zip_code: Mapped[str | None] = mapped_column(String(5), nullable=True)
 
 
 class InvoiceItem(Base, TenantScopedMixin, TimestampMixin):
@@ -85,54 +62,10 @@ class InvoiceItem(Base, TenantScopedMixin, TimestampMixin):
     invoice_id: Mapped[int] = mapped_column(
         Integer, ForeignKey("fin.invoices.id"), nullable=False, index=True
     )
-    # Texto libre histórico: lo consume el PDF actual y se conserva obligatorio.
     concept: Mapped[str] = mapped_column(String(60), nullable=False)
     description: Mapped[str | None] = mapped_column(String(255), nullable=True)
     quantity: Mapped[float] = mapped_column(Numeric(12, 2), nullable=False, server_default=text("1"))
     unit_amount: Mapped[float] = mapped_column(Numeric(14, 2), nullable=False, server_default=text("0"))
-    # ----- Datos fiscales de la partida (catálogos SAT) -----
-    concept_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("fin.concepts.id"), nullable=True, index=True
-    )
-    product_service_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("sat.products_services.id"), nullable=True
-    )
-    unit_of_measure_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("sat.units_of_measure.id"), nullable=True
-    )
-    tax_object_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("sat.tax_objects.id"), nullable=True
-    )
-
-
-class InvoiceItemTax(Base, TenantScopedMixin, TimestampMixin):
-    """Impuesto trasladado o retenido de una partida de la factura.
-
-    Es captura de detalle fiscal para el futuro CFDI: **no** interviene en el cálculo
-    de subtotal/IVA/total de la factura, que sigue saliendo de ``invoices.tax_rate``.
-    """
-
-    __tablename__ = "invoice_item_taxes"
-    __table_args__ = (
-        Index(
-            "uq_fin_invoice_item_taxes",
-            "invoice_item_id", "tax_id", "is_withholding",
-            unique=True,
-            postgresql_where=text("deleted_at IS NULL"),
-            sqlite_where=text("deleted_at IS NULL"),
-        ),
-        {"schema": "fin"},
-    )
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
-    invoice_item_id: Mapped[int] = mapped_column(
-        Integer, ForeignKey("fin.invoice_items.id"), nullable=False, index=True
-    )
-    tax_id: Mapped[int] = mapped_column(Integer, ForeignKey("sat.taxes.id"), nullable=False)
-    # false = trasladado (se cobra al cliente); true = retenido
-    is_withholding: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
-    rate: Mapped[float | None] = mapped_column(Numeric(8, 6), nullable=True)  # p. ej. 0.160000
-    amount: Mapped[float] = mapped_column(Numeric(14, 2), nullable=False, server_default=text("0"))
 
 
 class Payment(Base, TenantScopedMixin, TimestampMixin):

backend/api/v1/modules/fin/invoices/service.py

@@ -9,7 +9,6 @@ from api.v1.modules.crm.accounts.models import Account
 from api.v1.modules.crm.quotes.models import Quote, QuoteItem
 from api.v1.modules.ops.shipments.models import Shipment
 
-from ..concepts.models import Concept
 from .dto import (
     InvoiceClientReviewInput,
     InvoiceCreate,
@@ -332,50 +331,9 @@ def _get_item(db, item_id, tenant_id, company_id) -> InvoiceItem:
     return obj
 
 
-# Claves del SAT que la partida hereda del concepto del catálogo cuando no se envían.
-_CONCEPT_INHERITED_FIELDS = ("product_service_id", "unit_of_measure_id", "tax_object_id")
-
-
-def _resolve_item_concept(db, data: dict, tenant_id, company_id) -> None:
-    """Completa la partida a partir del concepto del catálogo.
-
-    Hereda dos cosas cuando el cliente no las manda:
-
-    - ``concept``: el PDF de la factura sigue leyendo esa columna de texto libre, así
-      que ahí va la descripción del concepto (recortada al largo de la columna).
-    - Las claves fiscales (``product_service_id``, ``unit_of_measure_id``,
-      ``tax_object_id``): sin ellas la partida capturada por catálogo quedaría
-      incompleta para el CFDI. Lo que el cliente sí envía manda sobre el catálogo,
-      para poder facturar una partida con una unidad distinta a la del concepto.
-    """
-    concept_id = data.get("concept_id")
-    if concept_id is not None:
-        catalog_concept = db.query(Concept).filter(
-            Concept.id == concept_id, Concept.tenant_id == tenant_id,
-            Concept.company_id == company_id, Concept.deleted_at.is_(None),
-        ).first()
-        if not catalog_concept:
-            raise HTTPException(
-                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-                detail="El concepto del catálogo no existe en esta empresa",
-            )
-        if not data.get("concept"):
-            data["concept"] = catalog_concept.description[:60]
-        for field in _CONCEPT_INHERITED_FIELDS:
-            if data.get(field) is None:
-                data[field] = getattr(catalog_concept, field)
-    if not data.get("concept"):
-        raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-            detail="La partida requiere un concepto o una referencia al catálogo de conceptos",
-        )
-
-
 def create_item(db, payload: InvoiceItemCreate, tenant_id, company_id) -> InvoiceItem:
     invoice = get_invoice(db, payload.invoice_id, tenant_id, company_id)
-    data = payload.model_dump()
-    _resolve_item_concept(db, data, tenant_id, company_id)
-    item = InvoiceItem(**data, tenant_id=tenant_id, company_id=company_id)
+    item = InvoiceItem(**payload.model_dump(), tenant_id=tenant_id, company_id=company_id)
     db.add(item)
     db.flush()
     _recompute(db, invoice)
@@ -386,12 +344,7 @@ def create_item(db, payload: InvoiceItemCreate, tenant_id, company_id) -> Invoic
 
 def update_item(db, item_id, payload: InvoiceItemUpdate, tenant_id, company_id) -> InvoiceItem:
     item = _get_item(db, item_id, tenant_id, company_id)
-    data = payload.model_dump(exclude_unset=True)
-    # Cambiar el concepto del catálogo revalida la referencia y vuelve a heredar
-    # descripción y claves fiscales del concepto nuevo.
-    if data.get("concept_id") is not None:
-        _resolve_item_concept(db, data, tenant_id, company_id)
-    for f, v in data.items():
+    for f, v in payload.model_dump(exclude_unset=True).items():
         setattr(item, f, v)
     db.flush()
     _recompute(db, get_invoice(db, item.invoice_id, tenant_id, company_id))

backend/api/v1/modules/fin/issuer/__init__.py

@@ -1 +0,0 @@
-"""Datos fiscales del emisor por empresa."""

backend/api/v1/modules/fin/issuer/dto.py

@@ -1,60 +0,0 @@
-"""Esquemas de los datos fiscales del emisor."""
-
-import re
-from datetime import datetime
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator
-
-from ..catalogs.dto import TaxRegimeResponse
-
-# RFC de persona moral (3 letras) o física (4 letras) + fecha + homoclave.
-RFC_PATTERN = re.compile(r"^[A-ZÑ&]{3,4}\d{6}[A-Z0-9]{3}$")
-ZIP_PATTERN = re.compile(r"^\d{5}$")
-
-
-class IssuerSettingsInput(BaseModel):
-    """Alta o actualización de los datos fiscales del emisor."""
-
-    legal_name: str = Field(..., min_length=1, max_length=255, description="Razón social")
-    rfc: str = Field(..., max_length=13, description="RFC del emisor")
-    tax_regime_id: int = Field(..., description="Régimen fiscal (c_RegimenFiscal)")
-    zip_code: str | None = Field(None, max_length=5, description="CP del lugar de expedición")
-
-    # mode="before": la normalización corre antes que el max_length del campo, para que
-    # un RFC con espacios de sobra no se rechace por longitud antes de limpiarlo.
-    @field_validator("rfc", mode="before")
-    @classmethod
-    def _validate_rfc(cls, value: str) -> str:
-        """Normaliza a mayúsculas sin espacios y valida el formato oficial del RFC."""
-        if not isinstance(value, str):
-            raise ValueError("El RFC debe ser texto")
-        normalized = value.replace(" ", "").replace("-", "").upper()
-        if not RFC_PATTERN.match(normalized):
-            raise ValueError("El RFC no tiene un formato válido (ej. XAXX010101000)")
-        return normalized
-
-    @field_validator("zip_code")
-    @classmethod
-    def _validate_zip(cls, value: str | None) -> str | None:
-        if value is None or value == "":
-            return None
-        normalized = value.strip()
-        if not ZIP_PATTERN.match(normalized):
-            raise ValueError("El código postal debe tener 5 dígitos")
-        return normalized
-
-
-class IssuerSettingsResponse(BaseModel):
-    model_config = ConfigDict(from_attributes=True)
-
-    id: int
-    tenant_id: int
-    company_id: int
-    legal_name: str
-    rfc: str
-    tax_regime_id: int
-    tax_regime: TaxRegimeResponse | None = None
-    zip_code: str | None = None
-    updated_by: str | None = None
-    created_at: datetime
-    updated_at: datetime

backend/api/v1/modules/fin/issuer/models.py

@@ -1,42 +0,0 @@
-"""Datos fiscales del emisor — ``fin.issuer_settings``.
-
-Es la identidad fiscal con la que la empresa emite CFDI: razón social, RFC, régimen
-fiscal y código postal del lugar de expedición. Hay **una sola configuración vigente
-por empresa**, garantizada con un índice único parcial.
-"""
-
-from sqlalchemy import ForeignKey, Index, Integer, String, text
-from sqlalchemy.orm import Mapped, mapped_column, relationship
-
-from api.v1.common.base_models import TenantScopedMixin, TimestampMixin
-from core.database import Base
-
-from ..catalogs.models import TaxRegime  # noqa: F401  (resuelve la relación)
-
-_ALIVE = text("deleted_at IS NULL")
-
-
-class IssuerSettings(Base, TenantScopedMixin, TimestampMixin):
-    """Configuración fiscal del emisor de la empresa."""
-
-    __tablename__ = "issuer_settings"
-    __table_args__ = (
-        Index(
-            "uq_fin_issuer_settings_company",
-            "tenant_id", "company_id",
-            unique=True, postgresql_where=_ALIVE, sqlite_where=_ALIVE,
-        ),
-        {"schema": "fin"},
-    )
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
-    legal_name: Mapped[str] = mapped_column(String(255), nullable=False)  # razón social
-    rfc: Mapped[str] = mapped_column(String(13), nullable=False)
-    tax_regime_id: Mapped[int] = mapped_column(
-        Integer, ForeignKey("sat.tax_regimes.id"), nullable=False, index=True
-    )
-    # CP del lugar de expedición del comprobante
-    zip_code: Mapped[str | None] = mapped_column(String(5), nullable=True)
-    updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
-
-    tax_regime: Mapped["TaxRegime"] = relationship("TaxRegime", lazy="selectin")

backend/api/v1/modules/fin/issuer/routes.py

@@ -1,48 +0,0 @@
-"""Endpoints de los datos fiscales del emisor (una configuración por empresa)."""
-
-from fastapi import APIRouter, Depends, Query
-from sqlalchemy.orm import Session
-
-from api.v1.modules.core.permissions.dependencies import PermissionChecker
-from core.database import get_core_db
-from core.security import get_current_user
-
-from . import service
-from .dto import IssuerSettingsInput, IssuerSettingsResponse
-
-router = APIRouter()
-
-
-@router.get(
-    "/settings/issuer",
-    response_model=IssuerSettingsResponse,
-    dependencies=[Depends(PermissionChecker(["fin.settings.view"]))],
-)
-def get_issuer_settings(
-    company_id: int = Query(..., description="Company ID"),
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """Devuelve 404 mientras la empresa no haya capturado sus datos fiscales."""
-    return service.get_issuer_settings(db, current_user["tenant_id"], company_id)
-
-
-@router.put(
-    "/settings/issuer",
-    response_model=IssuerSettingsResponse,
-    dependencies=[Depends(PermissionChecker(["fin.settings.edit"]))],
-)
-def save_issuer_settings(
-    payload: IssuerSettingsInput,
-    company_id: int = Query(..., description="Company ID"),
-    current_user: dict = Depends(get_current_user),
-    db: Session = Depends(get_core_db),
-):
-    """Alta o actualización (upsert) de los datos fiscales del emisor."""
-    return service.save_issuer_settings(
-        db,
-        payload,
-        current_user["tenant_id"],
-        company_id,
-        current_user.get("sub") or current_user.get("id"),
-    )

backend/api/v1/modules/fin/issuer/service.py

@@ -1,58 +0,0 @@
-"""Lógica de los datos fiscales del emisor.
-
-Una empresa tiene, a lo más, una configuración vigente: el guardado es un upsert, no
-un alta que pueda duplicar filas.
-"""
-
-from fastapi import HTTPException, status
-from sqlalchemy.orm import Session
-
-from ..catalogs.models import TaxRegime
-from .dto import IssuerSettingsInput
-from .models import IssuerSettings
-
-
-def _find(db: Session, tenant_id: int, company_id: int) -> IssuerSettings | None:
-    return db.query(IssuerSettings).filter(
-        IssuerSettings.tenant_id == tenant_id,
-        IssuerSettings.company_id == company_id,
-        IssuerSettings.deleted_at.is_(None),
-    ).first()
-
-
-def get_issuer_settings(db: Session, tenant_id: int, company_id: int) -> IssuerSettings:
-    obj = _find(db, tenant_id, company_id)
-    if not obj:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail="La empresa aún no tiene datos fiscales del emisor configurados",
-        )
-    return obj
-
-
-def save_issuer_settings(
-    db: Session,
-    payload: IssuerSettingsInput,
-    tenant_id: int,
-    company_id: int,
-    user_id: str | None = None,
-) -> IssuerSettings:
-    """Crea la configuración la primera vez y la actualiza en adelante."""
-    if db.query(TaxRegime.id).filter(TaxRegime.id == payload.tax_regime_id).first() is None:
-        raise HTTPException(
-            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
-            detail="El régimen fiscal indicado no existe en el catálogo del SAT",
-        )
-
-    obj = _find(db, tenant_id, company_id)
-    data = payload.model_dump()
-    if obj is None:
-        obj = IssuerSettings(**data, tenant_id=tenant_id, company_id=company_id, updated_by=user_id)
-        db.add(obj)
-    else:
-        for field, value in data.items():
-            setattr(obj, field, value)
-        obj.updated_by = user_id
-    db.commit()
-    db.refresh(obj)
-    return obj

backend/api/v1/modules/fin/permissions.py

@@ -3,7 +3,7 @@
 from api.v1.modules.core.permissions.registry import registry
 
 MODULE = "fin"
-_ENTITIES = [("invoice", "facturas"), ("payment", "pagos"), ("concept", "conceptos")]
+_ENTITIES = [("invoice", "facturas"), ("payment", "pagos")]
 _ACTIONS = [("view", "Ver"), ("create", "Crear"), ("edit", "Editar"), ("delete", "Eliminar")]
 
 
@@ -12,11 +12,6 @@ def register_permissions() -> None:
     for entity, label in _ENTITIES:
         for action, verb in _ACTIONS:
             registry.register(code=f"{MODULE}.{entity}.{action}", description=f"{verb} {label}", module=MODULE, action=action)
-    # Datos fiscales del emisor: es configuración de la empresa, no una entidad con CRUD,
-    # así que solo tiene ver/editar. Los catálogos del SAT no llevan permiso propio:
-    # son globales y de solo lectura, basta con fin.access.
-    registry.register(code=f"{MODULE}.settings.view", description="Ver datos fiscales del emisor", module=MODULE, action="view")
-    registry.register(code=f"{MODULE}.settings.edit", description="Editar datos fiscales del emisor", module=MODULE, action="edit")
 
 
 register_permissions()

backend/api/v1/modules/fin/router.py

@@ -5,14 +5,8 @@ from fastapi import APIRouter, Depends
 from api.v1.modules.core.permissions.dependencies import PermissionChecker
 
 from . import permissions  # noqa: F401  (side-effect: registra permisos)
-from .catalogs.routes import router as catalogs_router
-from .concepts.routes import router as concepts_router
 from .invoices.routes import router as invoices_router
-from .issuer.routes import router as issuer_router
 
 # Enforcement por área/carril (R-T-07): se exige fin.access para el módulo.
 router = APIRouter(dependencies=[Depends(PermissionChecker(["fin.access"]))])
-router.include_router(catalogs_router)
-router.include_router(concepts_router)
-router.include_router(issuer_router)
 router.include_router(invoices_router)

backend/core/config.py

@@ -42,6 +42,19 @@ class Settings(BaseSettings):
     PERMISSION_CACHE_ENABLED: bool = True
     PERMISSION_CACHE_TTL_SECONDS: int = 300
 
+    # Sesión local del CRM (patrón SIWEB) — desacopla la sesión de la app del
+    # token KC de 60s. Tras SSO/login se guardan los tokens KC en valkey y se emite
+    # una sesión local firmada (HS256) con vida por inactividad (idle) y cap
+    # absoluto. Así el refresh del token KC contra el Hub solo se intenta al expirar
+    # la sesión local (no cada ~60s), lo que elimina el bucle de login.
+    #
+    # SE RESPETA la revocación central de Keycloak: si el Hub rechaza el refresh, la
+    # sesión termina (no hay re-emisión local de fallback). Flag-gated para rollback:
+    # con SESSION_STORE_ENABLED=False el comportamiento no cambia.
+    SESSION_STORE_ENABLED: bool = False
+    SESSION_IDLE_MINUTES: int = 30
+    SESSION_MAX_HOURS: int = 10
+
     # Synchronization
     SYNC_SECRET_TOKEN: str = "change-this-sync-token-in-production"
     CENTRAL_SERVER_URL: str = "http://localhost:8000/api/v1/core/help-center/sync/"

backend/core/hub_token.py

@@ -0,0 +1,67 @@
+"""
+Obtención de un access token de Keycloak VÁLIDO para llamar a la API del Hub.
+
+Con el patrón de sesión local (SIWEB) el Bearer de la app es un JWT propio (HS256)
+que el Hub NO entiende. Para las llamadas server→Hub se usa el token KC guardado en
+la sesión (valkey, vía cookie crm_sid), refrescándolo si está por expirar.
+"""
+
+import logging
+import time
+from typing import Optional
+
+import httpx
+from jose import jwt
+
+from core.config import settings
+from core import session_store
+
+logger = logging.getLogger(__name__)
+
+
+def _kc_exp_ok(token: str, leeway_seconds: int = 30) -> bool:
+    """True si el token KC no está expirado (con margen)."""
+    try:
+        claims = jwt.get_unverified_claims(token)
+        exp = claims.get("exp")
+        return isinstance(exp, (int, float)) and (int(exp) - int(time.time())) > leeway_seconds
+    except Exception:
+        return False
+
+
+async def get_hub_access_token(request) -> Optional[str]:
+    """
+    Devuelve un access token KC válido tomado de la sesión (valkey vía crm_sid),
+    refrescándolo contra el Hub si está por expirar. None si no hay sesión.
+    Best-effort: si el refresh falla, devuelve el token guardado (puede estar vencido).
+    """
+    sid = request.cookies.get("crm_sid") if request is not None else None
+    if not sid:
+        return None
+    sess = session_store.get_session(sid)
+    if not sess:
+        return None
+
+    access = sess.get("access_token")
+    refresh = sess.get("refresh_token")
+
+    if access and _kc_exp_ok(access):
+        return access
+
+    if refresh:
+        try:
+            async with httpx.AsyncClient(timeout=8.0) as client:
+                r = await client.post(
+                    f"{settings.HUB_URL}api/v1/auth/refresh",
+                    json={"refresh_token": refresh},
+                )
+            if r.status_code == 200:
+                data = r.json()
+                new_access = data.get("access_token") or access
+                session_store.update_session_tokens(sid, new_access, data.get("refresh_token") or refresh)
+                return new_access
+            logger.info("get_hub_access_token: Hub refresh devolvió %s", r.status_code)
+        except Exception as exc:
+            logger.warning("get_hub_access_token: refresh falló: %s", exc)
+
+    return access

backend/core/local_session.py

@@ -0,0 +1,94 @@
+"""
+Sesión local del CRM (patrón SIWEB).
+
+Emite y valida un JWT de sesión propio (HS256, firmado con SECRET_KEY) que
+transporta la identidad YA verificada por Keycloak/Hub. Desacopla la sesión de la
+app del token KC de 60s: la app valida esta sesión local (sin ir al Hub) durante
+su ventana de inactividad, de modo que el refresh del token KC solo se intenta al
+expirar la sesión local — no cada ~60s. Esto elimina el bucle de login.
+
+Se RESPETA la revocación central: si el Hub rechaza el refresh, la sesión termina
+(no hay re-emisión de fallback).
+
+Marcadores del token:
+  - source: "local" + crm_session: True  → distingue de tokens KC (RS256) y del
+    token dev-local (dev_local: True).
+  - sst (session start time, epoch seg)   → fija la vida ABSOLUTA máxima (cap).
+  - exp                                    → sliding por inactividad (idle); se
+    re-emite en cada refresh mientras no se supere el cap.
+
+Seguridad: es un desacople CONSCIENTE de la revocación central de KC (OWASP A07).
+Se acota con idle corto (= ssoSessionIdleTimeout) y cap absoluto
+(= ssoSessionMaxLifespan); el logout elimina la sesión de valkey.
+"""
+
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from jose import JWTError, jwt
+
+from core.config import settings
+
+# Claims de identidad que se propagan del token KC a la sesión local.
+_IDENTITY_CLAIMS = (
+    "sub", "email", "preferred_username", "username", "name",
+    "given_name", "family_name", "first_name", "last_name",
+    "tenant_id", "tenant_slug", "roles", "permissions",
+    "is_hub_admin", "avatar_url",
+)
+
+
+def _now_epoch() -> int:
+    return int(datetime.now(timezone.utc).timestamp())
+
+
+def mint_session_token(claims: Dict[str, Any], session_start: Optional[int] = None) -> str:
+    """
+    Emite un JWT de sesión local a partir de los claims (verificados) del usuario.
+    `session_start` (epoch seg) fija el inicio de sesión para el cap absoluto; si
+    no se provee, se usa el momento actual (sesión nueva).
+    """
+    now = _now_epoch()
+    sst = int(session_start) if session_start else now
+
+    payload: Dict[str, Any] = {
+        k: claims[k] for k in _IDENTITY_CLAIMS if claims.get(k) is not None
+    }
+    payload.update({
+        "source": "local",
+        "crm_session": True,
+        "sst": sst,
+        "iat": now,
+        "exp": now + settings.SESSION_IDLE_MINUTES * 60,
+    })
+    return jwt.encode(payload, settings.SECRET_KEY, algorithm="HS256")
+
+
+def verify_session_token(token: str) -> Optional[Dict[str, Any]]:
+    """
+    Valida un JWT de sesión local. Retorna los claims si es válido, no expiró por
+    inactividad y no superó el cap absoluto de vida; None en cualquier otro caso.
+    Nunca lanza (para poder encadenar con la validación contra el Hub).
+    """
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=["HS256"])
+    except JWTError:
+        return None
+
+    # Solo aceptamos tokens de sesión local del CRM (no KC, no dev-local).
+    if not payload.get("crm_session") or payload.get("source") != "local":
+        return None
+
+    # Cap absoluto de vida de sesión (independiente del sliding por idle).
+    sst = payload.get("sst")
+    if isinstance(sst, (int, float)):
+        if _now_epoch() - int(sst) > settings.SESSION_MAX_HOURS * 3600:
+            return None
+
+    return payload
+
+
+def session_start_of(payload: Dict[str, Any]) -> Optional[int]:
+    """Extrae el epoch de inicio de sesión (sst) de un payload de sesión local."""
+    sst = payload.get("sst")
+    return int(sst) if isinstance(sst, (int, float)) else None

backend/core/middleware.py

@@ -3,6 +3,7 @@ import time
 import httpx
 from datetime import datetime, timezone
 from typing import Callable, Optional
+from cachetools import TTLCache
 from fastapi import Request, Response
 from fastapi.responses import JSONResponse
 from starlette.middleware.base import BaseHTTPMiddleware
@@ -12,6 +13,11 @@ from .security import get_tenant_from_token, verify_token, get_active_system
 
 logger = logging.getLogger(__name__)
 
+# Caché de validación de licencia por tenant (patrón SIWEB): evita consultar al
+# Hub en cada request. Valor: "valid" o "invalid:<mensaje>". TTL corto para que
+# los cambios de licencia se propaguen en minutos.
+_license_cache: TTLCache = TTLCache(maxsize=1000, ttl=600)
+
 
 def _normalize_text(value: str | None) -> str:
     if not value:
@@ -145,6 +151,18 @@ class LicenseValidationMiddleware(BaseHTTPMiddleware):
         
         token = auth_header.split(" ")[1]
 
+        # Sesión local del CRM (patrón SIWEB): el Bearer es un JWT HS256 propio que
+        # el Hub NO entiende. No se le reenvía: la licencia se valida con el token KC
+        # guardado en valkey y se cachea por tenant.
+        if getattr(settings, "SESSION_STORE_ENABLED", False):
+            try:
+                from core.local_session import verify_session_token
+                local_claims = verify_session_token(token)
+            except Exception:
+                local_claims = None
+            if local_claims is not None:
+                return await self._handle_local_session_license(request, call_next, local_claims)
+
         tenant_override = request.headers.get("X-Tenant-Override")
         if not tenant_override:
             # Fallback para flujos SSO cuando el override no viaja en header.
@@ -307,6 +325,136 @@ class LicenseValidationMiddleware(BaseHTTPMiddleware):
             }
         )
 
+    async def _handle_local_session_license(self, request: Request, call_next: Callable, local_claims: dict):
+        """
+        Valida licencia para una sesión local del CRM (patrón SIWEB).
+
+        El Hub no valida el JWT HS256 local, así que se usa el token KC guardado en
+        valkey (refrescándolo si está vencido) para consultar verify-license, con
+        caché por tenant. Si el Hub no es concluyente (p. ej. su refresh falla), se
+        permite el paso: la sesión local se emitió tras un login válido (el App
+        Launcher solo ofrece apps licenciadas), evitando bloquear por un problema
+        transitorio del Hub. Los resultados concluyentes (válido/ inválido) sí se cachean.
+        """
+        from core import session_store
+
+        tenant_key = str(local_claims.get("tenant_id") or "")
+
+        cached = _license_cache.get(tenant_key) if tenant_key else None
+        if cached == "valid":
+            return await call_next(request)
+        if isinstance(cached, str) and cached.startswith("invalid:"):
+            return JSONResponse(
+                status_code=402,
+                content={"error": "LICENSE_ERROR", "message": cached[len("invalid:"):], "status_code": 402},
+            )
+
+        tenant_override = (
+            tenant_key
+            or request.cookies.get("sso_tenant_id")
+            or request.cookies.get("sso_tenant_pub")
+            or ""
+        )
+
+        sid = request.cookies.get("crm_sid")
+        sess = session_store.get_session(sid) if sid else None
+        kc_token = (sess or {}).get("access_token") or ""
+        kc_refresh = (sess or {}).get("refresh_token") or ""
+
+        async def _verify(tok: str):
+            if not tok:
+                return None
+            headers = {"Authorization": f"Bearer {tok}"}
+            if tenant_override:
+                headers["X-Tenant-Override"] = str(tenant_override)
+            try:
+                async with httpx.AsyncClient(timeout=5.0) as client:
+                    return await client.get(
+                        f"{settings.HUB_URL}api/v1/auth/verify-license", headers=headers
+                    )
+            except Exception as exc:
+                logger.warning("[license] verify-license (sesión local) error de red: %s", exc)
+                return None
+
+        resp = await _verify(kc_token)
+
+        # ¿El KC token guardado está vencido? Refrescar una vez y reintentar.
+        needs_refresh = resp is None or resp.status_code == 401
+        if not needs_refresh and resp.status_code == 200:
+            try:
+                _d = resp.json()
+            except Exception:
+                _d = {}
+            if not _d.get("valid", False) and _is_token_issue_message(
+                _d.get("message"), _d.get("detail"), _d.get("reason")
+            ):
+                needs_refresh = True
+
+        if needs_refresh and kc_refresh:
+            try:
+                async with httpx.AsyncClient(timeout=8.0) as client:
+                    rr = await client.post(
+                        f"{settings.HUB_URL}api/v1/auth/refresh",
+                        json={"refresh_token": kc_refresh},
+                    )
+                if rr.status_code == 200:
+                    nt = rr.json()
+                    kc_token = nt.get("access_token") or kc_token
+                    if sid:
+                        session_store.update_session_tokens(
+                            sid, kc_token, nt.get("refresh_token") or kc_refresh
+                        )
+                    resp = await _verify(kc_token)
+                else:
+                    logger.warning("[license] refresh KC para verify-license devolvió %s", rr.status_code)
+            except Exception as exc:
+                logger.warning("[license] refresh KC para verify-license falló: %s", exc)
+
+        if resp is not None and resp.status_code == 200:
+            try:
+                data = resp.json()
+            except Exception:
+                data = {}
+            if data.get("valid", False):
+                expires_at_str = data.get("expires_at")
+                if expires_at_str:
+                    try:
+                        expires_at = datetime.fromisoformat(expires_at_str.replace("Z", "+00:00"))
+                        if expires_at.tzinfo is None:
+                            expires_at = expires_at.replace(tzinfo=timezone.utc)
+                        if expires_at < datetime.now(timezone.utc):
+                            msg = f"La licencia venció el {expires_at.strftime('%d/%m/%Y')}. Renueva tu suscripción."
+                            if tenant_key:
+                                _license_cache[tenant_key] = f"invalid:{msg}"
+                            return JSONResponse(
+                                status_code=402,
+                                content={"error": "LICENSE_EXPIRED", "message": msg, "status_code": 402},
+                            )
+                    except (ValueError, TypeError):
+                        pass
+                if tenant_key:
+                    _license_cache[tenant_key] = "valid"
+                request.state.license_info = data
+                return await call_next(request)
+
+            message = data.get("message", "Sin licencia asignada para este tenant")
+            if not _is_token_issue_message(data.get("message"), data.get("detail"), data.get("reason")):
+                if tenant_key:
+                    _license_cache[tenant_key] = f"invalid:{message}"
+                return JSONResponse(
+                    status_code=402,
+                    content={"error": "LICENSE_ERROR", "message": message, "status_code": 402},
+                )
+
+        # No concluyente (Hub no dio 200, o el problema de token persiste porque su
+        # refresh falla): la sesión local es válida → permitir sin cachear. Evita el
+        # bucle de 401 por el bug de refresh del Hub.
+        logger.warning(
+            "[license] verify-license no concluyente para sesión local (tenant=%s) — se permite",
+            tenant_key,
+        )
+        return await call_next(request)
+
 
 class RequestLoggingMiddleware(BaseHTTPMiddleware):
     """

backend/core/security.py

@@ -47,6 +47,19 @@ async def verify_token(token: str, tenant_id_override: str = None) -> Dict[str,
     if cache_key in token_cache:
         return token_cache[cache_key]
 
+    # Sesión local del CRM (patrón SIWEB): si el token es una sesión local firmada
+    # (HS256, crm_session), validarla sin ir al Hub en cada request. Así el refresh
+    # del token KC solo se intenta al expirar la sesión local (no cada ~60s), lo que
+    # elimina el bucle de login. verify_session_token retorna None para tokens KC
+    # (RS256), así que no interfiere con el flujo normal.
+    if settings.SESSION_STORE_ENABLED:
+        from core.local_session import verify_session_token
+
+        local_claims = verify_session_token(token)
+        if local_claims is not None:
+            token_cache[cache_key] = local_claims
+            return local_claims
+
     # Shortcut para tokens de desarrollo local
     if settings.DEV_LOCAL_AUTH:
         try:
@@ -653,6 +666,20 @@ def validate_access_to_resource(
 
     tenant_id = resolve_effective_tenant_id_from_user(current_user)
 
+    # Si el usuario no trae tenant en el token (p. ej. hub_admin del workspace),
+    # resolverlo desde la compañía activa (a76.company.tenant_id). Permite operar
+    # por compañía seleccionada cuando el token no está ligado a un tenant.
+    if tenant_id is None and company_id:
+        try:
+            from sqlalchemy import text as _text
+            row = db.execute(
+                _text("SELECT tenant_id FROM a76.company WHERE id = :c"), {"c": company_id}
+            ).first()
+            if row and row[0] is not None:
+                tenant_id = int(row[0])
+        except Exception as exc:
+            logger.warning("no se pudo resolver tenant desde company_id=%s: %s", company_id, exc)
+
     # Bypass de checks de permisos: hub_admin (atestado por el Hub en /auth/me)
     # o rol local "super_admin" en la compañía (fuente de verdad: BD de a76).
     # Se reemplazó el antiguo "admin" in realm_access.roles para que la

backend/core/session_store.py

@@ -0,0 +1,111 @@
+"""
+Store de sesión en Valkey/Redis (patrón SIWEB).
+
+Guarda los tokens de Keycloak (access + refresh) FUERA del browser, indexados por
+un session_id opaco. La app usa la sesión local firmada (ver core.local_session)
+para su propia auth; los tokens KC de aquí solo se usan para llamadas al Hub
+(provisioning, my-apps, my-tenants), refrescándolos best-effort.
+
+Fail-silent: si Valkey no está disponible, las operaciones degradan a None/no-op
+y la sesión local firmada sigue sosteniendo la app.
+"""
+
+import json
+import logging
+import uuid
+from typing import Optional
+
+from core.config import settings
+
+try:
+    import redis  # type: ignore
+except Exception:  # pragma: no cover - redis es opcional en algunos entornos
+    redis = None  # type: ignore
+
+logger = logging.getLogger(__name__)
+
+_KEY_PREFIX = "crm:session:"
+_client = None
+
+
+def _get_client():
+    """Cliente Redis/Valkey compartido (perezoso). None si no está disponible."""
+    global _client
+    if redis is None:
+        return None
+    if _client is None:
+        try:
+            _client = redis.Redis.from_url(settings.VALKEY_URL, decode_responses=True)
+        except Exception as exc:
+            logger.warning("session_store_init_failed: %s", exc)
+            return None
+    return _client
+
+
+def _ttl_seconds() -> int:
+    # La sesión en valkey vive como máximo lo que la vida absoluta de la sesión.
+    return settings.SESSION_MAX_HOURS * 3600
+
+
+def create_session(access_token: str, refresh_token: str, session_start: int) -> Optional[str]:
+    """Crea una sesión con los tokens KC y devuelve el session_id (o None si Valkey no está)."""
+    client = _get_client()
+    if client is None:
+        return None
+    session_id = str(uuid.uuid4())
+    data = json.dumps({
+        "access_token": access_token,
+        "refresh_token": refresh_token or "",
+        "sst": int(session_start),
+    })
+    try:
+        client.setex(f"{_KEY_PREFIX}{session_id}", _ttl_seconds(), data)
+        return session_id
+    except Exception as exc:
+        logger.warning("session_store_create_failed: %s", exc)
+        return None
+
+
+def get_session(session_id: str) -> Optional[dict]:
+    """Devuelve {access_token, refresh_token, sst} de la sesión, o None."""
+    client = _get_client()
+    if client is None or not session_id:
+        return None
+    try:
+        raw = client.get(f"{_KEY_PREFIX}{session_id}")
+        return json.loads(raw) if raw else None
+    except Exception as exc:
+        logger.warning("session_store_get_failed: %s", exc)
+        return None
+
+
+def update_session_tokens(session_id: str, access_token: str, refresh_token: str) -> None:
+    """Actualiza los tokens KC de una sesión existente conservando su TTL y su sst."""
+    client = _get_client()
+    if client is None or not session_id:
+        return
+    try:
+        key = f"{_KEY_PREFIX}{session_id}"
+        ttl = client.ttl(key)
+        if ttl and ttl > 0:
+            existing = client.get(key)
+            sst = json.loads(existing).get("sst") if existing else None
+            data = json.dumps({
+                "access_token": access_token,
+                "refresh_token": refresh_token or "",
+                "sst": sst,
+            })
+            client.setex(key, ttl, data)
+    except Exception as exc:
+        logger.warning("session_store_update_failed: %s", exc)
+
+
+def delete_session(session_id: str) -> None:
+    """Elimina la sesión (logout). Fail-silent."""
+    client = _get_client()
+    if client is None or not session_id:
+        return
+    try:
+        client.delete(f"{_KEY_PREFIX}{session_id}")
+    except Exception as exc:
+        logger.warning("session_store_delete_failed: %s", exc)

backend/tests/conftest.py

@@ -37,13 +37,9 @@ import api.v1.modules.crm.quotes.models  # noqa: E402,F401
 import api.v1.modules.crm.service_requests.models  # noqa: E402,F401
 import api.v1.modules.crm.suppliers.models  # noqa: E402,F401
 import api.v1.modules.ops.shipments.models  # noqa: E402,F401
-import api.v1.modules.fin.catalogs.models  # noqa: E402,F401
-import api.v1.modules.fin.concepts.models  # noqa: E402,F401
-import api.v1.modules.fin.issuer.models  # noqa: E402,F401
 import api.v1.modules.fin.invoices.models  # noqa: E402,F401
-from api.v1.modules.fin.catalogs.seed_data import sync_catalogs  # noqa: E402
 
-_SCHEMA_MAP = {"crm": None, "core": None, "ops": None, "fin": None, "sat": None}
+_SCHEMA_MAP = {"crm": None, "core": None, "ops": None, "fin": None}
 
 # Tabla mínima core.tenants para resolver la FK tenant_id de las tablas crm.
 # En CI (PostgreSQL) la tabla real la crea la migración inicial del core.
@@ -79,10 +75,6 @@ def db():
     Base.metadata.create_all(engine)
     session_factory = sessionmaker(bind=engine, future=True)
     session = session_factory()
-    # Los catálogos del SAT los siembra la migración en PostgreSQL; aquí se replica
-    # con la misma función para que conceptos y emisor tengan claves que referenciar.
-    sync_catalogs(session.connection())
-    session.commit()
     try:
         yield session
     finally:

backend/tests/test_fin_sat_catalogs.py

@@ -1,444 +0,0 @@
-"""Pruebas de los catálogos del SAT, el catálogo de conceptos y los datos fiscales
-del emisor (módulo fin).
-
-Cubren: lectura de los 8 catálogos y su filtrado, que no acepten escritura, el CRUD de
-conceptos con la relación 1:1 contra c_ClaveProdServ, el aislamiento multi-tenant, el
-upsert del emisor y el amarre de las partidas de factura al catálogo de conceptos.
-
-Los RFC de las pruebas son dummies (XAXX010101000): nunca datos reales.
-"""
-from decimal import Decimal
-
-import pytest
-import sqlalchemy as sa
-from fastapi import FastAPI, HTTPException
-from fastapi.testclient import TestClient
-from pydantic import ValidationError
-
-from api.v1.modules.crm.accounts import service as accounts_service
-from api.v1.modules.crm.accounts.dto import AccountCreate, AccountUpdate
-from api.v1.modules.fin.catalogs.models import CfdiUse, ProductService, TaxObject, TaxRegime, UnitOfMeasure
-from api.v1.modules.fin.catalogs.routes import router as catalogs_router
-from api.v1.modules.fin.catalogs.seed_data import CATALOGS, sync_catalogs
-from api.v1.modules.fin.concepts import service as concepts_service
-from api.v1.modules.fin.concepts.dto import ConceptCreate, ConceptUpdate
-from api.v1.modules.fin.invoices import service as invoices_service
-from api.v1.modules.fin.invoices.dto import (
-    InvoiceCreate,
-    InvoiceItemCreate,
-    InvoiceItemResponse,
-    InvoiceItemUpdate,
-)
-from api.v1.modules.fin.issuer import service as issuer_service
-from api.v1.modules.fin.issuer.dto import IssuerSettingsInput
-from api.v1.modules.fin.issuer.models import IssuerSettings
-from core.database import get_core_db
-from core.security import get_current_user
-
-T, C = 1, 1
-OTHER_TENANT, OTHER_COMPANY = 2, 2
-RFC_DUMMY = "XAXX010101000"
-
-
-@pytest.fixture()
-def client(db):
-    """App mínima con solo el router de catálogos: evita levantar auth y permisos."""
-    app = FastAPI()
-    app.include_router(catalogs_router, prefix="/fin")
-    app.dependency_overrides[get_core_db] = lambda: db
-    app.dependency_overrides[get_current_user] = lambda: {"sub": "tester", "tenant_id": T}
-    return TestClient(app)
-
-
-def _product_service(db, code: str = "78101600") -> ProductService:
-    return db.query(ProductService).filter(ProductService.code == code).one()
-
-
-def _concept_payload(db, code: str = "FLETE-MAR", ps_code: str = "78101600") -> ConceptCreate:
-    return ConceptCreate(
-        code=code,
-        description="Flete marítimo internacional",
-        product_service_id=_product_service(db, ps_code).id,
-        unit_of_measure_id=db.query(UnitOfMeasure).filter(UnitOfMeasure.code == "E48").one().id,
-        tax_object_id=db.query(TaxObject).filter(TaxObject.code == "02").one().id,
-        unit_price=Decimal("1500.00"),
-    )
-
-
-# ---------- Catálogos del SAT: lectura ----------
-
-CATALOG_EXPECTATIONS = [
-    ("tax-regimes", 19, "601"),
-    ("taxes", 3, "002"),
-    ("payment-forms", 22, "03"),
-    ("units-of-measure", 21, "H87"),
-    ("products-services", 11, "78101500"),
-    ("voucher-types", 5, "I"),
-    ("payment-methods", 2, "PUE"),
-    ("tax-objects", 4, "02"),
-    ("cfdi-uses", 24, "G03"),
-]
-
-
-@pytest.mark.parametrize("path,expected_count,sample_code", CATALOG_EXPECTATIONS)
-def test_catalog_endpoints_return_seeded_rows(client, path, expected_count, sample_code):
-    res = client.get(f"/fin/catalogs/{path}")
-    assert res.status_code == 200
-    rows = res.json()
-    assert len(rows) == expected_count
-    assert sample_code in [r["code"] for r in rows]
-
-
-def test_catalog_search_filters_by_code_or_description(client):
-    by_code = client.get("/fin/catalogs/payment-forms", params={"search": "03"}).json()
-    assert [r["code"] for r in by_code] == ["03"]
-
-    by_description = client.get("/fin/catalogs/payment-forms", params={"search": "transferencia"}).json()
-    assert [r["code"] for r in by_description] == ["03"]
-
-    prodserv = client.get("/fin/catalogs/products-services", params={"search": "marítimo"}).json()
-    assert [r["code"] for r in prodserv] == ["78101600"]
-
-
-def test_tax_regimes_person_type_excludes_individual_only(client):
-    moral = client.get("/fin/catalogs/tax-regimes", params={"person_type": "moral"}).json()
-    codes = [r["code"] for r in moral]
-    assert "601" in codes  # General de Ley Personas Morales
-    assert "605" not in codes  # Sueldos y Salarios: solo persona física
-    assert all(r["applies_to_legal_entity"] for r in moral)
-
-    fisica = client.get("/fin/catalogs/tax-regimes", params={"person_type": "fisica"}).json()
-    fisica_codes = [r["code"] for r in fisica]
-    assert "605" in fisica_codes and "601" not in fisica_codes
-
-
-def test_products_services_limit_caps_results(client):
-    assert len(client.get("/fin/catalogs/products-services", params={"limit": 3}).json()) == 3
-    assert client.get("/fin/catalogs/products-services", params={"limit": 500}).status_code == 422
-
-
-def test_catalogs_are_read_only(client):
-    """Los catálogos del SAT no exponen métodos de escritura."""
-    for method, path in [
-        ("post", "/fin/catalogs/payment-forms"),
-        ("put", "/fin/catalogs/tax-regimes"),
-        ("patch", "/fin/catalogs/units-of-measure"),
-        ("delete", "/fin/catalogs/products-services"),
-    ]:
-        res = client.request(method.upper(), path, json={"code": "XX", "description": "Inventado"})
-        assert res.status_code == 405, f"{method.upper()} {path} no debería aceptarse"
-
-
-def _catalog_counts(db) -> dict[str, int]:
-    return {
-        table.name: db.execute(sa.select(sa.func.count()).select_from(table)).scalar()
-        for table, _ in CATALOGS
-    }
-
-
-def test_sync_catalogs_is_idempotent(db):
-    """Volver a correrla no duplica ni borra filas."""
-    before = _catalog_counts(db)
-    inserted = sync_catalogs(db.connection())  # el fixture ya sembró los catálogos
-    db.commit()
-    assert sum(inserted.values()) == 0
-    assert _catalog_counts(db) == before
-
-
-# ---------- Conceptos ----------
-
-def test_concept_crud(db):
-    created = concepts_service.create_concept(db, _concept_payload(db), T, C, "tester")
-    assert created.code == "FLETE-MAR" and created.currency == "MXN" and created.is_active
-
-    fetched = concepts_service.get_concept(db, created.id, T, C)
-    assert fetched.product_service.code == "78101600"  # catálogo resuelto sin N+1
-
-    updated = concepts_service.update_concept(
-        db, created.id, ConceptUpdate(description="Flete marítimo FCL", is_active=False), T, C, "tester"
-    )
-    assert updated.description == "Flete marítimo FCL" and updated.is_active is False
-
-    assert concepts_service.get_concepts(db, T, C, active_only=False) == [updated]
-    assert concepts_service.get_concepts(db, T, C, active_only=True) == []
-
-    concepts_service.delete_concept(db, created.id, T, C)
-    assert concepts_service.get_concepts(db, T, C) == []
-    with pytest.raises(HTTPException) as exc:
-        concepts_service.get_concept(db, created.id, T, C)
-    assert exc.value.status_code == 404
-
-
-def test_duplicate_product_service_in_same_company_conflicts(db):
-    concepts_service.create_concept(db, _concept_payload(db), T, C)
-    with pytest.raises(HTTPException) as exc:
-        concepts_service.create_concept(db, _concept_payload(db, code="OTRO-CODIGO"), T, C)
-    assert exc.value.status_code == 409
-    assert "producto/servicio" in exc.value.detail
-
-
-def test_duplicate_concept_code_in_same_company_conflicts(db):
-    concepts_service.create_concept(db, _concept_payload(db), T, C)
-    with pytest.raises(HTTPException) as exc:
-        concepts_service.create_concept(db, _concept_payload(db, ps_code="78101500"), T, C)
-    assert exc.value.status_code == 409
-    assert "clave 'FLETE-MAR'" in exc.value.detail
-
-
-def test_same_product_service_allowed_in_another_company(db):
-    concepts_service.create_concept(db, _concept_payload(db), T, C)
-    other = concepts_service.create_concept(db, _concept_payload(db), T, OTHER_COMPANY)
-    assert other.company_id == OTHER_COMPANY
-    assert other.product_service_id == _product_service(db).id
-
-
-def test_soft_deleted_concept_frees_its_product_service(db):
-    first = concepts_service.create_concept(db, _concept_payload(db), T, C)
-    concepts_service.delete_concept(db, first.id, T, C)
-    reused = concepts_service.create_concept(db, _concept_payload(db), T, C)
-    assert reused.id != first.id
-    assert reused.product_service_id == first.product_service_id
-
-
-def test_concept_is_isolated_by_tenant(db):
-    other_tenant_concept = concepts_service.create_concept(db, _concept_payload(db), OTHER_TENANT, C)
-    assert concepts_service.get_concepts(db, T, C) == []
-    with pytest.raises(HTTPException) as exc:
-        concepts_service.get_concept(db, other_tenant_concept.id, T, C)
-    assert exc.value.status_code == 404
-    with pytest.raises(HTTPException) as exc:
-        concepts_service.update_concept(
-            db, other_tenant_concept.id, ConceptUpdate(description="Ajeno"), T, C
-        )
-    assert exc.value.status_code == 404
-
-
-def test_concept_rejects_unknown_sat_key(db):
-    payload = _concept_payload(db)
-    payload.product_service_id = 999999
-    with pytest.raises(HTTPException) as exc:
-        concepts_service.create_concept(db, payload, T, C)
-    assert exc.value.status_code == 422
-
-
-# ---------- Datos fiscales del emisor ----------
-
-def _issuer_payload(db, legal_name: str = "Empresa Demo SA de CV") -> IssuerSettingsInput:
-    regime = db.query(TaxRegime).filter(TaxRegime.code == "601").one()
-    return IssuerSettingsInput(
-        legal_name=legal_name, rfc=RFC_DUMMY, tax_regime_id=regime.id, zip_code="64000"
-    )
-
-
-def test_issuer_settings_upsert_keeps_one_row_per_company(db):
-    created = issuer_service.save_issuer_settings(db, _issuer_payload(db), T, C, "tester")
-    assert created.rfc == RFC_DUMMY
-
-    updated = issuer_service.save_issuer_settings(
-        db, _issuer_payload(db, legal_name="Empresa Demo Renombrada SA de CV"), T, C, "tester"
-    )
-    assert updated.id == created.id
-    assert updated.legal_name == "Empresa Demo Renombrada SA de CV"
-
-    rows = db.query(IssuerSettings).filter(
-        IssuerSettings.tenant_id == T, IssuerSettings.company_id == C, IssuerSettings.deleted_at.is_(None)
-    ).all()
-    assert len(rows) == 1
-
-
-def test_issuer_settings_missing_returns_404(db):
-    with pytest.raises(HTTPException) as exc:
-        issuer_service.get_issuer_settings(db, T, C)
-    assert exc.value.status_code == 404
-
-
-def test_issuer_rfc_is_validated_and_normalized(db):
-    regime = db.query(TaxRegime).filter(TaxRegime.code == "601").one()
-    with pytest.raises(ValidationError):
-        IssuerSettingsInput(legal_name="Demo", rfc="RFC-INVALIDO", tax_regime_id=regime.id)
-    with pytest.raises(ValidationError):
-        IssuerSettingsInput(legal_name="Demo", rfc=RFC_DUMMY, tax_regime_id=regime.id, zip_code="123")
-
-    normalized = IssuerSettingsInput(
-        legal_name="Demo", rfc=" xaxx010101000 ", tax_regime_id=regime.id
-    )
-    assert normalized.rfc == RFC_DUMMY
-
-
-def test_issuer_rejects_unknown_tax_regime(db):
-    payload = _issuer_payload(db)
-    payload.tax_regime_id = 999999
-    with pytest.raises(HTTPException) as exc:
-        issuer_service.save_issuer_settings(db, payload, T, C)
-    assert exc.value.status_code == 422
-
-
-# ---------- Amarre con las facturas ----------
-
-def test_invoice_item_inherits_concept_description(db):
-    concept = concepts_service.create_concept(db, _concept_payload(db), T, C)
-    invoice = invoices_service.create_invoice(db, InvoiceCreate(reference="F-SAT-1"), T, C)
-    item = invoices_service.create_item(
-        db,
-        InvoiceItemCreate(invoice_id=invoice.id, concept_id=concept.id, quantity=1, unit_amount=1500),
-        T,
-        C,
-    )
-    assert item.concept == concept.description  # copiada del catálogo para el PDF
-    assert item.concept_id == concept.id
-
-    # La respuesta expone las claves fiscales: el frontend etiqueta la partida con ellas.
-    payload = InvoiceItemResponse.model_validate(item).model_dump()
-    assert payload["concept_id"] == concept.id
-    assert payload["concept"] == concept.description
-    assert {"product_service_id", "unit_of_measure_id", "tax_object_id"} <= payload.keys()
-
-    # Si el cliente sí manda el texto, se respeta tal cual.
-    explicit = invoices_service.create_item(
-        db,
-        InvoiceItemCreate(
-            invoice_id=invoice.id, concept_id=concept.id, concept="Flete a la medida", unit_amount=100
-        ),
-        T,
-        C,
-    )
-    assert explicit.concept == "Flete a la medida"
-
-
-def test_invoice_item_without_concept_or_catalog_is_rejected(db):
-    invoice = invoices_service.create_invoice(db, InvoiceCreate(reference="F-SAT-2"), T, C)
-    with pytest.raises(HTTPException) as exc:
-        invoices_service.create_item(db, InvoiceItemCreate(invoice_id=invoice.id, unit_amount=10), T, C)
-    assert exc.value.status_code == 422
-
-
-def test_invoice_item_rejects_concept_from_another_company(db):
-    concept = concepts_service.create_concept(db, _concept_payload(db), T, OTHER_COMPANY)
-    invoice = invoices_service.create_invoice(db, InvoiceCreate(reference="F-SAT-3"), T, C)
-    with pytest.raises(HTTPException) as exc:
-        invoices_service.create_item(
-            db, InvoiceItemCreate(invoice_id=invoice.id, concept_id=concept.id, unit_amount=10), T, C
-        )
-    assert exc.value.status_code == 422
-
-
-def test_invoice_item_inherits_sat_keys_from_concept(db):
-    """La partida hereda las claves fiscales del concepto para quedar completa (CFDI)."""
-    concept = concepts_service.create_concept(db, _concept_payload(db), T, C)
-    invoice = invoices_service.create_invoice(db, InvoiceCreate(reference="F-SAT-4"), T, C)
-
-    item = invoices_service.create_item(
-        db, InvoiceItemCreate(invoice_id=invoice.id, concept_id=concept.id, unit_amount=1500), T, C
-    )
-    assert item.product_service_id == concept.product_service_id
-    assert item.unit_of_measure_id == concept.unit_of_measure_id
-    assert item.tax_object_id == concept.tax_object_id
-
-
-def test_invoice_item_sat_keys_sent_by_client_win_over_concept(db):
-    """Lo que el cliente envía manda: permite facturar con otra unidad de medida."""
-    concept = concepts_service.create_concept(db, _concept_payload(db), T, C)
-    invoice = invoices_service.create_invoice(db, InvoiceCreate(reference="F-SAT-5"), T, C)
-    other_unit = db.query(UnitOfMeasure).filter(UnitOfMeasure.code == "KGM").one()
-
-    item = invoices_service.create_item(
-        db,
-        InvoiceItemCreate(
-            invoice_id=invoice.id, concept_id=concept.id, unit_of_measure_id=other_unit.id, unit_amount=10
-        ),
-        T,
-        C,
-    )
-    assert item.unit_of_measure_id == other_unit.id
-    assert item.product_service_id == concept.product_service_id  # el resto sí se hereda
-
-
-def test_changing_item_concept_reinherits_keys(db):
-    """Cambiar el concepto de una partida revalida y vuelve a heredar del nuevo."""
-    first = concepts_service.create_concept(db, _concept_payload(db), T, C)
-    second = concepts_service.create_concept(
-        db, _concept_payload(db, code="DESPACHO", ps_code="78141600"), T, C
-    )
-    invoice = invoices_service.create_invoice(db, InvoiceCreate(reference="F-SAT-6"), T, C)
-    item = invoices_service.create_item(
-        db, InvoiceItemCreate(invoice_id=invoice.id, concept_id=first.id, unit_amount=100), T, C
-    )
-
-    updated = invoices_service.update_item(
-        db, item.id, InvoiceItemUpdate(concept_id=second.id), T, C
-    )
-    assert updated.concept_id == second.id
-    assert updated.product_service_id == second.product_service_id
-    assert updated.concept == second.description
-
-
-def test_updating_item_rejects_concept_from_another_tenant(db):
-    """El PATCH valida la referencia igual que el alta: no cruza tenants."""
-    mine = concepts_service.create_concept(db, _concept_payload(db), T, C)
-    alien = concepts_service.create_concept(db, _concept_payload(db), OTHER_TENANT, C)
-    invoice = invoices_service.create_invoice(db, InvoiceCreate(reference="F-SAT-7"), T, C)
-    item = invoices_service.create_item(
-        db, InvoiceItemCreate(invoice_id=invoice.id, concept_id=mine.id, unit_amount=100), T, C
-    )
-
-    with pytest.raises(HTTPException) as exc:
-        invoices_service.update_item(db, item.id, InvoiceItemUpdate(concept_id=alien.id), T, C)
-    assert exc.value.status_code == 422
-
-
-# ---------- Claves fiscales del receptor (crm.accounts) ----------
-
-def test_account_accepts_sat_fiscal_keys(db):
-    regime = db.query(TaxRegime).filter(TaxRegime.code == "601").one()
-    cfdi_use = db.query(CfdiUse).filter(CfdiUse.code == "G03").one()
-
-    account = accounts_service.create_account(
-        db,
-        AccountCreate(name="Cliente fiscal", tax_regime_id=regime.id, cfdi_use_id=cfdi_use.id),
-        T,
-        C,
-    )
-    assert account.tax_regime_id == regime.id and account.cfdi_use_id == cfdi_use.id
-
-
-def test_account_rejects_unknown_sat_fiscal_keys(db):
-    with pytest.raises(HTTPException) as exc:
-        accounts_service.create_account(db, AccountCreate(name="Cliente malo", cfdi_use_id=999999), T, C)
-    assert exc.value.status_code == 422
-
-    account = accounts_service.create_account(db, AccountCreate(name="Cliente ok"), T, C)
-    with pytest.raises(HTTPException) as exc:
-        accounts_service.update_account(db, account.id, AccountUpdate(tax_regime_id=999999), T, C)
-    assert exc.value.status_code == 422
-
-
-def test_account_free_text_fiscal_fields_are_preserved(db):
-    """El texto libre previo se conserva: las FK lo complementan, no lo sustituyen."""
-    account = accounts_service.create_account(
-        db, AccountCreate(name="Cliente heredado", tax_regime="601", cfdi_use="G03"), T, C
-    )
-    assert account.tax_regime == "601" and account.cfdi_use == "G03"
-    assert account.tax_regime_id is None and account.cfdi_use_id is None
-
-
-def test_legacy_invoices_keep_working_without_sat_fields(db, monkeypatch):
-    """Las facturas previas, sin claves del SAT, siguen listándose y generando PDF."""
-    stored = {}
-    monkeypatch.setattr(
-        "core.storage_s3.put_object_bytes",
-        lambda key, body, content_type="": stored.update({"key": key, "len": len(body)}),
-    )
-    account = accounts_service.create_account(db, AccountCreate(name="Cliente heredado"), T, C)
-    invoice = invoices_service.create_invoice(
-        db, InvoiceCreate(reference="F-LEGACY", account_id=account.id, tax_rate=Decimal("16")), T, C
-    )
-    invoices_service.create_item(
-        db, InvoiceItemCreate(invoice_id=invoice.id, concept="flete_internacional", unit_amount=1000), T, C
-    )
-    assert invoice.voucher_type_id is None and invoice.payment_form_id is None
-
-    listed = invoices_service.get_invoices(db, T, C)
-    assert invoice.id in [i.id for i in listed]
-
-    sent = invoices_service.send_invoice(db, invoice.id, T, C)
-    assert sent.status == "enviada" and stored["len"] > 0

backend/tests/test_local_session.py

@@ -0,0 +1,74 @@
+"""
+Pruebas de la sesión local del CRM (patrón SIWEB) — core.local_session.
+
+Lógica pura (firma HS256 + claims); no requiere BD ni valkey.
+"""
+
+from datetime import datetime, timezone
+
+from jose import jwt
+
+from core.config import settings
+from core.local_session import mint_session_token, verify_session_token, session_start_of
+
+
+def _now() -> int:
+    return int(datetime.now(timezone.utc).timestamp())
+
+
+def test_round_trip_conserva_identidad():
+    claims = {
+        "sub": "kc-user-123",
+        "email": "user@example.com",
+        "tenant_id": 11,
+        "tenant_slug": "aduanasoft",
+        "is_hub_admin": True,
+    }
+    token = mint_session_token(claims)
+    out = verify_session_token(token)
+
+    assert out is not None
+    assert out["sub"] == "kc-user-123"
+    assert out["tenant_id"] == 11
+    assert out["tenant_slug"] == "aduanasoft"
+    assert out["is_hub_admin"] is True
+    assert out["source"] == "local"
+    assert out["crm_session"] is True
+    assert isinstance(out["sst"], int)
+
+
+def test_cap_absoluto_rechaza_sesion_vieja():
+    # session_start más allá del cap absoluto → verify debe rechazar aunque no expiró por idle.
+    old_start = _now() - (settings.SESSION_MAX_HOURS * 3600 + 120)
+    token = mint_session_token({"sub": "x"}, session_start=old_start)
+    assert verify_session_token(token) is None
+
+
+def test_preserva_session_start():
+    start = _now() - 60
+    token = mint_session_token({"sub": "x"}, session_start=start)
+    out = verify_session_token(token)
+    assert out is not None
+    assert session_start_of(out) == start
+
+
+def test_firma_alterada_se_rechaza():
+    token = mint_session_token({"sub": "x"})
+    # Alterar el último carácter de la firma invalida el token.
+    tampered = token[:-1] + ("A" if token[-1] != "A" else "B")
+    assert verify_session_token(tampered) is None
+
+
+def test_token_no_crm_se_rechaza():
+    # Un HS256 válido pero SIN los marcadores de sesión local no debe aceptarse.
+    other = jwt.encode(
+        {"sub": "x", "exp": _now() + 600},
+        settings.SECRET_KEY,
+        algorithm="HS256",
+    )
+    assert verify_session_token(other) is None
+
+
+def test_token_basura_se_rechaza():
+    assert verify_session_token("no-es-un-jwt") is None
+    assert verify_session_token("") is None

deploy/RUNBOOK-produccion.md

@@ -0,0 +1,162 @@
+# Runbook — Despliegue a PRODUCCIÓN · CRM Agente de Carga
+
+> **Quién ejecuta:** un operador con acceso al servidor de producción y a la base de
+> datos de prod. **Este runbook no lo ejecuta ningún agente automático.**
+> **Prerrequisito de proceso:** el PR de `feature/crm-workspace-altas-org-usuario`
+> debe estar **revisado y mergeado** a la rama que corresponda antes de desplegar.
+>
+> **Antes de empezar: respaldo.** Toma un backup de la base `crm_core` de prod
+> (`pg_dump`) y del `.env` actual. Sin respaldo verificado, no continúes.
+
+Este cambio es grande (auth/RBAC): login 100% vía Workspace/Hub, **sesión local
+(patrón SIWEB)**, gestión de compañías/usuarios/roles y provisión vía Hub. Léelo
+completo antes de tocar prod.
+
+---
+
+## 0. Alcance del cambio
+
+- **Auth:** el login deja de hablar directo con Keycloak; todo pasa por el Hub
+  (App Launcher → `/auth/sso?relay=<uuid>` → `POST {HUB_URL}/api/v1/auth/sso-exchange`).
+- **Sesión local:** cookie de sesión propia (HS256) + token KC guardado en **valkey**
+  por `crm_sid`. Requiere valkey arriba. Se controla con `SESSION_STORE_ENABLED`.
+- **RBAC/Compañías:** compañías en `a76.company` por tenant; roles por carril
+  (Ventas, Operaciones, Facturación, Consulta); permisos por módulo.
+
+**Migraciones de esquema:** este set **no** agrega tablas nuevas (usa `core.*`,
+`a76.company` y valkey). Aun así, **verifica migraciones pendientes** en prod antes
+de desplegar (paso 5). No corras migraciones a ciegas.
+
+---
+
+## 1. Prerrequisitos de infraestructura
+
+- [ ] DNS de prod (p. ej. `crm.aduanasoft.com`) apuntando al server de prod.
+- [ ] Docker + Docker Compose en el server.
+- [ ] Servicios del stack: `backend`, `frontend`, `postgres`, `valkey`, `minio`,
+      `celery_worker`, `celery_beat`.
+- [ ] **valkey** operativo (lo usan la sesión local y `hub_token`).
+- [ ] nginx + TLS (certbot) para servir app + API en el **mismo origen**.
+- [ ] Acceso al **Hub de producción** (no el de testing) y al client/realm correctos.
+
+---
+
+## 2. Variables de entorno (`.env` en el server de prod)
+
+Basado en `deploy/env.testing.example`, pero con **hosts, dominio y secretos de
+producción**. Nunca subas el `.env` con secretos al repo.
+
+```env
+# --- Seguridad ---
+ENVIRONMENT=production
+DEV_LOCAL_AUTH=false
+SECRET_KEY=<openssl rand -hex 32>
+
+# --- Sesión local (patrón SIWEB) ---
+SESSION_STORE_ENABLED=true
+SESSION_IDLE_MINUTES=30
+SESSION_MAX_HOURS=10
+VALKEY_URL=redis://valkey:6379/0
+
+# --- Workspace / Hub de PRODUCCIÓN (mismo Hub que genera el relay) ---
+WORKSPACE_URL=https://<hub-produccion>
+HUB_URL=https://<hub-produccion>
+INTERNAL_HUB_URL=https://<hub-produccion>
+VITE_HUB_URL=https://<hub-produccion>
+
+# --- Keycloak (single-realm / single-client) ---
+KEYCLOAK_URL=https://<keycloak-produccion>/kcauth
+VITE_KEYCLOAK_URL=https://<keycloak-produccion>/kcauth
+KEYCLOAK_REALM=master
+KEYCLOAK_CLIENT_ID=aduanasoft
+KEYCLOAK_CLIENT_SECRET=<secret del producto provisionado en prod>
+
+# --- Dominio del CRM (mismo origen app + API vía nginx) ---
+ORIGIN=https://<dominio-crm-produccion>
+APP_PUBLIC_URL=https://<dominio-crm-produccion>
+VITE_API_URL=https://<dominio-crm-produccion>/api/
+INTERNAL_API_URL=http://backend:8000/api/
+CORS_ORIGINS=https://<dominio-crm-produccion>
+
+# --- PostgreSQL ---
+CORE_DB_HOST=postgres
+CORE_DB_PORT=5432
+CORE_DB_NAME=crm_core
+CORE_DB_USER=<usuario>
+POSTGRES_APP_PASSWORD=<password fuerte>
+
+# --- MinIO / S3 ---
+S3_ENDPOINT_URL=http://minio:9000
+S3_ACCESS_KEY=<access>
+S3_SECRET_KEY=<secret>
+S3_BUCKET=crm
+S3_REGION=us-east-1
+S3_USE_SSL=false
+```
+
+> **Importante:** `ENVIRONMENT=production` hace que el bootstrap de permisos solo dé
+> `super_admin` al **primer** usuario (no a todos). Es el comportamiento deseado en prod.
+
+---
+
+## 3. Build del frontend — **en CI, no en el server**
+
+La VM de prod no debe compilar el frontend (el build satura RAM). Compila la imagen
+en **Jenkins/CI** y publícala al registry, o compílala en una máquina de build:
+
+```bash
+docker compose -f docker-compose.yml -f docker-compose.prod.yml build frontend
+# push al registry interno si aplica
+```
+
+El backend usa la imagen/código directamente (uvicorn sin --reload).
+
+---
+
+## 4. Despliegue
+
+```bash
+# En el server de prod, en el directorio del proyecto:
+docker compose -f docker-compose.yml -f docker-compose.prod.yml pull        # si usas registry
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+docker compose ps            # verifica que todos queden healthy
+```
+
+---
+
+## 5. Post-despliegue (datos) — **operador humano, con respaldo hecho**
+
+1. **Verificar migraciones pendientes** (si el proyecto usa Alembic u otro):
+   revisar y aplicar **solo** las que correspondan, con backup previo.
+2. **Seed base** (compañía por tenant + carriles), equivalente a `seed_crm.py`
+   (`ensure_company` + roles Ventas/Operaciones/Facturación/Consulta).
+3. **Sync de permisos** (registra el catálogo por módulo):
+
+```bash
+docker compose exec backend python -c "from api.v1.modules.core.permissions.service import PermissionService; from core.database import CoreSessionLocal; PermissionService(CoreSessionLocal()).sync_permissions()"
+```
+
+---
+
+## 6. Verificación / smoke test
+
+```bash
+curl -fsS https://<dominio-crm-produccion>/api/health && echo OK
+```
+
+- [ ] Login vía **App Launcher del Workspace** entra sin bucle.
+- [ ] El dashboard carga compañías del tenant (switcher con el tenant correcto).
+- [ ] **Usuarios**: lista carga tras refrescar; alta por invitación crea enlace.
+- [ ] **Roles y permisos**: catálogo por módulo carga; marcar un permiso lo guarda
+      (toast) y persiste al refrescar.
+- [ ] Licencia válida (sin bucle 401 / "sesión expirada").
+
+---
+
+## 7. Rollback
+
+1. `docker compose ... up -d` con la **imagen/tag anterior** del frontend/backend.
+2. Restaurar `.env` anterior si se cambió.
+3. Restaurar el backup de `crm_core` **solo** si hubo cambios de datos irreversibles.
+4. `SESSION_STORE_ENABLED=false` revierte al comportamiento previo de sesión sin
+   redeploy de código (feature-flag), como mitigación rápida.

deploy/docker-compose.testing.yml

@@ -5,11 +5,26 @@
 #   docker compose -f docker-compose.yml -f deploy/docker-compose.testing.yml up -d --build
 services:
   backend:
+    # DNS por-contenedor: el resolver del host no es alcanzable desde los contenedores;
+    # el backend debe resolver workspace.aduanasoft.com (Hub) en runtime.
+    dns:
+      - "8.8.8.8"
+      - "1.1.1.1"
     ports: !override
       - "127.0.0.1:8000:8000"
+    # Sesión local del CRM (patrón SIWEB). El backend toma su config de esta lista
+    # (no lee el .env dentro del contenedor), así que los flags van aquí. Valores
+    # desde el .env por sustitución. SESSION_STORE_ENABLED=false revierte al comportamiento previo.
+    environment:
+      - SESSION_STORE_ENABLED=${SESSION_STORE_ENABLED:-true}
+      - SESSION_IDLE_MINUTES=${SESSION_IDLE_MINUTES:-30}
+      - SESSION_MAX_HOURS=${SESSION_MAX_HOURS:-10}
     command: ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--log-level", "info"]
 
   frontend:
+    dns:
+      - "8.8.8.8"
+      - "1.1.1.1"
     build:
       context: ./frontend
       dockerfile: Dockerfile.prod
@@ -21,8 +36,11 @@ services:
         VITE_KEYCLOAK_CLIENT_ID: ${KEYCLOAK_CLIENT_ID:-aduanasoft}
     environment:
       - NODE_ENV=production
+      # El callback OIDC (/auth/callback) intercambia el código por tokens con el
+      # secret del client confidencial 'aduanasoft'. El compose base no lo pasa al frontend.
+      - KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET:-}
     volumes: !override []
-    command: !override ["pnpm", "start"]
+    command: !override ["node", "build/index.js"]
     ports: !override
       - "127.0.0.1:5173:5173"
 
@@ -31,3 +49,10 @@ services:
 
   minio:
     ports: !override []
+
+# En el server no existe el Hub local: app-hub deja de ser red externa y se crea local.
+# El CRM alcanza el Hub por su URL pública (workspace.aduanasoft.com), no por esta red.
+networks:
+  app-hub:
+    external: false
+    driver: bridge

deploy/nginx/testing.crm.aduanasoft.com.conf

@@ -29,9 +29,8 @@ server {
 
 # ---- HTTPS ----
 server {
-    listen 443 ssl;
-    listen [::]:443 ssl;
-    http2 on;
+    listen 443 ssl http2;
+    listen [::]:443 ssl http2;
     server_name testing.crm.aduanasoft.com;
 
     ssl_certificate     /etc/letsencrypt/live/testing.crm.aduanasoft.com/fullchain.pem;
@@ -50,6 +49,13 @@ server {
     # Subida de documentos (máx. 25 MB en la app) + margen
     client_max_body_size 30m;
 
+    # Buffers grandes para headers de respuesta: /auth/sso setea el JWT (fragmentado
+    # si supera ~4KB) + refresh/id_token/tenant como cookies → el header excede el
+    # buffer default de nginx (evita "upstream sent too big header" → 502).
+    proxy_buffer_size 32k;
+    proxy_buffers 16 32k;
+    proxy_busy_buffers_size 64k;
+
     gzip on;
     gzip_types text/plain text/css application/javascript application/json image/svg+xml;
     gzip_min_length 1024;

frontend/Dockerfile.prod

@@ -38,6 +38,9 @@ ENV INTERNAL_API_URL=${INTERNAL_API_URL}
 # Copiar el resto del código
 COPY . .
 
+# Subir el límite de heap de Node para el build (VM chico → evita OOM en vite build)
+ENV NODE_OPTIONS="--max-old-space-size=3072"
+
 # Construir el proyecto
 RUN pnpm run build
 
@@ -49,10 +52,8 @@ FROM node:22-alpine AS runtime
 
 WORKDIR /app
 
-RUN apk add --no-cache wget
-
-RUN npm config set strict-ssl false && \
-    npm install -g pnpm
+# Runtime SIN dependencias de red (redes restringidas): busybox ya trae wget y
+# se arranca con node directo (sin pnpm), así el runtime no toca apk/npm.
 
 # Crear usuario no-root para seguridad antes de copiar con --chown
 RUN addgroup -g 1001 -S nodejs
@@ -85,5 +86,5 @@ ENV INTERNAL_API_URL=http://backend:8000/api/
 
 ENTRYPOINT ["/entrypoint.sh"]
 
-# Ejecutar aplicación con Node.js
-CMD ["pnpm", "start"]
+# Ejecutar aplicación con Node.js (adapter-node, sin pnpm)
+CMD ["node", "build/index.js"]

frontend/src/lib/api/crm/catalogs.ts

@@ -0,0 +1,64 @@
+/**
+ * Cliente API — Catálogos de referencia del CRM (SAT/ISO + del cliente).
+ * T2026-07-081/082.
+ */
+import { api, type ApiResponse } from '$lib/api';
+
+export interface CatalogItem {
+	id: number;
+	catalog: string;
+	code: string;
+	label: string;
+	parent_catalog?: string | null;
+	parent_code?: string | null;
+	tenant_id: number | null;
+	sort_order: number;
+	is_active: boolean;
+	is_system: boolean;
+	extra?: Record<string, unknown> | null;
+}
+
+export interface CatalogMeta {
+	catalog: string;
+	label: string;
+	scope: 'global' | 'tenant';
+	is_system: boolean;
+	count: number;
+}
+
+export interface CatalogItemInput {
+	code: string;
+	label: string;
+	parent_catalog?: string | null;
+	parent_code?: string | null;
+	sort_order?: number;
+	is_active?: boolean;
+}
+
+function qp(companyId: number, extra?: Record<string, string | number | boolean | undefined>) {
+	const qs = new URLSearchParams({ company_id: String(companyId) });
+	for (const [k, v] of Object.entries(extra ?? {})) if (v !== undefined && v !== '') qs.set(k, String(v));
+	return qs.toString();
+}
+async function unwrap<T>(p: Promise<{ data?: T; error?: string }>): Promise<T> {
+	const res = await p;
+	if (res.error) throw new Error(res.error);
+	return res.data as T;
+}
+
+export const referenceCatalogsAPI = {
+	/** Metadata de todos los catálogos (para la pantalla de administración). */
+	meta: (companyId: number) => unwrap<CatalogMeta[]>(api.get(`/v1/crm/catalogs?${qp(companyId)}`)),
+	/** Opciones activas de un catálogo (global + del tenant), con dependiente opcional. */
+	list: (catalog: string, companyId: number, parentCode?: string) =>
+		unwrap<CatalogItem[]>(api.get(`/v1/crm/catalogs/${catalog}?${qp(companyId, { parent_code: parentCode })}`)),
+	/** Todas las opciones incluyendo inactivas (administración). */
+	listAll: (catalog: string, companyId: number) =>
+		unwrap<CatalogItem[]>(api.get(`/v1/crm/catalogs/${catalog}?${qp(companyId, { include_inactive: true })}`)),
+	create: (catalog: string, companyId: number, data: CatalogItemInput, scope: 'tenant' | 'global' = 'tenant') =>
+		api.post(`/v1/crm/catalogs/${catalog}?${qp(companyId, { scope })}`, data) as Promise<ApiResponse<CatalogItem>>,
+	update: (catalog: string, id: number, companyId: number, data: Partial<CatalogItemInput>) =>
+		api.patch(`/v1/crm/catalogs/${catalog}/${id}?${qp(companyId)}`, data) as Promise<ApiResponse<CatalogItem>>,
+	remove: (catalog: string, id: number, companyId: number) =>
+		api.delete(`/v1/crm/catalogs/${catalog}/${id}?${qp(companyId)}`) as Promise<ApiResponse<void>>
+};

frontend/src/lib/api/crm/commercial.ts

@@ -157,7 +157,32 @@ export const quotesAPI = {
 	reject: (id: number, companyId: number) => unwrap<Quote>(api.patch(`/v1/crm/quotes/${id}/reject?${qp(companyId)}`, {})),
 	clone: (id: number, companyId: number) => unwrap<Quote>(api.post(`/v1/crm/quotes/${id}/clone?${qp(companyId)}`, {})),
 	remove: (id: number, companyId: number) => unwrap(api.delete(`/v1/crm/quotes/${id}?${qp(companyId)}`)),
-	items: (quoteId: number, companyId: number) => unwrap<QuoteItem[]>(api.get(`/v1/crm/quotes/${quoteId}/items?${qp(companyId)}`))
+	items: (quoteId: number, companyId: number) => unwrap<QuoteItem[]>(api.get(`/v1/crm/quotes/${quoteId}/items?${qp(companyId)}`)),
+	pdfBlob: (id: number, companyId: number) => (api as any).getBlob(`/v1/crm/quotes/${id}/pdf?${qp(companyId)}`) as Promise<Blob>,
+	sendEmail: (id: number, companyId: number, body: { to?: string | null; subject?: string | null; message?: string | null }) =>
+		unwrap<{ sent_to: string; reference: string }>(api.post(`/v1/crm/quotes/${id}/send-email?${qp(companyId)}`, body))
+};
+
+// ---------- Configuración de marca del formato de cotización ----------
+export interface QuoteSettings {
+	id?: number | null;
+	emitter_name?: string | null; emitter_rfc?: string | null; emitter_address?: string | null;
+	emitter_phone?: string | null; emitter_email?: string | null; emitter_website?: string | null;
+	logo_file_key?: string | null; accent_color?: string | null; quote_prefix?: string | null;
+	default_terms?: string | null; footer_note?: string | null;
+}
+
+export const quoteSettingsAPI = {
+	get: (companyId: number) => unwrap<QuoteSettings>(api.get(`/v1/crm/quote-settings?${qp(companyId)}`)),
+	save: (companyId: number, data: QuoteSettings) => unwrap<QuoteSettings>(api.put(`/v1/crm/quote-settings?${qp(companyId)}`, data)),
+	logoUrl: (companyId: number) => unwrap<{ url: string | null }>(api.get(`/v1/crm/quote-settings/logo-url?${qp(companyId)}`)),
+	async uploadLogo(companyId: number, file: File): Promise<QuoteSettings> {
+		const fd = new FormData();
+		fd.append('file', file);
+		const res = await (api as any).request(`/v1/crm/quote-settings/logo?${qp(companyId)}`, { method: 'POST', body: fd });
+		if (res.error) throw new Error(res.error);
+		return res.data as QuoteSettings;
+	}
 };
 
 // ---------- Catálogos de referencia (Incoterms, participantes) ----------

frontend/src/lib/api/crm/rates.ts

@@ -0,0 +1,107 @@
+/**
+ * Cliente API — Módulo Tarifario (tarifarios, rutas, import Excel, costeo).
+ */
+import { api } from '$lib/api';
+
+export type RateMode = 'aereo' | 'maritimo_fcl' | 'maritimo_lcl' | 'terrestre';
+
+export interface RateBreak { from_qty: number; rate: number; }
+export interface RateLane {
+	id: number; rate_sheet_id: number;
+	origin: string | null; destination: string | null; region: string | null;
+	equipment_type: string | null; rate_unit: string | null;
+	min_charge: number | null; flat_rate: number | null; transit_days: number | null; notes: string | null;
+	breaks: RateBreak[];
+}
+export interface RateSheet {
+	id: number; supplier_id: number | null; mode: RateMode; name: string;
+	currency: string | null; valid_from: string | null; valid_to: string | null;
+	default_origin: string | null; status: string; notes: string | null;
+	source_file: string | null; created_by: string | null; updated_by: string | null;
+	created_at: string; updated_at: string; lane_count: number | null;
+}
+export type RateSheetInput = Partial<Omit<RateSheet, 'id' | 'created_at' | 'updated_at' | 'lane_count' | 'source_file' | 'created_by' | 'updated_by'>> & {
+	mode: RateMode; name: string;
+};
+
+export interface RateCharge {
+	id: number; rate_sheet_id: number | null; rate_lane_id: number | null;
+	concept: string; charge_type: string; value: number | null; condition: string | null;
+}
+export interface RateChargeInput { concept: string; charge_type: string; value?: number | null; condition?: string | null; rate_lane_id?: number | null; }
+
+export interface ImportPreviewRow { row: number; data: Record<string, unknown>; ok: boolean; warnings: string[]; errors: string[]; }
+export interface ImportPreview { mode: RateMode; total: number; valid: number; rows: ImportPreviewRow[]; columns: string[]; }
+
+export interface CostRequest {
+	mode: RateMode; origin?: string | null; destination?: string | null; on_date?: string | null;
+	gross_weight_kg?: number | null; volume_m3?: number | null; equipment_type?: string | null;
+	quantity?: number; dangerous?: boolean;
+}
+export interface CostChargeLine { concept: string; amount: number; }
+export interface CostOption {
+	rate_sheet_id: number; rate_sheet_name: string; supplier_id: number | null; currency: string | null;
+	chargeable: number | null; base_cost: number; charges: CostChargeLine[]; total_cost: number;
+	transit_days: number | null; detail: string | null;
+}
+export interface CostResult { request: CostRequest; options: CostOption[]; }
+
+function qp(companyId: number, extra?: Record<string, string | number | undefined>) {
+	const qs = new URLSearchParams({ company_id: String(companyId) });
+	for (const [k, v] of Object.entries(extra ?? {})) if (v !== undefined && v !== '') qs.set(k, String(v));
+	return qs.toString();
+}
+async function unwrap<T>(p: Promise<{ data?: T; error?: string }>): Promise<T> {
+	const res = await p;
+	if (res.error) throw new Error(res.error);
+	return res.data as T;
+}
+
+export const rateSheetsAPI = {
+	list: (companyId: number, params?: { mode?: string; supplier_id?: number }) =>
+		unwrap<RateSheet[]>(api.get(`/v1/crm/rate-sheets?${qp(companyId, params)}`)),
+	get: (id: number, companyId: number) => unwrap<RateSheet>(api.get(`/v1/crm/rate-sheets/${id}?${qp(companyId)}`)),
+	create: (data: RateSheetInput, companyId: number) => unwrap<RateSheet>(api.post(`/v1/crm/rate-sheets?${qp(companyId)}`, data)),
+	update: (id: number, data: Partial<RateSheetInput>, companyId: number) => unwrap<RateSheet>(api.patch(`/v1/crm/rate-sheets/${id}?${qp(companyId)}`, data)),
+	remove: (id: number, companyId: number) => unwrap(api.delete(`/v1/crm/rate-sheets/${id}?${qp(companyId)}`)),
+	lanes: (id: number, companyId: number) => unwrap<RateLane[]>(api.get(`/v1/crm/rate-sheets/${id}/lanes?${qp(companyId)}`)),
+	addLane: (id: number, data: Partial<RateLane>, companyId: number) => unwrap<RateLane>(api.post(`/v1/crm/rate-sheets/${id}/lanes?${qp(companyId)}`, data)),
+	removeLane: (id: number, laneId: number, companyId: number) => unwrap(api.delete(`/v1/crm/rate-sheets/${id}/lanes/${laneId}?${qp(companyId)}`)),
+	charges: (id: number, companyId: number) => unwrap<RateCharge[]>(api.get(`/v1/crm/rate-sheets/${id}/charges?${qp(companyId)}`)),
+	addCharge: (id: number, data: RateChargeInput, companyId: number) => unwrap<RateCharge>(api.post(`/v1/crm/rate-sheets/${id}/charges?${qp(companyId)}`, data)),
+	removeCharge: (id: number, chargeId: number, companyId: number) => unwrap(api.delete(`/v1/crm/rate-sheets/${id}/charges/${chargeId}?${qp(companyId)}`)),
+
+	/** Descarga la plantilla Excel del modo. */
+	async downloadTemplate(mode: RateMode, companyId: number): Promise<void> {
+		const blob = await api.getBlob(`/v1/crm/rate-sheets/template?${qp(companyId, { mode })}`);
+		const url = URL.createObjectURL(blob);
+		const a = document.createElement('a');
+		a.href = url; a.download = `plantilla_tarifario_${mode}.xlsx`;
+		document.body.appendChild(a); a.click(); a.remove();
+		URL.revokeObjectURL(url);
+	},
+
+	async importPreview(mode: RateMode, file: File, companyId: number): Promise<ImportPreview> {
+		const fd = new FormData();
+		fd.append('mode', mode); fd.append('file', file);
+		const res = await (api as any).request(`/v1/crm/rate-sheets/import/preview?${qp(companyId)}`, { method: 'POST', body: fd });
+		if (res.error) throw new Error(res.error);
+		return res.data as ImportPreview;
+	},
+
+	async importSheet(companyId: number, header: { mode: RateMode; name: string; supplier_id?: number | null; currency?: string; valid_from?: string | null; valid_to?: string | null; default_origin?: string | null }, file: File): Promise<RateSheet> {
+		const fd = new FormData();
+		fd.append('mode', header.mode); fd.append('name', header.name);
+		if (header.supplier_id != null) fd.append('supplier_id', String(header.supplier_id));
+		if (header.currency) fd.append('currency', header.currency);
+		if (header.valid_from) fd.append('valid_from', header.valid_from);
+		if (header.valid_to) fd.append('valid_to', header.valid_to);
+		if (header.default_origin) fd.append('default_origin', header.default_origin);
+		fd.append('file', file);
+		const res = await (api as any).request(`/v1/crm/rate-sheets/import?${qp(companyId)}`, { method: 'POST', body: fd });
+		if (res.error) throw new Error(res.error);
+		return res.data as RateSheet;
+	},
+
+	quote: (req: CostRequest, companyId: number) => unwrap<CostResult>(api.post(`/v1/crm/rate-quote?${qp(companyId)}`, req))
+};

frontend/src/lib/api/crm/types.ts

@@ -24,15 +24,14 @@ export interface Account {
 	status: AccountStatus;
 	commercial_classification: string | null;
 	preferred_contact_method: string | null;
+	preferred_contact_other: string | null;
 	language: string | null;
 	email: string | null;
 	phone: string | null;
 	website: string | null;
-	/** Texto libre histórico; lo que vale al timbrar son las claves del SAT de abajo. */
+	commercial_observations: string | null;
 	tax_regime: string | null;
 	cfdi_use: string | null;
-	tax_regime_id: number | null;
-	cfdi_use_id: number | null;
 	payment_method: string | null;
 	payment_form: string | null;
 	currency: string | null;
@@ -69,6 +68,7 @@ export interface Supplier {
 	person_type: string | null;
 	status: AccountStatus;
 	classifications: string[];
+	classification_other: string | null;
 	services_offered: string | null;
 	coverage: string | null;
 	countries: string[];

frontend/src/lib/api/dashboard/admin/permissions.ts

@@ -57,7 +57,9 @@ export const permissionsAPI = {
 		if (params?.action) queryParams.set('action', params.action);
 		if (params?.search) queryParams.set('search', params.search);
 		const query = queryParams.toString();
-		const response = await api.get(`/v1/core/permissions/${query ? '?' + query : ''}`);
+		// Sin slash final: la ruta backend es @router.get("") = /v1/core/permissions.
+		// Con slash FastAPI responde 307 y el cliente server-side no lo sigue.
+		const response = await api.get(`/v1/core/permissions${query ? '?' + query : ''}`);
 		return response.data;
 	},
 
@@ -65,7 +67,7 @@ export const permissionsAPI = {
 	 * Obtener un permiso por ID
 	 */
 	async getById(id: number): Promise<Permission> {
-		const response = await api.get(`/v1/core/permissions/${id}/`);
+		const response = await api.get(`/v1/core/permissions/${id}`);
 		return response.data;
 	},
 
@@ -73,7 +75,7 @@ export const permissionsAPI = {
 	 * Crear un nuevo permiso
 	 */
 	async create(data: CreatePermissionData): Promise<Permission> {
-		const response = await api.post('/v1/core/permissions/', data);
+		const response = await api.post('/v1/core/permissions', data);
 		return response.data;
 	},
 
@@ -81,7 +83,7 @@ export const permissionsAPI = {
 	 * Actualizar un permiso
 	 */
 	async update(id: number, data: UpdatePermissionData): Promise<Permission> {
-		const response = await api.put(`/v1/core/permissions/${id}/`, data);
+		const response = await api.put(`/v1/core/permissions/${id}`, data);
 		return response.data;
 	},
 
@@ -89,14 +91,14 @@ export const permissionsAPI = {
 	 * Eliminar un permiso
 	 */
 	async delete(id: number): Promise<void> {
-		await api.delete(`/v1/core/permissions/${id}/`);
+		await api.delete(`/v1/core/permissions/${id}`);
 	},
 
 	/**
 	 * Obtener módulos únicos
 	 */
 	async getModules(): Promise<string[]> {
-		const response = await api.get('/v1/core/permissions/modules/');
+		const response = await api.get('/v1/core/permissions/modules');
 		return response.data;
 	},
 
@@ -104,7 +106,7 @@ export const permissionsAPI = {
 	 * Obtener acciones únicas
 	 */
 	async getActions(): Promise<string[]> {
-		const response = await api.get('/v1/core/permissions/actions/');
+		const response = await api.get('/v1/core/permissions/actions');
 		return response.data;
 	}
 };

frontend/src/lib/api/dashboard/admin/role-permissions.ts

@@ -48,7 +48,11 @@ export const rolePermissionsAPI = {
 		companyId: number,
 		data: AssignPermissionData
 	): Promise<RolePermission> {
-		const response = await api.post(`/v1/core/permissions/roles/${roleId}/permissions?company_id=${companyId}`, data);
+		// El backend recibe permission_id como query param (no en el body).
+		const response = await api.post(
+			`/v1/core/permissions/roles/${roleId}/permissions?permission_id=${data.permission_id}&company_id=${companyId}`,
+			{}
+		);
 		return response.data;
 	},
 

frontend/src/lib/api/fin/catalogs.test.ts

@@ -1,62 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-
-const get = vi.fn();
-
-// El cliente de catálogos solo usa `api.get`; se sustituye para contar peticiones.
-vi.mock('$lib/api', () => ({ api: { get } }));
-
-const { satCatalogsAPI, clearCatalogCache } = await import('./catalogs');
-
-const COMPANY_ID = 1;
-const PAYMENT_FORMS = [
-	{ id: 1, code: '01', description: 'Efectivo', is_active: true },
-	{ id: 2, code: '03', description: 'Transferencia electrónica de fondos', is_active: true }
-];
-
-describe('satCatalogsAPI — cacheo en memoria', () => {
-	beforeEach(() => {
-		clearCatalogCache();
-		get.mockReset();
-		get.mockResolvedValue({ data: PAYMENT_FORMS, status: 200 });
-	});
-
-	it('consulta el backend la primera vez y reusa el cache después', async () => {
-		const first = await satCatalogsAPI.paymentForms(COMPANY_ID);
-		const second = await satCatalogsAPI.paymentForms(COMPANY_ID);
-
-		expect(first).toEqual(PAYMENT_FORMS);
-		expect(second).toBe(first); // misma referencia: vino del cache
-		expect(get).toHaveBeenCalledTimes(1);
-	});
-
-	it('cachea por separado cada combinación de parámetros', async () => {
-		await satCatalogsAPI.paymentForms(COMPANY_ID);
-		await satCatalogsAPI.paymentForms(COMPANY_ID, { search: 'transferencia' });
-		await satCatalogsAPI.paymentForms(COMPANY_ID, { search: 'transferencia' });
-
-		expect(get).toHaveBeenCalledTimes(2);
-	});
-
-	it('no comparte cache entre compañías', async () => {
-		await satCatalogsAPI.paymentForms(COMPANY_ID);
-		await satCatalogsAPI.paymentForms(2);
-
-		expect(get).toHaveBeenCalledTimes(2);
-	});
-
-	it('clearCatalogCache obliga a volver a consultar', async () => {
-		await satCatalogsAPI.paymentForms(COMPANY_ID);
-		clearCatalogCache();
-		await satCatalogsAPI.paymentForms(COMPANY_ID);
-
-		expect(get).toHaveBeenCalledTimes(2);
-	});
-
-	it('propaga el error del backend y no lo cachea', async () => {
-		get.mockResolvedValueOnce({ error: 'Falla del servidor', status: 500 });
-		await expect(satCatalogsAPI.taxRegimes(COMPANY_ID)).rejects.toThrow('Falla del servidor');
-
-		await satCatalogsAPI.taxRegimes(COMPANY_ID);
-		expect(get).toHaveBeenCalledTimes(2);
-	});
-});

frontend/src/lib/api/fin/catalogs.ts

@@ -1,96 +0,0 @@
-/**
- * Cliente API — Catálogos del SAT (solo lectura).
- *
- * Son catálogos fijos que publica el SAT: una vez cargados no cambian durante la
- * sesión, así que se guardan en un `Map` del módulo para no repetir la petición en
- * cada selector. No hay POST/PUT/PATCH/DELETE: el backend tampoco los expone.
- */
-import { api } from '$lib/api';
-
-export interface SatCatalogItem {
-	id: number;
-	code: string;
-	description: string;
-	is_active: boolean;
-}
-
-export interface SatTaxRegime extends SatCatalogItem {
-	applies_to_individual: boolean; // persona física
-	applies_to_legal_entity: boolean; // persona moral
-}
-
-export interface SatTax extends SatCatalogItem {
-	is_withholding: boolean;
-	is_transferred: boolean;
-	is_local: boolean;
-}
-
-/** `description` es la nota larga del SAT y puede venir vacía; el nombre corto va en `name`. */
-export interface SatUnitOfMeasure extends Omit<SatCatalogItem, 'description'> {
-	description: string | null;
-	name: string;
-	symbol: string | null;
-}
-
-export type PersonType = 'fisica' | 'moral';
-
-type CatalogParams = Record<string, string | number | boolean | undefined>;
-
-/** Cache en memoria del módulo, con la query string completa como llave. */
-const cache = new Map<string, unknown>();
-
-function buildQuery(companyId: number, params?: CatalogParams): string {
-	const qs = new URLSearchParams({ company_id: String(companyId) });
-	for (const [key, value] of Object.entries(params ?? {})) {
-		if (value !== undefined && value !== '') qs.set(key, String(value));
-	}
-	qs.sort(); // llave de cache estable sin importar el orden de los parámetros
-	return qs.toString();
-}
-
-async function fetchCatalog<T>(
-	path: string,
-	companyId: number,
-	params?: CatalogParams
-): Promise<T[]> {
-	const query = buildQuery(companyId, params);
-	const key = `${path}?${query}`;
-	const cached = cache.get(key);
-	if (cached) return cached as T[];
-
-	const res = await api.get<T[]>(`/v1/fin/catalogs/${path}?${query}`);
-	if (res.error) throw new Error(res.error);
-	const rows = res.data ?? [];
-	cache.set(key, rows);
-	return rows;
-}
-
-/** Vacía el cache; útil tras actualizar los catálogos con `sync_catalogs`. */
-export function clearCatalogCache(): void {
-	cache.clear();
-}
-
-export const satCatalogsAPI = {
-	taxRegimes: (
-		companyId: number,
-		params?: { search?: string; person_type?: PersonType; active_only?: boolean }
-	) => fetchCatalog<SatTaxRegime>('tax-regimes', companyId, params),
-	taxes: (companyId: number, params?: { search?: string; active_only?: boolean }) =>
-		fetchCatalog<SatTax>('taxes', companyId, params),
-	paymentForms: (companyId: number, params?: { search?: string; active_only?: boolean }) =>
-		fetchCatalog<SatCatalogItem>('payment-forms', companyId, params),
-	unitsOfMeasure: (companyId: number, params?: { search?: string; active_only?: boolean }) =>
-		fetchCatalog<SatUnitOfMeasure>('units-of-measure', companyId, params),
-	productsServices: (
-		companyId: number,
-		params?: { search?: string; limit?: number; active_only?: boolean }
-	) => fetchCatalog<SatCatalogItem>('products-services', companyId, params),
-	voucherTypes: (companyId: number, params?: { search?: string; active_only?: boolean }) =>
-		fetchCatalog<SatCatalogItem>('voucher-types', companyId, params),
-	paymentMethods: (companyId: number, params?: { search?: string; active_only?: boolean }) =>
-		fetchCatalog<SatCatalogItem>('payment-methods', companyId, params),
-	taxObjects: (companyId: number, params?: { search?: string; active_only?: boolean }) =>
-		fetchCatalog<SatCatalogItem>('tax-objects', companyId, params),
-	cfdiUses: (companyId: number, params?: { search?: string; active_only?: boolean }) =>
-		fetchCatalog<SatCatalogItem>('cfdi-uses', companyId, params)
-};

frontend/src/lib/api/fin/concepts.ts

@@ -1,81 +0,0 @@
-/**
- * Cliente API — Catálogo de conceptos de facturación.
- *
- * Cada concepto está ligado 1:1 a una clave de producto/servicio del SAT dentro de la
- * empresa; el backend responde 409 si la clave ya está tomada.
- */
-import { api } from '$lib/api';
-import type { SatCatalogItem, SatUnitOfMeasure } from './catalogs';
-
-export interface Concept {
-	id: number;
-	code: string;
-	description: string;
-	product_service_id: number;
-	unit_of_measure_id: number | null;
-	tax_object_id: number | null;
-	unit_price: number | null;
-	currency: string;
-	is_active: boolean;
-	notes: string | null;
-	product_service: SatCatalogItem | null;
-	unit_of_measure: SatUnitOfMeasure | null;
-	tax_object: SatCatalogItem | null;
-	tenant_id: number;
-	company_id: number;
-	created_by: string | null;
-	updated_by: string | null;
-	created_at: string;
-	updated_at: string;
-}
-
-export interface ConceptInput {
-	code: string;
-	description: string;
-	product_service_id: number;
-	unit_of_measure_id?: number | null;
-	tax_object_id?: number | null;
-	unit_price?: number | null;
-	currency?: string;
-	is_active?: boolean;
-	notes?: string | null;
-}
-
-export const conceptsAPI = {
-	async list(
-		companyId: number,
-		params?: { search?: string; active_only?: boolean; product_service_id?: number }
-	): Promise<Concept[]> {
-		const qs = new URLSearchParams({ company_id: String(companyId) });
-		if (params?.search) qs.set('search', params.search);
-		if (params?.active_only !== undefined) qs.set('active_only', String(params.active_only));
-		if (params?.product_service_id !== undefined)
-			qs.set('product_service_id', String(params.product_service_id));
-		const res = await api.get<Concept[]>(`/v1/fin/concepts?${qs}`);
-		if (res.error) throw new Error(res.error);
-		return res.data!;
-	},
-
-	async get(id: number, companyId: number): Promise<Concept> {
-		const res = await api.get<Concept>(`/v1/fin/concepts/${id}?company_id=${companyId}`);
-		if (res.error) throw new Error(res.error);
-		return res.data!;
-	},
-
-	async create(data: ConceptInput, companyId: number): Promise<Concept> {
-		const res = await api.post<Concept>(`/v1/fin/concepts?company_id=${companyId}`, data);
-		if (res.error) throw new Error(res.error);
-		return res.data!;
-	},
-
-	async update(id: number, data: Partial<ConceptInput>, companyId: number): Promise<Concept> {
-		const res = await api.patch<Concept>(`/v1/fin/concepts/${id}?company_id=${companyId}`, data);
-		if (res.error) throw new Error(res.error);
-		return res.data!;
-	},
-
-	async remove(id: number, companyId: number): Promise<void> {
-		const res = await api.delete(`/v1/fin/concepts/${id}?company_id=${companyId}`);
-		if (res.error) throw new Error(res.error);
-	}
-};

frontend/src/lib/api/fin/index.ts

@@ -3,10 +3,6 @@
  */
 import { api } from '$lib/api';
 
-export * from './catalogs';
-export * from './concepts';
-export * from './issuer';
-
 export type InvoiceStatus = 'borrador' | 'emitida' | 'enviada' | 'en_revision_cliente' | 'pagada' | 'cancelada';
 
 export interface Invoice {
@@ -37,11 +33,6 @@ export interface Invoice {
 	owner_user_id: string | null;
 	created_by: string | null;
 	updated_by: string | null;
-	// Claves fiscales del CFDI (catálogos SAT); nulas mientras no se capturen.
-	voucher_type_id: number | null;
-	payment_form_id: number | null;
-	payment_method_id: number | null;
-	expedition_zip_code: string | null;
 	tenant_id: number;
 	company_id: number;
 	created_at: string;
@@ -52,26 +43,17 @@ export type InvoiceInput = Partial<Omit<Invoice, 'id' | 'status' | 'subtotal' |
 export interface InvoiceItem {
 	id: number;
 	invoice_id: number;
-	/** Texto libre que consume el PDF; se hereda del catálogo cuando hay `concept_id`. */
 	concept: string;
 	description: string | null;
 	quantity: number;
 	unit_amount: number;
 	line_total: number;
-	// Claves fiscales de la partida (catálogo de conceptos y catálogos SAT).
-	concept_id: number | null;
-	product_service_id: number | null;
-	unit_of_measure_id: number | null;
-	tax_object_id: number | null;
 	tenant_id: number;
 	company_id: number;
 }
-/**
- * `concept` es opcional cuando se envía `concept_id`: el backend copia ahí la
- * descripción del concepto del catálogo. Sin ninguno de los dos responde 422.
- */
 export type InvoiceItemInput = Partial<Omit<InvoiceItem, 'id' | 'line_total' | 'tenant_id' | 'company_id'>> & {
 	invoice_id: number;
+	concept: string;
 };
 
 export interface Payment {

frontend/src/lib/api/fin/issuer.ts

@@ -1,51 +0,0 @@
-/**
- * Cliente API — Datos fiscales del emisor (una configuración por empresa).
- */
-import { api } from '$lib/api';
-import type { SatTaxRegime } from './catalogs';
-
-/** RFC de persona moral (3 letras) o física (4 letras) + fecha + homoclave. */
-export const RFC_REGEX = /^[A-ZÑ&]{3,4}\d{6}[A-Z0-9]{3}$/;
-
-export interface IssuerSettings {
-	id: number;
-	tenant_id: number;
-	company_id: number;
-	legal_name: string;
-	rfc: string;
-	tax_regime_id: number;
-	tax_regime: SatTaxRegime | null;
-	zip_code: string | null;
-	updated_by: string | null;
-	created_at: string;
-	updated_at: string;
-}
-
-export interface IssuerSettingsInput {
-	legal_name: string;
-	rfc: string;
-	tax_regime_id: number;
-	zip_code?: string | null;
-}
-
-export const issuerAPI = {
-	/**
-	 * Devuelve `null` cuando la empresa todavía no captura sus datos fiscales: el
-	 * backend responde 404 y la pantalla debe abrirse en modo alta, no en error.
-	 */
-	async get(companyId: number): Promise<IssuerSettings | null> {
-		const res = await api.get<IssuerSettings>(`/v1/fin/settings/issuer?company_id=${companyId}`);
-		if (res.status === 404) return null;
-		if (res.error) throw new Error(res.error);
-		return res.data!;
-	},
-
-	async save(data: IssuerSettingsInput, companyId: number): Promise<IssuerSettings> {
-		const res = await api.put<IssuerSettings>(
-			`/v1/fin/settings/issuer?company_id=${companyId}`,
-			data
-		);
-		if (res.error) throw new Error(res.error);
-		return res.data!;
-	}
-};

frontend/src/lib/auth.ts

@@ -407,10 +407,12 @@ export const initAuth = async (): Promise<boolean> => {
 			return true;
 		}
 
-		// Sin token local, intentar Keycloak JS (flujo SSO)
-		const authenticated = await initKeycloak();
+		// Sin token local: no hay sesión en el cliente. El login entra SIEMPRE por
+		// el App Launcher del Workspace (relay → /auth/sso → Hub /sso-exchange);
+		// el CRM NO inicializa Keycloak en el browser. Si no hay token, el layout
+		// del servidor reenvía al Workspace.
 		authStore.setLoading(false);
-		return authenticated;
+		return false;
 	} catch (err) {
 		console.error('[auth] Error en initAuth:', err);
 		authStore.setLoading(false);

frontend/src/lib/components/crm/AccountFields.svelte

@@ -1,48 +1,23 @@
 <script lang="ts">
+	import { onMount } from 'svelte';
 	import type { AccountInput } from '$lib/api/crm';
-	import { satCatalogsAPI, type SatCatalogItem, type SatTaxRegime } from '$lib/api/fin';
-	import {
-		ACCOUNT_TYPES, ACCOUNT_STATUS, RECORD_TYPES, PERSON_TYPES,
-		COMMERCIAL_CLASSIFICATION, CONTACT_METHODS
-	} from '$lib/components/crm/format';
-	import { toast } from 'svelte-sonner';
+	import { ACCOUNT_TYPES } from '$lib/components/crm/format';
+	import { crmCatalogs } from '$lib/stores/crm-catalogs.svelte';
 
 	// `form` es un objeto reactivo del padre; se mutan sus propiedades vía bind:value.
-	// `companyId` solo se usa para consultar los catálogos del SAT del receptor.
-	let { form = $bindable(), tab, companyId = null }: { form: AccountInput; tab: string; companyId?: number | null } = $props();
-
-	let taxRegimes = $state<SatTaxRegime[]>([]);
-	let cfdiUses = $state<SatCatalogItem[]>([]);
-
-	// El régimen se acota al tipo de persona de la cuenta: una persona física no puede
-	// declararse en el 601 y viceversa. Sin tipo de persona se ofrecen todos.
-	const regimesForPersonType = $derived(
-		form.person_type === 'fisica'
-			? taxRegimes.filter((r) => r.applies_to_individual)
-			: form.person_type === 'moral'
-				? taxRegimes.filter((r) => r.applies_to_legal_entity)
-				: taxRegimes
-	);
-
-	$effect(() => {
-		const cid = companyId;
-		if (!cid || tab !== 'fiscal') return;
-		void loadCatalogs(cid);
-	});
-
-	async function loadCatalogs(cid: number) {
-		try {
-			[taxRegimes, cfdiUses] = await Promise.all([
-				satCatalogsAPI.taxRegimes(cid),
-				satCatalogsAPI.cfdiUses(cid)
-			]);
-		} catch (e) {
-			toast.error(e instanceof Error ? e.message : 'No se pudieron cargar los catálogos del SAT');
-		}
-	}
+	let { form = $bindable(), tab }: { form: AccountInput; tab: string } = $props();
 
 	const inputCls =
 		'rounded-md border bg-transparent px-3 py-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring';
+
+	// Catálogos que usa este formulario (se precargan; los selects se llenan solos).
+	onMount(() => {
+		void crmCatalogs.preload([
+			'tipo_registro', 'tipo_persona', 'estatus', 'giro', 'clasificacion_cliente',
+			'medio_contacto', 'idioma', 'regimen_fiscal', 'uso_cfdi', 'metodo_pago',
+			'forma_pago', 'moneda'
+		]);
+	});
 </script>
 
 {#if tab === 'generales'}
@@ -51,46 +26,32 @@
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Nombre comercial</span><input class={inputCls} bind:value={form.trade_name} /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">RFC</span><input class="font-mono {inputCls}" maxlength="13" bind:value={form.rfc} /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">CURP</span><input class="font-mono {inputCls}" maxlength="18" bind:value={form.curp} /></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Tipo de registro</span><select class={inputCls} bind:value={form.record_type}>{#each RECORD_TYPES as r (r.value)}<option value={r.value}>{r.label}</option>{/each}</select></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Tipo de persona</span><select class={inputCls} bind:value={form.person_type}><option value={undefined}>—</option>{#each PERSON_TYPES as p (p.value)}<option value={p.value}>{p.label}</option>{/each}</select></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Giro / Industria</span><input class={inputCls} bind:value={form.industry} /></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Tipo de registro</span><select class={inputCls} bind:value={form.record_type}>{#each crmCatalogs.options('tipo_registro') as r (r.value)}<option value={r.value}>{r.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Tipo de persona</span><select class={inputCls} bind:value={form.person_type}><option value={undefined}>—</option>{#each crmCatalogs.options('tipo_persona') as p (p.value)}<option value={p.value}>{p.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Giro / Industria</span><select class={inputCls} bind:value={form.industry}><option value={undefined}>—</option>{#each crmCatalogs.options('giro') as g (g.value)}<option value={g.value}>{g.label}</option>{/each}</select></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Tipo operativo</span><select class={inputCls} bind:value={form.account_type}><option value={undefined}>—</option>{#each ACCOUNT_TYPES as t (t.value)}<option value={t.value}>{t.label}</option>{/each}</select></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Estatus</span><select class={inputCls} bind:value={form.status}>{#each ACCOUNT_STATUS as s (s.value)}<option value={s.value}>{s.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Estatus</span><select class={inputCls} bind:value={form.status}>{#each crmCatalogs.options('estatus') as s (s.value)}<option value={s.value}>{s.label}</option>{/each}</select></label>
 	</div>
 {:else if tab === 'comercial'}
 	<div class="grid gap-4 sm:grid-cols-2">
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Clasificación</span><select class={inputCls} bind:value={form.commercial_classification}><option value={undefined}>—</option>{#each COMMERCIAL_CLASSIFICATION as c (c.value)}<option value={c.value}>{c.label}</option>{/each}</select></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Medio de contacto preferido</span><select class={inputCls} bind:value={form.preferred_contact_method}><option value={undefined}>—</option>{#each CONTACT_METHODS as m (m.value)}<option value={m.value}>{m.label}</option>{/each}</select></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Idioma</span><input class={inputCls} bind:value={form.language} /></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Clasificación del cliente</span><select class={inputCls} bind:value={form.commercial_classification}><option value={undefined}>—</option>{#each crmCatalogs.options('clasificacion_cliente') as c (c.value)}<option value={c.value}>{c.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Medio de contacto preferido</span><select class={inputCls} bind:value={form.preferred_contact_method}><option value={undefined}>—</option>{#each crmCatalogs.options('medio_contacto') as m (m.value)}<option value={m.value}>{m.label}</option>{/each}</select></label>
+		{#if form.preferred_contact_method === 'otro'}
+			<label class="flex flex-col gap-1 text-sm sm:col-span-2"><span class="font-medium">Especifica el medio de contacto</span><input class={inputCls} bind:value={form.preferred_contact_other} placeholder="Indica cuál" /></label>
+		{/if}
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Idioma</span><select class={inputCls} bind:value={form.language}><option value={undefined}>—</option>{#each crmCatalogs.options('idioma') as i (i.value)}<option value={i.value}>{i.label}</option>{/each}</select></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Email</span><input type="email" class={inputCls} bind:value={form.email} /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Teléfono</span><input class={inputCls} bind:value={form.phone} /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Sitio web</span><input class={inputCls} bind:value={form.website} /></label>
+		<label class="flex flex-col gap-1 text-sm sm:col-span-2"><span class="font-medium">Observaciones generales</span><textarea rows="3" class={inputCls} bind:value={form.commercial_observations}></textarea></label>
 	</div>
 {:else if tab === 'fiscal'}
 	<div class="grid gap-4 sm:grid-cols-2">
-		<label class="flex flex-col gap-1 text-sm">
-			<span class="font-medium">Régimen fiscal</span>
-			<select class={inputCls} bind:value={form.tax_regime_id}>
-				<option value={null}>Sin especificar</option>
-				{#each regimesForPersonType as r (r.id)}<option value={r.id}>{r.code} — {r.description}</option>{/each}
-			</select>
-			{#if !form.tax_regime_id && form.tax_regime}
-				<span class="text-xs text-muted-foreground">Capturado antes como texto: «{form.tax_regime}». Elige la clave del SAT que corresponde.</span>
-			{/if}
-		</label>
-		<label class="flex flex-col gap-1 text-sm">
-			<span class="font-medium">Uso de CFDI</span>
-			<select class={inputCls} bind:value={form.cfdi_use_id}>
-				<option value={null}>Sin especificar</option>
-				{#each cfdiUses as u (u.id)}<option value={u.id}>{u.code} — {u.description}</option>{/each}
-			</select>
-			{#if !form.cfdi_use_id && form.cfdi_use}
-				<span class="text-xs text-muted-foreground">Capturado antes como texto: «{form.cfdi_use}». Elige la clave del SAT que corresponde.</span>
-			{/if}
-		</label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Método de pago</span><input class={inputCls} bind:value={form.payment_method} /></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Forma de pago</span><input class={inputCls} bind:value={form.payment_form} /></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Moneda</span><input class={inputCls} maxlength="3" bind:value={form.currency} /></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Régimen fiscal</span><select class={inputCls} bind:value={form.tax_regime}><option value={undefined}>—</option>{#each crmCatalogs.options('regimen_fiscal') as r (r.value)}<option value={r.value}>{r.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Uso de CFDI</span><select class={inputCls} bind:value={form.cfdi_use}><option value={undefined}>—</option>{#each crmCatalogs.options('uso_cfdi') as u (u.value)}<option value={u.value}>{u.value} — {u.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Método de pago</span><select class={inputCls} bind:value={form.payment_method}><option value={undefined}>—</option>{#each crmCatalogs.options('metodo_pago') as m (m.value)}<option value={m.value}>{m.value} — {m.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Forma de pago</span><select class={inputCls} bind:value={form.payment_form}><option value={undefined}>—</option>{#each crmCatalogs.options('forma_pago') as f (f.value)}<option value={f.value}>{f.value} — {f.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Moneda</span><select class={inputCls} bind:value={form.currency}><option value={undefined}>—</option>{#each crmCatalogs.options('moneda') as c (c.value)}<option value={c.value}>{c.value} — {c.label}</option>{/each}</select></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Límite de crédito</span><input type="number" min="0" step="0.01" class={inputCls} bind:value={form.credit_limit} /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Días de crédito</span><input type="number" min="0" class={inputCls} bind:value={form.credit_days} /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Patente aduanal</span><input class={inputCls} maxlength="20" bind:value={form.patente_aduanal} /></label>
@@ -98,7 +59,7 @@
 	</div>
 {:else if tab === 'observaciones'}
 	<div class="grid gap-4 sm:grid-cols-2">
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Comentarios</span><textarea rows="4" class={inputCls} bind:value={form.notes}></textarea></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Comentarios generales</span><textarea rows="4" class={inputCls} bind:value={form.notes}></textarea></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Notas internas</span><textarea rows="4" class={inputCls} bind:value={form.internal_notes}></textarea></label>
 	</div>
 {/if}

frontend/src/lib/components/crm/RelatedManager.svelte

@@ -8,10 +8,16 @@
 		addressesAPI, contactsAPI, documentsAPI,
 		type Address, type Contact, type Document, type AddressInput, type ContactInput, type DocumentInput
 	} from '$lib/api/crm';
-	import { ADDRESS_TYPES, DOC_TYPES, CONTACT_AREAS, labelOf } from '$lib/components/crm/format';
+	import { DOC_TYPES, labelOf } from '$lib/components/crm/format';
+	import { crmCatalogs } from '$lib/stores/crm-catalogs.svelte';
+	import { onMount } from 'svelte';
 	import { uploadFile, uploadUrl } from '$lib/api/uploads';
 	import { toast } from 'svelte-sonner';
 
+	onMount(() => {
+		void crmCatalogs.preload(['tipo_domicilio', 'area', 'pais']);
+	});
+
 	// Dueño de los registros relacionados y qué sección mostrar
 	let {
 		ownerType,
@@ -31,7 +37,7 @@
 	let activeModal = $state<'address' | 'contact' | 'document' | null>(null);
 	let saving = $state(false);
 
-	let addressForm = $state<AddressInput>({ address_type: 'fiscal', country: 'MX', is_primary: false });
+	let addressForm = $state<AddressInput>({ address_type: 'fiscal', country: 'MEX', is_primary: false });
 	let contactForm = $state<ContactInput>({ first_name: '' });
 	let documentForm = $state<DocumentInput>({ doc_type: 'constancia_fiscal', name: '' });
 	let uploading = $state(false);
@@ -70,6 +76,11 @@
 		if (companyId && ownerId) void load(companyId);
 	});
 
+	// Estado depende del país seleccionado (catálogo dependiente)
+	$effect(() => {
+		if (addressForm.country) void crmCatalogs.ensure('estado', addressForm.country);
+	});
+
 	async function load(cid: number) {
 		try {
 			[addresses, contacts, documents] = await Promise.all([
@@ -83,7 +94,7 @@
 	}
 
 	function openModal(kind: 'address' | 'contact' | 'document') {
-		if (kind === 'address') addressForm = { address_type: 'fiscal', country: 'MX', is_primary: false };
+		if (kind === 'address') addressForm = { address_type: 'fiscal', country: 'MEX', is_primary: false };
 		if (kind === 'contact') contactForm = { first_name: '' };
 		if (kind === 'document') documentForm = { doc_type: 'constancia_fiscal', name: '' };
 		activeModal = kind;
@@ -174,7 +185,7 @@
 						<Table.Body>
 							{#each addresses as a (a.id)}
 								<Table.Row>
-									<Table.Cell>{labelOf(ADDRESS_TYPES, a.address_type)}{#if a.is_primary}<span class="ml-1 text-[10px] text-primary">(principal)</span>{/if}</Table.Cell>
+									<Table.Cell>{crmCatalogs.label('tipo_domicilio', a.address_type)}{#if a.is_primary}<span class="ml-1 text-[10px] text-primary">(principal)</span>{/if}</Table.Cell>
 									<Table.Cell class="text-sm">{[a.street, a.ext_number, a.neighborhood].filter(Boolean).join(' ') || '—'}</Table.Cell>
 									<Table.Cell>{a.postal_code ?? '—'}</Table.Cell>
 									<Table.Cell>{[a.city, a.state].filter(Boolean).join(', ') || '—'}</Table.Cell>
@@ -204,7 +215,7 @@
 							{#each contacts as c (c.id)}
 								<Table.Row>
 									<Table.Cell class="font-medium">{c.first_name} {c.last_name ?? ''}{#if c.is_primary}<span class="ml-1 text-[10px] text-primary">(principal)</span>{/if}</Table.Cell>
-									<Table.Cell class="text-sm">{[c.job_title, labelOf(CONTACT_AREAS, c.area) !== '—' ? labelOf(CONTACT_AREAS, c.area) : null].filter(Boolean).join(' · ') || '—'}</Table.Cell>
+									<Table.Cell class="text-sm">{[c.job_title, c.area ? crmCatalogs.label('area', c.area) : null].filter(Boolean).join(' · ') || '—'}</Table.Cell>
 									<Table.Cell>{c.email ?? '—'}</Table.Cell>
 									<Table.Cell>{c.phone ?? c.mobile ?? '—'}</Table.Cell>
 									<Table.Cell class="text-right"><Button variant="ghost" size="sm" onclick={() => removeContact(c)} aria-label="Eliminar"><Trash2 class="h-4 w-4 text-destructive" /></Button></Table.Cell>
@@ -252,15 +263,15 @@
 			{#if activeModal === 'address'}
 				<h3 class="mb-4 text-base font-semibold">Nueva dirección</h3>
 				<form class="grid gap-3 sm:grid-cols-2" onsubmit={saveAddress}>
-					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Tipo</span><select class={inputCls} bind:value={addressForm.address_type}>{#each ADDRESS_TYPES as t (t.value)}<option value={t.value}>{t.label}</option>{/each}</select></label>
+					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Tipo de domicilio</span><select class={inputCls} bind:value={addressForm.address_type}>{#each crmCatalogs.options('tipo_domicilio') as t (t.value)}<option value={t.value}>{t.label}</option>{/each}</select></label>
 					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Código Postal</span><input class={inputCls} maxlength="10" bind:value={addressForm.postal_code} /></label>
 					<label class="flex flex-col gap-1 text-sm sm:col-span-2"><span class="font-medium">Calle</span><input class={inputCls} bind:value={addressForm.street} /></label>
 					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Núm. exterior</span><input class={inputCls} bind:value={addressForm.ext_number} /></label>
 					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Núm. interior</span><input class={inputCls} bind:value={addressForm.int_number} /></label>
 					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Colonia</span><input class={inputCls} bind:value={addressForm.neighborhood} /></label>
-					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Municipio</span><input class={inputCls} bind:value={addressForm.city} /></label>
-					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Estado</span><input class={inputCls} bind:value={addressForm.state} /></label>
-					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">País</span><input class={inputCls} maxlength="2" bind:value={addressForm.country} /></label>
+					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Municipio / Ciudad</span><input class={inputCls} bind:value={addressForm.city} /></label>
+					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Estado</span>{#if crmCatalogs.options('estado', addressForm.country).length > 0}<select class={inputCls} bind:value={addressForm.state}><option value={undefined}>—</option>{#each crmCatalogs.options('estado', addressForm.country) as s (s.value)}<option value={s.value}>{s.label}</option>{/each}</select>{:else}<input class={inputCls} bind:value={addressForm.state} placeholder="Estado / provincia" />{/if}</label>
+					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">País</span><select class={inputCls} bind:value={addressForm.country}><option value={undefined}>—</option>{#each crmCatalogs.options('pais') as p (p.value)}<option value={p.value}>{p.label}</option>{/each}</select></label>
 					<label class="flex flex-col gap-1 text-sm sm:col-span-2"><span class="font-medium">Referencias</span><textarea rows="2" class={inputCls} bind:value={addressForm.reference_notes}></textarea></label>
 					<label class="flex items-center gap-2 text-sm sm:col-span-2"><input type="checkbox" class="h-4 w-4 rounded border" bind:checked={addressForm.is_primary} /><span>Domicilio principal</span></label>
 					<div class="flex justify-end gap-2 sm:col-span-2"><Button type="button" variant="outline" onclick={() => (activeModal = null)}>Cancelar</Button><Button type="submit" disabled={saving}>Guardar</Button></div>
@@ -271,7 +282,7 @@
 					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Nombre *</span><input class={inputCls} bind:value={contactForm.first_name} required /></label>
 					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Apellidos</span><input class={inputCls} bind:value={contactForm.last_name} /></label>
 					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Puesto</span><input class={inputCls} bind:value={contactForm.job_title} /></label>
-					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Área</span><select class={inputCls} bind:value={contactForm.area}><option value={undefined}>—</option>{#each CONTACT_AREAS as a (a.value)}<option value={a.value}>{a.label}</option>{/each}</select></label>
+					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Área / Departamento</span><select class={inputCls} bind:value={contactForm.area}><option value={undefined}>—</option>{#each crmCatalogs.options('area') as a (a.value)}<option value={a.value}>{a.label}</option>{/each}</select></label>
 					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Email</span><input type="email" class={inputCls} bind:value={contactForm.email} /></label>
 					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Teléfono</span><input class={inputCls} bind:value={contactForm.phone} /></label>
 					<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Extensión</span><input class={inputCls} bind:value={contactForm.extension} /></label>

frontend/src/lib/components/crm/SupplierFields.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
+	import { onMount } from 'svelte';
 	import type { SupplierInput } from '$lib/api/crm';
-	import { SUPPLIER_CLASSIFICATIONS, COVERAGE, ACCOUNT_STATUS, PERSON_TYPES } from '$lib/components/crm/format';
+	import { crmCatalogs } from '$lib/stores/crm-catalogs.svelte';
 
 	// listas separadas por coma también son bindables (el padre las convierte a arreglo)
 	let {
@@ -21,6 +22,15 @@
 
 	const inputCls =
 		'rounded-md border bg-transparent px-3 py-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring';
+
+	const hasOtro = $derived((form.classifications ?? []).includes('otro'));
+
+	onMount(() => {
+		void crmCatalogs.preload([
+			'tipo_persona', 'estatus', 'clasificacion_proveedor', 'cobertura', 'moneda',
+			'regimen_fiscal', 'metodo_pago', 'forma_pago'
+		]);
+	});
 </script>
 
 {#if tab === 'generales'}
@@ -28,25 +38,28 @@
 		<label class="flex flex-col gap-1 text-sm sm:col-span-2"><span class="font-medium">Razón social *</span><input class={inputCls} bind:value={form.name} required /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Nombre comercial</span><input class={inputCls} bind:value={form.trade_name} /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">RFC</span><input class="font-mono {inputCls}" maxlength="13" bind:value={form.rfc} /></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Tipo de persona</span><select class={inputCls} bind:value={form.person_type}><option value={undefined}>—</option>{#each PERSON_TYPES as p (p.value)}<option value={p.value}>{p.label}</option>{/each}</select></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Estatus</span><select class={inputCls} bind:value={form.status}>{#each ACCOUNT_STATUS as s (s.value)}<option value={s.value}>{s.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Tipo de persona</span><select class={inputCls} bind:value={form.person_type}><option value={undefined}>—</option>{#each crmCatalogs.options('tipo_persona') as p (p.value)}<option value={p.value}>{p.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Estatus</span><select class={inputCls} bind:value={form.status}>{#each crmCatalogs.options('estatus') as s (s.value)}<option value={s.value}>{s.label}</option>{/each}</select></label>
 	</div>
 	<div class="mt-4">
-		<p class="mb-2 text-sm font-medium">Clasificación (una o varias)</p>
+		<p class="mb-2 text-sm font-medium">Clasificación del proveedor (una o varias)</p>
 		<div class="grid grid-cols-2 gap-2 sm:grid-cols-3">
-			{#each SUPPLIER_CLASSIFICATIONS as c (c.value)}
+			{#each crmCatalogs.options('clasificacion_proveedor') as c (c.value)}
 				<label class="flex items-center gap-2 text-sm"><input type="checkbox" class="h-4 w-4 rounded border" value={c.value} bind:group={form.classifications} /><span>{c.label}</span></label>
 			{/each}
 		</div>
+		{#if hasOtro}
+			<label class="mt-3 flex max-w-md flex-col gap-1 text-sm"><span class="font-medium">Especifica la clasificación "Otro"</span><input class={inputCls} bind:value={form.classification_other} placeholder="Indica cuál" /></label>
+		{/if}
 	</div>
 {:else if tab === 'comercial'}
 	<div class="grid gap-4 sm:grid-cols-2">
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Cobertura</span><select class={inputCls} bind:value={form.coverage}><option value={undefined}>—</option>{#each COVERAGE as c (c.value)}<option value={c.value}>{c.label}</option>{/each}</select></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Moneda de cotización</span><input class={inputCls} maxlength="3" bind:value={form.quote_currency} /></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Países (separados por coma)</span><input class={inputCls} bind:value={countriesStr} placeholder="MX, US, PA" /></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Puertos</span><input class={inputCls} bind:value={portsStr} placeholder="Veracruz, Manzanillo" /></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Aeropuertos</span><input class={inputCls} bind:value={airportsStr} /></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Aduanas</span><input class={inputCls} bind:value={customsStr} placeholder="Nuevo Laredo, Colombia" /></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Cobertura</span><select class={inputCls} bind:value={form.coverage}><option value={undefined}>—</option>{#each crmCatalogs.options('cobertura') as c (c.value)}<option value={c.value}>{c.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Moneda de cotización</span><select class={inputCls} bind:value={form.quote_currency}><option value={undefined}>—</option>{#each crmCatalogs.options('moneda') as m (m.value)}<option value={m.value}>{m.value} — {m.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Países donde opera (separados por coma)</span><input class={inputCls} bind:value={countriesStr} placeholder="México, Estados Unidos" /></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Puertos donde opera</span><input class={inputCls} bind:value={portsStr} placeholder="Veracruz, Manzanillo" /></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Aeropuertos donde opera</span><input class={inputCls} bind:value={airportsStr} /></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Aduanas donde opera</span><input class={inputCls} bind:value={customsStr} placeholder="Nuevo Laredo, Colombia" /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Horario de atención</span><input class={inputCls} bind:value={form.business_hours} /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Tiempo prom. de respuesta</span><input class={inputCls} bind:value={form.avg_response_time} /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Email</span><input type="email" class={inputCls} bind:value={form.email} /></label>
@@ -56,16 +69,16 @@
 	</div>
 {:else if tab === 'fiscal'}
 	<div class="grid gap-4 sm:grid-cols-2">
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Régimen fiscal</span><input class={inputCls} bind:value={form.tax_regime} /></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Método de pago</span><input class={inputCls} bind:value={form.payment_method} /></label>
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Forma de pago</span><input class={inputCls} bind:value={form.payment_form} /></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Régimen fiscal</span><select class={inputCls} bind:value={form.tax_regime}><option value={undefined}>—</option>{#each crmCatalogs.options('regimen_fiscal') as r (r.value)}<option value={r.value}>{r.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Método de pago</span><select class={inputCls} bind:value={form.payment_method}><option value={undefined}>—</option>{#each crmCatalogs.options('metodo_pago') as m (m.value)}<option value={m.value}>{m.value} — {m.label}</option>{/each}</select></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Forma de pago</span><select class={inputCls} bind:value={form.payment_form}><option value={undefined}>—</option>{#each crmCatalogs.options('forma_pago') as f (f.value)}<option value={f.value}>{f.value} — {f.label}</option>{/each}</select></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Límite de crédito</span><input type="number" min="0" step="0.01" class={inputCls} bind:value={form.credit_limit} /></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Días de crédito</span><input type="number" min="0" class={inputCls} bind:value={form.credit_days} /></label>
 		<label class="flex flex-col gap-1 text-sm sm:col-span-2"><span class="font-medium">Condiciones comerciales</span><textarea rows="3" class={inputCls} bind:value={form.commercial_terms}></textarea></label>
 	</div>
 {:else if tab === 'observaciones'}
 	<div class="grid gap-4 sm:grid-cols-2">
-		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Comentarios</span><textarea rows="4" class={inputCls} bind:value={form.notes}></textarea></label>
+		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Comentarios generales</span><textarea rows="4" class={inputCls} bind:value={form.notes}></textarea></label>
 		<label class="flex flex-col gap-1 text-sm"><span class="font-medium">Notas internas</span><textarea rows="4" class={inputCls} bind:value={form.internal_notes}></textarea></label>
 	</div>
 {/if}

frontend/src/lib/components/crm/format.ts

@@ -43,7 +43,7 @@ export const ACCOUNT_STATUS: Option[] = [
 export const COMMERCIAL_CLASSIFICATION: Option[] = [
 	{ value: 'importador', label: 'Importador' },
 	{ value: 'exportador', label: 'Exportador' },
-	{ value: 'ambos', label: 'Importador / Exportador' }
+	{ value: 'importador_exportador', label: 'Importador / Exportador' }
 ];
 
 export const ACCOUNT_TYPES: Option[] = [
@@ -58,7 +58,7 @@ export const ACCOUNT_TYPES: Option[] = [
 export const CONTACT_METHODS: Option[] = [
 	{ value: 'llamada', label: 'Llamada telefónica' },
 	{ value: 'correo', label: 'Correo electrónico' },
-	{ value: 'videollamada', label: 'Videoconferencia' },
+	{ value: 'videoconferencia', label: 'Videoconferencia' },
 	{ value: 'whatsapp', label: 'WhatsApp' },
 	{ value: 'otro', label: 'Otro' }
 ];

frontend/src/lib/components/fin/ConceptFields.svelte

@@ -1,185 +0,0 @@
-<script lang="ts">
-	import { Button } from '$lib/components/ui/button';
-	import {
-		satCatalogsAPI,
-		type ConceptInput,
-		type SatCatalogItem,
-		type SatUnitOfMeasure
-	} from '$lib/api/fin';
-	import { toast } from 'svelte-sonner';
-
-	let {
-		form = $bindable(),
-		companyId,
-		/** Clave ProdServ ya elegida; se muestra resuelta en vez del buscador. */
-		productService = $bindable(),
-		/** Error del 409 del backend, mostrado junto al campo de clave ProdServ. */
-		productServiceError = $bindable()
-	}: {
-		form: ConceptInput;
-		companyId: number | null;
-		productService: SatCatalogItem | null;
-		productServiceError: string;
-	} = $props();
-
-	let unitsOfMeasure = $state<SatUnitOfMeasure[]>([]);
-	let taxObjects = $state<SatCatalogItem[]>([]);
-
-	let productServiceQuery = $state('');
-	let productServiceOptions = $state<SatCatalogItem[]>([]);
-	let searchingProductService = $state(false);
-
-	$effect(() => {
-		const cid = companyId;
-		if (!cid) return;
-		void loadCatalogs(cid);
-	});
-
-	async function loadCatalogs(cid: number) {
-		try {
-			[unitsOfMeasure, taxObjects] = await Promise.all([
-				satCatalogsAPI.unitsOfMeasure(cid),
-				satCatalogsAPI.taxObjects(cid)
-			]);
-		} catch (e) {
-			toast.error(e instanceof Error ? e.message : 'No se pudieron cargar los catálogos del SAT');
-		}
-	}
-
-	/** Busca claves ProdServ; a partir de 2 caracteres para no traer el catálogo completo. */
-	async function searchProductServices() {
-		const cid = companyId;
-		const term = productServiceQuery.trim();
-		if (!cid || term.length < 2) {
-			productServiceOptions = [];
-			return;
-		}
-		searchingProductService = true;
-		try {
-			productServiceOptions = await satCatalogsAPI.productsServices(cid, {
-				search: term,
-				limit: 20
-			});
-		} catch (e) {
-			toast.error(
-				e instanceof Error ? e.message : 'No se pudo buscar la clave de producto/servicio'
-			);
-		} finally {
-			searchingProductService = false;
-		}
-	}
-
-	function pick(option: SatCatalogItem) {
-		productService = option;
-		form.product_service_id = option.id;
-		productServiceQuery = '';
-		productServiceOptions = [];
-		productServiceError = '';
-	}
-
-	function clearProductService() {
-		productService = null;
-		form.product_service_id = 0;
-		productServiceOptions = [];
-	}
-
-	const inputCls =
-		'rounded-md border bg-transparent px-3 py-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring';
-</script>
-
-<div class="grid gap-4 sm:grid-cols-2">
-	<label class="flex flex-col gap-1 text-sm">
-		<span class="font-medium">Clave *</span>
-		<input class="font-mono {inputCls}" bind:value={form.code} maxlength="40" required />
-	</label>
-	<label class="flex flex-col gap-1 text-sm">
-		<span class="font-medium">Precio unitario</span>
-		<input type="number" step="0.01" min="0" class={inputCls} bind:value={form.unit_price} />
-	</label>
-
-	<label class="flex flex-col gap-1 text-sm sm:col-span-2">
-		<span class="font-medium">Descripción *</span>
-		<input class={inputCls} bind:value={form.description} maxlength="500" required />
-	</label>
-
-	<div class="flex flex-col gap-1 text-sm sm:col-span-2">
-		<span class="font-medium">Clave de producto/servicio del SAT *</span>
-		<p class="text-xs text-muted-foreground">
-			Una clave del SAT solo puede estar asignada a un concepto de la empresa.
-		</p>
-		{#if productService}
-			<div class="flex items-center justify-between gap-2 rounded-md border px-3 py-2">
-				<span class="text-sm">
-					<span class="font-mono">{productService.code}</span>
-					<span class="text-muted-foreground"> — {productService.description}</span>
-				</span>
-				<Button type="button" variant="ghost" size="sm" onclick={clearProductService}
-					>Cambiar</Button
-				>
-			</div>
-		{:else}
-			<input
-				class={inputCls}
-				placeholder="Escribe al menos 2 caracteres (clave o descripción)…"
-				bind:value={productServiceQuery}
-				oninput={searchProductServices}
-			/>
-			{#if searchingProductService}
-				<p class="text-xs text-muted-foreground">Buscando…</p>
-			{:else if productServiceOptions.length > 0}
-				<ul class="max-h-48 overflow-y-auto rounded-md border">
-					{#each productServiceOptions as option (option.id)}
-						<li>
-							<button
-								type="button"
-								class="w-full px-3 py-2 text-left text-sm hover:bg-muted"
-								onclick={() => pick(option)}
-							>
-								<span class="font-mono">{option.code}</span>
-								<span class="text-muted-foreground"> — {option.description}</span>
-							</button>
-						</li>
-					{/each}
-				</ul>
-			{:else if productServiceQuery.trim().length >= 2}
-				<p class="text-xs text-muted-foreground">Sin coincidencias en el catálogo.</p>
-			{/if}
-		{/if}
-		{#if productServiceError}
-			<p class="text-xs text-destructive">{productServiceError}</p>
-		{/if}
-	</div>
-
-	<label class="flex flex-col gap-1 text-sm">
-		<span class="font-medium">Unidad de medida</span>
-		<select class={inputCls} bind:value={form.unit_of_measure_id}>
-			<option value={null}>Sin especificar</option>
-			{#each unitsOfMeasure as unit (unit.id)}
-				<option value={unit.id}>{unit.code} — {unit.name}</option>
-			{/each}
-		</select>
-	</label>
-	<label class="flex flex-col gap-1 text-sm">
-		<span class="font-medium">Objeto de impuesto</span>
-		<select class={inputCls} bind:value={form.tax_object_id}>
-			<option value={null}>Sin especificar</option>
-			{#each taxObjects as taxObject (taxObject.id)}
-				<option value={taxObject.id}>{taxObject.code} — {taxObject.description}</option>
-			{/each}
-		</select>
-	</label>
-
-	<label class="flex flex-col gap-1 text-sm">
-		<span class="font-medium">Moneda</span>
-		<input class={inputCls} bind:value={form.currency} maxlength="3" />
-	</label>
-	<label class="flex items-center gap-2 self-end text-sm">
-		<input type="checkbox" class="h-4 w-4 rounded border" bind:checked={form.is_active} />
-		<span class="font-medium">Activo</span>
-	</label>
-
-	<label class="flex flex-col gap-1 text-sm sm:col-span-2">
-		<span class="font-medium">Notas</span>
-		<textarea rows="3" class={inputCls} bind:value={form.notes}></textarea>
-	</label>
-</div>

frontend/src/lib/components/sidebar/modules.ts

@@ -6,6 +6,7 @@ import {
 	Briefcase,
 	Ship,
 	Receipt,
+	Building,
 } from '@lucide/svelte';
 
 export type SystemContext = 'fixed_asset' | 'inventory';
@@ -48,9 +49,12 @@ export function getNavMain(): NavMainItem[] {
 				{ title: 'Contactos', url: '/dashboard/crm/contactos' },
 				{ title: 'Solicitudes', url: '/dashboard/crm/solicitudes' },
 				{ title: 'Cotizaciones', url: '/dashboard/crm/cotizaciones' },
+				{ title: 'Tarifarios', url: '/dashboard/crm/tarifarios' },
+				{ title: 'Cotizador', url: '/dashboard/crm/cotizador' },
 				{ title: 'Prospectos (embudo)', url: '/dashboard/crm/prospectos' },
 				{ title: 'Oportunidades', url: '/dashboard/crm/oportunidades' },
 				{ title: 'Actividades', url: '/dashboard/crm/actividades' },
+				{ title: 'Catálogos', url: '/dashboard/crm/catalogos' },
 			],
 		},
 		{
@@ -67,9 +71,13 @@ export function getNavMain(): NavMainItem[] {
 			icon: Receipt,
 			items: [
 				{ title: 'Facturas y cobranza', url: '/dashboard/fin/facturas' },
-				{ title: 'Conceptos', url: '/dashboard/fin/conceptos', permission: 'fin.concept.view' },
 			],
 		},
+		{
+			title: 'Compañías',
+			url: '/dashboard/companias',
+			icon: Building,
+		},
 		{
 			title: 'Usuarios',
 			url: '/dashboard/users',
@@ -86,7 +94,7 @@ export function getNavMain(): NavMainItem[] {
 			icon: Settings2,
 			items: [
 				{ title: 'General', url: '/dashboard/settings/general' },
-				{ title: 'Facturación', url: '/dashboard/settings/facturacion', permission: 'fin.settings.view' },
+				{ title: 'Formato de cotización', url: '/dashboard/settings/cotizacion' },
 			],
 		},
 	];

frontend/src/lib/components/sidebar/team-switcher.svelte

@@ -145,9 +145,18 @@
 			>
 				<DropdownMenu.Label class="text-xs text-muted-foreground">Tenant</DropdownMenu.Label>
 				{#if userTenants.length === 0}
-					<DropdownMenu.Item disabled class="gap-2 p-2">
-						<span class="text-muted-foreground">Sin tenant asignado</span>
-					</DropdownMenu.Item>
+					{#if companyStore.activeCompany?.tenant_name}
+							<DropdownMenu.Item disabled class="gap-2 p-2">
+								<div class="flex size-6 items-center justify-center rounded-md border bg-muted">
+									<BuildingIcon class="size-3.5" />
+								</div>
+								<span class="truncate font-medium">{companyStore.activeCompany.tenant_name}</span>
+							</DropdownMenu.Item>
+						{:else}
+							<DropdownMenu.Item disabled class="gap-2 p-2">
+								<span class="text-muted-foreground">Sin tenant asignado</span>
+							</DropdownMenu.Item>
+						{/if}
 				{:else}
 					{#each userTenants as tenant (tenant.id)}
 						<DropdownMenu.Item

frontend/src/lib/server/api.ts

@@ -82,6 +82,60 @@ export function clearAuthTokens(cookies: Cookies) {
 	cookies.delete('id_token', { path: '/' });
 	cookies.delete('active_company_id', { path: '/' });
 	cookies.delete('active_system', { path: '/' });
+	// Sesión local del CRM (patrón SIWEB)
+	cookies.delete('kc_access_token', { path: '/' });
+	cookies.delete('crm_sid', { path: '/' });
+}
+
+/**
+ * Token de Keycloak para llamadas DIRECTAS al Hub (my-apps, my-tenants,
+ * provisioning). Con el patrón de sesión local (SIWEB) el `access_token` guarda
+ * la sesión local del CRM, así que el token KC vive en su propia cookie
+ * `kc_access_token`. Fallback a `access_token` cuando el patrón está apagado
+ * (kc_access_token ausente) → comportamiento histórico intacto.
+ */
+export function getKcAccessToken(cookies: Cookies): string | null {
+	return cookies.get('kc_access_token') ?? getAccessTokenFromCookies(cookies);
+}
+
+/**
+ * Aplica a las cookies la respuesta de /v1/auth/refresh considerando la sesión
+ * local del CRM (patrón SIWEB):
+ *  - Con `session_token`: `access_token` = sesión local (bearer de la app),
+ *    `kc_access_token` = token KC (para el Hub), `crm_sid` = id de sesión valkey.
+ *  - Sin él: comportamiento histórico (`access_token` = token KC).
+ * Devuelve el token que la app debe usar para reintentar (la sesión local si aplica).
+ */
+export function applyRefreshedTokens(
+	cookies: Cookies,
+	data: { access_token?: string; refresh_token?: string; session_token?: string; session_id?: string }
+): string | null {
+	const secure = isSecureContext();
+	if (data.session_token) {
+		setAccessTokenCookies(cookies, data.session_token, { secure, maxAge: 60 * 60 * 24 * 7 });
+		// access_token KC vacío = fallback sin token fresco → conservar el actual.
+		if (data.access_token) {
+			cookies.set('kc_access_token', data.access_token, {
+				path: '/', httpOnly: true, sameSite: 'lax', secure, maxAge: 60 * 60 * 24 * 7
+			});
+		}
+		if (data.session_id) {
+			cookies.set('crm_sid', data.session_id, {
+				path: '/', httpOnly: true, sameSite: 'lax', secure, maxAge: 60 * 60 * 24 * 30
+			});
+		}
+		if (data.refresh_token) {
+			cookies.set('refresh_token', data.refresh_token, {
+				path: '/', httpOnly: true, sameSite: 'lax', secure, maxAge: 60 * 60 * 24 * 30
+			});
+		}
+		return data.session_token;
+	}
+	if (data.access_token) {
+		setAuthTokens(cookies, data.access_token, data.refresh_token);
+		return data.access_token;
+	}
+	return null;
 }
 
 /**
@@ -113,12 +167,21 @@ export async function refreshAccessToken(
 
 	try {
 		const baseUrl = getServerApiUrl();
+		// Sesión local actual del CRM (patrón SIWEB): se envía para preservar el
+		// inicio de sesión (cap absoluto) y permitir el re-emitido de fallback
+		// cuando el refresh del token KC contra el Hub falla.
+		const currentSession = getAccessTokenFromCookies(cookies);
+		const sessionId = cookies.get('crm_sid');
 		const response = await fetch(`${baseUrl}v1/auth/refresh`, {
 			method: 'POST',
 			headers: {
 				'Content-Type': 'application/json'
 			},
-			body: JSON.stringify({ refresh_token: refreshToken })
+			body: JSON.stringify({
+				refresh_token: refreshToken,
+				...(currentSession ? { session_token: currentSession } : {}),
+				...(sessionId ? { session_id: sessionId } : {})
+			})
 		});
 
 		if (!response.ok) {
@@ -127,10 +190,8 @@ export async function refreshAccessToken(
 
 		const data = await response.json();
 
-		// Actualizar las cookies con los nuevos tokens
-		setAuthTokens(cookies, data.access_token, data.refresh_token);
-
-		return data.access_token;
+		// Actualiza las cookies teniendo en cuenta la sesión local (o histórico si no aplica).
+		return applyRefreshedTokens(cookies, data);
 	} catch (error) {
 		console.error('🔄 [API] Error al refrescar token:', error);
 		return null;

frontend/src/lib/server/workspace-auth.ts

@@ -5,9 +5,14 @@ const DEFAULT_WORKSPACE_BASE_URL = 'https://workspace.aduanasoft.com';
 const RETURN_PATH_COOKIE = 'workspace_return_path';
 
 /**
- * Returns true only when the public-facing URL uses HTTPS.
- * Use this for cookie `secure` flag instead of NODE_ENV so that
- * cookies work on HTTP LAN dev environments (e.g. 192.168.x.x).
+ * Autenticación 100% vía el Hub/Workspace (patrón SIWEB). El CRM NUNCA habla
+ * directo a Keycloak: el login entra por el App Launcher del workspace (relay
+ * → /auth/sso → Hub /sso-exchange) y el resto de auth va por la API del Hub.
+ */
+
+/**
+ * True solo cuando la URL pública usa HTTPS. Se usa para el flag `secure` de las
+ * cookies (en vez de NODE_ENV) para que funcionen en dev HTTP LAN (192.168.x.x).
  */
 export function isSecureContext(): boolean {
 	const origin = (env.ORIGIN || process.env.ORIGIN || '').trim();
@@ -20,9 +25,8 @@ function stripTrailingSlashes(value: string): string {
 }
 
 /**
- * Detecta si una URL apunta a un host que solo es accesible localmente:
- * localhost, 127.0.0.1, IPs de red LAN/privada y hostnames internos de Docker.
- * Estas URLs no son válidas como redirect_uri ni como KC public URL en producción.
+ * Detecta URLs solo accesibles localmente (localhost, IPs LAN/privadas, hosts
+ * internos de Docker). No son válidas como URL pública del Workspace.
  */
 function isDevOnlyUrl(rawUrl: string): boolean {
 	try {
@@ -60,27 +64,14 @@ export function getWorkspaceBaseUrl(): string {
 }
 
 /**
- * Normaliza la URL base del sistema (Mi Aplicación) para construir redirect_uri seguros.
- *
- * Problema habitual en producción: SvelteKit deriva `url.origin` de la variable de entorno
- * `ORIGIN`. Si el contenedor se despliega con `ORIGIN=http://localhost:5173` (valor del .env
- * de dev), todos los redirect_uri generados por el servidor apuntan a localhost.
- *
- * Esta función:
- * 1. Usa `requestOrigin` si ya es una URL pública (no dev-only).
- * 2. Si es localhost, busca `SITE_URL` (env var de producción recomendada) como fallback.
- * 3. Como último recurso devuelve requestOrigin tal cual (entorno dev genuino).
- *
- * Var de entorno recomendada en producción:
- *   SITE_URL=https://mi-app.dominio.com   (además de arreglar ORIGIN)
+ * Normaliza la URL base del sistema (Mi Aplicación) para construir redirect_uri.
+ * Corrige el caso donde `ORIGIN` env var apunta a localhost en producción.
  */
 export function resolveSystemBaseUrl(requestOrigin: string): string {
 	if (!isDevOnlyUrl(requestOrigin)) {
 		return stripTrailingSlashes(requestOrigin);
 	}
 
-	// requestOrigin es dev-only → ORIGIN env var apunta a localhost en producción.
-	// Buscar URL pública en env vars adicionales.
 	const candidates = [
 		(env.SITE_URL || '').trim(),
 		(env.APP_URL || '').trim(),
@@ -93,31 +84,17 @@ export function resolveSystemBaseUrl(requestOrigin: string): string {
 		}
 	}
 
-	// Entorno dev genuino: devolver requestOrigin tal cual
 	return stripTrailingSlashes(requestOrigin);
 }
 
-export type WorkspaceLoginUrlOptions = {
-	/**
-	 * URL del login del Hub sin `return_to`. Usar en `post_logout_redirect_uri` para que,
-	 * tras logout en KC, el Hub aplique myApps() (launcher si el usuario tiene varias apps).
-	 * Con `return_to` a Mi Aplicación, el re-login siempre rebotaba a esa app aunque hubiera más.
-	 */
-	forPostLogout?: boolean;
-};
-
-export function getWorkspaceLoginUrl(
-	systemBaseUrl: string,
-	options?: WorkspaceLoginUrlOptions
-): string {
-	const workspaceBaseUrl = getWorkspaceBaseUrl();
-	if (options?.forPostLogout) {
-		return `${workspaceBaseUrl}/login`;
-	}
-	// return_to includes sso_verified=1 so the workspace preserves it when redirecting
-	// back, regardless of what additional params the workspace appends.
-	const loginUrl = `${systemBaseUrl}/login?sso_verified=1`;
-	return `${workspaceBaseUrl}/login?return_to=${encodeURIComponent(loginUrl)}`;
+/**
+ * URL de login del Workspace. NO lleva `return_to` a Mi Aplicación: el Hub
+ * muestra el App Launcher y el usuario re-entra al CRM por relay
+ * (→ /auth/sso?relay=). Así se evita el rebote a /login sin sesión (bucle) y no
+ * se usa ningún flujo OIDC directo contra Keycloak.
+ */
+export function getWorkspaceLoginUrl(): string {
+	return `${getWorkspaceBaseUrl()}/login`;
 }
 
 export function storeReturnPath(cookies: Cookies, path: string): void {
@@ -131,26 +108,6 @@ export function storeReturnPath(cookies: Cookies, path: string): void {
 	});
 }
 
-export function getPublicKeycloakBaseUrl(): string {
-	const configuredKeycloakUrl = (env.VITE_KEYCLOAK_URL || '').trim();
-	// Si VITE_KEYCLOAK_URL apunta a un host dev-only (localhost, IP LAN, Docker service),
-	// ignorarlo y derivar la URL del hostname público del Workspace.
-	// Esto protege contra builds donde el .env de dev llega a producción por error.
-	if (configuredKeycloakUrl && !isDevOnlyUrl(configuredKeycloakUrl)) {
-		return stripTrailingSlashes(configuredKeycloakUrl);
-	}
-
-	return `${getWorkspaceBaseUrl()}/kcauth`;
-}
-
-export function getKeycloakRealm(): string {
-	return (env.KEYCLOAK_REALM || env.VITE_KEYCLOAK_REALM || 'master').trim();
-}
-
-export function getKeycloakClientId(): string {
-	return (env.KEYCLOAK_CLIENT_ID || env.VITE_KEYCLOAK_CLIENT_ID || 'app-frontend').trim();
-}
-
 export function getCleanReturnPath(url: URL): string {
 	const cleanParams = new URLSearchParams(url.searchParams);
 	cleanParams.delete('sso_verified');
@@ -186,68 +143,9 @@ export function clearWorkspaceReturnPath(cookies: Cookies): void {
 	cookies.delete(RETURN_PATH_COOKIE, { path: '/' });
 }
 
-export function buildKeycloakAuthorizationUrl(systemBaseUrl: string, redirectPath: string): string {
-	const keycloakBaseUrl = getPublicKeycloakBaseUrl();
-	// resolveSystemBaseUrl corrige el caso donde url.origin es localhost por ORIGIN env var mal configurado
-	const publicBase = resolveSystemBaseUrl(systemBaseUrl);
-	const redirectUri = `${publicBase}/auth/callback`;
-	const state = JSON.stringify({ redirect_url: redirectPath });
-	const params = new URLSearchParams({
-		client_id: getKeycloakClientId(),
-		redirect_uri: redirectUri,
-		response_type: 'code',
-		scope: 'openid',
-		prompt: 'none',
-		state
-	});
-
-	return `${keycloakBaseUrl}/realms/${getKeycloakRealm()}/protocol/openid-connect/auth?${params.toString()}`;
-}
-
-/**
- * Construye URL de login directo en KC sin prompt=none.
- * Usa la sesión KC existente si la hay; si no, muestra el form de login.
- * Usar cuando se recibe ?redirect= del Hub (rompe el loop Hub↔login).
- */
-export function buildKeycloakLoginUrl(systemBaseUrl: string, redirectPath: string): string {
-	const keycloakBaseUrl = getPublicKeycloakBaseUrl();
-	// resolveSystemBaseUrl corrige el caso donde url.origin es localhost por ORIGIN env var mal configurado
-	const publicBase = resolveSystemBaseUrl(systemBaseUrl);
-	const redirectUri = `${publicBase}/auth/callback`;
-	const state = JSON.stringify({ redirect_url: redirectPath });
-	const params = new URLSearchParams({
-		client_id: getKeycloakClientId(),
-		redirect_uri: redirectUri,
-		response_type: 'code',
-		scope: 'openid',
-		state
-	});
-
-	return `${keycloakBaseUrl}/realms/${getKeycloakRealm()}/protocol/openid-connect/auth?${params.toString()}`;
-}
-
-export function redirectToWorkspaceLogin(cookies: Cookies, url: URL): never {
-	// Modo local: nunca salir al workspace, mostrar el login local.
-	if ((env.DEV_LOCAL_AUTH ?? '').toLowerCase() === 'true') {
-		throw redirect(303, '/login');
-	}
-	storeWorkspaceReturnPath(cookies, url);
-	throw redirect(303, getWorkspaceLoginUrl(url.origin));
-}
-
-export function redirectToKeycloakAuthorization(systemBaseUrl: string, redirectPath: string): never {
-	throw redirect(303, buildKeycloakAuthorizationUrl(systemBaseUrl, redirectPath));
-}
-
-export function redirectToKeycloakLogin(systemBaseUrl: string, redirectPath: string): never {
-	throw redirect(303, buildKeycloakLoginUrl(systemBaseUrl, redirectPath));
-}
-
 /**
  * URL del Hub FastAPI para llamadas server-to-server (ej. sso-exchange).
  * No aplica isDevOnlyUrl: las URLs internas de Docker son válidas aquí.
- * Lee HUB_BACKEND_URL (override explícito) → INTERNAL_HUB_URL (ya en docker-compose)
- * → fallback a URL pública del workspace (vía proxy SvelteKit del Hub).
  */
 export function getHubBackendUrl(): string {
 	const direct =
@@ -257,19 +155,15 @@ export function getHubBackendUrl(): string {
 	return getWorkspaceBaseUrl();
 }
 
-export function buildKeycloakLogoutUrl(systemBaseUrl: string, idTokenHint?: string): string {
-	const keycloakBaseUrl = getPublicKeycloakBaseUrl();
-	const postLogoutRedirectUri = `${systemBaseUrl}/auth/post-logout`;
-	const params = new URLSearchParams({
-		client_id: getKeycloakClientId(),
-		post_logout_redirect_uri: postLogoutRedirectUri
-	});
-
-	// Con id_token_hint KC acepta cualquier post_logout_redirect_uri sin necesidad
-	// de que esté registrado explícitamente en el cliente.
-	if (idTokenHint) {
-		params.set('id_token_hint', idTokenHint);
+/**
+ * Redirige al login del Workspace (App Launcher). Único punto de entrada de
+ * login: el CRM no inicia ningún flujo contra Keycloak.
+ */
+export function redirectToWorkspaceLogin(cookies: Cookies, url: URL): never {
+	// Modo local: nunca salir al workspace, mostrar el login local.
+	if ((env.DEV_LOCAL_AUTH ?? '').toLowerCase() === 'true') {
+		throw redirect(303, '/login');
 	}
-
-	return `${keycloakBaseUrl}/realms/${getKeycloakRealm()}/protocol/openid-connect/logout?${params.toString()}`;
-}
+	storeWorkspaceReturnPath(cookies, url);
+	throw redirect(303, getWorkspaceLoginUrl());
+}

frontend/src/lib/server/workspace-provision.shared.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+import {
+	slugifyTenantName,
+	validateTenantForm,
+	hubErrorMessage,
+	isForbiddenStatus,
+	TENANT_SLUG_RE
+} from './workspace-provision.shared';
+
+describe('slugifyTenantName', () => {
+	it('convierte nombre con acentos y espacios a slug válido', () => {
+		const slug = slugifyTenantName('Logística Peña & Cía S.A. de C.V.');
+		expect(slug).toBe('logistica-pena-cia-s-a-de-c-v');
+		expect(TENANT_SLUG_RE.test(slug)).toBe(true);
+	});
+
+	it('quita guiones al inicio y al final', () => {
+		expect(slugifyTenantName('  --Hola--  ')).toBe('hola');
+	});
+
+	it('cadena sin caracteres válidos da string vacío', () => {
+		expect(slugifyTenantName('!!!')).toBe('');
+	});
+});
+
+describe('validateTenantForm', () => {
+	it('acepta datos válidos', () => {
+		expect(
+			validateTenantForm({ name: 'Empresa ABC', slug: 'empresa-abc', contact_email: 'a@b.com' })
+		).toBeNull();
+	});
+
+	it('rechaza nombre demasiado corto', () => {
+		expect(
+			validateTenantForm({ name: 'A', slug: 'a-b', contact_email: 'a@b.com' })
+		).toMatch(/al menos 2/);
+	});
+
+	it('rechaza slug con mayúsculas o espacios', () => {
+		expect(
+			validateTenantForm({ name: 'Empresa ABC', slug: 'Empresa ABC', contact_email: 'a@b.com' })
+		).toMatch(/slug/i);
+	});
+
+	it('rechaza email inválido', () => {
+		expect(
+			validateTenantForm({ name: 'Empresa ABC', slug: 'empresa-abc', contact_email: 'no-email' })
+		).toMatch(/email/i);
+	});
+});
+
+describe('hubErrorMessage', () => {
+	it('devuelve el detail string tal cual', () => {
+		expect(hubErrorMessage({ detail: 'Slug ya existe' }, 409)).toBe('Slug ya existe');
+	});
+
+	it('formatea el primer error de validación de Pydantic', () => {
+		const body = { detail: [{ loc: ['body', 'contact_email'], msg: 'value is not a valid email' }] };
+		expect(hubErrorMessage(body, 422)).toBe('contact_email: value is not a valid email');
+	});
+
+	it('mensaje de permisos ante 403 sin detail', () => {
+		expect(hubErrorMessage(null, 403)).toMatch(/permisos/i);
+	});
+
+	it('mensaje genérico con status ante cuerpo desconocido', () => {
+		expect(hubErrorMessage(null, 500)).toMatch(/500/);
+	});
+});
+
+describe('isForbiddenStatus', () => {
+	it('true para 401 y 403', () => {
+		expect(isForbiddenStatus(401)).toBe(true);
+		expect(isForbiddenStatus(403)).toBe(true);
+	});
+	it('false para otros', () => {
+		expect(isForbiddenStatus(422)).toBe(false);
+		expect(isForbiddenStatus(200)).toBe(false);
+	});
+});

frontend/src/lib/server/workspace-provision.shared.ts

@@ -0,0 +1,85 @@
+/**
+ * Helpers puros para el alta de organizaciones/usuarios en el Workspace (Hub).
+ * Sin dependencias de entorno para poder testearse en aislamiento (Vitest).
+ */
+
+// Slug del tenant: mismas reglas que el Hub (TenantCreateDTO.slug → ^[a-z0-9-]+$).
+export const TENANT_SLUG_RE = /^[a-z0-9-]+$/;
+
+// Roles válidos para invitar un usuario. Son los que el Hub reconoce en su
+// flujo de alta (ver ProvisionUserRequestDTO / create_invite). No inventar otros.
+export const WORKSPACE_INVITE_ROLES = ['user', 'admin', 'supervisor', 'operador', 'visor'] as const;
+export type WorkspaceInviteRole = (typeof WORKSPACE_INVITE_ROLES)[number];
+
+/**
+ * Deriva un slug candidato a partir del nombre de la organización:
+ * minúsculas, sin acentos, espacios y símbolos → guiones.
+ */
+export function slugifyTenantName(name: string): string {
+	return name
+		.normalize('NFD')
+		.replace(/[̀-ͯ]/g, '') // quita acentos (marcas combinantes Unicode)
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		.slice(0, 100);
+}
+
+export type TenantFormValues = {
+	name: string;
+	slug: string;
+	contact_email: string;
+};
+
+/**
+ * Valida los campos obligatorios del alta de organización antes de llamar al Hub,
+ * para dar feedback inmediato sin gastar un round-trip.
+ * Devuelve un mensaje de error o null si es válido.
+ */
+export function validateTenantForm(values: TenantFormValues): string | null {
+	if (!values.name || values.name.trim().length < 2) {
+		return 'El nombre de la organización debe tener al menos 2 caracteres.';
+	}
+	if (!TENANT_SLUG_RE.test(values.slug)) {
+		return 'El slug solo admite minúsculas, dígitos y guiones (sin espacios ni acentos).';
+	}
+	if (!values.contact_email || !values.contact_email.includes('@')) {
+		return 'El email de contacto es obligatorio y debe ser válido.';
+	}
+	return null;
+}
+
+/**
+ * Extrae un mensaje legible del cuerpo de error de FastAPI (Hub).
+ * - 401/403 → mensaje de permisos.
+ * - detail string → tal cual.
+ * - detail array (422 Pydantic) → "campo: msg" del primer error.
+ * - cualquier otro → mensaje genérico con el status.
+ */
+export function hubErrorMessage(body: unknown, status: number): string {
+	const detail =
+		body && typeof body === 'object' ? (body as { detail?: unknown }).detail : null;
+
+	if (typeof detail === 'string' && detail.trim()) {
+		return detail;
+	}
+
+	if (Array.isArray(detail) && detail.length > 0) {
+		const first = detail[0] as { loc?: unknown[]; msg?: string };
+		const loc = Array.isArray(first.loc) ? first.loc : [];
+		const field = loc.length ? String(loc[loc.length - 1]) : '';
+		const msg = first.msg ?? 'dato inválido';
+		return field ? `${field}: ${msg}` : msg;
+	}
+
+	if (status === 401 || status === 403) {
+		return 'No tienes permisos de administrador en el workspace para esta acción.';
+	}
+
+	return `El workspace respondió con un error (${status}).`;
+}
+
+/** True si el status del Hub indica falta de permisos/sesión. */
+export function isForbiddenStatus(status: number): boolean {
+	return status === 401 || status === 403;
+}

frontend/src/lib/server/workspace-provision.ts

@@ -0,0 +1,126 @@
+/**
+ * Orquestación del Hub (Workspace) para dar de alta ORGANIZACIONES (tenants) y
+ * USUARIOS (invitaciones) desde el CRM.
+ *
+ * Principio de seguridad: SIEMPRE se llama server-side reenviando el token del
+ * usuario autenticado (Bearer). Es el Hub quien valida el permiso —
+ * `hub_admin`/superadmin para tenants, `hub_admin` o `admin` del tenant para
+ * invitaciones. El CRM NO guarda secretos ni hace bypass de autorización.
+ *
+ * Endpoints del Hub (base = getHubBackendUrl()):
+ *   GET  /api/v1/hub/tenants   → lista de organizaciones (solo hub_admin)
+ *   POST /api/v1/hub/tenants   → crea tenant + realm Keycloak (solo hub_admin)
+ *   POST /api/v1/hub/invites   → invitación de un solo uso + email (hub_admin | admin del tenant)
+ */
+
+import { getHubBackendUrl } from '$lib/server/workspace-auth';
+import { hubErrorMessage, isForbiddenStatus } from '$lib/server/workspace-provision.shared';
+
+const HUB_API_PREFIX = '/api/v1/hub';
+
+function hubUrl(path: string): string {
+	return `${getHubBackendUrl()}${HUB_API_PREFIX}${path}`;
+}
+
+export type WorkspaceTenant = {
+	id: number;
+	name: string;
+	slug: string;
+	display_name?: string | null;
+	contact_name?: string | null;
+	contact_email: string;
+	status: string;
+	is_self_hosted: boolean;
+	has_license: boolean;
+	created_at: string;
+};
+
+export type WorkspaceInvite = {
+	id: number;
+	email: string;
+	tenant_slug: string;
+	role: string;
+	invite_url: string;
+	expires_at: string;
+	created_at: string;
+};
+
+export type HubResult<T> =
+	| { ok: true; data: T }
+	| { ok: false; status: number; forbidden: boolean; error: string };
+
+/** Construye el resultado de error a partir de una respuesta no-2xx del Hub. */
+async function toErrorResult<T>(res: Response): Promise<HubResult<T>> {
+	const body = await res.json().catch(() => null);
+	return {
+		ok: false,
+		status: res.status,
+		forbidden: isForbiddenStatus(res.status),
+		error: hubErrorMessage(body, res.status)
+	};
+}
+
+const jsonHeaders = (accessToken: string) => ({
+	Authorization: `Bearer ${accessToken}`,
+	'Content-Type': 'application/json'
+});
+
+/** Lista las organizaciones del workspace. Requiere hub_admin (403 si no). */
+export async function listWorkspaceTenants(
+	accessToken: string,
+	fetch: typeof globalThis.fetch
+): Promise<HubResult<WorkspaceTenant[]>> {
+	const res = await fetch(hubUrl('/tenants'), {
+		headers: { Authorization: `Bearer ${accessToken}` }
+	});
+	if (!res.ok) return toErrorResult<WorkspaceTenant[]>(res);
+	const data = (await res.json()) as { tenants?: WorkspaceTenant[] };
+	return { ok: true, data: Array.isArray(data.tenants) ? data.tenants : [] };
+}
+
+export type CreateTenantInput = {
+	name: string;
+	slug: string;
+	contact_email: string;
+	contact_name?: string;
+	contact_phone?: string;
+	display_name?: string;
+	is_self_hosted: boolean;
+	app_url?: string;
+};
+
+/** Crea una organización (tenant) y provisiona su realm en Keycloak. */
+export async function createWorkspaceTenant(
+	accessToken: string,
+	fetch: typeof globalThis.fetch,
+	input: CreateTenantInput
+): Promise<HubResult<WorkspaceTenant>> {
+	const res = await fetch(hubUrl('/tenants'), {
+		method: 'POST',
+		headers: jsonHeaders(accessToken),
+		body: JSON.stringify(input)
+	});
+	if (!res.ok) return toErrorResult<WorkspaceTenant>(res);
+	return { ok: true, data: (await res.json()) as WorkspaceTenant };
+}
+
+export type CreateInviteInput = {
+	email: string;
+	tenant_slug: string;
+	role: string;
+};
+
+/** Genera una invitación de un solo uso para un usuario en un tenant. */
+export async function createWorkspaceInvite(
+	accessToken: string,
+	fetch: typeof globalThis.fetch,
+	input: CreateInviteInput
+): Promise<HubResult<WorkspaceInvite>> {
+	const res = await fetch(hubUrl('/invites'), {
+		method: 'POST',
+		headers: jsonHeaders(accessToken),
+		body: JSON.stringify(input)
+	});
+	if (!res.ok) return toErrorResult<WorkspaceInvite>(res);
+	return { ok: true, data: (await res.json()) as WorkspaceInvite };
+}

frontend/src/lib/stores/company.svelte.ts

@@ -11,6 +11,8 @@ interface Company {
 	rfc?: string;
 	logo?: string;
 	tenant_id: number;
+	tenant_name?: string;
+	tenant_slug?: string;
 }
 
 class CompanyStore {
@@ -158,7 +160,9 @@ class CompanyStore {
 					headers: {
 						'Content-Type': 'application/json'
 					},
-					body: JSON.stringify({ companyId: company.id }),
+					// tenant_id de la compañía → override para que el backend escale por
+					// ese tenant (necesario cuando el usuario es hub_admin sin tenant en el token).
+					body: JSON.stringify({ companyId: company.id, tenantId: company.tenant_id }),
 					credentials: 'include'
 				});
 			} catch (error) {

frontend/src/lib/stores/crm-catalogs.svelte.ts

@@ -0,0 +1,77 @@
+/**
+ * Store reactivo de catálogos de referencia del CRM.
+ *
+ * Carga desde el backend (/v1/crm/catalogs) y cachea por catálogo. Los
+ * formularios leen `options(catalog)` (reactivo) sin refetch. Los catálogos
+ * dependientes (Estado por País) se piden con `ensure(catalog, parentCode)`.
+ */
+import { referenceCatalogsAPI } from '$lib/api/crm/catalogs';
+import { companyStore } from '$lib/stores/company.svelte';
+import type { Option } from '$lib/components/crm/format';
+
+class CrmCatalogStore {
+	private _cache = $state<Record<string, Option[]>>({});
+	private _pending = new Set<string>();
+	private _companyId: number | null = null;
+
+	/** Toma la compañía activa; si cambió, limpia el caché. Devuelve su id (o null). */
+	private syncCompany(): number | null {
+		const cid = companyStore.activeCompany?.id ?? null;
+		if (cid !== this._companyId) {
+			this._companyId = cid;
+			this._cache = {};
+			this._pending.clear();
+		}
+		return cid;
+	}
+
+	private keyOf(catalog: string, parentCode?: string): string {
+		return parentCode ? `${catalog}:${parentCode}` : catalog;
+	}
+
+	/** Opciones de un catálogo ya cargado (vacío si aún no se ha cargado). */
+	options(catalog: string, parentCode?: string): Option[] {
+		return this._cache[this.keyOf(catalog, parentCode)] ?? [];
+	}
+
+	/** Descripción de una clave (para listados/detalle). */
+	label(catalog: string, code: string | null | undefined): string {
+		if (!code) return '—';
+		return this.options(catalog).find((o) => o.value === code)?.label ?? code;
+	}
+
+	/** Carga un catálogo (con dependiente opcional) si aún no está en caché. */
+	async ensure(catalog: string, parentCode?: string): Promise<void> {
+		const cid = this.syncCompany();
+		const key = this.keyOf(catalog, parentCode);
+		if (cid == null || key in this._cache || this._pending.has(key)) return;
+		this._pending.add(key);
+		try {
+			const items = await referenceCatalogsAPI.list(catalog, cid, parentCode);
+			this._cache[key] = items.map((i) => ({ value: i.code, label: i.label }));
+		} catch {
+			this._cache[key] = [];
+		} finally {
+			this._pending.delete(key);
+		}
+	}
+
+	/** Precarga varios catálogos globales en paralelo. */
+	async preload(catalogs: string[]): Promise<void> {
+		await Promise.all(catalogs.map((c) => this.ensure(c)));
+	}
+
+	/** Invalida el caché de un catálogo (tras editar en administración). */
+	invalidate(catalog?: string): void {
+		if (!catalog) {
+			this._cache = {};
+			return;
+		}
+		for (const k of Object.keys(this._cache)) {
+			if (k === catalog || k.startsWith(`${catalog}:`)) delete this._cache[k];
+		}
+		this._cache = { ...this._cache };
+	}
+}
+
+export const crmCatalogs = new CrmCatalogStore();

frontend/src/routes/api-sveltekit/auth/silent-refresh/+server.ts

@@ -14,8 +14,8 @@
 
 import { json } from '@sveltejs/kit';
 import type { RequestEvent } from '@sveltejs/kit';
-import { getServerApiUrl, setAuthTokens } from '$lib/server/api';
-import { clearAccessTokenCookies } from '$lib/server/access-token-cookie';
+import { getServerApiUrl, applyRefreshedTokens, clearAuthTokens } from '$lib/server/api';
+import { getAccessTokenFromCookies } from '$lib/server/access-token-cookie';
 
 export const POST = async ({ cookies, fetch }: RequestEvent) => {
 	const refreshToken = cookies.get('refresh_token');
@@ -27,34 +27,43 @@ export const POST = async ({ cookies, fetch }: RequestEvent) => {
 	try {
 		const baseUrl = getServerApiUrl();
 
+		// Sesión local actual del CRM (patrón SIWEB): se reenvía para preservar el
+		// inicio de sesión y permitir el re-emitido de fallback cuando el refresh KC falla.
+		const currentSession = getAccessTokenFromCookies(cookies);
+		const sessionId = cookies.get('crm_sid');
+
 		const response = await fetch(`${baseUrl}v1/auth/refresh`, {
 			method: 'POST',
 			headers: { 'Content-Type': 'application/json' },
-			body: JSON.stringify({ refresh_token: refreshToken })
+			body: JSON.stringify({
+				refresh_token: refreshToken,
+				...(currentSession ? { session_token: currentSession } : {}),
+				...(sessionId ? { session_id: sessionId } : {})
+			})
 		});
 
 		if (!response.ok) {
-			// El refresh token expiró o fue invalidado por Keycloak (sesión terminada).
-			// Limpiar las cookies para que el servidor redirigir al login en la siguiente carga.
-			cookies.delete('refresh_token', { path: '/' });
-			clearAccessTokenCookies(cookies);
-			cookies.delete('active_company_id', { path: '/' });
+			// El refresh falló y no hubo sesión local que re-emitir (cap superado o
+			// patrón apagado). Limpiar cookies para que el server redirija al login.
+			clearAuthTokens(cookies);
 
 			const status = response.status === 401 ? 401 : 400;
 			return json({ error: 'Refresh token expired or invalid' }, { status });
 		}
 
 		const data = (await response.json()) as {
-			access_token: string;
+			access_token?: string;
 			refresh_token?: string;
+			session_token?: string;
+			session_id?: string;
 			expires_in?: number;
 		};
 
-		// Actualizar las cookies HttpOnly con los nuevos tokens
-		setAuthTokens(cookies, data.access_token, data.refresh_token);
+		// Actualiza cookies considerando la sesión local; devuelve el bearer de la app.
+		const appToken = applyRefreshedTokens(cookies, data);
 
-		// Devolver solo el access_token al cliente
-		return json({ access_token: data.access_token });
+		// Devolver solo el token de app al cliente (sesión local si aplica, o KC).
+		return json({ access_token: appToken ?? data.access_token ?? '' });
 	} catch (error) {
 		console.error('[silent-refresh] Error inesperado:', error);
 		return json({ error: 'Internal server error' }, { status: 500 });

frontend/src/routes/api-sveltekit/auth/switch-tenant/+server.ts

@@ -9,7 +9,7 @@
 import { json } from '@sveltejs/kit';
 import { env } from '$env/dynamic/private';
 import type { RequestEvent } from '@sveltejs/kit';
-import { getServerApiUrl, getAuthTokens, setAuthTokens } from '$lib/server/api';
+import { getServerApiUrl, getAuthTokens, getKcAccessToken, setAuthTokens } from '$lib/server/api';
 
 export const POST = async ({ request, cookies, fetch }: RequestEvent) => {
 	const body = await request.json();
@@ -28,9 +28,11 @@ export const POST = async ({ request, cookies, fetch }: RequestEvent) => {
 	// Modo SSO relay: validar acceso vía Hub y actualizar cookie de override
 	if (tenant_id) {
 		try {
+			// Validación contra el Hub → token KC (el access_token puede ser la sesión local).
+			const kcToken = getKcAccessToken(cookies) ?? accessToken;
 			const hubUrl = (env.INTERNAL_HUB_URL || env.HUB_URL || 'http://localhost:8001').replace(/\/+$/, '');
 			const tenantsRes = await fetch(`${hubUrl}/api/v1/auth/my-tenants`, {
-				headers: { 'Authorization': `Bearer ${accessToken}` },
+				headers: { 'Authorization': `Bearer ${kcToken}` },
 			});
 			if (!tenantsRes.ok) {
 				return json({ error: 'Could not validate tenant access' }, { status: 403 });

frontend/src/routes/api-sveltekit/company/set-active/+server.ts

@@ -6,22 +6,28 @@ import type { RequestHandler } from './$types';
 
 export const POST: RequestHandler = async ({ cookies, request }) => {
 	try {
-		const { companyId } = await request.json();
+		const body = await request.json();
+		const companyId = body?.companyId;
+		const tenantId = body?.tenantId;
 
 		if (!companyId || typeof companyId !== 'number') {
 			return json({ error: 'Invalid company ID' }, { status: 400 });
 		}
 
-		// Establecer la cookie desde el servidor
-		cookies.set('active_company_id', companyId.toString(), {
-			path: '/',
-			maxAge: 60 * 60 * 24 * 30, // 30 días
-			sameSite: 'lax',
-			httpOnly: false, // Permitir acceso desde JavaScript
-			secure: process.env.NODE_ENV === 'production'
-		});
+		const isProd = process.env.NODE_ENV === 'production';
+		const base = { path: '/', maxAge: 60 * 60 * 24 * 30, sameSite: 'lax' as const, secure: isProd };
 
-		return json({ success: true, companyId });
+		// Compañía activa (legible desde JS)
+		cookies.set('active_company_id', companyId.toString(), { ...base, httpOnly: false });
+
+		// Fijar el tenant de la compañía como override → el backend escala por ese
+		// tenant aunque el token no lo traiga (caso hub_admin operando por compañía).
+		if (typeof tenantId === 'number' && Number.isFinite(tenantId)) {
+			cookies.set('sso_tenant_id', tenantId.toString(), { ...base, httpOnly: true });
+			cookies.set('sso_tenant_pub', tenantId.toString(), { ...base, httpOnly: false });
+		}
+
+		return json({ success: true, companyId, tenantId: tenantId ?? null });
 	} catch (error) {
 		console.error('Error setting active company:', error);
 		return json({ error: 'Internal server error' }, { status: 500 });

frontend/src/routes/auth/callback/+page.server.ts

@@ -1,132 +1,15 @@
-import { redirect, isRedirect } from '@sveltejs/kit';
+import { redirect } from '@sveltejs/kit';
 import type { PageServerLoad } from './$types';
-import { setAccessTokenCookies } from '$lib/server/access-token-cookie';
-import {
-	clearWorkspaceReturnPath,
-	getWorkspaceLoginUrl,
-	readWorkspaceReturnPath,
-	storeReturnPath,
-} from '$lib/server/workspace-auth';
 
-export const load: PageServerLoad = async ({ url, cookies, fetch }) => {
-	// Obtener el código y state de los query params
-	const code = url.searchParams.get('code');
-	const state = url.searchParams.get('state');
-	const errorParam = url.searchParams.get('error');
-	const errorDescription = url.searchParams.get('error_description');
-	
-	if (errorParam) {
-		console.error('❌ [Callback Server] KC auth error:', errorParam, errorDescription);
-		// login_required means no KC session exists yet → send to Workspace login.
-		// Preserve the intended destination through the detour so /login can pick it up.
-		if (state) {
-			try {
-				const stateObj = JSON.parse(state);
-				const returnPath = stateObj.redirect_url;
-				if (returnPath && returnPath.startsWith('/') && returnPath !== '/login') {
-					storeReturnPath(cookies, returnPath);
-				}
-			} catch { /* ignore malformed state */ }
-		}
-		throw redirect(303, getWorkspaceLoginUrl(url.origin));
-	}
-	
-	if (!code) {
-		console.error('❌ [Callback Server] No se recibió código de autorización');
-		throw redirect(303, getWorkspaceLoginUrl(url.origin));
-	}
-	
-	try {
-		// Intercambiar código por tokens usando el backend de Keycloak
-		// En el servidor (SSR), usar KEYCLOAK_URL que apunta a http://keycloak:8080
-		// En producción o fuera de Docker, usar VITE_KEYCLOAK_URL como fallback
-		const KEYCLOAK_URL = process.env.KEYCLOAK_URL || process.env.VITE_KEYCLOAK_URL || 'http://localhost:8080';
-		const KEYCLOAK_REALM = process.env.KEYCLOAK_REALM || process.env.VITE_KEYCLOAK_REALM || 'master';
-		const KEYCLOAK_CLIENT_ID = process.env.KEYCLOAK_CLIENT_ID || process.env.VITE_KEYCLOAK_CLIENT_ID || 'app-backend';
-		const KEYCLOAK_CLIENT_SECRET = process.env.KEYCLOAK_CLIENT_SECRET || '';
-		
-		// La redirect_uri debe coincidir exactamente con la registrada en Keycloak.
-		// resolveSystemBaseUrl corrige el caso donde url.origin es localhost porque
-		// ORIGIN env var apunta a localhost en producción (usa SITE_URL como fallback).
-		const { resolveSystemBaseUrl } = await import('$lib/server/workspace-auth');
-		const redirectUri = `${resolveSystemBaseUrl(url.origin)}/auth/callback`;
-		
-		const tokenEndpoint = `${KEYCLOAK_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token`;
-		
-		const body = new URLSearchParams({
-			grant_type: 'authorization_code',
-			code: code,
-			redirect_uri: redirectUri,
-			client_id: KEYCLOAK_CLIENT_ID,
-			...(KEYCLOAK_CLIENT_SECRET && { client_secret: KEYCLOAK_CLIENT_SECRET })
-		});
-		
-		const tokenResponse = await fetch(tokenEndpoint, {
-			method: 'POST',
-			headers: {
-				'Content-Type': 'application/x-www-form-urlencoded'
-			},
-			body: body.toString()
-		});
-		
-		if (!tokenResponse.ok) {
-			const errorData = await tokenResponse.text();
-			console.error('❌ [Callback Server] Error al intercambiar código:', errorData);
-			throw new Error('Error al obtener tokens');
-		}
-		
-		const tokens = await tokenResponse.json();
-		
-		// Establecer las cookies en el servidor
-		// access_token → NO HttpOnly (el cliente JS lo usa para el header Authorization)
-		// refresh_token → HttpOnly (el JS nunca lo lee; el servidor lo gestiona)
-		const { isSecureContext } = await import('$lib/server/workspace-auth');
-		const isProduction = isSecureContext();
-		
-		setAccessTokenCookies(cookies, tokens.access_token, {
-			secure: isProduction,
-			maxAge: 60 * 60 * 24 * 7 // 7 días
-		});
-		
-		if (tokens.refresh_token) {
-			cookies.set('refresh_token', tokens.refresh_token, {
-				path: '/',
-				httpOnly: true,    // *** HttpOnly: nunca expuesto a JS ***
-				secure: isProduction,
-				sameSite: 'lax',
-				maxAge: 60 * 60 * 24 * 30 // 30 días
-			});
-		}
-
-		if (tokens.id_token) {
-			cookies.set('id_token', tokens.id_token, {
-				path: '/',
-				httpOnly: true,
-				secure: isProduction,
-				sameSite: 'lax',
-				maxAge: 60 * 60 * 24 * 7
-			});
-		}
-		
-		// Obtener la URL de redirección del state o ir al dashboard
-		let redirectTo = readWorkspaceReturnPath(cookies, '/dashboard');
-		if (state) {
-			try {
-				const stateObj = JSON.parse(state);
-				redirectTo = stateObj.redirect_url || '/dashboard';
-			} catch (e) {
-				console.warn('⚠️ [Callback Server] No se pudo obtener redirect_url del state');
-			}
-		}
-
-		clearWorkspaceReturnPath(cookies);
-		
-		// Redirigir a la página de destino
-		throw redirect(303, redirectTo);
-		
-	} catch (err: any) {
-		if (isRedirect(err)) throw err;
-		console.error('❌ [Callback Server] Error procesando autenticación:', err);
-		throw redirect(303, getWorkspaceLoginUrl(url.origin));
-	}
+/**
+ * Callback OIDC — OBSOLETO.
+ *
+ * El CRM ya no inicia flujo de autorización contra Keycloak: el login entra por
+ * el App Launcher del Workspace (relay → /auth/sso → Hub /sso-exchange). Esta
+ * ruta se conserva solo para no romper enlaces viejos; cualquier acceso se
+ * redirige al dashboard (el layout valida la sesión y, si no hay, reenvía al
+ * Workspace). No se intercambia ningún `code` con Keycloak.
+ */
+export const load: PageServerLoad = async () => {
+	throw redirect(303, '/dashboard');
 };

frontend/src/routes/auth/post-logout/+server.ts

@@ -3,11 +3,10 @@ import type { RequestHandler } from './$types';
 import { getWorkspaceLoginUrl } from '$lib/server/workspace-auth';
 
 /**
- * KC redirects here after completing the logout flow.
- * This URL is covered by the app's registered wildcard in KC (e.g. mi-app.dominio.com/*).
- * We then send the user to workspace login so it can apply myApps() launcher logic.
+ * Ruta de retorno post-logout. El CRM ya no dispara logout contra Keycloak
+ * (el cierre completo se hace desde el Workspace); se conserva por compatibilidad
+ * y redirige al App Launcher del Workspace.
  */
-export const GET: RequestHandler = async ({ request, url }) => {
-	const systemBaseUrl = url.origin;
-	throw redirect(303, getWorkspaceLoginUrl(systemBaseUrl, { forPostLogout: true }));
+export const GET: RequestHandler = async () => {
+	throw redirect(303, getWorkspaceLoginUrl());
 };

frontend/src/routes/auth/sso/+page.server.ts

@@ -134,12 +134,32 @@ export const load: PageServerLoad = async ({ url, cookies }) => {
 	const isProduction = isSecureContext();
 	console.log('[SSO] ORIGIN-based secure context:', isProduction);
 
+	// Sesión local del CRM (patrón SIWEB): si el refresh proactivo devolvió una
+	// sesión local firmada, el access_token guarda ESA sesión (bearer de la app,
+	// sobrevive aunque el refresh KC del Hub falle) y el token KC va a su propia
+	// cookie kc_access_token (solo para llamadas directas al Hub). Si no vino
+	// (flag apagado), comportamiento histórico: access_token = token KC.
+	const sessionToken = typeof tokens.session_token === 'string' ? tokens.session_token : null;
+	const kcAccessToken = tokens.access_token as string;
+
 	// access_token — NO HttpOnly (Bearer desde JS); fragmentado si el JWT supera ~4KB
-	setAccessTokenCookies(cookies, tokens.access_token as string, {
+	setAccessTokenCookies(cookies, sessionToken ?? kcAccessToken, {
 		secure: isProduction,
 		maxAge: 60 * 60 * 24 * 7,
 	});
 
+	if (sessionToken) {
+		// kc_access_token — HttpOnly; solo el server lo usa para llamar al Hub.
+		cookies.set('kc_access_token', kcAccessToken, {
+			path: '/', httpOnly: true, secure: isProduction, sameSite: 'lax', maxAge: 60 * 60 * 24 * 7,
+		});
+		if (typeof tokens.session_id === 'string') {
+			cookies.set('crm_sid', tokens.session_id, {
+				path: '/', httpOnly: true, secure: isProduction, sameSite: 'lax', maxAge: 60 * 60 * 24 * 30,
+			});
+		}
+	}
+
 	// refresh_token — HttpOnly (never exposed to JS)
 	if (typeof tokens.refresh_token === 'string') {
 		cookies.set('refresh_token', tokens.refresh_token, {