Configuración de Paqueterías

Configure las credenciales de API y el modo de operación de DHL, FedEx, Estafeta y 99minutos para habilitar la generación de guías y el rastreo automático de envíos.

Carriers disponibles

ALTUM ERP incluye adaptadores nativos para cuatro paqueterías mexicanas:

Carrier	Identificador interno	Cobertura principal
DHL	DHL	Nacional e internacional
FedEx	FEDEX	Nacional e internacional
Estafeta	ESTAFETA	Nacional
99minutos	NOVENTA_Y_NUEVE_MINUTOS	CDMX, Guadalajara y Monterrey

Nota

99minutos solo acepta envíos cuyo código postal de destino pertenezca a las zonas metropolitanas de Ciudad de México, Guadalajara o Monterrey. Intentar cotizar hacia otros códigos postales resultará en un rechazo previo a la llamada al carrier.

Requisitos y permisos

Permiso requerido	Descripción
paqueteria.configuracion_editar	Permite ver y guardar la configuración de carriers

Si al ingresar a la pantalla aparece un mensaje de acceso restringido, solicite al administrador de su empresa que le asigne el permiso correspondiente.

Pantalla principal

Acceda desde el módulo Paquetería → botón Configuración (esquina superior derecha de la pantalla principal).

La pantalla presenta cuatro pestañas, una por carrier: DHL, FedEx, Estafeta y 99minutos. Cada pestaña muestra el formulario de configuración de ese carrier de forma independiente.

Campos del formulario por carrier

Cada carrier comparte la misma estructura de formulario:

Campo	Descripción	Obligatorio
API Key	Clave de acceso a la API del carrier	Sí
API Secret	Secreto complementario a la API Key	No en Estafeta
Número de cuenta	Número de cuenta contractual con el carrier	Sí
Modo	SANDBOX (pruebas) o PRODUCCION	Sí
Webhook Secret	Secreto para validar notificaciones entrantes del carrier	Solo DHL
Activo	Habilita o deshabilita el carrier para cotizaciones y generación de guías	Sí

Precaución

DHL requiere obligatoriamente un Webhook Secret. Si intenta guardar la configuración de DHL sin este campo, el sistema mostrará un error de validación.

Flujo paso a paso: configurar un carrier

Paso 1: Seleccionar la pestaña del carrier

En la pantalla de Configuración de Paquetería, haga clic en la pestaña del carrier que desea configurar (por ejemplo, FedEx).

Paso 2: Ingresar las credenciales

Complete los campos API Key, API Secret (si aplica) y Número de cuenta con los datos proporcionados por el carrier en su portal de desarrolladores o mediante su ejecutivo de cuenta.

Paso 3: Seleccionar el modo de operación

• Use SANDBOX mientras prueba la integración con credenciales de prueba del carrier.
• Cambie a PRODUCCION solo cuando las credenciales sean las de su contrato vigente con el carrier.

Paso 4: Configurar el Webhook Secret (solo DHL)

Si está configurando DHL, ingrese el secreto HMAC que DHL le proporciona para validar la autenticidad de las notificaciones de eventos de envío que el carrier envía al sistema.

Paso 5: Activar el carrier

Asegúrese de que el campo Activo esté habilitado para que el carrier aparezca en las cotizaciones y pueda generar guías.

Paso 6: Guardar

Haga clic en Guardar. El sistema cifra las credenciales antes de almacenarlas (AES-256-GCM) y registra el cambio en la bitácora de auditoría. Aparecerá una notificación de confirmación.

Reglas y validaciones

• Las credenciales se almacenan cifradas; nunca se muestran en texto claro tras el guardado inicial.
• Si ya existe una configuración para el carrier, la operación de guardar actualiza los campos; no crea un duplicado.
• Un carrier desactivado (Activo = false) no aparecerá en la lista de opciones al cotizar ni al generar guías, aunque sus credenciales sigan guardadas.
• La URL del webhook se genera automáticamente a partir de la URL pública del API (/api/v1/shipping/webhooks/{carrier}). Regístrela en el portal del carrier para que las notificaciones de tracking lleguen al sistema.

Casos frecuentes

El formulario muestra un esqueleto de carga durante varios segundos. El sistema está obteniendo la configuración actual desde el servidor. Si persiste más de 15 segundos, verifique la conectividad con el backend.

Aparece el error “webhookSecret es requerido” al guardar DHL. El campo Webhook Secret es obligatorio para DHL. Obténgalo en el portal de desarrolladores de DHL y complételo antes de guardar.

Guardé la configuración pero el carrier sigue sin aparecer en cotizaciones. Verifique que el campo Activo esté habilitado. Un carrier desactivado no participa en cotizaciones aunque tenga credenciales válidas.

¿Puedo tener el mismo carrier en modo SANDBOX y en modo PRODUCCION al mismo tiempo? No. Solo existe una configuración por carrier por tenant. Para alternar entre modos, edite el campo Modo y guarde de nuevo.