Integrar Pancake POS con Shopify: tutorial técnico para marcas COD en Colombia

Si vendes en Shopify y operas COD en Colombia, lo más probable es que estés usando Pancake POS o Pancake Chat para coordinar despachos por WhatsApp con Hoko u otra transportadora. Mantener los dos sistemas sincronizados a mano (copiando pedidos uno a uno) es lento, propenso a errores y se vuelve insostenible más allá de 100 pedidos al día.

Este tutorial cubre cómo conectarlos para que el flujo sea automático: pedido en Shopify → pedido en Pancake POS → mensaje WhatsApp al cliente → despacho.

Lo que vas a necesitar

• Tienda Shopify activa (plan Basic o superior).
• Cuenta Pancake POS con el shop_id de tu marca a mano (lo encuentras en la URL del dashboard de Pancake).
• Un endpoint público que reciba webhooks (un VPS, Cloudflare Workers, Vercel, lo que tengas).
• Token de Pancake con permisos order.create y order.read.

Arquitectura básica

Shopify ──► webhook (orders/create) ──► tu servicio
                                          │
                                          ├─► Pancake POS API ──► pedido creado
                                          │
                                          └─► Pancake Chat ──► mensaje WhatsApp

La pieza intermedia ("tu servicio") es donde traduces el formato Shopify al formato Pancake. Idealmente la armas como microservicio Node.js o un endpoint serverless — cualquier cosa que pueda recibir un POST y hacer dos llamadas HTTP.

Paso 1: registrar el webhook en Shopify

En Shopify Admin → Settings → Notifications → Webhooks, crea un webhook con:

• Evento: Order creation
• Formato: JSON
• URL: https://api.tudominio.com/webhooks/shopify/orders-create
• Versión: la última estable (2025-10 al momento de escribir).

Guarda el webhook signing secret que te aparece — lo vas a necesitar para validar la autenticidad de cada llamada.

Paso 2: validar la firma HMAC

Shopify envía el header X-Shopify-Hmac-Sha256 con cada webhook. Tu servidor debe verificarlo:

import crypto from "node:crypto";

function verifyShopifyHmac(rawBody: Buffer, header: string, secret: string) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("base64");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(header),
  );
}

Importante: tienes que validar contra el body crudo (Buffer), no contra el JSON parseado. Si tu framework parsea automáticamente, vas a obtener firmas inválidas.

Paso 3: traducir el pedido a formato Pancake

El payload de Shopify trae más información de la que Pancake necesita. Los campos críticos son:

const pancakePayload = {
  shop_id: process.env.PANCAKE_SHOP_ID,
  customer_name: shopifyOrder.shipping_address.name,
  customer_phone: shopifyOrder.shipping_address.phone,
  shipping_address: [
    shopifyOrder.shipping_address.address1,
    shopifyOrder.shipping_address.address2,
    shopifyOrder.shipping_address.city,
    shopifyOrder.shipping_address.province,
  ].filter(Boolean).join(", "),
  items: shopifyOrder.line_items.map((li) => ({
    product_id: li.sku,
    quantity: li.quantity,
    price: parseFloat(li.price),
  })),
  total: parseFloat(shopifyOrder.total_price),
  note: `Shopify order ${shopifyOrder.order_number}`,
};

Notas prácticas:

• Pancake espera teléfonos con código de país (+57...). Si Shopify te entrega solo 10 dígitos, prepéndelo.
• El campo note es oro: pon ahí el order_number de Shopify para reconciliar después.
• Si tu producto no tiene SKU en Shopify, usa el variant_id numérico — Pancake lo acepta.

Paso 4: llamar la API de Pancake

const response = await fetch(
  `https://pos.pancake.vn/api/v1/shops/${SHOP_ID}/orders`,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Pancake-Token": process.env.PANCAKE_TOKEN!,
    },
    body: JSON.stringify(pancakePayload),
  },
);

if (!response.ok) {
  const text = await response.text();
  throw new Error(`Pancake POS error ${response.status}: ${text}`);
}

const { order_id } = await response.json();

Paso 5: idempotencia — el detalle que evita pedidos duplicados

Shopify reintenta el webhook si tu endpoint responde con cualquier código que no sea 2xx, o si demora más de 5 segundos. Sin idempotencia, vas a crear pedidos duplicados en Pancake.

La solución es guardar el X-Shopify-Webhook-Id en una tabla y rechazar duplicados:

const webhookId = req.headers["x-shopify-webhook-id"];
const exists = await db.webhookEvent.findUnique({ where: { id: webhookId } });
if (exists) return res.status(200).send("ok");
await db.webhookEvent.create({ data: { id: webhookId, processedAt: new Date() } });

Paso 6 (opcional pero recomendado): confirmar antes de despachar

Una vez creado el pedido en Pancake POS, lo siguiente es confirmar con el cliente vía WhatsApp o llamada antes de que entre al picking. Aquí es donde la mayoría de marcas pierde plata por despachar pedidos que el cliente nunca confirmó.

Si quieres automatizar el paso de confirmación con voz IA en español colombiano, Nexa Calls lo hace por ti — el agente llama, confirma datos, registra el resultado en Pancake Chat y devuelve el estado al webhook.

Errores comunes y cómo evitarlos

• Latencia alta en Pancake. Si tu endpoint de webhook hace la llamada a Pancake de forma síncrona, una caída de 30 segundos del API te tumba la integración. Encolar la creación en un job (BullMQ, SQS, lo que prefieras) y responder 200 rápido al webhook es la única manera de operar a escala.
• Reintentos sin backoff. Cuando Pancake responde 5xx, no reintentes inmediatamente. Backoff exponencial (1s, 5s, 30s, 5min) evita amplificar incidentes.
• Cambios de dirección post-despacho. Si el cliente cambia la dirección después del pedido y tu sistema solo escucha orders/create, te quedas con datos viejos. Suscríbete también a orders/updated.

Con este setup tendrás un flujo Shopify → Pancake estable, idempotente y listo para escalar a miles de pedidos al día sin intervención manual.