Oleada 5 · Documentación

Inventario omnicanal

Un catálogo central y un stock compartido entre tu tienda propia y tus marketplaces conectados.

Qué resuelve PushSLog

PushSLog mantiene un inventario maestro por tenant. Cada producto tiene un SKU maestro y, por cada tienda conectada, un mapeo de canal que enlaza el listing externo (Shopify, WooCommerce, Mercado Libre, Tienda Nube o API CUSTOM) con ese SKU.

Cuando la fuente de verdad está en PUSHSLOG_CENTRAL, una venta pagada en cualquier canal descuenta stock en el catálogo central y puede replicarse hacia los demás canales mapeados. Si falta mapeo o hay conflicto, el panel expone alertas para corregir antes de seguir vendiendo.

Requiere plan con feature inventario (Basic o superior). Conecta canales antes en Guías por plataforma.

Conceptos clave

SKU maestro — Identificador único del tenant en el catálogo central (masterSku). Es la referencia común entre canales.
Mapeo de canal — Fila que vincula channelVariantId / channelSku de una tienda con el maestro. Estados: linked (OK), unmapped (sin vínculo), conflict (duplicado o ambigüedad).
Fuente de verdad — Configuración del tenant: PUSHSLOG_CENTRAL (stock maestro en PushSLog) o SHOP (una tienda manda el stock). La réplica automática tras ventas aplica con PUSHSLOG_CENTRAL.
Sync de catálogo — Importación de productos y variantes desde las tiendas hacia PushSLog. No sustituye el mapeo: tras el sync conviene revisar mapeos o ejecutar backfill.

Canales soportados

Importación de catálogo y mapeo automático post-sync:

Plataforma	Conexión	Guía
Shopify	OAuth desde el panel	Ver guía
WooCommerce	Plugin + API key pk_	Ver guía
Mercado Libre	OAuth o registro seller	Ver guía
Tienda Nube	OAuth o token	Ver guía
API CUSTOM	POST catálogo con pk_	Quick Start

Falabella / VTEX: en roadmap; no forman parte del contrato estable actual.

Flujo operativo recomendado

Conecta cada tienda (canales) y confirma tokens válidos.
En el panel → Inventario → Catálogo central, pulsa Sincronizar tiendas o usa la API (abajo).
Revisa SKUs por canal: mapeos linked, pendientes unmapped o conflict.
Si hace falta, Regenerar mapeos (OWNER/ADMIN) o vincula manualmente vía API.
Configura fuente PUSHSLOG_CENTRAL en Alertas inventario si quieres baja y réplica automática tras ventas.
Monitoriza alertas (stock 0, sin mapear, duplicados) y la auditoría de deducciones en el mismo módulo.

Integración con API key (pk_)

Para automatizar sync desde tu backend, cron o plugin, usa la misma pk_ que en el Quick Start. Header recomendado: x-api-key: pk_… (también Authorization: Bearer pk_…).

Rutas de sync y estado aceptan pk_ o sesión JWT. Listado de mapeos, config de inventario y publicación masiva requieren hoy sesión del panel (rol manager donde aplique).

Método	Ruta	Auth	Descripción
POST	/api/v1/tenant/catalog/sync	pk_ o Bearer sesión (OWNER/ADMIN si es sesión)	Importa catálogo desde tiendas activas (Shopify, Woo, ML, TN, CUSTOM). Body opcional { shopId }.
GET	/api/v1/tenant/catalog/sync/jobs/:jobId	pk_ o Bearer sesión	Estado del job en cola catalog-sync (completed, failed, result).
GET	/api/v1/tenant/shops/:shopId/sync-status	pk_ o Bearer sesión	Última sincronización registrada para una tienda del tenant.
GET	/api/v1/woocommerce/shops/:shopId/sync-status	pk_	Alias histórico Woo; preferir /tenant/shops/:shopId/sync-status.

1. Sincronizar todas las tiendas activas (Shopify, Woo, ML, TN, CUSTOM del tenant):

curl -s -X POST "https://api.pushslog.com/api/v1/tenant/catalog/sync" \
  -H "x-api-key: $PUSHSLOG_API_KEY"

2. Sincronizar una sola tienda — útil para Pushopy (Shopify) o una Woo concreta:

curl -s -X POST "https://api.pushslog.com/api/v1/tenant/catalog/sync" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PUSHSLOG_API_KEY" \
  -d '{ "shopId": "uuid-de-tu-tienda" }'

Con colas activas en el servidor (REDIS_URL), la respuesta es 202 y debes consultar el job:

{
  "success": true,
  "queued": true,
  "jobId": "catalog-sync:tenant-id:…",
  "message": "Sincronización de catálogo en cola; consulta el estado con GET /api/v1/tenant/catalog/sync/jobs/:jobId."
}

curl -s "https://api.pushslog.com/api/v1/tenant/catalog/sync/jobs/JOB_ID" \
  -H "x-api-key: $PUSHSLOG_API_KEY"

Cuando state es completed, result incluye el detalle por tienda:

{
  "success": true,
  "data": {
    "jobId": "catalog-sync:…",
    "state": "completed",
    "tenantId": "…",
    "shopId": null,
    "result": {
      "shopsProcessed": 2,
      "shopsFailed": 0,
      "productsSynced": 48,
      "variantsSynced": 112,
      "hasMore": false,
      "shopResults": [
        {
          "shopId": "…",
          "shopName": "Pushopy",
          "platform": "SHOPIFY",
          "productsSynced": 24,
          "variantsSynced": 56,
          "hasMore": false,
          "lastSyncAt": "2026-06-09T18:30:00.000Z"
        },
        {
          "shopId": "…",
          "shopName": "Mi Woo",
          "platform": "WOOCOMMERCE",
          "productsSynced": 24,
          "variantsSynced": 56,
          "hasMore": false,
          "lastSyncAt": "2026-06-09T18:30:05.000Z"
        }
      ]
    }
  }
}

3. Consultar última sync de una tienda (sin esperar cola):

curl -s "https://api.pushslog.com/api/v1/tenant/shops/SHOP_ID/sync-status" \
  -H "x-api-key: $PUSHSLOG_API_KEY"

API del panel (sesión JWT)

El módulo Inventario del panel consume estas rutas con el token de sesión. Son la base del contrato si construyes un cliente propio sobre el panel (no sustituyen pk_ para sync desatendido).

Método	Ruta	Auth	Descripción
GET	/api/v1/tenant/catalog/products	Bearer sesión · plan inventario	Listado paginado del catálogo central (search, limit, offset).
PATCH	/api/v1/tenant/catalog/master-variants/:masterVariantId	Bearer sesión · manager	Actualiza stock o metadatos del SKU maestro.
GET	/api/v1/tenant/catalog/channel-mappings	Bearer sesión · plan inventario	Mapeos canal ↔ maestro (shopId, status, search, limit).
POST	/api/v1/tenant/catalog/channel-mappings	Bearer sesión · manager	Vincula manualmente un listing de canal con un SKU maestro.
POST	/api/v1/tenant/catalog/channel-mappings/backfill	Bearer sesión · manager	Regenera mapeos desde variantes ya importadas (body opcional { shopId }).
GET	/api/v1/tenant/inventory/config	Bearer sesión	Fuente de verdad de stock y preferencias de alertas.
PATCH	/api/v1/tenant/inventory/config	Bearer sesión · manager	Define PUSHSLOG_CENTRAL o SHOP maestro; configura alertas.
GET	/api/v1/tenant/inventory/alerts/summary	Bearer sesión · plan inventario	Contadores: stock 0, sin mapear, conflictos, deducciones unmapped.
GET	/api/v1/tenant/inventory/stock-deductions	Bearer sesión · plan inventario	Auditoría de bajas de stock por ventas en canal.
POST	/api/v1/tenant/catalog/publish-bulk	Bearer sesión · manager	Publicación masiva de stock/SKU hacia canales elegidos (cola catalog-publish).

Ejemplo de ítem en listado de mapeos (GET …/channel-mappings):

{
  "id": "…",
  "shopId": "…",
  "shopName": "Pushopy",
  "platform": "SHOPIFY",
  "masterVariantId": "…",
  "masterSku": "CAMISETA-AZUL-M",
  "masterName": "Camiseta azul — M",
  "channelVariantId": "gid://shopify/ProductVariant/…",
  "channelSku": "CAMISETA-AZUL-M",
  "status": "linked",
  "lastSyncedAt": "2026-06-09T18:30:00.000Z"
}

Configuración de fuente de verdad y alertas (PATCH /api/v1/tenant/inventory/config):

{
  "inventorySourceType": "PUSHSLOG_CENTRAL",
  "inventorySourceShopId": null,
  "inventoryAlertsEnabled": true,
  "inventoryAlertWebhookUrl": "https://ops.mi-tienda.com/hooks/inventario",
  "inventoryAlertEmails": "[email protected]"
}

Exportación puntual de stock hacia un canal (manager): POST /api/v1/tenant/catalog/export-stock/{woocommerce|shopify|mercadolibre|tiendanube|custom} y variantes /bulk. Publicación masiva: POST /api/v1/tenant/catalog/publish-bulk + GET …/publish-bulk/jobs/:jobId.

Ventas y stock multi-canal

Los pedidos entrantes siguen el flujo de cada canal (webhooks). Cuando el tenant tiene PUSHSLOG_CENTRAL y el SKU está linked, PushSLog registra una deducción de stock (applied) y puede empujar el nuevo stock a otros canales mapeados.

Línea sin mapeo → deducción unmapped; corrige el mapeo y usa POST …/inventory/stock-deductions/retry.
Cancelación o reembolso → reversión reversed cuando el canal lo notifica.
Shopify conectado antes de scopes de inventario puede requerir re-autorizar OAuth en Mis tiendas.
Órdenes pagadas antes de activar la regla no retroactivan deducción: usa pedidos de prueba nuevos.

Errores frecuentes

HTTP	error	Cuándo
403	PLAN_INVENTARIO_LOCKED	El tenant no tiene plan con feature inventario (Basic o superior).
202	—	Sync o publicación encolados; consulta jobId con GET …/jobs/:jobId.
400	INVALID_INVENTORY_SOURCE_TYPE	inventorySourceType distinto de SHOP, PUSHSLOG_CENTRAL o null.
400	INVALID_MAPPING_STATUS	Filtro status en channel-mappings distinto de linked, unmapped, conflict.
404	JOB_NOT_FOUND	jobId inexistente o de otro tenant.
404	SHOP_NOT_FOUND	shopId no pertenece al tenant.
500	CATALOG_SYNC_FAILED	Fallo al leer catálogo del canal (token, OAuth o red); revisa credenciales.

Errores transversales de auth (API_KEY_INVALID, SESSION_REQUIRED): Autenticación y FAQ.

Límites y buenas prácticas

Sync WooCommerce puede devolver hasMore: true en catálogos grandes; repite la sync hasta completar páginas.
Listados de mapeos en panel: hasta 200 filas por consulta; usa shopId, status y search para acotar.
No publiques masivamente a canales con mapeos unmapped o conflict sin revisar alertas.
Rate limits por plan: reduce concurrencia si recibes 429.

Documentación relacionada

Guías por plataforma — conexión OAuth, registro y webhooks.
Referencia API — tabla resumida de rutas v1.
Autenticación — pk_ vs JWT.
Webhooks — pedidos que disparan deducciones.

¿Integración en producción o dudas sobre mapeos? Contacta soporte con tenant, shopId, masterSku y hora UTC del incidente.