---
audiencia: usuario
screen_key: importaciones
aliases: [importaciones, importacion, importación, embarque, embarques, despacho, despacho aduanero, chasis, vin, autos, vehiculos, vehículos, escribania, escribanía, transferencia, cedula verde, cédula verde, chapa, prorrateo, costeo, fob, cif, ncm, isc, iva importacion, arancel, recostificacion, recostificación, sellado, korea, japon, japón, mercaderia del exterior, mercadería del exterior, factura del exterior, proveedor del exterior, consumo masivo, china, cotizacion importacion, cotización importación, liberar al deposito, liberar al depósito, importaciones en curso, cuenta puente, anticipo de despacho, anticipo al proveedor, cierre de importacion, cierre de importación, ire, retencion ire]
titulo: Importaciones
---

# Importaciones — Guía para el Usuario

> **¿Solo querés cargar/ingresar stock sin pasar por Importaciones?** Importaciones NO es la vía. Andá a **Productos → pestaña "Ajuste"** (tipo **Entrada**) para sumar stock a mano; ver `guia-inventario.md` §7 "Ajuste de Stock".

Esta guía cubre el módulo **Importaciones**: gestión del expediente de una importación desde el origen (subasta / proveedor extranjero) hasta el alta del vehículo en stock. En **v1 está activo el perfil AUTOS** (autos importados de Corea / Japón); el modelo de datos nace preparado para el perfil **CONSUMO_MASIVO** (China) sin cambios estructurales.

> ### Estado de implementación (v1)
>
> **Implementado y operativo:**
> - Expediente de embarque (cabecera) con máquina de estados BORRADOR → EN_TRANSITO → ARRIBADO → EN_DESPACHO → DESPACHADO → LIBERADO → CERRADO → SELLADO.
> - Ítems (perfil AUTOS: un chasis = un ítem), con recálculo de costo.
> - Componentes de costo con prorrateo (FOB / PESO / CBM / CANTIDAD / IGUAL) y costeo en tiempo real.
> - Despacho aduanero como entidad (BORRADOR → Confirmar) con generación de asiento contable.
> - Liberación al depósito: en AUTOS crea un producto por chasis; en **CONSUMO_MASIVO suma el stock al producto ya mapeado** en cada ítem (2026-09).
> - **Factura de mercadería del exterior** vinculada al embarque desde Compras, con su CxP y su costo FOB (2026-09).
> - **IVA del despacho en el Libro IVA de compras** como crédito fiscal (2026-09).
> - Generación de CxP desde un componente de costo.
> - Configuración operativa: activar el módulo y elegir **perfil activo** (AUTOS / CONSUMO_MASIVO).
> - **Conceptos de costo**: CRUD completo (catálogo sistema + por empresa), pantalla propia.
> - **Tabla ISC de vehículos**: CRUD completo, pantalla propia.
> - Bitácora del expediente.
>
> ⚠️ **Ojo con instrucciones tipo "andá a Configuración → Importaciones → Conceptos de costo/Tabla ISC"**: esa ruta de menú **no existe**. La única pantalla de Configuración → Importaciones tiene dos campos (switch "Módulo operativo activo" y selector "Perfil activo"), nada de conceptos ni ISC. **Ambos catálogos viven como tabs dentro del propio módulo Importaciones** (`/importaciones`, junto a la tab "Embarques"), no en Configuración. Ver sección *"¿Dónde encuentro esto en el menú?"* más abajo para la ruta exacta.
>
> **Modelado pero NO implementado aún (roadmap):** las secciones marcadas con ⚠️ más abajo — **Escribanías y trámites de transferencia**, **sincronización automática con Ventas** (estado VENDIDO) y **reportes del módulo**. Se documentan como diseño previsto, no como funcionalidad disponible.
>
> El perfil **CONSUMO_MASIVO** dejó de ser roadmap: el circuito completo (factura del exterior → costo → despacho → stock) está implementado. Ver `plan-importacion-mercaderia-exterior.md`.

---

## ¿Dónde encuentro esto en el menú?

- **Importaciones** (módulo propio, `/importaciones`): al entrar, una barra de tabs en la parte superior con tres opciones:
  - **Embarques** (default): lista de embarques. Al abrir uno, el detalle tiene sus propias tabs internas:
    - **Información** (cabecera).
    - **Ítems** (vehículos por chasis).
    - **Costos** (componentes de costo, incluidos los ajustes posteriores al cierre).
    - **Despacho** (liquidación aduanera).
    - **Bitácora** (histórico de cambios).
    - ⚠️ **Trámites** (transferencias) — tab presente pero deshabilitada ("Trámites · próx. fase"), *roadmap, no implementado en v1*.
  - **Conceptos de costo**: catálogo de qué tipos de gastos pueden aparecer en un embarque (alta, edición y desactivación). Solo se pueden editar/desactivar los conceptos propios de la empresa — los del sistema (`es_sistema = true`) son de solo lectura. Permiso `IMP_CFG_CONFIG_EDITAR`.
  - **Tasas ISC vehículos**: rangos cilindrada + año → tasa % (alta, edición y eliminación). Mismo criterio: solo los propios de la empresa son editables. Permiso `IMP_CFG_CONFIG_EDITAR`.
- **Configuración → Importaciones**: pantalla aparte, con solo dos campos — switch **"Módulo operativo activo"** y selector **"Perfil activo"** (AUTOS / CONSUMO_MASIVO). **No tiene conceptos de costo ni tasas ISC** — esos viven dentro del módulo Importaciones (ver arriba).
  - ⚠️ **SLA / Maestro de escribanías** — *roadmap, no implementado en v1 (ni backend ni frontend)*.

---

## Conceptos generales

### Expediente de importación

Cada importación es un **embarque** con cabecera (proveedor, ruta, fechas, modalidad) y dentro:

- **Ítems** (en perfil AUTOS, un ítem = un chasis / vehículo).
- **Componentes de costo** (FOB, fletes, seguros, gastos en aduana, tributos del despacho, gastos extras).
- **Despacho** (liquidación aduanera).
- **Trámites de transferencia** (uno por venta).

### Estados del embarque

```
BORRADOR ─▶ EN_TRANSITO ─▶ ARRIBADO ─▶ EN_DESPACHO ─▶ DESPACHADO ─▶ LIBERADO ─▶ CERRADO ─▶ SELLADO
```

| Estado | Significa | Acción que disparó |
|--------|-----------|---------------------|
| **BORRADOR** | Cargando datos. Editable. | Se crea el expediente. |
| **EN_TRANSITO** | "Embarcado" — salió del origen. | Click "→ Embarcado". |
| **ARRIBADO** | "Marcado como llegado" al puerto destino. | Click "→ Marcado como llegado". |
| **EN_DESPACHO** | El despachante está procesando. | Click "→ Iniciar despacho". |
| **DESPACHADO** | Confirmado el despacho con tributos. Asiento contable generado. | Botón "Confirmar despacho" en el tab Despacho. |
| **LIBERADO** | "Liberar al depósito" — **crea producto en `productos`** por cada chasis, con `código = chasis`, stock = 1, costo = calculado. | Click "→ Liberar al depósito". |
| **CERRADO** | Expediente cerrado para nuevos costos normales. | Click "→ Cerrar expediente". |
| **SELLADO** | 🔒 Bloqueado definitivo (estado terminal). | Cambio de estado CERRADO → SELLADO con `IMP_EMB_EMBARQUE_EDITAR`. |

### Estados del ítem (vehículo)

Implementado en v1 (default del ítem: **`PENDIENTE`**):

```
PENDIENTE ─▶ EN_TRANSITO ─▶ ARRIBADO ─▶ DISPONIBLE
```

- El ítem acompaña las transiciones del embarque (EN_TRANSITO, ARRIBADO).
- **DISPONIBLE** se setea al **liberar** el embarque al depósito.

> ⚠️ **Roadmap (no implementado en v1)**: los estados **RESERVADO / VENDIDO / ENTREGADO** dependen de la sincronización automática con Ventas y del flujo de escribanías, todavía no implementados. Hoy no hay nada que mueva el ítem a VENDIDO al facturar.

### Permisos del módulo (`IMP_*`)

El módulo `IMPORTACIONES` agrupa privilegios en submódulos (`IMP_EMBARQUES`, `IMP_COSTOS`, `IMP_DESPACHOS`, `IMP_CONFIG`, `IMP_REPORTES`) con códigos de privilegio de 3 niveles `IMP_<GRUPO>_<ENTIDAD>_<ACCIÓN>`:

| Código | Para qué |
|--------|----------|
| `IMP_EMB_EMBARQUE_VER` | Ver embarques, ítems y bitácora; buscar productos para vincular. |
| `IMP_EMB_EMBARQUE_CREAR` | Crear embarques. |
| `IMP_EMB_EMBARQUE_EDITAR` | Editar cabecera, cambiar estado (incluye **sellar**) y editar ítems en estados editables. |
| `IMP_EMB_EMBARQUE_ELIMINAR` | Eliminar embarque (soft delete). |
| `IMP_EMB_EMBARQUE_CERRAR` | **Liberar al depósito** (DESPACHADO → LIBERADO). |
| `IMP_COS_COSTO_VER` | Ver conceptos y componentes de costo. |
| `IMP_COS_COSTO_CREAR` | Crear componentes de costo. |
| `IMP_COS_COSTO_EDITAR` | Editar / eliminar componentes y **generar CxP** desde un componente. |
| `IMP_DES_DESPACHO_VER` | Ver el despacho aduanero. |
| `IMP_DES_DESPACHO_CREAR` | Crear despacho (BORRADOR). |
| `IMP_DES_DESPACHO_EDITAR` | Editar despacho (sólo BORRADOR). |
| `IMP_DES_DESPACHO_ELIMINAR` | Eliminar despacho (sólo BORRADOR). |
| `IMP_DES_DESPACHO_PROCESAR` | **Confirmar despacho** (congela cotización, inserta tributos, dispara asiento). |
| `IMP_CFG_CONFIG_VER` | Ver configuración operativa, conceptos de costo y tasas ISC. |
| `IMP_CFG_CONFIG_EDITAR` | Editar configuración operativa, conceptos de costo y tasas ISC. |
| `IMP_REP_REPORTE_VER` / `IMP_REP_REPORTE_EXPORTAR` | ⚠️ Reservados para reportes — sin endpoints en v1. |

> No existen los permisos `IMP_SELLAR_COSTO` ni `IMP_GESTIONAR_ESCRIBANIAS` (versiones previas de esta guía los mencionaban). **Sellar** un embarque cerrado se hace con `IMP_EMB_EMBARQUE_EDITAR` vía cambio de estado CERRADO → SELLADO.

---

## Configuración del módulo (paso obligatorio antes de operar)

Hay dos pantallas separadas — es fácil confundirlas porque las dos dicen "configuración" pero están en lugares distintos del menú:

**Configuración → Importaciones** (pantalla de Configuración general del sistema), con dos campos:

- **Módulo operativo activo** (switch): si está apagado, nadie puede crear ni editar embarques aunque tenga permisos.
- **Perfil activo**: AUTOS o CONSUMO_MASIVO. El cambio se bloquea si hay embarques activos del perfil actual — hay que cerrarlos antes.
- **Criterio de cotización**: con qué tipo de cambio se valoriza la mercadería importada. Tres opciones: la **fecha de la factura** del proveedor (default), la **fecha del despacho** o la **cotización de cierre del embarque**. Es criterio contable: definilo con tu contador antes de cargar importaciones en dólares, porque cambia el costo unitario final del stock. Si elegís una opción cuyo dato todavía no existe —por ejemplo la del despacho cuando la factura se carga antes—, el sistema usa la de la factura en vez de valorizar a cotización 1.

Permiso: `IMP_CFG_CONFIG_EDITAR` (ver también `ADM_IMC_CONFIG_EDITAR`, el que efectivamente valida esta pantalla).

**Importaciones → tabs "Conceptos de costo" y "Tasas ISC vehículos"** (dentro del propio módulo, junto a la tab "Embarques") — acá están los catálogos operativos:

### A) Conceptos de costo

Catálogo de qué tipo de gastos pueden aparecer en un embarque. El formulario de alta/edición pide: código (único por empresa, mayúsculas/números/guion bajo), nombre, grupo (ORIGEN/TRANSITO/ADUANA/LOGISTICA/FINANCIERO, opcional), moneda default (USD/GS), imputación (DIRECTO/COMPARTIDO) y criterio de prorrateo default (solo habilitado si la imputación es COMPARTIDO).

- **Alta / edición / desactivación** desde la tab **Conceptos de costo**. Permiso `IMP_CFG_CONFIG_EDITAR`. La desactivación pide confirmación (diálogo estándar del sistema, no un `confirm()` del navegador).
- Los conceptos del **sistema** (`es_sistema = true`, sin `empresa_id`) son de **solo lectura** — no se pueden editar ni desactivar, están marcados con el chip "Sistema" en la tabla.
- Los conceptos **propios de la empresa** se pueden editar y desactivar (chip "Empresa"). Desactivar no borra histórico, solo saca el concepto de la lista para nuevos costos.
- Estos conceptos (sistema + empresa) son los que aparecen en el dropdown al cargar un componente de costo (tab **Costos** del embarque).
- **No hay selector de "perfil aplicable" en el formulario.** La tabla muestra una columna **Perfil** (informativa: Autos / Consumo masivo / Ambos) porque el modelo de datos la soporta y algunos conceptos del **sistema** están restringidos a un perfil — pero a propósito **no se ofrece como opción al crear o editar un concepto de empresa**: una empresa solo puede tener un perfil activo a la vez (ver "Configuración del módulo" arriba — el cambio de perfil se bloquea mientras haya embarques activos del perfil actual), así que pedirle a la empresa "¿para qué perfil es este concepto?" no tiene sentido práctico. Los conceptos nuevos de empresa quedan siempre con perfil "Ambos".

### B) Tabla ISC (vehículos)

Rangos que devuelven una tasa ISC sugerida según **cilindrada (cc) + año del modelo**:

| Año desde | Año hasta | cc desde | cc hasta | Tasa ISC % | Descripción |
|-----------|-----------|----------|----------|------------|-------------|
| 2020 | 2030 | 1001 | 2000 | 5,00 % | Sedanes 1001-2000cc |

Vigencia con `vigente_desde` y `vigente_hasta` (vacío = abierta). Alta / edición / eliminación desde la tab **Tasas ISC vehículos**. Igual criterio que conceptos: las tasas del sistema (`empresa_id` nulo) son de solo lectura, las de la empresa se pueden editar/eliminar (con confirmación) — permiso `IMP_CFG_CONFIG_EDITAR`.

### C) Maestro de escribanías y D) SLA — ⚠️ roadmap (no implementado en v1)

El diseño previsto incluye un maestro de escribanías (razón social, escribano titular, RUC, matrícula, tarifario) y una configuración de SLA por sub-trámite. **Ninguno está implementado en v1**: no hay tablas, endpoints ni pantallas de escribanías. Ver la sección *"Escribanías y trámites"* más abajo para el detalle del roadmap.

---

## Alta de embarque (cabecera)

El formulario está agrupado por bloques (UX estándar):

| Bloque | Campos |
|--------|--------|
| **Proveedor y origen** | Proveedor (extranjero), Moneda, País de origen (KR / JP / CN / …). |
| **Ruta y logística** | Puerto origen, Puerto destino (campo libre, sin default — el placeholder sugiere "Villeta, Asunción"), **Modalidad** (RoRo / FCL 20' / FCL 40' / FCL 40' HC / LCL), Booking, Bill of Lading. |
| **Fechas** | Fecha de embarque, **ETA** (estimada de arribo), Arribo real. |
| **Notas** | Texto libre (visible solo en edición). |

El proveedor extranjero se carga desde **Contactos → Proveedores** con los campos extendidos (`país`, `SWIFT`, `banco corresponsal`, `es_extranjero`). La cotización de cierre **NO se carga acá**: se congela al cerrar el despacho.

---

## Ítems del embarque (perfil AUTOS)

Cada ítem es un vehículo. Formulario agrupado:

| Bloque | Campos |
|--------|--------|
| **Identificación** | **Chasis (VIN)** — 17 caracteres alfanuméricos, único, **se convierte en el código del producto**; Motor; Marca; Modelo; Año. |
| **Especificaciones** | Versión; Cilindrada (cc); Color; Kilometraje; N° de dueños anteriores (0 = 0 km). |
| **Origen y precio** | **FOB unitario USD**; Inland origen USD (flete interno hasta puerto); Lote de subasta. |

Validaciones de UI:
- **Chasis** con contador de caracteres en tiempo real `(X/17)`, rojo si no llega.
- **Año** entre 1900 y año actual + 1.
- **Cilindrada** > 0 si se completa.
- **FOB unitario** > 0.

> El precio FOB de cada chasis es la **base** sobre la que se prorratean los costos compartidos cuando el criterio elegido es FOB.

---

## Ítems del embarque (perfil CONSUMO_MASIVO)

| Bloque | Campos |
|--------|--------|
| **Identificación** | SKU del proveedor, **SKU interno mapeado** (a `productos`), descripción de origen. |
| **Logística** | Cantidad, Unidad (PCS / PAR / SET / CJ / KG), Peso unitario kg, CBM unitario (m³). |
| **Comercio exterior** | FOB unitario USD, **NCM** (Nomenclatura Común del Mercosur), Arancel %, ISC %. |

El **mapeo de SKU del proveedor → SKU interno** se memoriza en `imp_sku_alias_proveedor`: la siguiente importación con el mismo proveedor + SKU se resuelve automáticamente.

> ⚠️ **El SKU interno es obligatorio para liberar.** A diferencia de AUTOS, acá el sistema **no crea productos**: el mismo SKU se repite entre embarques y crear uno por importación llenaría el catálogo de duplicados. Si algún ítem queda sin mapear, la liberación se rechaza entera y te dice cuáles faltan — no entra media carga al depósito.

---

## Componentes de costo

Cada gasto del embarque se carga como un componente. Formulario por bloques:

| Bloque | Campos |
|--------|--------|
| **¿Qué costo es?** | Concepto (catálogo) o descripción libre, Moneda. |
| **¿De quién?** | Proveedor (opcional), N° de factura. |
| **¿Cómo se aplica?** | Toggle **"Costo directo a un ítem"** (si se activa, eligir el ítem) o **Criterio de prorrateo** (FOB / PESO / CBM / CANTIDAD / Partes iguales). |
| **Fechas** | **Devengo** (cuándo se generó la obligación, ej. fecha factura), **Pago** (cuándo se pagó o se va a pagar). |
| **Importe** | Importe en la moneda elegida + **Cotización** (sugerida desde `cont_tipo_cambio`) → calcula `Importe Gs.`. |
| **Extras** | Toggle **"Gasto extra de gestión"** con motivo obligatorio (queda auditado). |

### Criterios de prorrateo

| Criterio | Distribuye según |
|----------|------------------|
| **FOB** | Valor FOB de cada ítem. |
| **PESO** | Peso unitario × cantidad. |
| **CBM** | Volumen en m³ de cada ítem. |
| **CANTIDAD** | Cantidad de unidades. |
| **Partes iguales** | Mismo monto por ítem. |

### Factura de mercadería del exterior

La factura del proveedor del exterior **se carga desde Compras**, no desde acá, y se vincula al embarque con el selector **«Factura de importación»** de la cabecera. Al guardarla, el sistema arma solo:

- El **componente de costo FOB** del embarque, con el importe y la cotización de la factura.
- La **cuenta por pagar** al proveedor, si la compra es a crédito (sale por el flujo normal de compras).

**Tres cosas que esta factura NO hace, y son a propósito:**

| | Por qué |
|---|---|
| **No va al Libro IVA de compras** | No es comprobante paraguayo. El IVA de esa importación se paga en aduana y se declara con el **despacho**, que sí entra al libro. Si entrara también la factura, la base gravada se contaría dos veces. |
| **No mueve stock al cargarla** | La mercadería entra al depósito recién al **liberar** el embarque, con el costo prorrateado completo. Si entrara también acá, se duplicarían las unidades y quedarían valorizadas solo al FOB, sin flete ni tributos. |
| **No se contabiliza dos veces** | La compra genera su propio asiento; el asiento de cierre del despacho excluye los costos que ya tienen su comprobante cargado. |

#### Regularizar un FOB cargado a mano

Si el costo de la mercadería ya se había tipeado a mano como componente y después aparece la factura, **no cargues la factura aparte**: se duplicaría el costeo. Usá el botón de la fila del costo en la tab **Costos** del embarque — en el FOB lleva a **Compras** (y en el resto de los conceptos, a **Gastos**), con proveedor, número de factura y moneda ya precargados. Al guardar, la factura **toma ese componente existente** en vez de crear otro, y el importe pasa a ser el del comprobante, que es el dato con respaldo.

Un costo que ya tiene comprobante muestra un chip (**Factura** o **Gasto**) en vez del botón, y el sistema rechaza intentar vincularle un segundo comprobante.

---

### Generar CxP desde un componente

Al confirmar el componente se puede generar la **Cuenta por Pagar** correspondiente en `cuentas_pagar` con `embarque_id` para que quede trazado (endpoint `POST /importaciones/embarques/:id/costos/:costoId/generar-cxp`). El pago se hace después desde **Compras → Orden de Pago**.

### Gastos extras de gestión

- Administración los carga manualmente.
- **Motivo obligatorio** (texto libre).
- Quedan auditados en la bitácora.
- No tienen flujo de aprobación formal.
- Si se cargan **después del cierre** del despacho, **disparan recostificación** (ver sección).

---

## Algoritmo de costeo (en tiempo real)

Para cada ítem `i` el sistema calcula:

```
Costo_unitario_i [Gs.] = Σ(directos_i × cotización) + Σ(compartido_k × cot_k × f_i_k)
```

Donde `f_i_k = Base_i / ΣBase` según el criterio del componente (FOB, PESO, CBM, CANTIDAD o IGUAL).

- El cálculo se hace **en memoria** mientras se editan costos → la pantalla muestra el costo unitario actualizado al instante.
- Se persiste en `imp_embarque_items.costo_unitario_gs` **al cerrar el despacho**.
- Cada componente puede tener su propia **cotización** (sugerida desde `cont_tipo_cambio`, editable). Eso permite el modelo **híbrido multi-moneda**: cada gasto se valoriza con el TC del día en que se devengó.
- Al cerrar el despacho, las cotizaciones quedan **congeladas**.

---

## Despacho aduanero

Tab dedicado en el detalle del embarque. Datos:

| Bloque | Campos |
|--------|--------|
| **Cabecera** | Nº de despacho, fecha, despachante (proveedor). |
| **Impuestos principales** | Arancel, IVA Importación, ISC. |
| **Impuestos adicionales** | INC (Impuesto No Contribuyente), Anticipo IRE, Tasa ANA, Otros tributos. |
| **Total** | `total_tributos_gs` calculado, sticky en el pie del panel. |

### Tooltips obligatorios

| Tributo | Significa |
|---------|-----------|
| **Arancel** | Derecho aduanero según el NCM. |
| **IVA Importación** | IVA aplicado en aduana (10 % del CIF típicamente). |
| **ISC** | Impuesto Selectivo al Consumo — ver Tabla ISC. |
| **INC** | Impuesto a la No Contribuyente. |
| **Anticipo IRE** | Anticipo del Impuesto a la Renta Empresarial. |
| **Tasa ANA** | Tasa de la Administración Nacional de Aduanas. |

### Cotización del despacho

El sistema sugiere el TC del día (`cont_tipo_cambio`). Al **Confirmar despacho** la cotización queda **congelada** en `cotizacion_usada` y deja de poder editarse desde acá.

### Ciclo del despacho (entidad)

El despacho es una **entidad** dentro del embarque (`imp_despachos`), no solo campos sueltos:

1. **Crear** (`POST …/despachos`) — queda en **BORRADOR**. Solo se permite cuando el embarque está en **ARRIBADO** o **EN_DESPACHO**; si estaba en ARRIBADO, el embarque pasa automáticamente a **EN_DESPACHO**.
2. **Editar / eliminar** (`PATCH` / `DELETE`) — solo mientras el despacho está en BORRADOR.
3. **Confirmar** (`POST …/despachos/:id/confirmar`) — requiere que el embarque esté en **EN_DESPACHO**.

### Confirmar despacho

Acción **irreversible** (el sistema avisa con alert antes). Al confirmar:

1. **Congela la cotización** usada.
2. **Inserta los tributos como componentes de costo** y **recalcula** los costos de los ítems.
3. Estado del embarque → **DESPACHADO**.
4. Genera el **asiento contable** (vía `ContabilidadIntegracionService`).
5. El **IVA importación pasa a figurar en el Libro IVA de compras** del mes del despacho, como crédito fiscal. Es el único comprobante de esa importación que se declara: la factura del proveedor del exterior no va al libro.
6. Quedan disponibles los botones para liberar al depósito.

> En v1 hay **un despacho por embarque**. No hay despachos parciales.

---

## El circuito contable de la importación

> Aplica sólo si la empresa **mapea la cuenta `IMPORTACIONES_EN_CURSO`**. Sin ese mapeo el sistema sigue con el asiento de siempre: al confirmar el despacho, el costo va directo a Inventario contra el proveedor. Configurarlo es lo que activa todo lo de esta sección.

La idea: la importación **no toca inventario hasta que se cierra**. Mientras dura, todo lo que se va gastando se acumula en una cuenta puente —«Importaciones en curso»— y recién al cerrarla se descarga contra mercaderías.

### Los pagos al proveedor y al despachante

Se cargan desde **Tesorería y Bancos → Egreso**. En el diálogo, el bloque *«Imputar a una importación»* permite elegir el embarque y qué cubre el pago:

| Qué cubre | A dónde va | Cuándo se consume |
|---|---|---|
| **Pago al proveedor del exterior** | Directo a **Importaciones en curso** | Ya es costo desde que sale |
| **Anticipo de despacho** | A **Anticipos de despacho** | Se aplica al confirmar el despacho |

Se admite **un solo pago de cada tipo por importación**. Si necesitás reemplazar uno, anulá el anterior primero.

El sobrante del anticipo de despacho —lo que se anticipó de más— **queda como saldo en la cuenta de anticipos**. No se suma al costo ni pasa a otra importación.

### Qué genera cada paso

| Paso | Asiento |
|---|---|
| Pago al proveedor | Debe *Importaciones en curso* · Haber *Banco* |
| Anticipo de despacho | Debe *Anticipos de despacho* · Haber *Banco* |
| Facturas del exterior y gastos | Debe *Importaciones en curso* · Haber según el comprobante |
| Confirmar el despacho | Debe *Importaciones en curso* (tributos que son costo) · Debe *IVA crédito* · Debe *Retenciones de renta* (el IRE) · Haber *Anticipos de despacho* |
| **Cerrar la importación** | Debe *Mercaderías* · Haber *Importaciones en curso* |

### Dos cosas que no son costo

**El IVA importación** es crédito fiscal: va a su cuenta y al Libro IVA, no al costo de la mercadería.

**El anticipo de IRE** es impuesto a la renta. Sale del costo y del prorrateo, y va a *Retenciones de renta a favor*. Si el concepto de costo tiene el switch **«afecta al costo»** apagado, se comporta igual — es el mismo mecanismo.

---

## Liberación al depósito

Click en **"→ Liberar al depósito"** desde el embarque DESPACHADO. El depósito destino **se elige en cada liberación**, no está fijo por empresa.

**Perfil AUTOS** — por cada ítem se **crea un producto** en `productos`:
   - `código` = chasis, `stock` = 1, `costo` = `costo_unitario_gs` calculado.

**Perfil CONSUMO_MASIVO** — por cada ítem se **suma stock al producto ya mapeado** (SKU interno):
   - Se incrementa `stock_deposito` en el depósito elegido.
   - Se registra el movimiento de inventario con el embarque como documento de origen.
   - El costo que va al kardex es el **prorrateado** (FOB + flete + seguro + tributos), no el FOB solo.

En ambos casos: estado del embarque → **LIBERADO**, estado de cada ítem → **DISPONIBLE**, y la mercadería queda lista para facturarse desde Ventas / POS.

> **Antes de escribir nada, la liberación valida todo.** Si hay ítems sin producto mapeado, con cantidad en cero o con productos inexistentes, se rechaza la operación completa y no se toca el inventario. Es a propósito: liberar no se puede deshacer desde la pantalla, y un embarque a medias dejaría stock inconsistente sin forma de rehacerlo.

---

## Sincronización con Ventas — ⚠️ roadmap (no implementado en v1)

Diseño previsto: al emitir una factura de venta cuyo ítem es un producto que existe como chasis, el sistema cambiaría el estado del ítem del embarque a **VENDIDO**, lo vincularía a la factura y habilitaría el trámite de transferencia.

**En v1 esto NO está implementado.** El producto creado al liberar (código = chasis) se vende como cualquier producto, pero el ítem del embarque **no** cambia a VENDIDO ni se vincula a la factura (`imp_embarque_items` no tiene `factura_venta_id`). El vehículo, una vez liberado, se factura desde Ventas / POS como producto normal.

---

## Escribanías y trámites de transferencia — ⚠️ roadmap (no implementado en v1)

Todo lo de esta sección es **diseño previsto para una versión futura**. En v1 **no hay** tablas, endpoints, permisos ni pantallas de escribanías/trámites: nada de esto está operativo.

Diseño previsto (referencia, no disponible aún):

- Un **trámite de transferencia** por chasis vendido, con tipos TRANSFERENCIA / TRANSFERENCIA_PRENDA (contrato prendario) / PRIMERA_INSCRIPCION (0 km).
- **Asignación** de escribanía (del maestro) o ad-hoc con motivo, congelando el honorario del tarifario.
- **Checklist** de sub-trámites con fechas (asignación, firma, inscripción RACPR, gestión de chapa, cédula verde, entrega de documentos) y estado general ASIGNADO → EN_CURSO → FIRMADO → INSCRITO → ENTREGADO.
- **SLA** por sub-trámite con semáforo y `alerta_sla`.

Cuando se implemente, el flujo se disparará **desde Importaciones** (no desde Facturación) y dependerá de la sincronización con Ventas (también roadmap).

---

## Recostificación (ajuste de costo posterior al cierre)

Permite cargar un gasto **después** de que el embarque está CERRADO sin tener que reabrirlo, dejando el rastro del ajuste.

Cómo funciona en v1:

- Se carga como un **componente de costo normal**. El flag `es_posterior_cierre` se marca **automáticamente** cuando el embarque está en **CERRADO** o **SELLADO** (o se puede forzar en el DTO).
- El componente entra en el **recálculo de costos** del embarque como cualquier otro.
- No hay una tabla `imp_recostificaciones` dedicada ni un asiento de ajuste automático propio: el componente queda en `imp_componentes_costo` marcado como posterior al cierre, y se lo identifica por ese flag y por la bitácora.
- Sobre un embarque **SELLADO**, cargar/editar costos requiere `IMP_EMB_EMBARQUE_EDITAR` (SELLADO es el estado terminal; ver máquina de estados).

> Nota: la persistencia del costo unitario al **producto** ocurre en la liberación/despacho. Un ajuste posterior al cierre queda registrado como componente `es_posterior_cierre` y recalcula el costo del embarque; verificá el impacto en el costo del producto ya liberado antes de asumir que se propagó solo.

---

## Reportes — ⚠️ roadmap (no implementado en v1)

Los permisos `IMP_REP_REPORTE_VER` / `IMP_REP_REPORTE_EXPORTAR` están **reservados** en el seed de seguridad, pero **no hay endpoints de reportes** en el módulo (`ImportacionesController` no expone ninguno). Los siguientes reportes están previstos pero no disponibles:

| Reporte (previsto) | Qué mostraría |
|--------------------|---------------|
| **Liquidación de embarque** | Costos por ítem, prorrateos, tributos del despacho, costo unitario final |
| **Embarques por estado** | Conteos por estado del flujo |
| **Costo promedio** | Por marca / modelo / período |
| **% Gastos extras / FOB** | Peso de los "gastos no previstos" por embarque |
| **Trámites por estado / SLA** | (Depende de escribanías, también roadmap) |

Mientras tanto, el costo por ítem y los prorrateos se ven en el **detalle del embarque** (tab Costos), calculados en tiempo real.

---

## Bitácora del expediente

La pestaña **Bitácora** es un historial automático y de solo lectura. Registra quién realizó cada acción, cuándo ocurrió y qué datos funcionales cambiaron.

- Las ediciones muestran **campo, valor anterior y valor nuevo**.
- Proveedores, monedas, conceptos, ítems y depósitos aparecen por su nombre o identificación comercial.
- Los eventos históricos que no guardaron el valor anterior se muestran como **"No registrado"**.
- Los identificadores técnicos internos no se muestran en esta pantalla.
- Si una referencia histórica ya no está disponible, se informa **"Referencia no disponible"** sin exponer datos técnicos.

El detalle técnico original se conserva internamente para auditoría, pero no forma parte de la respuesta visible para usuarios del módulo.

---

## Integraciones con el resto del ERP

| Módulo | Cuándo se integra | Qué hace |
|--------|-------------------|----------|
| **Contactos → Proveedores** | Alta de embarque y de componente | Reutiliza `proveedores` con campos extendidos (país, SWIFT, banco corresponsal). |
| **Contabilidad → Tipo de Cambio** | Carga de componente USD | Sugiere la cotización del día. |
| **Contabilidad → Asientos** | Confirmar despacho, recostificación | Asiento automático vía `ContabilidadIntegracionService`. |
| **Cuentas por Pagar** | Al generar CxP desde un componente | Crea registro en `cuentas_pagar` con `embarque_id`. Se paga desde **Compras → Orden de Pago**. |
| **Productos / Inventario** | Al liberar al depósito | Crea producto con `código = chasis`, stock 1, costo calculado. |
| **Facturación** | ⚠️ Roadmap | *Previsto*: cambiar el ítem a VENDIDO al facturar. No implementado en v1. |
| **Configuración → Importaciones** | Módulo activo + perfil | Solo esos dos campos. |
| **Importaciones → tabs Conceptos de costo / Tasas ISC** | Catálogos operativos | CRUD completo, ver sección "Configuración del módulo" más arriba. |

---

## UX y componentes estándar

- `SectionDivider` — separador visual con label dentro de formularios largos (agrupa campos por bloque).
- `InfoTooltip` — ícono `?` con explicación para campos técnicos (NCM, FOB, CBM, ISC).
- `StateChip` — chips de estado con colores semánticos:

| Estado | Color |
|--------|-------|
| BORRADOR | gris |
| EN_TRANSITO | azul |
| ARRIBADO | azul oscuro |
| EN_DESPACHO | naranja |
| DESPACHADO | amarillo |
| LIBERADO | verde claro |
| CERRADO | verde |
| SELLADO | verde oscuro + 🔒 |

- `NextStepAlert` — panel "Próximo paso" en el header del detalle, indica la acción esperada según el estado.
- Botones de transición traducidos al lenguaje de negocio (no enums internos): "→ Embarcado", "→ Marcado como llegado", "→ Iniciar despacho", "→ Liberar al depósito", "→ Cerrar expediente", "→ Sellar".
- Alert de irreversibilidad antes de **Confirmar despacho** y antes de **Sellar**.

---

## Validaciones del backend (mensajes que pueden aparecer)

### Embarque

- **"Proveedor extranjero es obligatorio"**.
- **"Modalidad inválida"** (solo RoRo, FCL 20', FCL 40', FCL 40' HC, LCL).
- **"No se puede eliminar un embarque sellado"**.
- Cambios de estado fuera de la máquina de estados (transición no permitida).

### Ítems

- **"Chasis (VIN) debe tener 17 caracteres alfanuméricos"**.
- **"Chasis ya existe en otro embarque"** (índice único).
- **"Año inválido"** (entre 1900 y año actual + 1).
- **"FOB unitario debe ser mayor a 0"**.
- **"No se puede modificar el ítem: el embarque ya fue LIBERADO"**.

### Costos

- **"Los costos directos requieren item_id"** / **"El ítem indicado no pertenece al embarque"**.
- **"Los costos compartidos requieren criterio de prorrateo"**.
- **"Los gastos extras requieren un motivo obligatorio"**.
- **"Concepto de costo inválido"** / **"Componente de costo no encontrado"**.

### Despacho

- **"El embarque ya tiene un despacho cargado"** (un despacho por embarque).
- **"Solo se puede crear despacho cuando el embarque está en ARRIBADO o EN_DESPACHO (actual: …)"**.
- **"Despachante inválido para la empresa"**.
- **"Solo se puede modificar/eliminar un despacho en BORRADOR"**.
- **"Solo se puede confirmar un despacho en estado BORRADOR"** / **"Para confirmar el despacho el embarque debe estar en EN_DESPACHO (actual: …)"**.

### Embarque / estado

- **"No se puede eliminar un embarque sellado"**.
- Transición de estado no permitida por la máquina de estados (ej. saltear pasos, o cualquier salida desde SELLADO, que es terminal).

> Los ajustes posteriores al cierre se cargan como componentes con `es_posterior_cierre` (ver Recostificación); **no** hay validaciones de escribanías/trámites en v1 (roadmap).

---

## Lo que NO se puede hacer

- Cargar dos chasis iguales en el mismo embarque ni en uno distinto (VIN/chasis es único por empresa).
- Editar / eliminar un despacho que no esté en BORRADOR.
- Confirmar el despacho dos veces (solo se confirma un despacho en BORRADOR; es irreversible).
- Liberar al depósito sin haber confirmado el despacho.
- Eliminar un embarque **SELLADO**.
- Salir del estado **SELLADO** (es terminal en la máquina de estados).
- Hacer despachos parciales o cargar más de un despacho por embarque (uno por embarque en v1).

---

## Problemas frecuentes

- **"El costo unitario me da 0"**: faltan componentes o el FOB del ítem es 0 — si el criterio de prorrateo es FOB y el ítem no tiene FOB, no recibe parte de los compartidos.
- **"Se cargó un costo después del cierre y el producto no actualizó su costo"**: el componente no se marcó como `es_posterior_cierre`. La recostificación es manual.
- **"No me deja crear el producto al liberar"**: el chasis ya existe en `productos` (probablemente un embarque previo). Revisar duplicidad.
- **"El asiento contable del despacho no se generó"**: la empresa no tiene módulo Contabilidad activo o faltan cuentas mapeadas (CxP / IVA Crédito Importación / etc.).
- **"El TC sugerido no aparece"**: no hay tipo de cambio cargado para la fecha del componente. Cargar manual o pedir al contador que cargue el día en Contabilidad → Tipo de Cambio.
- **"El sistema dice que no hay tasa ISC"**: el rango cc + año no está cubierto en la Tabla ISC. Ir a **Importaciones → tab "Tasas ISC vehículos"** y agregar el rango faltante (permiso `IMP_CFG_CONFIG_EDITAR`).
- **"Quiero modificar un embarque sellado"**: SELLADO es un estado **terminal** (no hay transición de salida en la máquina de estados). El sellado es la garantía de inmutabilidad del costo del producto vendido; si necesitás ajustar, la vía prevista son los componentes posteriores al cierre antes de sellar.

---

## Limitaciones actuales

- **CONSUMO_MASIVO ya opera** el circuito completo (factura del exterior → costo → despacho → stock, 2026-09). Lo que sigue pendiente es la **memoria del mapeo** SKU proveedor→interno (`imp_sku_alias_proveedor`): hoy hay que elegir el producto en cada ítem, no se recuerda del embarque anterior.
- **Escribanías y trámites de transferencia**: no implementados (sin tablas, endpoints ni permisos). Roadmap.
- **Sincronización con Ventas**: al facturar un chasis, el ítem del embarque no cambia a VENDIDO ni se vincula a la factura. Roadmap.
- **Reportes del módulo**: permisos reservados (`IMP_REP_REPORTE_*`) pero sin endpoints. Roadmap.
- **Un despacho por embarque** — no hay despachos parciales en v1.
- **Sin integración Sofia / MIC / DTA** (despachante carga manualmente los datos).
- **Sin parser automático del PDF del despachante**.
- **Sin tracking marítimo en tiempo real** (AIS): las fechas son manuales.
- **Sin firma digital con escribanía**.
- **Sin marketplace** de vehículos.
- **El despacho no va al export de Marangatu.** Su IVA aparece en el Libro IVA en pantalla y en el CSV, pero **no** en el archivo que se sube a la DNIT: falta confirmar con el contador el tipo de comprobante correcto, y poner uno equivocado ahí es peor que no tenerlo.
- **Decisiones abiertas con cliente**: costo específico por chasis vs. promedio ponderado para inventario; multi-moneda EUR; múltiples proveedores por SKU en v2; **criterio de cotización por defecto** para empresas que no lo configuren.

---

## Documentos relacionados

- `guia-compras.md` — el flujo de compra "tradicional" vs. el flujo de importación.
- `guia-contactos.md` — alta del proveedor extranjero y de las escribanías.
- `guia-contabilidad.md` — asientos del despacho y de la recostificación, tipo de cambio.
- `guia-cobros-finanzas.md` — generación de CxP y pago al proveedor extranjero / despachante.
- `guia-facturacion.md` — venta del vehículo (dispara el cambio de estado a VENDIDO).
- `guia-inventario.md` — el producto creado al liberar al depósito.
- `plan-importaciones-v1.md` — diseño funcional completo, modelo de datos, decisiones.
- `plan-importacion-mercaderia-exterior.md` — el circuito de mercadería del exterior: diseño, decisiones del cliente y qué falta.
- `plan-importaciones-fase2-contable.md` — el modelo contable con cuenta puente y anticipos.
- `plan-prueba-importaciones-circuito-contable.md` — guion de prueba del circuito completo, paso a paso.
- `qa-importacion-mercaderia-exterior.md` — pruebas de integración de ese circuito y el recorrido manual pendiente.
- `plan-prueba-usuario-importaciones.md` — guion paso a paso de pruebas.
- `plan-ux-mejoras-importaciones.md` — guion de mejoras UX (agrupación, helperText, tooltips, chips de estado, "próximo paso").