Preguntas frecuentes
Autenticación y seguridad
Sección titulada «Autenticación y seguridad»¿Qué hago si mi API Key se filtra?
Sección titulada «¿Qué hago si mi API Key se filtra?»Contactá a soporte@lubee.com.ar inmediatamente. Pickwise revoca la key anterior y emite una nueva. Ver guía de autenticación para buenas prácticas y cómo evitarlo (variables de entorno, secret managers, IP allowlist).
¿Puedo usar la API desde el navegador?
Sección titulada «¿Puedo usar la API desde el navegador?»No se recomienda. La API Key no debe exponerse al frontend. Usá un backend intermediario que proxy-ee las requests a Pickwise y firme con la key desde ahí. De otra manera, cualquiera que inspeccione el tráfico en el navegador puede ver y reusar tu key.
¿Cómo pruebo la integración sin afectar producción?
Sección titulada «¿Cómo pruebo la integración sin afectar producción?»Pedí a soporte una API Key de staging o un tenant de prueba. Usá externalId distintivos (ej: TEST-*) para que sean fáciles de filtrar y limpiar.
Productos
Sección titulada «Productos»¿Cómo elimino un producto?
Sección titulada «¿Cómo elimino un producto?»La API pública no expone DELETE. Para desactivar un producto, enviá POST /products con isActive: false. El producto sigue existiendo (integridad referencial con órdenes históricas) pero no aparece en listados con active_only=true. Ver sincronización de productos.
¿El externalId es case-sensitive?
Sección titulada «¿El externalId es case-sensitive?»Sí. ERP-PROD-001 y erp-prod-001 son productos distintos. Elegí una convención y mantenela en todo tu sistema.
¿Qué pasa si envío un producto con un externalId que ya existe?
Sección titulada «¿Qué pasa si envío un producto con un externalId que ya existe?»Se actualiza el producto existente (upsert). Los campos que envíes sobrescriben los anteriores. Los campos que no envíes se mantienen sin cambios — no se resetean a default.
¿Cómo hago una sincronización completa del catálogo?
Sección titulada «¿Cómo hago una sincronización completa del catálogo?»GET /products?limit=200en loop con cursor para traer todo lo que está en Pickwise.- Compará contra tu catálogo maestro.
- Para nuevos / actualizados:
POST /products/batchen chunks de 200. - Para eliminados en tu sistema:
POST /productsconisActive: false.
Ver guía de productos para ejemplos de código.
Órdenes
Sección titulada «Órdenes»¿Puedo cancelar una orden en cualquier estado?
Sección titulada «¿Puedo cancelar una orden en cualquier estado?»No. Solo órdenes en PENDING o PENDING_VALIDATION pueden cancelarse vía API. Para estados posteriores (IN_PICKING, PICKED, PACKED, DISPATCHED), contactá al equipo de almacén. Ver ciclo de vida de órdenes.
¿Puedo modificar el externalId de una orden existente?
Sección titulada «¿Puedo modificar el externalId de una orden existente?»No. El externalId es inmutable. Si necesitás “cambiarlo”, cancelá la orden (si todavía podés) y creá una nueva con el externalId correcto.
¿Qué pasa si un producto referenciado en una orden no existe?
Sección titulada «¿Qué pasa si un producto referenciado en una orden no existe?»La orden se crea en estado PENDING_VALIDATION con hasIssues: true. El equipo de almacén resuelve el problema manualmente (típicamente cargando el producto faltante). Recibís el webhook order.issue_resolved cuando se completa. Ver ciclo de vida de órdenes.
¿El id de Pickwise y mi externalId son lo mismo?
Sección titulada «¿El id de Pickwise y mi externalId son lo mismo?»No. El id es el UUID interno de Pickwise. Tu externalId es el identificador en tu sistema. Para toda la API pública, usá siempre tu externalId.
Webhooks
Sección titulada «Webhooks»¿Qué pasa si mi endpoint de webhook está caído?
Sección titulada «¿Qué pasa si mi endpoint de webhook está caído?»Pickwise reintenta hasta 5 veces con delays crecientes (1min, 15min, 1h, 3h, 6h). Si los 5 intentos fallan, el evento va a la Dead Letter Queue. Podés re-enviarlos con POST /webhooks/{id}/replay una vez que tu endpoint esté operativo. Ver guía de webhooks.
¿Puedo tener múltiples webhooks?
Sección titulada «¿Puedo tener múltiples webhooks?»Sí. Podés configurar URLs diferentes para diferentes subsets de eventos, o la misma URL para todos. Típicamente uno por ambiente (dev, staging, prod) o uno por responsabilidad (uno para órdenes, otro para stock).
¿Cuándo uso webhook y cuándo polling?
Sección titulada «¿Cuándo uso webhook y cuándo polling?»- Webhook: default. Más rápido, más barato en rate limit.
- Polling con
updated_since: cuando tu integración no puede recibir conexiones entrantes (ej: cliente interno sin puerto público) o como fallback si el webhook se perdió.
Rate limiting y resiliencia
Sección titulada «Rate limiting y resiliencia»¿Cómo sé cuántas peticiones me quedan?
Sección titulada «¿Cómo sé cuántas peticiones me quedan?»Cada respuesta incluye headers X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Ver guía de rate limiting.
¿Qué pasa si la misma idempotency key llega con parámetros distintos?
Sección titulada «¿Qué pasa si la misma idempotency key llega con parámetros distintos?»Recibís 409 IDEMPOTENCY_CONFLICT. Generá una key nueva para esa operación distinta. Ver guía de idempotencia.
Soporte
Sección titulada «Soporte»Si tu pregunta no está acá, escribinos a soporte@lubee.com.ar. Incluí siempre el requestId del error que estés viendo (viene en toda respuesta de la API).