Magento 2 + AtoShip
Importa los pedidos de tu tienda Magento 2 a atoship, compra etiquetas de USPS / UPS / FedEx con descuento y devuelve los números de seguimiento — con un completo panel de rastreo dentro de tu propio panel de administración de Magento.
Cómo funciona
La integración tiene dos partes: una extensión de Magento 2 que añade a tu tienda la visualización del seguimiento y el procesamiento de webhooks, y una conexión OAuth desde tu panel de atoship que sincroniza los pedidos y devuelve los datos de rastreo automáticamente.
Los nuevos pedidos aparecen en Magento
Un cliente hace un pedido en tu tienda
Los pedidos se sincronizan con atoship
Se importan automáticamente con los datos del cliente, artículos y pesos
Compra la etiqueta y el seguimiento regresa
El número de seguimiento, la transportadora y el progreso se escriben en el pedido de Magento
Instalación
Paso 1 — Instala la extensión de Magento
Descarga el archivo atoship-for-magento.zipdesde la barra lateral (o el botón de abajo). Descomprímelo en tu instalación de Magento:
Opción A: Copiar a app/code (recomendado)
# Descomprime y copia a la raíz de tu Magento
unzip atoship-for-magento.zip
cp -r atoship-shipping/ <magento-root>/app/code/Atoship/Shipping/
# Activa el módulo
cd <magento-root>
php bin/magento module:enable Atoship_Shipping
php bin/magento setup:upgrade
php bin/magento cache:flushTras ejecutar setup:upgrade, el módulo crea la tabla atoship_trackingy registra las rutas de webhook automáticamente.
Paso 2 — Conecta mediante integración OAuth
En tu panel de administración de Magento, ve a System → Integrations y haz clic en Add New Integration. Completa lo siguiente:
https://atoship.com/api/channels/magento/callbackhttps://atoship.com/api/channels/magento/identity
Completa el Name, la Callback URL y la Identity Link URL. El campo Email es opcional.
Paso 3 — Configura los permisos de la API
Haz clic en la pestaña APIde la izquierda. En "Resource Access", selecciona All u otorga acceso a estos recursos específicos:
- Sales — Pedidos, facturas, envíos, notas de crédito
- Catalog — Productos (para pesos y dimensiones)
- Stores — Configuración y vistas de la tienda
Consejo: "All" es la opción más sencilla y garantiza que todas las funciones de sincronización funcionen. Puedes restringirlo más adelante si lo necesitas.
Paso 4 — Guarda y activa
Haz clic en Save para crear la integración. Luego búscala en la lista y haz clic en el enlace Activate. Magento te pedirá que confirmes — haz clic en Allow.
Haz clic en el enlace Activate junto a la integración de atoship para iniciar el intercambio (handshake) OAuth.
Importante: asegúrate de haber iniciado sesión en tu cuenta de atoship en el mismo navegador antes de hacer clic en Activate. Magento redirige tu navegador a la Identity Link URL de atoship, y atoship necesita tu sesión para asociar la tienda con tu cuenta.
Paso 5 — Configura la extensión
Ve a Stores → Configuration → Sales → AtoShip e introduce tu clave secreta de webhook (la encuentras en tu página Channels de atoship). Configura las preferencias de notificación y de finalización automática.
La integración de atoship aparece como Active en la lista System → Integrations de Magento.
Ajustes de la extensión
Todos los ajustes están en Stores → Configuration → Sales → AtoShip. Esto es lo que hace cada opción:
General
- Enable — Interruptor principal de la extensión. Cuando está desactivado, los webhooks se ignoran y los paneles de rastreo quedan ocultos.
- Webhook Secret — Clave secreta HMAC-SHA256 para verificar los webhooks entrantes de atoship. Cópiala desde tu página Channels de atoship.
- Debug Logging — Escribe registros detallados en
var/log/atoship.log. Mantenlo desactivado en producción.
Tracking
- Auto Complete on Delivery — Marca los pedidos como "Complete" automáticamente cuando el seguimiento de la transportadora confirma la entrega.
- Notify Customer on Ship — Envía un correo de notificación de envío con enlace de seguimiento al comprar una etiqueta.
- Notify Customer on Delivery — Envía un correo de confirmación de entrega cuando el paquete es entregado.
Qué se sincroniza
Magento → atoship
- Número de pedido, fecha y total
- Direcciones de facturación y de envío
- Líneas de artículos con SKU, cantidad y peso
- Nombre y correo del cliente
- Estado del pedido e información de pago
atoship → Magento
- Número de seguimiento, transportadora y nombre del servicio
- Barra de progreso visual (Etiqueta creada → Recogido → En tránsito → Entregado)
- Cronología completa del seguimiento con eventos y ubicaciones
- Costo de la etiqueta y enlace al PDF de la etiqueta
- Creación del envío en el pedido
- Actualizaciones del estado del pedido (→ Complete)
- Notificaciones de entrega y de incidencias
Los datos de rastreo se guardan en la tabla atoship_trackingy se muestran en un completo panel de seguimiento tanto en la vista de pedido como en la de envío del panel de administración — sin necesidad de ninguna extensión de rastreo adicional.
Panel de seguimiento del pedido
Cuando compras una etiqueta en atoship, la extensión añade un completo panel AtoShip Trackingtanto a la página de detalle del pedido como a la del envío en el panel de administración. Los clientes también ven el progreso del seguimiento en la vista de sus pedidos en Mi cuenta.
Transportadora y servicio
Muestra el logo real de la transportadora (FedEx, UPS, USPS, DHL), su nombre y el nivel de servicio (Ground, Priority, Express).
Barra de progreso
Indicador visual de 4 pasos: Etiqueta creada → Recogido → En tránsito → Entregado. Se actualiza automáticamente a medida que cambia el estado del seguimiento.
Cronología del seguimiento
Cronología de eventos plegable, con marcas de tiempo y ubicaciones, ordenada de más reciente a más antiguo.
Acciones rápidas
Rastrear en la página de seguimiento de atoship, ver en el sitio oficial de la transportadora y mostrar el costo de la etiqueta (solo administradores).
El número de seguimiento enlaza a la página de rastreo de atoship para ver el detalle. Los datos de seguimiento se envían mediante webhook en tiempo real.
Eventos de webhook
La extensión recibe los eventos de webhook de atoship en /atoship/webhook/receive. Todas las solicitudes se verifican con una firma HMAC-SHA256 usando tu clave secreta de webhook.
| Evento | Acción |
|---|---|
label.created | Guarda el registro de seguimiento y añade un comentario al pedido en el panel de administración |
label.purchased | Guarda el seguimiento, pasa el pedido a Processing y notifica al cliente |
label.voided | Marca el seguimiento como anulado y añade un comentario en el panel de administración |
tracking.updated | Actualiza el estado y la cronología de eventos, y añade un comentario visible para el cliente |
tracking.delivered | Marca como entregado, completa el pedido automáticamente (si está activado) y notifica al cliente |
tracking.exception | Registra una advertencia y añade un comentario de alerta solo para administradores |
Alternativa: entrada manual de tokens
Si ya creaste una integración y tienes los 4 tokens de la API (Consumer Key, Consumer Secret, Access Token, Access Token Secret), puedes introducirlos directamente:
- Ve a atoship → Channels → Add Channel → Magento
- Cambia a la pestaña Manual Tokens
- Introduce la URL de tu tienda y los 4 tokens
- Haz clic en Connect
Esto resulta útil si tu tienda Magento no puede acceder a internet (por ejemplo, entornos de staging detrás de un firewall) o si prefieres gestionar los tokens manualmente.
Desconexión
Puedes desconectar desde cualquiera de los dos lados:
- Desde atoship: ve a Channels, busca tu tienda Magento y haz clic en Disconnect.
- Desde Magento: ve a System → Integrations, busca "AtoShip" y haz clic en Delete o Reset.
Desconectar no elimina ningún pedido, envío ni dato de seguimiento que ya esté en tu tienda. Solo detiene la sincronización futura. La extensión se puede desinstalar por separado con module:disable Atoship_Shipping.
Solución de problemas
Error "State not found or expired"
El intercambio (handshake) OAuth debe completarse en 10 minutos. Si tardaste demasiado entre Save y Activate, elimina la integración en Magento y crea una nueva.
La redirección lleva a la página de inicio de sesión
Debes haber iniciado sesión en atoship en el mismo navegador antes de hacer clic en Activate en Magento. Inicia sesión en atoship primero y vuelve a intentar Activate (es posible que tengas que recrear la integración).
El panel de seguimiento no aparece
Asegúrate de que la extensión esté activada (php bin/magento module:status | grep Atoship) y de que el ajuste "Enable" esté en Yes en Stores → Configuration → Sales → AtoShip. Ejecuta cache:flush después de cualquier cambio de configuración.
No se reciben los eventos de webhook
Verifica que la clave secreta de webhook coincida entre atoship y tu configuración de Magento. Revisavar/log/atoship.log (activa Debug Logging) en busca de fallos de verificación de firma. Tu tienda debe ser accesible desde internet.
Los pedidos no se importan
Verifica que la tienda aparezca como "Active" en tu página Channels. Comprueba que la integración tenga los permisos de la API requeridos (Sales, Catalog, Stores). La sincronización de pedidos se ejecuta de forma programada — los pedidos recién realizados pueden tardar unos minutos en aparecer.
Requisitos
- Magento 2.4+ (Open Source o Commerce)
- PHP 8.1+
- API REST activada (por defecto)
- HTTPS obligatorio
- Acceso de administrador para crear integraciones e instalar extensiones
app/code/Atoship/Shipping/.Callback URL
https://atoship.com/api/channels/magento/callbackIdentity Link URL
https://atoship.com/api/channels/magento/identity