Conecta tu web a POSFEL, paso a paso y con código.

Cómo funciona la integración

Tres actores: la tienda (dueño, en POSFEL), el integrador (IA o desarrollador, en el código de la web) y el comprador. Cinco piezas, cada una con un solo trabajo — si entiendes esta tabla, entiendes la integración.

Integrar con una IA

No hace falta que escribas tú el manifiesto ni el checkout: la skill le da a la IA todo lo que necesita para hacerlo leyendo el código de tu web.

Lee https://posfel.com/integrations/skill-posfel-ecommerce.md
y sigue esa skill para integrar esta web con POSFEL.
Mi token de integración está en la variable POSFEL_TOKEN.

Lo único que la IA no puede hacer por ti es el paso 1 (el token lo genera el dueño de la tienda en POSFEL) y el paso 4 (la aprobación del sync). El resto lo resuelve con la skill y el CLI.

Paso 1 — Genera el token TIENDA

Lo hace el dueño de la tienda, en POSFEL. Es lo único que el integrador debe pedirle.

En POSFEL: Configuración → Integraciones → Web propia → Conectar. Ponle nombre y la URL de tu web, y copia el token — no volverá a mostrarse. Único requisito real de la tienda: una pasarela con el canal "Web propia" encendido (Stripe, Tilopay o CyberSource) en Configuración → Pagos. El marketplace público de posfel.com es opcional: tu web vende vía la integración aunque esté apagado.

# guárdalo fuera del control de versiones
echo "pfi_TU_TOKEN" > .posfel-token
echo ".posfel-token" >> .gitignore

• El token es secreto de servidor: jamás en el JS del navegador ni en el repo.
• Rotarlo (en el mismo modal) invalida el anterior al instante.
• La clave publicable pk_… del mismo modal sí es pública — esa es la que va en el navegador (paso 5, forma 2).

Paso 2 — El manifiesto del catálogo INTEGRADOR

Crea posfel-catalog.json en la raíz del proyecto. Es el contrato entre tu web y POSFEL.

Regla de oro: cada combinación vendible (color × talla) es una variante, y un producto con variantes no lleva precio ni stock propios. El externalId es tu identificador estable — no lo cambies entre syncs o se duplicarán productos.

{
  "version": 1,
  "site": { "name": "MI TIENDA", "url": "https://mitienda.com" },
  "products": [
    {
      "externalId": "chaqueta-alpina",
      "name": "Chaqueta Alpina Pro",
      "description": "Chaqueta impermeable 3 capas…",
      "images": ["https://mitienda.com/img/chaqueta.webp"],
      "options": ["Color", "Talla"],
      "variants": [
        { "externalId": "negro-s", "name": "Negro / S", "price": 189.0, "stock": 5,
          "images": ["https://…/negro-frontal.webp", "https://…/negro-posterior.webp"] },
        { "externalId": "negro-m", "name": "Negro / M", "price": 189.0, "stock": 8 }
      ]
    },
    { "externalId": "gorra", "name": "Gorra básica", "price": 79.0, "stock": 20, "images": ["https://…"] }
  ]
}

• Con variantes ⇒ el producto NO lleva price/stock/sku propios.
• Sin variantes ⇒ price > 0 obligatorio.
• images del producto: URLs https públicas, fotos del producto (packshots) — nunca heros o banners del landing. La primera es la principal.
• Imágenes por variante: cada variante acepta images: [] (máx 5) — si hay foto frontal y posterior por color, ambas van en las images de cada variante de ese color, no revueltas en la galería del producto.
• stock: manda el inventario inicial REAL (pídeselo al dueño si la web no lo maneja) — con stock 0 el producto queda creado pero no comprable.
• publish: false si no quieres publicarlo al marketplace todavía.

Paso 3 — Corre el push INTEGRADOR

El push genera el ANÁLISIS — no aplica nada todavía.

POSFEL analiza el manifiesto (qué productos se crearían o actualizarían, con sus variantes y precios), valida la configuración de la tienda (pasarela, marketplace, FEL, tarifas de envío, Envia) y deja todo pendiente de aprobación. Cada error llega con su fix exacto.

$ POSFEL_TOKEN=pfi_TU_TOKEN npx posfel-sync@latest push

✔ Análisis listo — PENDIENTE DE APROBACIÓN

  Se crearían:      3 productos
  Variantes:        12
  ⚠ Sin tarifas de envío nacionales
    Fix: Configura las tarifas por departamento en Configuración → Envíos.

→ El dueño debe APROBAR el sync en POSFEL → Integraciones

# sin npm: curl -O https://posfel.com/integrations/posfel-sync.mjs  →  node posfel-sync.mjs push

Paso 4 — El dueño revisa y APRUEBA TIENDA

Nada entra a la tienda sin la aprobación explícita del dueño.

En POSFEL la tarjeta Web propia muestra REVISAR SYNC PENDIENTE: el modal enseña exactamente qué propone la web (cada producto con su precio, acción CREAR/ACTUALIZAR y variantes), los errores del manifiesto con su corrección, y el checklist de configuración de la tienda.

• APROBAR ejecuta el sync en segundo plano — el modal muestra el progreso ("SINCRONIZANDO TU CATÁLOGO…") y avisa al terminar con el resumen: productos, variantes e imágenes.
• RECHAZAR descarta sin tocar nada; la web puede corregir y volver a hacer push.
• Tras aprobar, el integrador corre npx posfel-sync status para escribir posfel.map.json con los IDs.

Paso 5 — Cablea el checkout INTEGRADOR

Dos formas. En ambas nunca pongas un formulario de tarjeta: el pago siempre ocurre en la página de la pasarela. Y el marketplace público es opcional.

function posfelCheckout(storeId, pk, items) {
  const cart = JSON.stringify({ storeId, pk, items });
  location.href = "https://posfel.com/marketplace/checkout/multi?cart="
    + encodeURIComponent(cart);
}

// producto con variantes ⇒ SIEMPRE productId + variantId
posfelCheckout("cmb2xk4pq0003l70a", "pk_TU_CLAVE", [
  { productId: "cm…shell", variantId: "cm…negroM", quantity: 1 }
]);

$ POSFEL_TOKEN=pfi_TU_TOKEN npx posfel-sync@latest sdk

✔ posfel-storefront.js escrito (moneda GTQ)

// vitrina: precios y stock EN VIVO (y agotados deshabilitados)
const cat = await POSFEL.catalog();

// checkout propio: tarifa de envío con las tarifas de TU tienda
const envio = await POSFEL.quoteEnvio("GU", "Mixco");

// pagar: crea el pedido (valida y reserva stock) y redirige a la pasarela
POSFEL.checkout({
  items: [{ externalId: "chaqueta-alpina", variantExternalId: "negro-m", quantity: 1 }],
  buyer: { name, email, phone, nit }, // nit vacío = CF · phone con código de país
  shipping: { address, department: "GU", municipality: "Mixco" },
  successUrl: location.origin + "/gracias.html",
  cancelUrl: location.origin + "/carrito.html"
});

// confirmFromUrl() espera solo mientras el pago siga "pending"
// (el webhook de la pasarela tarda unos segundos más que el redirect)
const o = await POSFEL.confirmFromUrl();
if (o?.paid) {
  vaciarCarrito();                      // ÚNICO caso que vacía el carrito
  mostrarExito(o.orderId);
} else if (o?.status === "pending") {
  mostrar("Estamos verificando tu pago…");  // + botón "Ver mi pedido" → o.portalUrl
} else if (o) {                        // failed | cancelled | expired
  mostrar("El pago no se completó.");      // + botón REINTENTAR → o.portalUrl
}

// Aquí cae quien canceló o abandonó la pasarela. El carrito local
// sigue INTACTO — no lo toques. Ofrece dos salidas:
const id = new URLSearchParams(location.search).get("posfel_order");
if (id) {
  const o = await POSFEL.orderStatus(id);
  mostrarAviso("No completaste el pago", {
    reintentar: o.portalUrl,  // paga el MISMO pedido (stock reservado 15 min)
    seguirComprando: "/carrito.html" // pagar de nuevo crea pedido nuevo
  });
}

Paso 6 — Vende: POSFEL cierra el círculo COMPRADOR

Lo que pasa después de que el comprador paga — sin que la web haga nada más.

El checkout reserva stock 15 minutos, cobra con la pasarela de la tienda y al confirmarse el pago: venta creada, factura FEL automática (el PDF viaja por WhatsApp y correo), stock descontado y pedido en Órdenes. Las devoluciones funcionan exactamente igual que las de una venta de mostrador: parciales o totales, anulación de FEL, reversión de stock por variante y reembolso por la pasarela.

• Si el pago no se completa, el pedido expira solo a los 15 minutos y libera el stock — nada queda trabado.
• Con checkout propio (forma 2), tus páginas de gracias y cancelación ya saben manejar cada desenlace (paso 5 · Cablea el checkout → FORMA 2 → C).
• El stock vive en POSFEL desde el primer sync: la vitrina de tu web se refresca con POSFEL.catalog() o el feed google-merchant.xml.

Reglas y límites

Las que definen quién manda sobre cada dato.

Errores comunes

Los cinco que resuelven el 95% de los tickets.