Codingrow Order Export & Tracking Import

Instalación

Requisitos

Magento 2.4.x — probado en 2.4.9, compatible con versiones 2.4.* anteriores. PHP 8.1–8.5. Requiere codingrow/module-core (instalado automáticamente como dependencia de Composer) para el menú de administración compartido de Codingrow y la validación de la licencia.

Pasos de instalación

Añade las credenciales que recibirás por email a auth.json en la raíz de tu proyecto Magento:
```
{ "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }
```
composer config repositories.codingrow composer https://repo.codingrow.com
composer require codingrow/module-oeti
bin/magento module:enable Codingrow_Oeti
bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush
Pega tu clave de licencia en Admin → Stores → Configuration → Codingrow → Order Export & Tracking Import → License → Clave de licencia, guarda, y luego bin/magento cache:flush.
En el grupo General de esa misma sección, pon Habilitar módulo en "Yes" — el módulo se distribuye habilitado a nivel de Magento pero funcionalmente apagado, así que no exporta nada hasta que lo actives explícitamente.
Crea tu primer perfil en Codingrow → Order Export & Tracking Import → Export Profiles — consulta Perfiles más abajo.

Todo el panel de administración de perfiles, el generador de mapeo, el registro y cada email de notificación están disponibles en 7 idiomas, seleccionados automáticamente según el idioma de cada usuario administrador:

Configuración admin

La configuración está en Stores → Configuration → Codingrow Extensions → Order Export & Tracking Import (Licencia más los ajustes de export/tracking). Los perfiles de export y su mapeo / condiciones de disparo se gestionan desde la parrilla Order Export dedicada.

Order Export & Tracking Import admin configuration in Magento

Desinstalación

composer remove codingrow/module-oeti y después bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush. Los perfiles y el registro de exportaciones y seguimiento (codingrow_oeti_profile, codingrow_oeti_log, codingrow_oeti_tracking_log) nunca se eliminan automáticamente — usa primero Exportar perfil si quieres conservar una copia de la configuración de tu perfil.

Guía de usuario

Perfiles

Todo en el módulo está organizado en torno a perfiles, listados en Codingrow → Order Export & Tracking Import → Export Profiles. Cada perfil es completamente independiente: tiene su propio nombre, su propio interruptor de habilitado/deshabilitado, sus propios estados disparadores, su propio destino (canal + formato), su propio mapeo de campos y su propia fila en el registro de exportaciones — puedes ejecutar tantos perfiles en paralelo como quieras (uno por proveedor, uno por transportista, uno para un ERP interno), y deshabilitar o eliminar uno nunca afecta a los demás.

Un perfil deshabilitado (Perfil habilitado = "No") nunca exporta nada, ya sea que se active automáticamente, desde la acción manual o desde el comando CLI — esto es independiente del interruptor Habilitar módulo a nivel de módulo en System Config, que actúa como un único interruptor maestro para apagar todos los perfiles a la vez.

Canales & formatos

Cada perfil elige un canal (dónde se entrega el payload) y un formato (cómo se serializa) — ambas elecciones son independientes, así que cualquier formato funciona con cualquier canal.

Canal	Uso típico	Ajustes clave
REST API	Envía el payload como una solicitud HTTP a un servicio web	URL de destino, método HTTP (GET/POST/PUT/PATCH), autenticación (Ninguna, HTTP Basic, token Bearer), segundos mínimos entre solicitudes (limitación de tasa, 1 segundo por defecto)
FTP / SFTP	Sube el payload como un archivo a un servidor remoto	Host, puerto (21 por defecto), usuario, contraseña, ruta remota, FTPS opcional (TLS explícito), modo pasivo
Archivo local	Escribe el payload en un archivo bajo el `pub/media/` propio de esta tienda, para que un sistema externo lo recoja por HTTP	Subcarpeta — el archivo se guarda bajo `pub/media/codingrow_oeti/<subcarpeta>/` (subcarpeta por defecto: "default")

Formatos: JSON, XML o CSV, elegidos de forma independiente del canal anterior — el mismo mapeo de campos (ver abajo) alimenta los tres, el formato solo cambia cómo se serializa.

Mapeo de campos

La pestaña Mapping es una tabla de filas, cada una conectando un target (el nombre del campo en la salida — un punto indica un nivel de anidamiento, p. ej. customer.email) con una ruta de origen elegida en un desplegable con todos los campos disponibles del pedido/cliente/artículo. Las filas vacías se ignoran al guardar.

Las filas se leen de arriba a abajo con la misma forma que la propia salida: primero una plantilla opcional de Header, luego las filas de mapeo a nivel de pedido, después los Repeat blocks (ver abajo), y por último una plantilla opcional de Footer.

Transformaciones

Cada fila de mapeo puede aplicar una transformación al valor de origen antes de escribirlo en el campo de destino:

Transformación	Qué hace
Ninguna	Copia directa del valor de la ruta de origen (recurre a "Default value" cuando el origen está vacío).
Valor estático	Ignora por completo el origen, siempre escribe el texto fijo de "Value".
Eliminar etiquetas HTML	Elimina el marcado HTML del valor de origen — útil para un nombre o descripción de producto que arrastra formato residual.
Plantilla de texto	Texto libre con marcadores de posición, p. ej. `{order.shipping_address.firstname} {order.shipping_address.lastname}`. También hay una función disponible dentro de un marcador de posición: `striphtml{path}` (igual que la transformación Eliminar etiquetas HTML, usable en línea) y `substr{path,N}` (elimina los primeros N caracteres, p. ej. `substr{order.some_code,3}`).
Buscar y reemplazar	Busca el texto "Search" dentro del valor de origen (sin distinguir mayúsculas y minúsculas) y lo sustituye por "Value" exactamente como se indica.
Número	Serializa el valor como un número JSON real en lugar de una cadena entre comillas — úsalo cuando el destino valida el TIPO del campo de forma estricta (una cantidad enviada como la cadena en bruto de base de datos `"1.0000"` es rechazada por algunas APIs, mientras que `1.0` como número real se acepta). Esto no es el comportamiento por defecto para campos con aspecto numérico a propósito: activarlo en todas partes eliminaría silenciosamente los ceros iniciales de cosas como un código postal o un código de artículo, así que es una elección opt-in por fila, no un comportamiento automático.

La misma sintaxis {path} / striphtml{} / substr{} usada en las filas Plantilla de texto también está disponible en las filas de Repeat block y en el Header/Footer opcional del perfil.

Bloques repetidos

Un bloque repetido construye un array anidado en la salida — el caso más común es una entrada por artículo del pedido. Cada bloque tiene una Block output key (dónde se escribe el array en la salida) y una source collection (sobre qué itera, p. ej. los artículos del pedido), además de su propio conjunto de filas de mapeo debajo, evaluadas una vez por elemento con "current" limitado a ese elemento — así que la ruta de origen de una fila dentro de un bloque repetido se refiere a los campos del artículo actual, no del pedido en su conjunto.

Ejemplo. Un bloque con output key items, source collection "Order items", y dos filas (sku ← SKU del artículo actual, qty ← cantidad del artículo actual) produce:

{
  "items": [
    { "sku": "43241", "qty": 2 }
  ]
}

Un perfil puede definir cualquier número de bloques repetidos independientes — por ejemplo uno para la lista de artículos y otro separado para una lista de descuentos aplicados.

Condiciones disparadoras

La pestaña General incluye un generador de condiciones AND/OR anidables — la misma interfaz en árbol que las Cart Price Rules de Magento (un enlace "Add" en cada grupo para añadir una condición o un subgrupo anidado, un icono de eliminar en cada nodo) — que decide tanto qué filas del pedido exporta realmente el perfil como si el perfil exporta el pedido o no. Cada condición compara un atributo de producto (p. ej. sku, un atributo personalizado "supplier code", price...) con un valor, con un operador: igual a/distinto de, contiene/no contiene, empieza por/termina en, mayor que/menor que (o igual a), está vacío/no está vacío.

Las condiciones dentro de un grupo se combinan con ALL (AND) o ANY (OR), y los grupos pueden anidarse dentro de otros grupos — por ejemplo sku contains "ABC" OR (supplier_code = "Supplier2" AND price > 10). Sin condiciones configuradas = sin filtro, se exporta cada fila (igual que el antiguo "Only supplier items" = "No" antes de la versión 1.3.0).

Uso típico con varios proveedores en dropshipping: un perfil por proveedor, cada uno con su propia condición (p. ej. Perfil A: supplier_code = "Supplier1", Perfil B: supplier_code = "Supplier2") — un pedido que contiene artículos de ambos proveedores activa correctamente los dos perfiles en paralelo, cada uno exportando solo las filas que le pertenecen. Si ninguna fila cumple las condiciones de un perfil dado, ese perfil simplemente no exporta ese pedido (ver el estado de registro "Skipped" más abajo) — no es un error.

Cada atributo usado en una condición pasa automáticamente a estar disponible como campo mapeable en el payload (items.attributes.<code>, ver Mapeo de campos arriba). Cuando las condiciones excluyen filas de un pedido, la vista previa en vivo muestra un aviso explícito indicando cuántas filas se dejaron fuera y por qué — así un payload vacío o más corto de lo esperado nunca es una sorpresa silenciosa.

Vista previa en vivo

El botón Preview en la página de edición del perfil construye un perfil temporal, nunca guardado, a partir de lo que haya actualmente en el formulario — incluidos cambios que aún no has guardado — y lo ejecuta sobre un pedido real que elijas, a través de exactamente el mismo camino de código usado para una exportación genuina. El resultado es el payload literal JSON/XML/CSV que ese pedido produciría, así puedes corregir el mapeo antes de llegar a activar el perfil, en lugar de descubrirlo por una exportación real fallida.

Disparador & deduplicación

El selector múltiple Estado disparador en la pestaña General lista qué estado(s) del pedido inician una exportación automática para ese perfil (Ctrl/Cmd-clic para seleccionar más de uno) — solo se comprueba en el disparador automático basado en eventos; la acción manual desde la cuadrícula y el comando CLI lo ignoran a propósito, ya que activar la exportación a mano ya es en sí misma la decisión deliberada de exportar sin importar el estado. La acción manual "Export via Codingrow Order Export" en la cuadrícula Sales > Orders ejecuta con un clic cada perfil habilitado sobre los pedidos seleccionados — las Condiciones disparadoras propias de cada perfil deciden qué se envía realmente, exactamente igual que en el disparador automático.

Cada intento se escribe en el registro de ese perfil (ver abajo), y el registro es también lo que evita duplicados: el mismo pedido nunca se exporta dos veces automáticamente desde el mismo perfil, pase lo que pase con el pedido después (más ediciones, cambios de estado hacia adelante y atrás). Si hace falta un reenvío genuino — tras arreglar un problema del lado del destino, por ejemplo — usa Forzar reenvío, que evita explícitamente esta protección.

Importación de seguimiento

Una pestaña Tracking Import por perfil (desactivada por defecto) ejecuta una consulta automática por pedido — rediseñada en la v1.5.0. Cada pedido que este perfil exportó con éxito y que aún tiene artículos por enviar, y que no tiene más de 45 días, se consulta individualmente por su propio estado de envío; para los artículos reportados como enviados crea un envío nativo de Magento con su número de seguimiento, reutilizando las propias Condiciones disparadoras del perfil para saber qué artículos del pedido le pertenecen. No hay ninguna ventana de fechas por lotes — el modelo es estrictamente una solicitud por cada pedido abierto en cada ciclo.

Un pedido que sigue sin enviarse por completo tras 45 días sale del ciclo automático: se escribe una sola vez en el log con estado Timeout (más un email opcional), de modo que nunca sigue consultando al proveedor indefinidamente.

Request. La mitad superior de la pestaña define la llamada saliente:

Campo	Significado
Check endpoint URL	URL base del endpoint de estado del proveedor, sin ninguna query string.
HTTP method	GET o POST.
Poll frequency (minutes)	Cada cuánto se ejecuta el cron de este perfil.
Minimum seconds between requests	Rate limit entre las llamadas individuales por pedido dentro de un mismo ciclo (por defecto 1s; 0 = sin límite).
Different authentication than the profile	Si es No (por defecto) la comprobación reutiliza las credenciales del canal del propio perfil; en Sí el endpoint de seguimiento tiene su propia autenticación.
Request parameters	Una cuadrícula de filas Name + Type + Value, una por cada parámetro enviado al endpoint (ver los cinco tipos de parámetro más abajo).
Request preview (JSON)	Vista previa en vivo de la llamada exacta; el botón Send test request contiguo lanza una llamada HTTP real, y al pegar un ejemplo de solicitud en la vista previa las filas de parámetros se reconstruyen a partir de él.

Cada fila de Request parameters elige uno de cinco Type de valor:

Type	Valor enviado
Fixed value	El texto literal introducido en Value.
Today	La fecha de hoy (Y-m-d).
Order export date	La fecha en la que se exportó ese pedido.
Mapped export field	El valor que la exportación calculó para un target elegido de ese pedido — p. ej. la referencia del pedido en el proveedor.
Template	Texto libre con la función `date{N}` (hoy ±N días), p. ej. `date{-7}`.

Response mapping. La mitad inferior mapea la respuesta del proveedor. Nunca escribes las rutas de la respuesta a mano: obtén una respuesta real — con Send test request, o pegando una respuesta capturada en el recuadro Response sample — y cada desplegable de abajo se rellena con los campos realmente encontrados en esa respuesta.

Campo	Significado
Reference field	Qué target de Order Export contiene la referencia del pedido (capturada en cada intento de exportación, con éxito o con error).
Order match field in response	El campo de la respuesta con el que se compara para identificar el pedido correcto.
Tracking number / Tracking URL	Campos de la respuesta que contienen el número de seguimiento y, si lo hay, su enlace clicable.
Carrier code / Carrier name	Campos de la respuesta que contienen el código del transportista y su etiqueta.
Multiple tracking numbers for this shipment	Conmutador para los proveedores que devuelven más de un número de seguimiento por envío; muestra Tracking numbers: collection (el array de entradas de seguimiento) y Tracking numbers: value path in each element (dónde está el número dentro de cada entrada).
Shipped items: collection	El array de la respuesta que lista los artículos enviados.
Shipped items: SKU path in each element / Shipped items: quantity path in each element	Dónde están el código del artículo y la cantidad enviada dentro de cada elemento de ese array.
Item matching attribute	El atributo de producto con el que reconocer los artículos del proveedor, ya que los proveedores reportan su propio código, no el SKU de Magento.

Envíos parciales. Si un pedido tiene artículos de varios proveedores (o un proveedor envía en más de una tanda), cada comprobación crea un envío solo para los artículos realmente reportados como enviados en ese momento, nunca más allá de lo que aún queda por enviar — así que un pedido que acaba legítimamente con varios envíos a lo largo del tiempo es el comportamiento previsto, no un error.

Email al cliente. Cuando el proveedor proporciona un enlace de seguimiento en el que se puede hacer clic (una URL, no solo un número), el cliente recibe un email con un botón "Track your package" en lugar del email nativo básico de Magento (que solo mostraría el número, sin enlace funcional para un transportista que Magento no reconoce de forma nativa). Cuando el proveedor no proporciona ninguna URL, se usa el email nativo estándar, sin cambios.

Migración automática. Los perfiles ya configurados con la versión anterior se migran automáticamente al actualizar — no hace falta reconfigurar nada.

No hace falta ninguna acción manual en funcionamiento normal: las comprobaciones por pedido se ejecutan solas en segundo plano al ritmo configurado (el cron de Magento debe estar en marcha, como para cualquier tarea programada).

¿Quieres probar la importación de seguimiento? Usa nuestro endpoint de seguimiento de ejemplo permanente (JSON, en inglés) como fuente de la respuesta mientras construyes el mapeo de la respuesta:
https://codingrow.com/sample-tracking.json
OpenAPI: https://codingrow.com/sample-api.openapi.yaml

Registro & Force resend

Desde la versión 1.4.0 el registro ya no está dividido por perfil (una pestaña de registro dentro de cada perfil). Una única página de Registro (botón en la cuadrícula Export Profiles) lista pedidos — no intentos individuales — uno por fila, paginados, con el último estado de exportación y el último estado de seguimiento uno junto al otro: un vistazo a un pedido incluso cuando hay varios perfiles/proveedores implicados.

Al hacer clic en Ver historial completo se abre el historial completo de ese pedido, dividido en dos secciones — Registro de exportaciones y Registro de seguimiento — cada una con todos los intentos/comprobaciones de todos los perfiles implicados, con una fila de detalles desplegable (payload exacto de la solicitud enviada, cuerpo de la respuesta recibida) y, en el lado de exportación, un botón Force resend por fila.

En el lado de exportación, un intento es Success, Error o Skipped. Skipped no es un error: ningún artículo del pedido cumplía las Condiciones disparadoras de ese perfil, así que no se envió nada — útil con varios perfiles/proveedores para ver de un vistazo por qué un perfil determinado no exportó un pedido determinado. En el lado de seguimiento, una comprobación fallida normalmente solo significa que el proveedor aún no ha reportado nada enviado para esos artículos; se reintenta automáticamente en la siguiente consulta, sin necesidad de ninguna acción manual.

El botón Force resend de una fila fallida o Skipped (solo en el lado de exportación) vuelve a ejecutar ahora mismo la exportación para ese pedido exacto a través de ese perfil exacto, ignorando la protección de deduplicación — un diálogo de confirmación lo explica antes de ejecutarse, ya que es una anulación deliberada, disponible tanto desde la página principal de Registro como desde el detalle del pedido. El seguimiento no tiene un equivalente manual de "force check": la siguiente consulta programada simplemente vuelve a intentarlo.

Emails de notificación de error

Dos ajustes de la pestaña General controlan las notificaciones de error, independientemente del registro (que siempre guarda cada intento sin importar estos ajustes): Destinatarios de notificación (una o más direcciones de email, separadas por comas — déjalo vacío para no enviar nada) y Enviar correo para (qué eventos activan una notificación).

El cuerpo del email incluye el error real devuelto por el destino, no solo una línea de estado HTTP genérica: cuando el cuerpo de la respuesta es JSON interpretable con un campo message, ese mensaje se incluye tal cual (p. ej. "Destination returned HTTP 422 - Minimum product quantity is 1.0"); en caso contrario se incluye el cuerpo bruto de la respuesta, truncado a 500 caracteres — así la causa real es visible directamente desde la bandeja de entrada, sin necesidad de abrir el registro.

Importar / Exportar perfil

El botón Exportar perfil en la página de edición de un perfil descarga toda su configuración — ajustes generales, destino, filas de mapeo y bloques repetidos — como un único archivo JSON, con las credenciales del destino excluidas a propósito, para que el archivo sea seguro de guardar, compartir con soporte o incluir en un despliegue. El botón Importar perfil en la cuadrícula Export Profiles recrea un perfil a partir de un archivo así — el uso típico es mover un perfil de una tienda de staging/demo a producción, o conservar una copia de seguridad de un mapeo con el que estés satisfecho antes de seguir experimentando. Las credenciales siempre deben volver a introducirse a mano tras una importación, ya que nunca estuvieron en el archivo.

Licencia

Una licencia por dominio, introducida en Admin → Stores → Configuration → Codingrow → Order Export & Tracking Import → License → Clave de licencia. Incluye todas las actualizaciones para ese dominio. ¿Necesitas pasar a un dominio distinto (staging → producción, o una migración de sitio)? Tu primer cambio de dominio es gratuito e instantáneo desde tu página de cuenta — sin esperas, sin necesidad de ticket. A partir del segundo cambio, se permite un cambio una vez al año. También puedes solicitar un reembolso dentro de los 30 días posteriores a la compra, por tu cuenta, desde la misma página de cuenta.

Documentación de Order Export & Tracking Import