El modelo canónico

Venga de VTEX, de un headless o de un ERP, tu catálogo llega a CrossUp como cinco entidades. Todo es opcional salvo lo que identifica, y un campo que tu sistema no tiene se omite: no va vacío ni en cero.

Las cinco entidades

`entity`	Qué es
`taxonomy_node`	Una categoría. `parent_id` es el `external_id` del padre; una raíz lo omite
`item`	Un producto: título, descripción, medios, marca, tags, categorías
`variant`	Una variante: SKU, atributos, precios. `item_id` es el `external_id` de su producto
`availability`	El stock de una variante
`order`	Una orden con líneas, pagos, envíos y estados

Todas se identifican por su external_id, el id que tienen en tu sistema. item, variant y availability terminan en el mismo producto, y se pueden mandar por separado. La disponibilidad lleva el external_id de su variante, sin sufijos. Una variante tiene una sola disponibilidad: si mandás dos depósitos para la misma, el segundo pisa al primero.

Los campos

item

Campo	Tipo	Nota
`title`, `description`, `handles`	texto por idioma	`{ "es": "…", "pt": "…" }`; un idioma que no tenés se omite
`urls`	objeto por idioma	La URL pública del producto
`media[]`	`{ url, alt }`	`alt` por idioma
`published`	boolean	Si está visible en la tienda
`brand`	string
`tags[]`	string
`free_shipping`	boolean
`taxonomy_ids[]`	string	Los `external_id` de sus categorías

variant

Campo	Tipo	Nota
`item_id`	string	El `external_id` de su producto
`sku`	string
`title`	texto por idioma
`attributes[]`	`{ name, value }`	Los dos por idioma: talle, color
`price`, `promotional_price`, `cost`	dinero	`{ "amount": "12900.00", "currency": "ARS" }`
`published`	boolean
`media[]`	`{ url, alt }`
`shipping`	dimensiones	Peso y medidas, como texto decimal

availability

Campo	Tipo	Nota
`variant_id` (obligatorio)	string	El `external_id` de la variante. Es también el `external_id` de la observación
`stock_mode` (obligatorio)	`unlimited` · `tracked` · `unknown`	«Vende siempre», «tiene esta cantidad», «no lo dice». Tratar `unknown` como cero apaga productos que están a la venta
`quantity`	decimal como string	Sólo con `tracked`, y ahí es obligatoria
`sellability` (obligatorio)	`sellable` · `unsellable` · `unknown`	Si se puede comprar, según tu sistema
`location_metadata` (obligatorio)	`resolved` · `unresolved`	Con `location_id`, va `resolved`
`location_id`, `external_location_id`	string	Informativos: de qué depósito sale el número. No forman parte de la identidad

taxonomy_node

Campo	Tipo	Nota
`name`, `description`, `handles`	texto por idioma
`parent_id`	string	El `external_id` del padre; una raíz lo omite
`visible`	boolean

order

Campo	Tipo	Nota
`number`, `origin`, `language`, `currency`	string
`lines[]`	líneas	Cada una con `line_id`, `name`, `quantity`, `unit_price` y `subtotal`; `variant_external_id` para que la venta se mida
`subtotal`, `total`	dinero
`discounts[]`, `payments[]`, `fulfillments[]`
`statuses`	estados	Si va, lleva los seis: pago, envío y orden, normalizados y como los manda tu sistema
`contact`, `shopper`, `billing`, `shipping`	datos del comprador	Opcionales. No se escriben en ningún log
`created_at`, `updated_at`	RFC 3339
`external_references`	objeto	Otros ids de tu sistema

// Sin precio, el campo se omite; no se manda cero.
const variant = {
  item_id: "1001",                      // el producto padre, con tu id
  sku: "REM-NEG-M",
  title: { es: "Remera negra M" },      // por idioma
  ...(price ? { price: { amount: price, currency: "ARS" } } : {}), // texto, nunca un número
};

variant := map[string]any{
    "item_id": "1001",
    "sku":     "REM-NEG-M",
    "title":   map[string]string{"es": "Remera negra M"},
}
if price, ok := precioDe(v); ok {
    variant["price"] = map[string]string{"amount": price, "currency": "ARS"} // el monto es texto
}

Tres tipos que no son lo que parecen

Dinero es un string. amount es un decimal como texto: un float binario cambia el precio y aparece como un centavo de menos en el checkout.
Texto es por idioma. Un idioma que no tenés se omite: no copies el español en el portugués.
Stock tiene tres estados. unlimited, tracked y unknown, y unknown no es cero.

Las órdenes

No hay una entidad de clientes: lo del comprador viaja dentro de la orden, y todo es opcional. Lo que mandes ahí no lo escribas en ningún log. Para que la venta quede medida, la orden tiene que poder cruzarse con la recomendación:

El external_id de la orden es el mismo cart_id que tu tienda manda al pedir recomendaciones.
Cada línea trae variant_external_id. Una línea cuenta como vendida si su variante está en la orden.

Cuando la orden cambie (el pago, el total), mandala de nuevo: el cruce se rehace y da lo mismo, sin duplicar.

Cómo llega a tu tienda

CrossUp conserva tus external_id y asigna sus propios ids (itm_…, var_…). Tu tienda puede pedir un producto por tu id con GET /v1/catalog/items/by-external/{external_id}.

Qué vas a ver

Cada entidad aceptada aparece en el catálogo con los campos que mandaste, y ninguno más. Un quarantined dice el campo exacto que no validó.

Si no lo ves

Lo que pasa	Qué hacer
`quarantined` en una variante	Casi siempre `price.amount` como número
`quarantined` en una disponibilidad	Falta `stock_mode` o `sellability`, hay `quantity` sin `tracked`, o su `external_id` no es el de la variante
Productos sin precio en las recomendaciones (`missing_price`)	La variante llegó sin `price`. Es correcto si tu sistema no lo tiene, pero sin precio CrossUp no decide
Ventas que no se miden	La orden no trae `variant_external_id` en sus líneas, o su `external_id` no es el `cart_id` de la tienda

SDK de conector y protocolo

El contrato de estas entidades, en OpenAPI.

Qué decide CrossUp

Qué entra, qué sale y qué queda de tu lado.

Conectores

Referencia del protocolo

El modelo canónico

Las cinco entidades

Los campos

Tres tipos que no son lo que parecen

Las órdenes

Cómo llega a tu tienda

Qué vas a ver

Si no lo ves

SDK de conector y protocolo

Qué decide CrossUp

​Las cinco entidades

​Los campos

​Tres tipos que no son lo que parecen

​Las órdenes

​Cómo llega a tu tienda

​Qué vas a ver

​Si no lo ves

SDK de conector y protocolo

Qué decide CrossUp

Las cinco entidades

Los campos

Tres tipos que no son lo que parecen

Las órdenes

Cómo llega a tu tienda

Qué vas a ver

Si no lo ves