posfel-sync

CLI oficial de POSFEL para conectar tu web o ecommerce propio: sube tu catálogo (productos, variantes, precios e imágenes) a POSFEL y recibe los IDs para cablear el checkout alojado. POSFEL administra el stock, los pedidos, las devoluciones y la factura FEL certificada por la SAT de cada venta — tu web nunca toca tarjetas.

Uso rápido

# 1. Genera tu token en POSFEL → Configuración → Integraciones → Web propia
# 2. Crea posfel-catalog.json en la raíz de tu proyecto (ver la guía)
# 3. Sube el catálogo:
POSFEL_TOKEN=pfi_xxx npx posfel-sync@latest push

El push genera un análisis (qué se crearía o actualizaría + checklist de la tienda con el fix de cada error) que queda pendiente de aprobación: el dueño lo revisa y aprueba en POSFEL → Configuración → Integraciones → Web propia. Nada se aplica hasta ese OK.

# Tras la aprobación: estado del catálogo vinculado + escribe posfel.map.json
# (mapeo externalId → productId/variantId y storeId — los IDs que tu carrito
# y tu botón de pagar necesitan):
POSFEL_TOKEN=pfi_xxx npx posfel-sync@latest status

# ¿Tu web ya tiene carrito y checkout propios? Genera el SDK del navegador:
POSFEL_TOKEN=pfi_xxx npx posfel-sync@latest sdk

sdk escribe posfel-storefront.js ya configurado con tu clave publicable y la moneda de tu tienda (GTQ Guatemala / USD El Salvador). Expone window.POSFEL con: catalog() (precio/stock en vivo), quoteEnvio(dept, muni) (tarifas configuradas de la tienda), quoteEnvioIntl(items, destino) (Envia.com con la cuenta del vendedor), checkout({...}) (crea el pedido y redirige al pago, con regreso a tu web) y orderStatus(id). La tarjeta nunca se pide en tu web: el pago ocurre en la pasarela de la tienda.

El token también puede vivir en un archivo .posfel-token en el directorio actual (agrégalo a .gitignore — es un secreto de servidor).

Documentación

• Guía técnica completa (manifiesto, checkout, reglas): https://posfel.com/integraciones/guia
• Skill para IAs (Claude y otras pueden integrar tu web solas): https://posfel.com/integrations/skill-posfel-ecommerce.md
• ¿Qué es la integración?: https://posfel.com/integraciones

Variantes con dimensiones (Color × Talla)

Si tu producto tiene 2+ dimensiones, declara en el manifiesto "options": ["Color", "Talla"] y nombra cada variante "Negro / M" (o pasa optionValues: ["Negro", "M"] explícitos). POSFEL mostrará selectores agrupados con swatches en el marketplace y en todas sus herramientas.

Requisitos

• Node.js ≥ 18 (sin dependencias — un solo archivo).
• Una tienda POSFEL con marketplace habilitado y una pasarela de pago activa (Stripe, Tilopay o CyberSource).