Integrar una tienda en línea

Guía con el caso de una tienda en línea que vende con el catálogo y el stock de un comercio de Wink POS. No es exclusiva de ninguna app en particular: cualquier app con los scopes correctos sigue el mismo camino.

1. Conectar y configurar

Al instalarse, pide la configuración base del comercio:

• GET /public/v1/locations: ubicaciones del comercio, para elegir desde cuál despacha la tienda.
• GET /public/v1/channels: canales de venta (cada canal tiene su propia lista de precios). Elige o deja elegir al Dueño cuál usar para la tienda en línea.
• GET /public/v1/payment-accounts: cuentas de cobro disponibles, para accountId en payments[] al crear una venta.
• GET /public/v1/price-lists: lista de precios del canal elegido.

Guarda locationId, channelId y accountId como configuración de la instalación: no cambian en cada pedido.

2. Primera sincronización

Trae el catálogo completo una vez (GET /public/v1/products, /categories, /stock, paginando por cursor) y desde ahí vive de los webhooks (product.*, price.changed, stock.changed) más ?updatedSince= para ponerte al día si te perdiste eventos (por ejemplo, tras una pausa de tu suscripción).

Por qué no consultar en cada visita de un cliente: el límite de lectura es 120 por minuto por instalación — una tienda con tráfico real lo agota rápido — y el catálogo no cambia visita a visita. Sincroniza a tu propia base y sirve desde ahí.

3. Un pedido nuevo

POST /public/v1/sales
Idempotency-Key: <id del pedido en tu sistema>
Content-Type: application/json

{
  "channelId": "...",
  "locationId": "...",
  "paymentTerms": "cash",
  "lines": [{ "variantId": "...", "quantity": "2.000", "unitPriceUsd": "1.5000" }],
  "payments": [{ "accountId": "...", "amount": "3.0000" }]
}

Usa el id del pedido de tu propio sistema como Idempotency-Key: si tu llamada falla por red y reintentas con la misma clave, nunca duplicas la venta.

4. Cliente nuevo

POST /public/v1/contacts
{ "type": "customer", "name": "...", "email": "...", "phone": "..." }

Crea el contacto antes de la venta si el cliente es nuevo, y pasa su id como customerId en POST /sales.

5. Manejar errores de plataforma

Código	Qué significa	Qué hacer
401	Token vencido, revocado o app suspendida	Renueva con el refresh token; si falla, pide reinstalación
429 rate_limited	Pasaste el cupo de lecturas o escrituras	Espera Retry-After antes de reintentar
app.uninstalled (webhook)	El comercio te desinstaló	Borra lo que guardas de ese comercio en tu base

Limitaciones de esta fase

• La venta exige turno de caja abierto si el comercio tiene el compartimento de caja activo: una app no abre turno, así que una ubicación sin turno abierto responde 409, igual que a una persona. Avisa en tu app que el Dueño debe abrir caja antes de vender por esa ubicación.
• Productos y precios son de solo lectura en esta fase: no hay POST/PATCH de catálogo todavía. Llega en una fase posterior.
• Imágenes de producto no están disponibles aún por la API pública.