Zent para desarrolladores

• Creá la tienda en Zent: Conectar tienda › Tienda propia (nombre, dirección, moneda y zona horaria). Te da la clave zk_live_…, que se ve una sola vez.
• Cargá la historia: productos, clientes, órdenes y carritos (el SDK lo hace en el orden correcto).
• Conectá: Zent corre los chequeos. Con un error, la tienda no se conecta y el reporte dice qué arreglar; sin errores, queda conectada y Zent arma sus campañas.
• Mandá cada cambio cuando pasa (tiempo real): una orden cobrada, un cliente nuevo, un cambio de stock, un carrito.
• Verificá tu dominio de envío en Zent › Dominios: los mails de una tienda propia salen sólo desde el dominio de la tienda (por ejemplo, mail.mitienda.com.ar).

Node 20.19 o más nuevo, sin dependencias. Valida cada registro antes de mandarlo con las mismas reglas que Zent.

npm install @usezent/connect

import { ZentConnect } from '@usezent/connect';

const zent = new ZentConnect({ apiKey: process.env.ZENT_API_KEY });

// 1. La historia: arrays o iterables async (se parten en lotes de 500).
const result = await zent.backfill({
  products: allProducts(),
  customers: allCustomers(),
  orders: allOrders(),
  checkouts: openCheckouts(),
});

// 2. Los chequeos de Zent: si algo está mal, la tienda no se conecta y te dice qué arreglar.
console.log(result.report.errors, result.report.warnings);

Cada pedido lleva Authorization: Bearer zk_live_…. La clave identifica a la tienda: no hace falta mandar nada más. Guardala en el servidor (ZENT_API_KEY), nunca en el navegador ni en el repositorio. Si se filtra, generá otra en Zent: la anterior deja de valer en el acto.

El catálogo entero, también lo que ya no vendés (published: false): las órdenes viejas lo referencian. Cada combinación que se compra por separado es una variante.

{
  "id": "remera-basica",
  "name": "Remera básica",
  "url": "https://mitienda.com.ar/productos/remera-basica",
  "images": [
    "https://cdn.mitienda.com.ar/remera-basica-1.jpg"
  ],
  "categories": [
    {
      "id": "remeras",
      "name": "Remeras"
    }
  ],
  "variants": [
    {
      "id": "remera-basica-m",
      "price": 15000,
      "stock": 12,
      "options": {
        "Talle": "M"
      }
    },
    {
      "id": "remera-basica-l",
      "price": 15000,
      "stock": 0,
      "options": {
        "Talle": "L"
      }
    }
  ]
}

Quién compró o se registró. accepts_marketing es lo que eligió la persona: Zent no lo supone por vos.

{
  "id": "1042",
  "email": "ana@ejemplo.com",
  "name": "Ana Pérez",
  "created_at": "2026-10-01T14:30:00-03:00",
  "accepts_marketing": true
}

Todas las órdenes, con sus líneas. Sólo payment_status = paid cuenta como venta.

{
  "id": "A-20931",
  "customer": {
    "id": "1042",
    "email": "ana@ejemplo.com"
  },
  "created_at": "2026-10-28T19:02:00-03:00",
  "paid_at": "2026-10-28T19:03:10-03:00",
  "currency": "ARS",
  "payment_status": "paid",
  "status": "open",
  "subtotal": 30000,
  "discounts": {
    "coupon": 3000
  },
  "shipping": 2500,
  "total": 29500,
  "coupon_codes": [
    "HOLA10"
  ],
  "items": [
    {
      "product_id": "remera-basica",
      "variant_id": "remera-basica-m",
      "name": "Remera básica · M",
      "quantity": 2,
      "unit_price": 15000
    }
  ]
}

Carritos con mail que no terminaron en compra. Cuando un carrito se convierte, alcanza con mandar la orden: Zent lo cierra solo (por el mail o el cliente).

{
  "id": "cart_88f1",
  "email": "ana@ejemplo.com",
  "created_at": "2026-11-01T21:10:00-03:00",
  "updated_at": "2026-11-01T21:14:00-03:00",
  "recovery_url": "https://mitienda.com.ar/carrito/recuperar/cart_88f1",
  "currency": "ARS",
  "total": 15000,
  "accepts_marketing": true,
  "items": [
    {
      "product_id": "remera-basica",
      "variant_id": "remera-basica-l",
      "name": "Remera básica · L",
      "quantity": 1,
      "unit_price": 15000
    }
  ]
}

• Un id es un texto o un entero de hasta 64 caracteres: el de tu base (un número, un UUID, un SKU). Se guarda tal cual.
• Usá los mismos ids en todos lados: items[].product_id y variant_id son los id que mandás en Productos.
• Si un producto no tiene variantes, mandá una con el mismo id que el producto y usá ese id como variant_id.
• Mandar un registro que ya está lo actualiza (upsert por id): podés reenviar sin duplicar.

Con la tienda conectada, cada cambio que mandás entra al momento. Una orden cobrada en las últimas 48 horas recalcula al comprador y lo que le toca; un cliente registrado en la última hora puede recibir la Bienvenida. Lo más viejo entra como historia y lo toma la vuelta diaria. Que un error de Zent nunca te rompa la compra: atrapalo y reintentá.

// Después de crear o cobrar una orden:
await zent.orders.upsert([toZentOrder(order)]);

// Cuando se registra un cliente:
await zent.customers.upsert([toZentCustomer(customer)]);

// Cuando cambia el precio o el stock:
await zent.products.upsert([toZentProduct(product)]);

// Cuando un carrito queda con mail y sin comprar (por ejemplo, a la hora):
await zent.checkouts.upsert([toZentCheckout(cart)]);

Los cupones de tu tienda los guarda Zent (los de cada mail, el del pop-up, el del carrito, el beneficio por monto). Tu checkout los valida y los canjea con el SDK, y Zent los empieza a usar recién cuando lo activás: hasta entonces los mails salen sin cupón.

• Validar cuando el comprador escribe un código: zent.coupons.validate(code, { subtotal }). Un cupón que no vale no tira error: vuelve valid: false con el motivo y un texto para mostrarle.
• Canjear al crear la orden: zent.coupons.redeem(code, { orderId, subtotal }). Con el mismo orderId no gasta otro uso: podés reintentar.
• Mandar el código en la orden (coupon_codes), tal como lo emitió Zent: así esa venta se le atribuye. Una orden cobrada con un código de Zent cuenta como canje aunque no hayas llamado a redeem.
• El link del carrito abandonado trae el cupón en ?zent_coupon=CÓDIGO: aplicalo solo al abrir el carrito.
• Activar, una vez, cuando todo lo anterior ya anda: zent.coupons.enable().

// Cuando el comprador escribe un código:
const v = await zent.coupons.validate(code, { subtotal: cart.subtotal });
if (!v.valid) return showError(v.message); // «Ese cupón venció.», «Ese cupón ya se usó.»…
applyDiscount(v.discount); // envío gratis: v.coupon.type === 'free_shipping'

// Al crear la orden (idempotente por orderId):
await zent.coupons.redeem(code, { orderId: order.id, subtotal: cart.subtotal });

// Una vez, cuando todo esto ya anda en producción:
await zent.coupons.enable();

El pop-up de captación suma suscriptos con su cupón de bienvenida, y el mismo script registra qué productos mira cada contacto que llega desde un mail de Zent: con eso sale el Abandono de navegación. Se activa en Zent › Add-ons (pide los cupones activos) y se instala pegando un script en todas las páginas de tu tienda:

<script src="https://usezent.xyz/zent-capture.js" data-zent-store="<id de tu tienda en Zent>" defer></script>

En la página de un producto, decile cuál es con una meta (el mismo id que mandás en Productos). Si tu sitio cambia de producto sin recargar la página, llamá a Zent.viewProduct(id) en cada cambio.

<meta name="zent:product" content="remera-basica">

// Si tu sitio cambia de producto sin recargar:
Zent.viewProduct('remera-basica');

Zent elige el producto que mejor acompaña el carrito (el mismo motor que en Tiendanube) y tu checkout lo muestra. Corre en el navegador, sin clave: @usezent/connect/storefront habla con los ids de tu tienda. Se activa en Zent › Add-ons.

import { ZentStorefront } from '@usezent/connect/storefront';

const zent = new ZentStorefront({ store: '<id de tu tienda en Zent>' });
const { offer } = await zent.offer({
  cartId: cart.id,
  subtotal: cart.subtotal,
  items: cart.items.map((i) => ({ product_id: i.productId })), // tus ids
});

if (offer) {
  render(offer.items); // productId y variants[].id ya son los de tu tienda
  zent.offerEvent({ offerId: offer.id, type: 'shown' });
}

// Al sumarlo:
await addToCart({ productId, variantId, quantity: 1, zent_offer: offer.id });
zent.offerEvent({ offerId: offer.id, type: 'added', productId, variantId, quantity: 1 });

• La línea que suma el producto lleva zent_offer: offer.id, y la orden la manda igual (items[].zent_offer): así esa venta se le atribuye a Zent.
• Los eventos (shown, added, dismissed, completed) sólo ajustan cómo aprende: la venta sale de la orden cobrada.
• Si activás el beneficio por monto, la respuesta trae benefit; al llegar al objetivo, claimBenefit da un cupón de un solo uso para ese carrito.

zent.connect() (o npx @usezent/connect check, que sale con código 1 si hay errores) mira lo cargado en conjunto, lo que un registro solo no muestra. Las reglas entre órdenes se miden sobre las últimas 5.000. Un error frena la conexión; un aviso conecta y te dice qué no va a funcionar. Ya conectada, revisar de nuevo nunca la desconecta.

ZENT_API_KEY=zk_live_… npx @usezent/connect check

✗ No pasó los chequeos: la tienda no se conectó.
Miramos: products 412 · customers 9310 · orders 22071 · checkouts 0 (las reglas entre órdenes, sobre las últimas 5000)

Errores (arreglalos para conectar):
  [items_unknown_products] Órdenes con productos que no llegaron: 1204 de 9877 líneas (12,2 %) apuntan a un producto o una variante que no llegó (1204 por el producto, 0 por la variante).
    → Hay líneas cuyo product_id (o variant_id) no está en lo que mandaste en Productos. Usá los mismos ids en los dos lados y cargá también los productos que ya no vendés.
    https://usezent.xyz/desarrolladores#chequeos-items_unknown_products

Un lote es todo o nada: con un registro mal no se escribe ninguno, y la respuesta trae todos los errores. Cada uno con un code estable, dónde está (path), el id del registro, cómo arreglarlo y el link a esta página. Nunca repite un mail, un nombre ni un teléfono.

HTTP/1.1 422
{
  "ok": false,
  "errors": [
    {
      "code": "invalid_enum",
      "path": "data[3].payment_status",
      "record_id": "A-20934",
      "message": "«payment_status» tiene que ser uno de: paid, pending, authorized, partially_refunded, refunded, voided (recibimos completed).",
      "hint": "Traducí tu valor al vocabulario de Zent (la tabla de valores está en la documentación).",
      "docs": "https://usezent.xyz/desarrolladores#ordenes-payment_status"
    }
  ]
}

import { ZentValidationError } from '@usezent/connect';

try {
  await zent.orders.upsert(orders);
} catch (e) {
  if (e instanceof ZentValidationError) console.error(e.toString()); // o e.errors
  else throw e;
}

• Hasta 500 registros y 4 MB por pedido (el SDK parte solo).
• Hasta 240 pedidos por minuto por tienda: una carga de 100.000 órdenes son 200 pedidos. Pasado eso, 429 con Retry-After (el SDK espera y reintenta).
• Las fechas van en ISO 8601 con zona horaria y nunca más de un día en el futuro.
• Montos en la moneda de tu tienda en Zent, ≥ 0.

Si un cliente te pide borrar sus datos, pedíselo también a Zent: sus órdenes quedan sin datos personales, el cliente se borra y su mail no vuelve a recibir nada.

await zent.customers.redact({ ids: ['1042'] });
// o por mail: await zent.customers.redact({ emails: ['ana@ejemplo.com'] });

El SDK es una capa fina: lo mismo se hace con cualquier cliente HTTP.

• POST /api/connect/v1/products · customers · orders · checkouts: cuerpo { "data": [...] }; con "validate_only": true valida sin escribir.
• POST /api/connect/v1/connect: los chequeos (y conectar).
• GET /api/connect/v1/status: la tienda, cuánto llegó, el último reporte y el dominio de envío.
• POST /api/connect/v1/redact: { "customer_ids": [...], "emails": [...] }.
• POST /api/connect/v1/coupons/validate · redeem · enable: { "code", "subtotal", "order_id" } (Cupones).
• POST /api/connect/v1/storefront/offer · event: desde el navegador, sin clave, con "store" (Cross-sell).

curl https://usezent.xyz/api/connect/v1/orders \
  -H "Authorization: Bearer $ZENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": [ { "id": "A-20931", "...": "..." } ] }'

Si la integración la escribe un agente (Claude Code, Cursor, Codex), el paquete trae AGENTS.md con las reglas: leer el código y no los datos de tus clientes, el permiso de marketing explícito, cómo traducir los estados y dónde enganchar el tiempo real. Pegale esto:

Conectá esta tienda con Zent usando @usezent/connect. Seguí al pie de la letra
node_modules/@usezent/connect/AGENTS.md y https://usezent.xyz/desarrolladores:
mapeos puros por recurso, un script de carga inicial y los enganches de tiempo real.
No leas datos reales de clientes. Terminá cuando `npx @usezent/connect check` dé ✓.