Generar Guía de Envío

Genere guías de envío directamente desde ALTUM ERP: cotice tarifas entre los carriers activos, seleccione la opción más conveniente y obtenga el número de rastreo y la etiqueta PDF en un solo flujo.

Requisitos y permisos

Requisito	Detalle
Permiso `paqueteria.cotizaciones_crear`	Permite acceder a la pantalla de cotización y generar guías
Al menos un carrier activo	Debe existir al menos una configuración de carrier activa (ver Configuración de Paqueterías)
Proveedor activo en el tenant	El sistema crea automáticamente un gasto logístico vinculado al primer proveedor activo del tenant

Pantalla principal

Acceda desde el módulo Paquetería → botón Nueva Cotización (esquina superior derecha).

También puede llegar aquí desde una venta usando el parámetro ?ventaId=<id> en la URL, lo que pre-vinculará la guía a esa venta.

La pantalla se divide en dos columnas (en dispositivos medianos o mayores):

Columna izquierda: formulario de cotización con los datos del paquete y destino.
Columna derecha: lista de tarifas disponibles o un aviso informativo mientras no se haya cotizado.

Campos del formulario de cotización

Campo	Descripción	Obligatorio
Código Postal destino	CP de 5 dígitos del destino	Sí
Ciudad	Ciudad del destino	Sí
Estado	Estado del destino	Sí
Peso (kg)	Peso real del paquete en kilogramos	Sí
Largo (cm)	Dimensión largo en centímetros	Sí
Ancho (cm)	Dimensión ancho en centímetros	Sí
Alto (cm)	Dimensión alto en centímetros	Sí
Valor declarado (MXN)	Valor declarado del contenido (opcional, para seguro)	No
Tipo de servicio	`Estándar`, `Express`, `Mismo día` o `Día siguiente`	Sí
ID de venta	Si viene de una venta, se pre-llena desde la URL	No

Tipos de servicio disponibles

Tipo	Etiqueta en pantalla	Velocidad
`STANDARD`	Estándar	Normal
`EXPRESS`	Express	Urgente
`SAME_DAY`	Mismo día	Inmediato
`NEXT_DAY`	Día siguiente	Al día siguiente

Flujo paso a paso: cotizar y generar guía

Paso 1: Abrir la pantalla de cotización

Desde el módulo Paquetería, haga clic en Nueva Cotización. Si la guía es para una venta específica, también puede llegar desde el detalle de esa venta.

Paso 2: Completar los datos del paquete y destino

Ingrese el código postal, ciudad, estado, dimensiones, peso y tipo de servicio del envío.

Paso 3: Cotizar

Haga clic en el botón Cotizar. El sistema consulta simultáneamente a todos los carriers activos que soporten el tipo de servicio seleccionado. La consulta tiene un tiempo límite de 10 segundos por carrier.

Mientras los carriers responden, el botón muestra un indicador de carga.

Paso 4: Revisar los resultados

La columna derecha muestra las tarifas disponibles con:

Nombre del carrier y tipo de servicio
Precio en MXN (impuestos incluidos según la tarifa del carrier)
Tiempo estimado de entrega en días
Vigencia de la tarifa

Si algún carrier no respondió, aparecerá un aviso tipo advertencia en la parte superior indicando cuáles carriers fallaron, pero se seguirán mostrando las tarifas de los que sí respondieron.

Si todos los carriers fallan, la columna derecha muestra un mensaje de error con los detalles de cada carrier.

Paso 5: Seleccionar una tarifa y generar la guía

Haga clic en la tarifa que desea usar. El sistema realiza las siguientes acciones de forma atómica:

Llama a la API del carrier para crear el envío (máx. 10 s).
Obtiene el número de rastreo y la URL de la etiqueta PDF.
Crea un registro de Gasto Logístico (FacturaProveedor tipo GASTO_LOGISTICO) vinculado al costo del envío.
Crea el registro de Envío con estado GENERADO.
Marca la tarifa como elegida para evitar duplicados.

Al completarse, el sistema lo redirige automáticamente a la pantalla de detalle del envío.

Reglas y validaciones

Peso y dimensiones > 0: si cualquier valor es cero o negativo, la validación falla antes de llamar al carrier.
Código postal de 5 dígitos: el campo acepta solo dígitos; longitudes distintas de 5 son rechazadas.
Carrier activo requerido: si el carrier de la tarifa seleccionada se desactivó entre la cotización y la generación, el sistema muestra el error CARRIER_CONFIG_NOT_FOUND.
Consolidación de ventas (FR-016): si se consolidan múltiples ventas en un mismo envío, todas deben pertenecer al mismo cliente y tener el mismo domicilio de destino.
Transacción atómica: si la llamada al carrier tiene éxito pero falla algún paso de base de datos, la operación se revierte por completo. Si la llamada al carrier falla, no se crea ningún registro.

Casos frecuentes

El botón Cotizar no hace nada o muestra un error inmediatamente. Verifique que todos los campos obligatorios estén completos y que al menos un carrier esté configurado y activo en Configuración de Paquetería.

Aparece “Algunos carriers no respondieron” en color amarillo. Es normal si un carrier tiene problemas de conectividad o rechazó la solicitud. Las tarifas de los otros carriers siguen disponibles para seleccionar.

El sistema muestra TARIFA_EXPIRED al seleccionar una tarifa. La vigencia de esa tarifa venció (cada carrier define su propio tiempo de vigencia). Haga clic en Cotizar de nuevo para obtener tarifas actualizadas.

No hay configuración activa para el carrier seleccionado. El carrier fue desactivado entre la cotización y la generación. Vaya a Configuración de Paquetería y reactive el carrier, o seleccione una tarifa de otro carrier.

Error NO_PROVEEDOR_FOR_LOGISTIC_COST. El tenant no tiene proveedores activos. Registre al menos un proveedor en el módulo de Compras y vuelva a intentarlo.