Guía de Solución de Problemas, Preguntas Frecuentes y Comportamiento Esperado

Esta guía cubre tres categorías de preguntas sobre BundlesIQ:

1. Comportamiento esperado — Su pedido se ve diferente a lo esperado, pero BundlesIQ está funcionando correctamente según su modo de manejo. Comience con Sección 1 si su pedido "se ve mal" pero el procesamiento tuvo éxito.
2. Diagnóstico de errores — Algo salió mal durante el procesamiento. Consulte Sección 2 para la lista de verificación y Sección 3 para la resolución detallada de errores.
3. Preguntas frecuentes y procedimientos — Preguntas comunes sobre procesamiento, precios, inventario y tareas operativas. Consulte Sección 4 hasta Sección 7.

1. Entendiendo el Comportamiento Esperado Según el Modo de Manejo

BundlesIQ transforma los pedidos de manera diferente según su modo de manejo. Antes de solucionar problemas, confirme que lo que ve no es el comportamiento previsto de su modo elegido.

1.1 Referencia Rápida: Lo Que Hace Cada Modo a Su Pedido

En los cuatro modos, el total del pedido permanece sin cambios respecto a lo que el cliente pagó en el checkout.

Para verificar su modo: Abra el paquete en BundlesIQ > Paquetes y observe el campo Modo de Manejo. Si dice "Usar predeterminado de la tienda", verifique BundlesIQ > Configuración > Modo de Manejo Predeterminado.

1.2 ¿Por Qué BundlesIQ Eliminó el Paquete de Mi Pedido?

Respuesta corta: Está utilizando modo operativo. Eliminar la línea del paquete es el comportamiento correcto y esperado.

En el modo operativo, BundlesIQ establece la cantidad del paquete (SKU fantasma) en cero y agrega los SKU de componentes individuales con sus precios asignados. El total del pedido permanece sin cambios. Esto está diseñado para almacenes, distribuidores y 3PL que requieren una precisión estricta a nivel de SKU: no queda ninguna abstracción de paquete.

Ejemplo — antes del procesamiento:

Paquete de Esenciales de Verano (x1)    $99.00

Después del procesamiento en modo operativo:

Gafas de sol (x1)                  $41.25
Toalla de playa (x1)               $33.00
Protector solar (x1)                $24.75
Total                            $99.00

La línea del paquete ha desaparecido. Solo permanecen los SKU reales y cumplibles.

Si no desea que se elimine el paquete, cambie a uno de estos modos:

• Modo híbrido — El paquete permanece en el pedido a $0, los componentes se agregan con precios asignados. Bueno para B2B y mayoristas.
• Modo reportando — El paquete permanece a su precio original, los componentes se agregan a $0. Bueno para DTC y reportes de ingresos limpios.
• Modo Solo Padre (BOM) — El paquete permanece a su precio original, no se agregan líneas de componentes. Bueno para flujos de trabajo hechos a pedido y de kits.

Consulte Modos de Manejo Explicados para una comparación completa.

Los cambios de modo se aplican solo a nuevos pedidos. Los pedidos procesados previamente no se modifican retroactivamente. Consulte Sección 1.7.

1.3 ¿Por Qué Mis Componentes Aparecen a $0?

Respuesta corta: Está utilizando modo reportando. Los componentes a $0 son el comportamiento correcto y esperado.

En el modo reportando, la línea del paquete mantiene su precio original ($99.00 en el ejemplo), y los componentes individuales se agregan a $0.00 cada uno. Esto mantiene los ingresos atribuidos al SKU del paquete, lo cual es ideal para marcas DTC que desean análisis de Shopify limpios y vistas de pedidos amigables para el cliente.

Ejemplo — después del procesamiento en modo reportando:

Paquete de Esenciales de Verano (x1)    $99.00
Gafas de sol (x1)                       $0.00
Toalla de playa (x1)                    $0.00
Protector solar (x1)                    $0.00
Total                            $99.00

Si necesita líneas de componentes con precios, cambie a modo híbrido o modo operativo.

Nota 3PL: Algunos 3PL esperan que todos los artículos de línea tengan precios para las declaraciones de aduanas. Si su 3PL informa problemas con líneas de componentes a $0, considere el modo híbrido en su lugar.

1.4 ¿Por Qué El Paquete Aparece a $0 en el Pedido?

Respuesta corta: Está utilizando modo híbrido. El paquete a $0 es el comportamiento correcto y esperado.

En el modo híbrido, la línea del paquete se establece en $0.00 y las líneas de los componentes llevan los precios asignados. Esto preserva tanto lo que se compró (la línea del paquete) como lo que necesita ser cumplido (los componentes con precios), lo que lo hace ideal para B2B y mayoristas.

Ejemplo — después del procesamiento en modo híbrido:

Paquete de Esenciales de Verano (x1)     $0.00
Gafas de sol (x1)                       $41.25
Toalla de playa (x1)                    $33.00
Protector solar (x1)                    $24.75
Total                            $99.00

Si desea que el paquete mantenga su precio original, cambie a modo reportando o modo Solo Padre (BOM).

1.5 ¿Por Qué No Se Agregaron Líneas de Componentes a Mi Pedido?

Respuesta corta: Es muy probable que esté utilizando modo Solo Padre (BOM). No tener líneas de componentes en el pedido es el comportamiento correcto y esperado.

En el modo Solo Padre, el paquete permanece en el pedido exactamente como se colocó: no se agregan artículos de línea, no se cambian precios. BundlesIQ gestiona el inventario de componentes en segundo plano reservando, consumiendo y reabasteciendo el stock de componentes automáticamente.

Ejemplo — después del procesamiento en modo Solo Padre:

Paquete de Esenciales de Verano (x1)    $99.00
Total                            $99.00

(No hay líneas de artículos de componente en el pedido.
 El inventario de componentes se reserva, consume y reabastece en segundo plano.)

Cómo verificar que el procesamiento tuvo éxito:

1. Verifique el tablero de salud de BundlesIQ — el pedido debe mostrar el estado Procesado
2. Verifique la etiqueta de pedido BIQ_READY en Shopify Admin
3. Verifique el inventario de los productos componentes — las cantidades reservadas deben haber aumentado

Si esperaba que aparecieran líneas de componentes, verifique:

• Su modo de manejo no está configurado como Solo Padre (verifique tanto el paquete como el predeterminado de la tienda)
• Si el modo es correcto pero los componentes aún no aparecieron, consulte Sección 2.1 para el diagnóstico de fallas de procesamiento

1.6 ¿Qué Ve el Cliente Después del Checkout?

La experiencia de checkout del cliente es idéntica en los cuatro modos: compran el producto del paquete a su precio listado. La transformación ocurre después del checkout, por lo que el tiempo es importante:

Perspectiva clave: El correo electrónico de confirmación del pedido casi siempre muestra el pedido antes de la transformación porque Shopify envía el correo inmediatamente después de la creación del pedido, antes de que BundlesIQ reciba el webhook y lo procese.

Si la claridad del pedido para el cliente es importante, use modo reportando o modo Solo Padre — estos preservan la vista de pedido más familiar para el cliente, ya que el nombre y el precio del paquete permanecen visibles incluso después de la transformación.

1.7 Cambié Mi Modo de Manejo Pero Los Pedidos Antiguos No Cambiaron

Esto es esperado. Los cambios en el modo de manejo se aplican solo a nuevos pedidos. Los pedidos procesados previamente no se modifican retroactivamente.

Por qué: BundlesIQ utiliza la API de Edición de Pedidos de Shopify, que crea cambios con seguimiento de auditoría. Volver a transformar pedidos retroactivamente generaría nuevas entradas de edición de pedidos, podría confundir la contabilidad y poner en riesgo la integridad de los datos para pedidos que ya pueden haber sido cumplidos o parcialmente cumplidos.

Lo que puede hacer:

• Para futuros pedidos: El nuevo modo entra en efecto inmediatamente para los pedidos realizados después del cambio
• Para pedidos específicos pasados (solo pedidos borrador): Utilice la herramienta Revertir y Reprocesar para re-transformar pedidos borrador individuales bajo el nuevo modo
• Para pedidos cumplidos: Estos no pueden ser re-transformados. Ajuste los informes manualmente si es necesario
• Para pedidos regulares no cumplidos: Estos no pueden ser revertidos (limitación de la API de Edición de Pedidos de Shopify), pero puede reprocesarlos si la transformación original falló

2. Diagnóstico de Fallas de Procesamiento

2.1 El Paquete No Se Procesó / Los Componentes No Aparecieron

Síntomas: Colocó un pedido que contiene un producto de paquete, pero el pedido aún muestra solo el SKU fantasma sin líneas de artículos de componente.

Modo Solo Padre (BOM): Si su paquete utiliza el modo Solo Padre, este es el comportamiento esperado. En el modo Solo Padre, no se agregan líneas de artículos de componente al pedido. La línea del paquete se mantiene tal cual y el inventario de componentes se gestiona en segundo plano. Verifique el tablero de salud de BundlesIQ para confirmar que el pedido se procesó con éxito, y verifique que las cantidades reservadas de los componentes hayan aumentado. Consulte Sección 1.5.

Verifique lo siguiente en orden:

1. ¿Está el paquete Activo?

   • Abra el paquete en BundlesIQ > Paquetes y verifique que el estado sea Activo (no Borrador, Inactivo o Archivado)

2. ¿Está habilitado el procesamiento de pedidos?

   • Vaya a BundlesIQ > Configuración y verifique que Procesar pedidos esté habilitado (o Procesar pedidos borrador si fue un pedido borrador)

3. ¿El alcance del procesamiento incluye este pedido?

   • Si su alcance de procesamiento está configurado como "Solo etiquetados", verifique que el pedido tenga la etiqueta requerida
   • Si tiene etiquetas de exclusión configuradas, verifique que el pedido no tenga una etiqueta excluida

4. ¿Se recibió el webhook?

   • Verifique el tablero de salud de BundlesIQ para el pedido. Si el pedido no aparece en absoluto, Shopify puede no haber entregado el webhook
   • En Shopify Admin, vaya a Configuración > Notificaciones > Webhooks y verifique si hay entregas fallidas

   

5. ¿Hubo un error de procesamiento?

   • Verifique el tablero de salud para un estado Fallido en el pedido
   • Mire el mensaje de error para obtener detalles (por ejemplo, variante de componente faltante, error de API)

6. ¿El pedido ya ha sido cumplido?

   • BundlesIQ solo procesa pedidos que no han sido cumplidos. Si el estado de cumplimiento del pedido no es "no cumplido", se omite el procesamiento

7. ¿El pedido ya fue procesado?

   • BundlesIQ es idempotente: verifica la existencia de metadatos de transformación antes de procesar. Si el pedido ya fue transformado, no se procesará de nuevo. Verifique el metafield del pedido bundles_iq.transformation_audit

8. ¿Está en modo Solo Padre sin darse cuenta?

   • Si el predeterminado de su tienda o la anulación a nivel de paquete está configurada como Solo Padre, el pedido fue procesado pero no se agregaron líneas de componentes — esto es por diseño. Consulte Sección 1.5

Si ninguno de los anteriores se aplica, contacte al soporte con el número de pedido y una captura de pantalla de su tablero de salud de BundlesIQ.

Puede enviar un ticket de soporte directamente desde la página de detalles de procesamiento del pedido:

Los tickets de soporte incluyen una conversación de chat en vivo con el equipo de Zapstra:

2.2 Referencia Completa de Códigos de Error

Cuando el procesamiento falla, BundlesIQ registra un código de error en el tablero de salud. A continuación se presenta la referencia completa de todos los códigos de error, agrupados por categoría.

Errores de Autenticación

Errores de API de Shopify

Errores de Pedido Borrador

Errores de Precios

Errores de Producto y Variante

Errores de Validación

Errores de Derecho y Procesamiento

Errores del Sistema

Errores BOM (Solo Padre)

Estos errores se aplican solo a paquetes que utilizan modo Solo Padre (BOM):

2.3 Entendiendo los Elementos de Atención

Los elementos de atención aparecen en el tablero de salud para señalar pedidos que necesitan revisión. Se diferencian de los errores: el pedido aún puede haberse procesado con éxito, pero se detectó algo inusual.

2.4 Entendiendo las Banderas de Transformación

Las banderas de transformación son marcadores informativos añadidos a los pedidos procesados para explicar decisiones de precios. Aparecen en el tablero de salud bajo los detalles de procesamiento del pedido.

Las banderas no necesariamente significan que algo esté mal. Muchas banderas son informativas — por ejemplo, ORDER_LEVEL_PROMO_ROUNDING_VARIANCE simplemente significa que BundlesIQ agregó una línea de reconciliación para manejar una diferencia de redondeo de 1-2 centavos, lo cual es normal.

3. Análisis Específico de Errores

3.1 Variación de Precio Crítica

Código de error: PRICE_VARIANCE_CRITICAL

Síntoma: El pedido falla en el procesamiento con un error de "variación de precio crítica", o el tablero de salud muestra un elemento de atención price_variance_critical.

Lo que significa: BundlesIQ detectó que la suma de los precios asignados de los componentes difiere significativamente del precio original del paquete. Esta verificación de seguridad evita que los pedidos sean transformados con totales incorrectos.

Causas comunes:

1. El precio del componente cambió en Shopify después de que se configuró el paquete

   • Si el precio de Shopify de un componente aumentó desde que configuró el paquete, BundlesIQ no puede aumentar el precio del artículo de línea en pedidos finalizados (limitación de la API de Edición de Pedidos de Shopify)
   • La brecha entre la asignación esperada y el precio real alcanzable crea una variación

2. Interacción con el código de descuento

   • Un código de descuento aplicado por el cliente puede crear una asignación que entra en conflicto con la estrategia de precios del paquete
   • Descuentos porcentuales en paquetes con precios de componentes en dólares pueden crear casos límite

3. Redondeo de moneda en pedidos internacionales

   • Los pedidos en múltiples monedas pueden producir diferencias de redondeo que exceden el umbral de variación

Resolución:

1. Abra el pedido en el tablero de salud y revise los detalles de precios
2. Verifique el precio actual de cada componente en Shopify frente a la asignación configurada del paquete
3. Si un precio de componente cambió, actualice la configuración de precios del paquete para reflejar los precios actuales
4. Reproceso el pedido desde el tablero de salud después de corregir la configuración
5. Si la variación es pequeña y esperada, contacte al soporte para discutir el ajuste del umbral de variación

3.2 Se Detectó Edición Concurrente en Pedidos Borrador

Código de error: DRAFT_CONCURRENT_EDIT

Síntoma: Un pedido borrador falla en el procesamiento con un error de "edición concurrente".

Lo que significa: Mientras BundlesIQ estaba transformando el pedido borrador, otro proceso (otra aplicación, un usuario de Shopify Admin o un flujo de trabajo de Shopify) modificó el mismo pedido borrador. La API de Pedidos Borrador de Shopify utiliza concurrencia optimista: si el borrador se modifica entre la lectura de BundlesIQ y la escritura de la transformación, la escritura falla.

Causas comunes:

1. Otra aplicación editando pedidos borrador — Aplicaciones que modifican pedidos borrador (por ejemplo, aplicaciones de descuentos, aplicaciones de impuestos) pueden entrar en conflicto
2. Edición manual durante el procesamiento — Un miembro del personal editó el pedido borrador en Shopify Admin mientras BundlesIQ lo estaba procesando
3. Automatización de flujo de trabajo de Shopify — Un flujo que modifica pedidos borrador puede activarse al mismo tiempo que BundlesIQ

Resolución:

1. Reintentar — Haga clic en Reintentar en el tablero de salud. En la mayoría de los casos, la edición concurrente fue una condición de carrera única y el reintento tiene éxito
2. Si los reintentos siguen fallando — Identifique el otro proceso que está editando el pedido borrador y coordine el tiempo. Es posible que necesite:
   • Desactivar temporalmente otras aplicaciones de pedidos borrador
   • Ajustar el tiempo del flujo de trabajo de Shopify
   • Asegurarse de que el personal no edite manualmente los pedidos borrador antes de que BundlesIQ los procese

Este error no se aplica a pedidos regulares. El procesamiento de pedidos regulares utiliza la API de Edición de Pedidos, que tiene diferentes semánticas de concurrencia.

3.3 Errores Específicos de BOM

Estos errores se aplican solo a paquetes que utilizan modo Solo Padre (BOM). Se relacionan con operaciones de reserva, consumo y liberación de inventario.

BOM_INSUFFICIENT_AVAILABLE

Síntoma: El procesamiento del pedido falla porque un componente no tiene suficiente inventario disponible.

Causa: La cantidad disponible del componente en la ubicación de inventario objetivo es menor de lo que requiere el paquete.

Resolución:

1. Verifique el inventario del componente en Shopify Admin en la ubicación relevante
2. Reabastezca el componente o ajuste la estrategia de ubicación
3. Si utiliza la estrategia de "ubicación del pedido de cumplimiento", verifique que el pedido tenga un pedido de cumplimiento asignado a una ubicación con suficiente stock
4. Reproceso el pedido después de que el inventario esté disponible

BOM_RESERVATION_FAILED

Síntoma: La llamada a la API de reserva de inventario falló a pesar de que parece haber suficiente inventario disponible.

Causa: Un error transitorio de la API de Inventario de Shopify, o otro proceso modificó el inventario entre la verificación de disponibilidad y la llamada de reserva.

Resolución:

1. Vuelva a intentar desde el tablero de salud — esto generalmente resuelve problemas transitorios de API
2. Si persiste, verifique si otra aplicación de gestión de inventario está en conflicto
3. Verifique que la ubicación de inventario esté configurada correctamente en Shopify

BOM_CONSUMPTION_FAILED

Síntoma: Cuando se cumplió el pedido, BundlesIQ no pudo consumir (decrementar) el inventario reservado.

Causa: La reserva puede haber sido liberada o consumida manualmente por otro proceso, o ocurrió un error de API de Shopify.

Resolución:

1. Verifique los niveles de inventario del componente — si la reserva ya fue consumida, no se necesita ninguna acción
2. Si el inventario es incorrecto, ajústelo manualmente en Shopify Admin
3. Verifique los registros del tablero de salud para el error específico de la API

BOM_RELEASE_FAILED

Síntoma: Cuando se canceló el pedido, BundlesIQ no pudo liberar el inventario reservado de nuevo a disponible.

Causa: La reserva puede haber sido consumida ya (si el pedido fue cumplido antes de la cancelación) o liberada por otro proceso.

Resolución:

1. Verifique si el inventario ya fue liberado — si las cantidades disponibles parecen correctas, no se necesita ninguna acción
2. Si el inventario está atascado en estado reservado, ajústelo manualmente en Shopify Admin
3. Contacte al soporte si esto ocurre repetidamente

BOM_LOCATION_NOT_FOUND

Síntoma: BundlesIQ no puede determinar qué ubicación de inventario usar para la reserva.

Causa: Depende de la estrategia de ubicación:

• "Ubicación del pedido de cumplimiento" — El pedido no tiene un pedido de cumplimiento con una ubicación asignada, o la ubicación asignada no lleva el componente
• "Ubicación única" — La ubicación configurada no existe o no tiene el componente en stock

Resolución:

1. Verifique la estrategia de ubicación en BundlesIQ > Configuración o la configuración de anulación del paquete
2. Si utiliza la ubicación del pedido de cumplimiento, verifique que el pedido tenga un pedido de cumplimiento asignado a una ubicación válida
3. Si utiliza una ubicación única, verifique que la ubicación configurada exista y tenga los productos componentes en stock
4. Asegúrese de que los componentes estén en stock en la ubicación relevante en Shopify Admin

3.4 Errores de API de Shopify

Códigos de error: SHOPIFY_THROTTLED, SHOPIFY_API_ERROR, SHOPIFY_TIMEOUT

Síntoma: El procesamiento falla con un error relacionado con la API de Shopify.

Cómo BundlesIQ maneja problemas de API de Shopify:

• Límites de tasa (SHOPIFY_THROTTLED): BundlesIQ espera automáticamente y vuelve a intentar con un retraso exponencial. No se necesita acción en la mayoría de los casos. Durante eventos de alto volumen (ventas rápidas, importaciones masivas), puede ver un breve retraso en el procesamiento.
• Errores de API (SHOPIFY_API_ERROR): Estos suelen ser transitorios. BundlesIQ vuelve a intentar automáticamente hasta el número máximo de intentos configurado (predeterminado: 1 reintento automático).
• Tiempos de espera (SHOPIFY_TIMEOUT): La API de Shopify tardó demasiado en responder. BundlesIQ vuelve a intentar automáticamente.

Cuándo tomar acción:

• Si un error de API de Shopify persiste después de reintentos automáticos, verifique Estado de Shopify para problemas de plataforma en curso
• Si la limitación de tasa es frecuente, revise si otras aplicaciones en su tienda están consumiendo una cuota excesiva de API
• Haga clic en Reintentar en el tablero de salud para activar manualmente un reintento después de que se resuelva el problema

3.5 Errores de Autenticación

Códigos de error: AUTH_MISSING_CREDENTIALS, AUTH_MISSING_TOKEN, AUTH_INVALID_TOKEN, AUTH_PERMISSIONS_REVOKED

Síntoma: El procesamiento falla con un error de autenticación. Todos los pedidos fallan, no solo paquetes específicos.

Causas comunes:

1. Se revocaron los permisos de la aplicación — Alguien cambió los permisos de la aplicación en Shopify Admin
2. La aplicación fue desinstalada y reinstalada — El token de acceso anterior fue invalidado
3. Rotación de token de Shopify — Raro, pero Shopify puede rotar tokens durante actualizaciones de plataforma

Resolución:

1. Vaya a Shopify Admin > Configuración > Aplicaciones y canales de ventas
2. Encuentre BundlesIQ y haga clic en Administrar
3. Si faltan permisos, haga clic para volver a otorgarlos
4. Si el problema persiste, desinstale y reinstale BundlesIQ desde la App Store de Shopify
5. Después de la reinstalación, verifique que sus paquetes y configuraciones estén intactos (se almacenan en el servidor y se volverán a conectar)

Todos los pedidos en cola se procesarán una vez que se restablezca la autenticación. No se pierden pedidos.

4. Solución de Problemas de Precios y Reportes

4.1 Descuento o Precio Se Ve Mal

Síntomas: Después del procesamiento del paquete, los precios de los componentes en el pedido no coinciden con lo que esperaba.

Verifique lo siguiente en orden:

1. Verifique su estrategia de precios

   • Abra el paquete en BundlesIQ y verifique el modo de precios (dirigido por el paquete o dirigido por componentes) y la estrategia
   • Revise la vista previa del precio para ver la asignación esperada

2. Verifique si hay advertencias de precios (banderas de transformación)

   • En el tablero de salud de BundlesIQ, busque banderas en el pedido:

   

   • BUNDLE_EXCEEDS_COMPONENTS — El precio del paquete es más alto que la suma de los precios de los componentes. Consulte Sección 2.4
   • PRICE_INCREASE_NOT_POSSIBLE — No se pudo establecer un componente al precio objetivo porque la API de Edición de Pedidos de Shopify no permite aumentos de precio. Consulte Sección 2.4
   • SPECIFIC_RETAIL_EXCEEDS_CONTEXTUAL — El precio de venta al por menor configurado de un componente en BundlesIQ es más alto que su precio actual en Shopify. Se utiliza el precio de Shopify en su lugar
   • DOLLAR_DISCOUNT_EXCEEDS_RETAIL — Un descuento en dólares es mayor que el precio de venta del componente. El descuento se limita al precio de venta
   • ORDER_LEVEL_PROMO_ROUNDING_VARIANCE — Se detectó una pequeña diferencia de redondeo al distribuir una promoción a nivel de pedido. Se agregó una línea de reconciliación para equilibrar el total

3. Verifique si se aplicó un código de descuento de Shopify

   • Si el cliente utilizó un código de descuento en el checkout, BundlesIQ lo tiene en cuenta en la asignación de precios
   • El efecto combinado de la asignación del paquete + el código de descuento puede producir precios por componente que parecen inesperados

4. Verifique si hay variaciones de redondeo

   • Pueden ocurrir pequeñas diferencias de 1-10 centavos debido al redondeo durante la asignación de precios
   • El absorbedor de variancia de BundlesIQ corrige automáticamente estas, pero puede ver porcentajes de descuento ligeramente diferentes en componentes individuales

5. Verifique el precio actual de Shopify del componente

   • BundlesIQ utiliza el precio actual de Shopify del componente (precio contextual) al calcular descuentos
   • Si el precio de un componente cambió después de que se configuró el paquete, la asignación puede diferir de la vista previa

4.2 El Reporte No Coincide Con Lo Que Espero

Síntomas: Shopify Analytics o sus herramientas de reporte muestran atribución de ingresos inesperada, clasificaciones de los más vendidos o datos de ventas después de implementar BundlesIQ.

Entienda la causa raíz:

La atribución de ingresos depende completamente de su modo de manejo:

Si desea ingresos en el SKU del paquete: Use modo reportando o modo Solo Padre (BOM)

Si desea ingresos en los SKU de componentes: Use modo híbrido o modo operativo

Si ya procesó pedidos en el modo incorrecto:

• Cambie su modo de manejo de aquí en adelante (solo nuevos pedidos)
• Los pedidos procesados previamente no se cambian retroactivamente
• Es posible que deba reconciliar manualmente los datos históricos en sus herramientas de reporte

Clasificaciones de los más vendidos:

• En los modos Híbrido y Operativo, los componentes individuales pueden aparecer como los más vendidos en lugar del paquete
• En los modos Reportando y Solo Padre, el producto del paquete aparece en las clasificaciones de los más vendidos

Feeds de canal (Meta, TikTok, Google):

• Algunas integraciones de canal leen datos de pedidos para determinar el rendimiento del producto
• En los modos Híbrido y Operativo, la analítica del canal puede atribuir ventas a SKU de componentes
• Si la atribución del canal es importante, considere el modo reportando

5. Inventario y Disponibilidad

5.1 El Paquete Muestra Sin Stock

Síntomas: Su producto de paquete muestra como "Sin stock" en la tienda, pero cree que los componentes tienen inventario.

Verifique lo siguiente en orden:

1. Verifique todos los niveles de inventario de los componentes

   • La disponibilidad del paquete se determina por el componente menos disponible
   • Abra cada producto componente en Shopify Admin y verifique su inventario en la ubicación relevante
   • Incluso un componente en cero hace que todo el paquete no esté disponible

2. Verifique la ubicación correcta

   • Si tiene múltiples ubicaciones de Shopify, verifique el inventario en la ubicación que atiende pedidos en línea
   • Un componente puede tener stock en una ubicación pero no en otra

3. Verifique la configuración de seguimiento de inventario del SKU fantasma

   • Si el seguimiento de inventario está habilitado en el SKU fantasma, BundlesIQ establece su cantidad disponible en función de los componentes
   • Si el seguimiento de inventario está deshabilitado, el producto debería mostrarse siempre como en stock — verifique otras razones por las que podría estar oculto (estado del producto, disponibilidad del canal)

4. Verifique "Continuar vendiendo cuando esté sin stock"

   • En la variante del SKU fantasma: si esto está deshabilitado y el inventario es 0, Shopify muestra "Sin stock"
   • Si desea permitir compras incluso cuando la disponibilidad calculada sea 0, habilite esta configuración (pero tenga en cuenta el riesgo de sobreventa)

5. Verifique si la sincronización de inventario está habilitada

   • En BundlesIQ > Configuración, verifique que Sincronizar inventario del paquete esté habilitado
   • En el paquete específico, verifique que la sincronización de inventario no esté deshabilitada a nivel de paquete

6. Calcule la disponibilidad manualmente

   • Para cada componente: divida la cantidad disponible por la cantidad por paquete
   • El resultado mínimo es la disponibilidad del paquete
   • Compare con el inventario actual del SKU fantasma en Shopify

7. Modo Solo Padre (BOM): verifique las cantidades reservadas

   • Si utiliza el modo Solo Padre, el inventario reservado de componentes reduce la cantidad disponible
   • Si muchos pedidos tienen componentes reservados pero aún no consumidos, la cantidad disponible puede ser menor de lo esperado
   • Verifique el desglose de reservado vs. disponible del componente en Shopify Admin

5.2 Solo Padre: Inventario de Componentes No Reservado

Síntomas: Colocó un pedido con un paquete Solo Padre, pero las cantidades reservadas de inventario de componentes no cambiaron.

Verifique lo siguiente en orden:

1. ¿Se procesó el pedido?

   • Verifique el tablero de salud de BundlesIQ para el estado del pedido
   • Si el pedido no está listado, el webhook puede no haber sido recibido

2. Verifique la configuración de tiempo de reserva

   • Si el tiempo de reserva está configurado como orders/paid, el inventario solo se reserva después de que se confirma el pago
   • Si el pedido no está pagado, cambie a orders/create para reservar inmediatamente, o espere el pago

3. Verifique la estrategia de ubicación

   • Si está configurada como "ubicación del pedido de cumplimiento", verifique que el pedido tenga un pedido de cumplimiento asignado a una ubicación con inventario de componentes
   • Si está configurada como "ubicación única", verifique que la ubicación configurada tenga suficiente stock de componentes

4. Verifique los niveles de inventario de los componentes

   • Si un componente tiene cero disponible en la ubicación objetivo, la reserva puede fallar
   • Verifique el tablero de salud para obtener detalles de error — consulte Sección 3.3 para la resolución de errores específicos de BOM

6. Procedimientos y Orientación Operativa

6.1 Reintentar vs. Reprocesar: ¿Cuál Debo Usar?

Ambas opciones están disponibles en el tablero de salud, pero hacen cosas diferentes:

Guía de decisión:

• El pedido falló con SHOPIFY_THROTTLED, SHOPIFY_API_ERROR o SHOPIFY_TIMEOUT → Reintentar
• El pedido falló con DRAFT_CONCURRENT_EDIT → Reintentar (la edición concurrente fue probablemente una condición de carrera única)
• Cambió la configuración del paquete (componentes, precios, modo de manejo) → Reprocesar
• El pedido tiene un estado de procesamiento obsoleto o dañado → Reprocesar (modo forzado)
• El pedido falló con PRODUCT_NOT_FOUND o VARIANT_NOT_FOUND y usted corrigió el producto → Reprocesar
• No está seguro → Comience con Reintentar. Si falla nuevamente con el mismo error, investigue y luego Reprocesar después de corregir el problema

Nota sobre el modo Solo Padre (BOM): Reprocesar un pedido Solo Padre liberará cualquier reserva de inventario existente antes de volver a ejecutar el pipeline. Si el pedido ya ha sido parcialmente cumplido, algunas reservas pueden haber sido consumidas ya — use precaución.

6.2 Cómo Saber Si un Pedido Fue Procesado

Hay varias maneras de confirmar si BundlesIQ ha procesado un pedido:

1. Verifique las etiquetas del pedido en Shopify Admin

   • BIQ_READY — El pedido fue procesado con éxito
   • BIQ_PROCESSING — El procesamiento está actualmente en progreso
   • BIQ_ERROR — El procesamiento falló (verifique el tablero de salud para obtener detalles)
   • BIQ_REVERTED — Un pedido borrador fue revertido a su estado anterior a la transformación

2. Verifique el metafield del pedido

   • Busque el metafield bundles_iq.transformation_audit en el pedido
   • Esto contiene el registro completo de transformación incluyendo asignaciones de paquetes, asignaciones de precios y banderas

3. Verifique el tablero de salud de BundlesIQ

   • Busque el pedido por número o ID
   • El tablero muestra el estado de procesamiento, la línea de tiempo y cualquier error o elemento de atención

4. Verifique las líneas de artículos de componente (solo en modos Híbrido, Operativo y Reportando)

   • En modo híbrido: paquete a $0, componentes con precios
   • En modo operativo: paquete eliminado, solo permanecen los componentes
   • En modo reportando: paquete al precio original, componentes a $0
   • En modo Solo Padre: no hay cambios visibles en el pedido — use el tablero de salud o la etiqueta BIQ_READY en su lugar

6.3 Reprocesar y Revertir Pedidos

BundlesIQ proporciona herramientas administrativas para reprocesar pedidos fallidos y revertir transformaciones de pedidos borrador. Estas herramientas son accesibles desde la página de detalles del pedido/pedido borrador en Shopify Admin a través del menú de acción Herramientas de Paquete.

Reprocesar (Pedidos y Pedidos Borrador)

Reprocesar vuelve a ejecutar el pipeline completo de transformación del paquete para un pedido. Úselo cuando:

• El procesamiento falló y se resolvió el error (por ejemplo, se volvió a agregar una variante faltante)
• Se cambió la configuración del paquete y desea re-transformar un pedido
• Necesita limpiar un estado de procesamiento obsoleto

Consulte Sección 6.1 para obtener orientación sobre cuándo reintentar vs. reprocesar.

Cómo reprocesar:

1. Abra el pedido o pedido borrador en Shopify Admin
2. Haga clic en la acción Herramientas de Paquete (en el menú "Más acciones")
3. Haga clic en Reprocesar Paquete
4. Si el pedido ya fue procesado con éxito, BundlesIQ le advertirá y ofrecerá una opción de Forzar Reproceso

Lo que sucede durante el reprocesamiento:

1. Las instancias de paquete existentes en BundlesIQ se cancelan y eliminan
2. Se eliminan todas las etiquetas BIQ_* del pedido (incluyendo BIQ_PROCESSING, BIQ_READY, BIQ_ERROR y BIQ_REVERTED)
3. Si el metafield del paquete ya existe en el pedido, se elimina (solo modo forzado)
4. Se recuperan los datos completos del pedido de Shopify y se publican para procesamiento
5. El trabajador de webhook detecta paquetes y los procesa como si el pedido fuera nuevo

Forzar Reproceso es una escalación de seguridad. Elimina instancias procesadas existentes y metafields antes de volver a ejecutar el pipeline. Úselo solo cuando esté seguro de que la transformación anterior necesita ser reemplazada.

Nota sobre el modo Solo Padre (BOM): Reprocesar un pedido Solo Padre liberará cualquier reserva de inventario existente antes de volver a ejecutar el pipeline. Si el pedido ya ha sido parcialmente cumplido, algunas reservas pueden haber sido consumidas ya — use precaución y verifique los niveles de inventario después de reprocesar.

Revertir (Solo Pedidos Borrador)

Revertir deshace una transformación de paquete en un pedido borrador, restaurándolo a su estado anterior a BundlesIQ. Esto solo está disponible para pedidos borrador — los pedidos regulares no pueden ser revertidos porque la API de Edición de Pedidos no admite la eliminación de artículos de línea previamente agregados.

Cómo revertir:

1. Abra el pedido borrador en Shopify Admin
2. Haga clic en la acción Herramientas de Paquete
3. Elija una de:
   • Revertir Solo — Elimina todos los componentes del paquete y restaura las líneas de SKU fantasma originales. El pedido borrador se deja en su estado anterior a la transformación y no se reprocesará (se aplica una etiqueta BIQ_REVERTED para prevenir re-transformación automática)
   • Revertir y Reprocesar — Revierte el pedido borrador y luego vuelve a ejecutar inmediatamente el pipeline completo de procesamiento. Se eliminan todas las etiquetas BIQ_* y se inicia un procesamiento limpio

Lo que hace la reversión según el modo de manejo:

La Etiqueta BIQ_REVERTED

Cuando se revierte un pedido borrador (sin reprocesar), BundlesIQ aplica la etiqueta BIQ_REVERTED. Esta etiqueta le dice al trabajador de webhook que omita el pedido borrador cuando se activa el webhook draft_orders/update (que Shopify envía en respuesta a la mutación de reversión). Sin esta etiqueta, el trabajador volvería a transformar inmediatamente el pedido borrador.

• Revertir Solo: la etiqueta BIQ_REVERTED se mantiene — previene la re-transformación automática
• Revertir y Reprocesar: se eliminan todas las etiquetas BIQ_* — la publicación intencionada activa un reprocesamiento limpio

7. Preguntas Frecuentes

7.1 ¿Cuánto Tiempo Toma el Procesamiento?

BundlesIQ procesa pedidos de manera asíncrona después de recibir el webhook de Shopify:

Si la protección 3PL está habilitada, el pedido se retiene hasta que se complete el procesamiento, por lo que las variaciones de tiempo no causan problemas de cumplimiento.

7.2 ¿Se Transfieren las Propiedades de Artículos de Línea a los Componentes?

BundlesIQ actualmente no transfiere propiedades de artículos de línea (como mensajes de regalo, texto de grabado o campos personalizados) de la línea del SKU fantasma a las líneas de artículos de componente.

Solución alternativa: Si necesita propiedades de artículos de línea en los componentes, puede:

• Agregar las propiedades manualmente después de que BundlesIQ procese el pedido
• Usar un flujo de trabajo de Shopify para copiar propiedades de la línea original a las líneas de componentes
• Contactar al soporte para discutir su caso de uso específico

7.3 ¿Pueden los Clientes Seguir Aplicando Códigos de Descuento?

Sí. Los clientes pueden aplicar códigos de descuento de Shopify en el checkout como de costumbre. BundlesIQ detecta cualquier descuento aplicado y lo tiene en cuenta en la asignación de precios de los componentes durante la transformación.

Cómo funciona:

• El código de descuento se aplica al SKU fantasma en el checkout
• BundlesIQ detecta el descuento y su tipo (porcentaje, monto fijo, BOGO, etc.)
• Durante la transformación, BundlesIQ distribuye tanto el descuento de asignación del paquete como el descuento del checkout entre los componentes

Limitaciones:

• Los descuentos automáticos de Shopify funcionan de la misma manera — BundlesIQ los tiene en cuenta
• El comportamiento de apilamiento de descuentos está gobernado por las reglas de Shopify (por ejemplo, solo un código de descuento por pedido a menos que su tienda soporte apilamiento)

7.4 ¿Funciona BundlesIQ con Shopify POS?

Sí. BundlesIQ procesa pedidos de todos los canales de Shopify, incluido POS. Cuando un pedido de POS contiene un SKU de paquete fantasma, se procesa de la misma manera que un pedido en línea.

Nota: BundlesIQ no proporciona una interfaz de usuario específica para POS. El personal que utiliza POS debe agregar el producto SKU fantasma a la venta; BundlesIQ transforma el pedido después de que se crea.

7.5 ¿Qué Sucede Si Cambio Mi Modo de Manejo Después de Procesar Pedidos?

El cambio de modo se aplica solo a nuevos pedidos. Los pedidos procesados previamente no se modifican retroactivamente. Consulte Sección 1.7 para obtener detalles.

Anulaciones por paquete: Puede establecer diferentes modos de manejo por paquete. Esto significa que puede ejecutar el modo operativo para sus paquetes mayoristas y el modo reportando para sus paquetes DTC simultáneamente.

7.6 ¿Por Qué el Cliente Ve Algo Diferente en Su Correo Electrónico de Confirmación de Pedido?

El correo electrónico de confirmación del pedido es enviado por Shopify inmediatamente después de la creación del pedido — antes de que BundlesIQ reciba el webhook y procese el pedido. Esto significa que el correo muestra el pedido original, antes de la transformación (solo el producto del paquete al precio de compra).

Después del procesamiento (típicamente 2-15 segundos después), el pedido en Shopify Admin muestra la versión transformada. Si el cliente revisa su página de estado del pedido o el historial de cuentas después de que se complete el procesamiento, verá el pedido transformado.

Consulte Sección 1.6 para el desglose completo.

Consejo: Si desea que el pedido visible para el cliente coincida lo más posible con el correo electrónico, use modo reportando o modo Solo Padre — estos preservan el nombre y el precio del paquete en el pedido, por lo que el pedido transformado se ve muy similar al correo electrónico.

7.7 Pedidos de Múltiples Paquetes: Qué Esperar

Cuando un solo pedido contiene múltiples paquetes, BundlesIQ procesa todos los paquetes en una sola transformación:

• Todos los paquetes en el pedido se detectan durante el procesamiento inicial del webhook
• Cada paquete se transforma de manera independiente de acuerdo con su propio modo de manejo (si se establecen anulaciones por paquete)
• Se agregan líneas de componentes para cada paquete — si dos paquetes comparten una variante de componente, esas líneas de componentes aparecen por separado (una por paquete)
• El tiempo de procesamiento aumenta ligeramente con múltiples paquetes (5-15 segundos típico)

Modos de manejo mixtos en un pedido:

Si un paquete está configurado en modo híbrido y otro en modo operativo, la transformación de cada paquete sigue las reglas de su propio modo. El pedido puede mostrar una mezcla de líneas de paquetes a $0, líneas de paquetes eliminadas y líneas de componentes con precios.

Consejo: Para simplificar, recomendamos usar el mismo modo de manejo para todos los paquetes en una sola tienda. Los modos mixtos en un pedido son compatibles, pero pueden crear pedidos que se vean confusos.

7.8 El Procesamiento Toma Más Tiempo de lo Esperado

Síntomas: Los pedidos no se transforman dentro de la ventana esperada de 2-15 segundos.

Causas posibles:

1. Alto volumen de webhook — Durante eventos de ventas o importaciones masivas de pedidos, el procesamiento de webhook puede estar en cola
2. Limitación de API de Shopify — Si su tienda está alcanzando los límites de tasa de la API de Shopify, BundlesIQ espera y vuelve a intentar
3. Paquetes complejos — Los paquetes con muchos componentes o múltiples paquetes en un solo pedido tardan más
4. Reintento en progreso — Si el procesamiento inicial falló, BundlesIQ puede estar esperando el período de enfriamiento antes de volver a intentar

Qué hacer:

• Verifique el tablero de salud para el estado del pedido
• Si el pedido muestra "Pendiente" o "Procesando", espere unos minutos
• Si el pedido muestra "Fallido", verifique el mensaje de error y resuelva el problema
• Si la protección 3PL está habilitada, el pedido permanece retenido hasta que se complete el procesamiento — sin riesgo de cumplimiento

7.9 Preguntas Comunes de la Semana de Lanzamiento

Si acaba de activar BundlesIQ, aquí están las situaciones más comunes durante la primera semana:

"Mi 3PL importó pedidos antes de que BundlesIQ los procesara"

Si su 3PL extrae pedidos inmediatamente después de la creación (antes de la ventana de procesamiento de 2-15 segundos de BundlesIQ), el 3PL puede haber importado el pedido antes de la transformación.

Solución: Habilite la protección 3PL (retención de cumplimiento) en BundlesIQ > Configuración. Esto coloca una retención de cumplimiento en los pedidos hasta que se complete el procesamiento, previniendo la importación prematura del 3PL. La retención se libera automáticamente después de una transformación exitosa.

"Mi almacén está confundido por líneas de componentes a $0"

Si utiliza el modo reportando, las líneas de componentes aparecen a $0. Algunos empleados del almacén o 3PL interpretan esto como "artículos gratuitos" o están confundidos por las líneas de cero dólares.

Soluciones:

• Cambie a modo operativo si el almacén solo necesita SKU y precios reales (sin referencia de paquete necesaria)
• Cambie a modo híbrido si desea que la referencia del paquete sea visible pero los componentes tengan precios
• Entrene al personal del almacén que las líneas a $0 en modo reportando son artículos solo para cumplimiento — la línea del paquete lleva el precio total
• Use la función de encabezado de paquete en Opciones de Escritor para agregar etiquetas de agrupación

"Algunos pedidos fueron procesados pero otros no"

Verifique estas causas comunes de la semana de lanzamiento:

1. Alcance de procesamiento: ¿Está configurado en "Todos los pedidos" o "Solo etiquetados"? Si solo etiquetados, verifique las etiquetas
2. Estado del paquete: ¿Todos los paquetes están configurados como Activos? Los paquetes borradores no se procesan
3. Tiempo del pedido: Los pedidos realizados antes de que BundlesIQ se instalara/habilitara no se procesan retroactivamente
4. Desajuste de SKU fantasma: Verifique que el ID de variante del SKU fantasma en el paquete coincida con el producto variante real de Shopify

"Lancé con el modo de manejo incorrecto"

No hay problema: cambie el modo en BundlesIQ > Configuración (o anulación por paquete). El nuevo modo se aplica a todos los nuevos pedidos de inmediato. Los pedidos procesados previamente no se ven afectados. Si necesita re-transformar pedidos borrador específicos, use Revertir y Reprocesar.

8. Páginas Relacionadas

• Introducción
• Modos de Manejo Explicados
• Cómo Se Ven los Pedidos en Cada Modo
• Configuración de Estrategia de Precios
• Reglas de Inventario
• Lista de Verificación de Lanzamiento
• Guía de Integración 3PL
• Resumen de Configuración Global