Sincronización inicial

La sincronización inicial sube de una vez tus productos y tus órdenes históricas, para que CrossUp arranque sabiendo qué vendés y qué ya se compró junto. Se hace una sola vez, con un snapshot por entidad: lo abrís, mandás páginas y lo cerrás. Necesitás el connection_id y la clave cct_… de los tres pasos. $BASE es la URL de la API de ingesta de CrossUp.

Qué sincronizás

Tu catálogo

Categorías, productos, variantes y stock. Es lo que CrossUp puede recomendar.

Tus órdenes históricas

El último año de ventas. De ahí CrossUp aprende qué se compra con qué desde el primer día.

Los tres pasos

Abrí el run

Un run por tipo de entidad. La respuesta trae su run_id (snp_…).

Mandá las páginas

Hasta 500 entidades por página, todas con upsert.

Cerralo

Al cerrar, lo que no vino de ese tipo se da de baja. En la sincronización inicial no hay nada que dar de baja.

RUNS="$BASE/internal/v1/connections/$CONNECTION_ID/snapshots"

# 1 · Abrir el run de productos → 201 { "run_id": "snp_…" }
curl -X POST "$RUNS" -H "Authorization: Bearer $CCT_KEY" \
  -H "Content-Type: application/json" -d '{ "entity": "item" }'

# 2 · Mandar una página → 200 { "results": [ … ] }
curl -X POST "$RUNS/$RUN_ID/pages" -H "Authorization: Bearer $CCT_KEY" \
  -H "Content-Type: application/json" -d '{
  "observations": [
    { "entity": "item", "external_id": "1001", "operation": "upsert",
      "document": { "title": { "es": "Remera negra" }, "published": true } }
  ]
}'

# 3 · Cerrar → 200 { "received": …, "deleted": 0, "quarantined": 0 }
curl -X POST "$RUNS/$RUN_ID/close" -H "Authorization: Bearer $CCT_KEY"
# Lo mismo para cada entidad; las órdenes históricas van al final: { "entity": "order" }

const runs = `${BASE}/internal/v1/connections/${CONNECTION_ID}/snapshots`;
const headers = {
  Authorization: `Bearer ${process.env.CCT_KEY}`, // secreta: sólo en tu servidor
  "Content-Type": "application/json",
};
const post = (url: string, body?: unknown) =>
  fetch(url, { method: "POST", headers, body: body === undefined ? undefined : JSON.stringify(body) });

// Primero el catálogo; las órdenes históricas, al final
for (const entity of ["taxonomy_node", "item", "variant", "availability", "order"]) {
  const { run_id } = await (await post(runs, { entity })).json();
  for (const page of chunk(datos[entity], 500)) { // datos: lo que exportaste; chunk: corta de a 500
    const { results } = await (await post(`${runs}/${run_id}/pages`, { observations: page })).json();
    revisar(results);                             // uno por posición: ver abajo
  }
  await post(`${runs}/${run_id}/close`);
}

Si la carga se corta a la mitad, no cierres el run: daría de baja lo que todavía no mandaste. Un run sin cerrar expira solo a las 24 horas, sin borrar nada.

Leé la respuesta

Cada página devuelve un resultado por posición, en el mismo orden en que mandaste las entidades.

{
  "results": [
    { "index": 0, "status": "accepted", "observation_id": "obs_…" },
    { "index": 1, "status": "unchanged" },
    { "index": 2, "status": "stale" },
    { "index": 3, "status": "quarantined", "reason": "document.quantity: required" }
  ]
}

`status`	Qué pasó	Qué hacés
`accepted`	Se escribió; trae su `observation_id`	Nada
`unchanged`	Es idéntica a la última aplicada	Nada: fue un reenvío
`stale`	Su revisión ya fue superada	Nada: hay una más nueva aplicada
`quarantined`	No validó; `reason` dice qué campo	Corregila y reenviá sólo esa

Una entidad en cuarentena no frena a las demás: el resto del lote entra igual. Qué es una revisión y por qué reentregar es seguro está en Mantenerse al día.

Primero el catálogo, después el historial

Un run por entidad, en este orden: categorías (taxonomy_node), productos (item), variantes (variant), disponibilidad (availability) y, al final, las órdenes históricas (order). Si un producto nombra una categoría que todavía no llegó, no falla: se resuelve cuando llega. Hay un solo run abierto por conexión y entidad. Con dos, el cierre del primero daría de baja lo del segundo.

Qué vas a ver

El cierre devuelve received, deleted y quarantined. En una sincronización inicial limpia, deleted y quarantined dan cero. Después, tu tienda puede leer un producto por tu propio id con GET /v1/catalog/items/by-external/{external_id} y su clave de storefront.

Si no lo ves

Lo que pasa	Qué hacer
`409` con `snapshot_open` al abrir	Ya hay un run abierto de esa entidad. Cerralo si está completo; si no, esperá a que expire
`404` en una página o en el cierre	El run expiró, ya se cerró o es de otra conexión. Abrí uno nuevo
`413`	La página trae más de 500 entidades y se rechazó entera. Partila
`quarantined` por un precio	`amount` va como texto decimal (`"12900.00"`), nunca como número
`quarantined` en una disponibilidad	Con `stock_mode: "tracked"` va `quantity`; con los otros dos, no

Mantenerse al día

Cada cambio después de la sincronización inicial.

El modelo canónico

Los campos de cada entidad.

Conectores

Referencia del protocolo

Sincronización inicial

Qué sincronizás

Tu catálogo

Tus órdenes históricas

Los tres pasos

Leé la respuesta

Primero el catálogo, después el historial

Qué vas a ver

Si no lo ves

Mantenerse al día

El modelo canónico

​Qué sincronizás

Tu catálogo

Tus órdenes históricas

​Los tres pasos

​Leé la respuesta

​Primero el catálogo, después el historial

​Qué vas a ver

​Si no lo ves

Mantenerse al día

El modelo canónico

Qué sincronizás

Los tres pasos

Leé la respuesta

Primero el catálogo, después el historial

Qué vas a ver

Si no lo ves