Oleada 5 · Documentación

FAQ técnica

Respuestas rápidas sobre integración, errores frecuentes y buenas prácticas.

General y API

¿Cuál es la URL base de la API?
Todas las rutas de integración usan https://api.pushslog.com. Comprueba disponibilidad con GET /health y GET /health/ready. Catálogo en /docs/api-reference.
¿JWT del panel o API key pk_?
El panel (app.pushslog.com) usa JWT (login/refresh). Scripts, plugins y backends usan pk_ en x-api-key. No mezcles: Shopify OAuth /start requiere Bearer de sesión, no pk_.
¿Hay rate limits?
Límites por plan y tenant en producción. Ante HTTP 429 reduce concurrencia y contacta soporte para umbrales de contrato.
¿Existe entorno sandbox separado?
Hoy la documentación describe producción (api.pushslog.com). Para pruebas aisladas usa flujo CUSTOM con datos sintéticos o consulta soporte por tenant de staging.

¿Cómo autentico llamadas servidor a servidor?
Crea pk_ en Tiendas → Custom → API personalizada (OWNER/ADMIN). Envía x-api-key: pk_… o Authorization: Bearer pk_…. Ver /docs/autenticacion.
Recibo 401 API_KEY_REQUIRED o 403 API_KEY_INVALID
401: falta header. 403: clave revocada, typo o tenant distinto. Revoca y crea nueva pk_ si hace falta.
¿Cómo invito a mi equipo al panel?
OWNER o ADMIN: Configuración → Seguridad → Roles y permisos → Equipo del tenant. Invita con correo, rol y contraseña temporal. Ver matriz de permisos en la misma página.
Recibo 403 FORBIDDEN en billetera o finanzas
Tu rol no tiene acceso (p. ej. OPERATOR o MEMBER). Billetera y COD requieren OWNER, ADMIN o FINANCE. Consulta /config/seguridad#roles.

¿Dónde obtengo webhookSecret para CUSTOM?
En la respuesta de POST /api/v1/custom/shops/register: webhookEndpoint y webhookSecret. No se reexpone si lo generó el servidor.
Recibo 404 CUSTOM_SHOP_NOT_FOUND
shopId no corresponde al tenant de la pk_. Usa el shopId devuelto al registrar la tienda. Guía: /docs/quick-start.
¿Cómo verifico que un pedido CUSTOM llegó?
Tras POST /api/v1/custom/orders (201), busca orderId u orderNumber en https://app.pushslog.com/shipments.
¿Puedo probar sin tienda real?
Sí: CUSTOM con externalShopId de prueba y pedidos sintéticos. Marketplaces requieren OAuth o tokens reales.

¿Cómo valido la firma de un webhook?
Depende del canal: HMAC Shopify/TN, firma plugin Woo, notificación ML, X-PushSLog-Signature en CUSTOM. Detalle en /docs/webhooks.
¿PushSLog reintenta si mi endpoint falla?
Los marketplaces y Shopify suelen reintentar según su política. Responde 2xx rápido; procesa en background. Errores 5xx prolongados pueden pausar entregas en el origen.

¿Por qué Shopify OAuth no acepta mi pk_?
GET /api/v1/shopify/oauth/start exige sesión JWT del panel. Conecta desde Tiendas → Shopify o usa Bearer del accessToken tras login.
¿Cómo conecto WooCommerce?
Instala pushslog-for-woocommerce, crea pk_ en el panel y configura la URL de webhook hacia /api/v1/webhook/woocommerce. Opcional: POST …/woocommerce/shops/register. Ver /docs/canales#woocommerce.
Tienda Nube / Mercado Libre muestran «próximamente»
La API de registro/OAuth puede estar documentada antes que el botón del panel para tu plan. Revisa /docs/canales y contacta soporte para habilitar producción.
¿Qué hay disponible de Falabella?
Integración API en roadmap; el panel puede mostrar mensajes demo. Estado en /docs/canales#falabella.