Oleada 5 · Documentación

Referencia API (v1)

Catálogo de endpoints públicos de integración. OpenAPI 3.1 parcial para Postman e Insomnia.

Base URL: https://api.pushslog.com. Éxito: { "success": true, "data": … }. Error: { "error": "CODE", "message": "…" }.

Descargar openapi.json · Quick Start · Autenticación · Guías por plataforma · Inventario omnicanal · Webhooks (firmas) · FAQ

Salud y disponibilidad

Método	Ruta	Auth	Descripción
GET	/health	Público	Liveness — proceso arriba.
GET	/health/ready	Público	Readiness — PostgreSQL y Redis (503 si no listo).

Autenticación y API keys

Login/registro/refresh son para el panel. Las integraciones servidor a servidor usan pk_ (ver tabla y Autenticación).

Método	Ruta	Auth	Descripción
POST	/api/v1/auth/login	Público	Inicio de sesión panel (tenantSlug, email, password) → accessToken + refreshToken.
POST	/api/v1/auth/register	Público	Alta de usuario tenant (acepta términos/privacidad/SIC).
POST	/api/v1/auth/refresh	Público	Renueva tokens con refreshToken.
GET	/api/v1/tenant/api-keys	Bearer sesión	Lista API keys del tenant (sin secretos).
POST	/api/v1/tenant/api-keys	Bearer sesión	Crea pk_… (se muestra una sola vez).
DELETE	/api/v1/tenant/api-keys/:apiKeyId	Bearer sesión	Revoca una API key.

API CUSTOM (ecommerce propio)

Método	Ruta	Auth	Descripción
POST	/api/v1/custom/shops/register	x-api-key pk_	Registra tienda CUSTOM; devuelve shopId, webhookEndpoint y webhookSecret.
POST	/api/v1/custom/orders	x-api-key pk_	Ingesta de pedido (orderId, total, shippingAddress opcional).
POST	/api/v1/custom/catalog/products	x-api-key pk_	Alta/actualización masiva de catálogo (products[] o items[]).

POST https://api.pushslog.com/api/v1/custom/shops/register
x-api-key: pk_…
Content-Type: application/json

{
  "externalShopId": "mi-tienda.com",
  "name": "Mi tienda"
}

POST https://api.pushslog.com/api/v1/custom/orders
x-api-key: pk_…
Content-Type: application/json

{
  "shopId": "uuid-de-tienda",
  "orderId": "ORD-1001",
  "total": 129900,
  "currency": "COP",
  "shippingAddress": {
    "city": "Bogotá",
    "address": "Calle 123",
    "zip": "110111"
  }
}

POST https://api.pushslog.com/api/v1/custom/catalog/products
x-api-key: pk_…

{
  "shopId": "uuid-tienda",
  "products": [
    { "sku": "SKU-1", "name": "Producto", "price": 19900, "stock": 10 }
  ]
}

Canales (registro y OAuth)

Detalle paso a paso y curls en Guías por plataforma. Shopify OAuth requiere Bearer de sesión, no pk_.

Método	Ruta	Auth	Descripción
GET	/api/v1/shopify/oauth/diagnostics	Público	Diagnóstico OAuth Shopify (redirect_uri, scopes) sin secretos.
GET	/api/v1/shopify/oauth/start?shop={myshopify.com}	Bearer sesión (panel)	Inicia OAuth Shopify; devuelve authorizationUrl o connected:true.
POST	/api/v1/woocommerce/shops/register	x-api-key pk_	Registra tienda Woo (shopUrl, opcional consumerKey/Secret para webhooks).
GET	/api/v1/woocommerce/shops/:shopId/sync-status	x-api-key pk_	Estado de sincronización de una tienda Woo registrada.
POST	/api/v1/mercadolibre/shops/register	x-api-key pk_	Registra seller ML (sellerUserId + accessToken).
GET	/api/v1/mercadolibre/oauth/start	x-api-key pk_	OAuth Mercado Libre → authorizationUrl.
POST	/api/v1/tiendanube/shops/register	x-api-key pk_	Registra TN (storeId + accessToken); crea webhooks de pedido.
GET	/api/v1/tiendanube/oauth/start	x-api-key pk_	OAuth Tienda Nube → authorizationUrl.

Webhooks entrantes

URLs que configuran Shopify, Woo, ML, TN o tu backend CUSTOM. Verificación en documentación de webhooks.

Método	Ruta	Auth	Descripción
POST	/api/v1/webhook/shopify	HMAC Shopify	Eventos de tienda conectada por OAuth.
POST	/api/v1/webhook/woocommerce	Firma plugin	Pedidos desde pushslog-for-woocommerce.
POST	/api/v1/webhook/mercadolibre	Notificación ML	Topics orders / orders_v2 / shipments.
POST	/api/v1/webhook/tiendanube	HMAC Tienda Nube	Eventos order/* (TIENDANUBE_APP_SECRET).
POST	/api/v1/webhook/custom	X-PushSLog-Shop-Id + X-PushSLog-Signature	Ingesta pedido CUSTOM; secret de /custom/shops/register.

Inventario omnicanal (sync pk_ y panel)

Guía completa con flujo, ejemplos curl y reglas de stock en Inventario omnicanal.

Integración automatizada (pk_ o sesión)

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.

Panel y gestión (sesión JWT)

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).

Errores frecuentes (transversales)

HTTP	error	Cuándo
401	API_KEY_REQUIRED	Falta x-api-key pk_ en rutas de integración
403	API_KEY_INVALID	pk_ revocada o de otro tenant
401	SESSION_REQUIRED	Ruta de panel sin Bearer JWT
400	BAD_REQUEST	Body o query incompleto
429	—	Rate limit por plan (reduce concurrencia)
500	*_FAILED	Error interno; reintenta con soporte

Panel (sesión JWT) — fuera de pk_

Envíos, cotizador, finanzas y preferencias se consumen desde app.pushslog.com con JWT. No están en openapi.json parcial; el panel usa BFF/proxy cuando aplica.

Envíos y tracking: POST /api/v1/shipments · GET /api/v1/shipments/:id
Cotización: POST /api/v1/quote · GET /api/v1/carriers
Finanzas y COD: GET /api/v1/finance/:tenantId/overview · pagos COD

Próximamente en OpenAPI

Ampliación de schemas (request/response) para canales y envíos. Importa openapi.json en Postman y completa variables apiKeyAuth / bearerAuth.