O modelo canônico

Venha da VTEX, de um headless ou de um ERP, seu catálogo chega à CrossUp como cinco entidades. Tudo é opcional exceto o que identifica, e um campo que o seu sistema não tem é omitido: não vai vazio nem zerado.

As cinco entidades

`entity`	O que é
`taxonomy_node`	Uma categoria. `parent_id` é o `external_id` do pai; uma raiz o omite
`item`	Um produto: título, descrição, mídias, marca, tags, categorias
`variant`	Uma variante: SKU, atributos, preços. `item_id` é o `external_id` do seu produto
`availability`	O estoque de uma variante
`order`	Um pedido com linhas, pagamentos, envios e estados

Todas são identificadas pelo seu external_id, o id que têm no seu sistema. item, variant e availability terminam no mesmo produto, e podem ser enviados separadamente. A disponibilidade leva o external_id da sua variante, sem sufixos. Uma variante tem uma única disponibilidade: se você enviar dois depósitos para a mesma, o segundo sobrescreve o primeiro.

Os campos

item

Campo	Tipo	Nota
`title`, `description`, `handles`	texto por idioma	`{ "pt": "…", "es": "…" }`; um idioma que você não tem é omitido
`urls`	objeto por idioma	A URL pública do produto
`media[]`	`{ url, alt }`	`alt` por idioma
`published`	boolean	Se está visível na loja
`brand`	string
`tags[]`	string
`free_shipping`	boolean
`taxonomy_ids[]`	string	Os `external_id` das suas categorias

variant

Campo	Tipo	Nota
`item_id`	string	O `external_id` do seu produto
`sku`	string
`title`	texto por idioma
`attributes[]`	`{ name, value }`	Os dois por idioma: tamanho, cor
`price`, `promotional_price`, `cost`	dinheiro	`{ "amount": "129.00", "currency": "BRL" }`
`published`	boolean
`media[]`	`{ url, alt }`
`shipping`	dimensões	Peso e medidas, como texto decimal

availability

Campo	Tipo	Nota
`variant_id` (obrigatório)	string	O `external_id` da variante. É também o `external_id` da observação
`stock_mode` (obrigatório)	`unlimited` · `tracked` · `unknown`	“Vende sempre”, “tem esta quantidade”, “não informa”. Tratar `unknown` como zero desliga produtos que estão à venda
`quantity`	decimal como string	Só com `tracked`, e aí é obrigatória
`sellability` (obrigatório)	`sellable` · `unsellable` · `unknown`	Se dá para comprar, segundo o seu sistema
`location_metadata` (obrigatório)	`resolved` · `unresolved`	Com `location_id`, vai `resolved`
`location_id`, `external_location_id`	string	Informativos: de qual depósito sai o número. Não fazem parte da identidade

taxonomy_node

Campo	Tipo	Nota
`name`, `description`, `handles`	texto por idioma
`parent_id`	string	O `external_id` do pai; uma raiz o omite
`visible`	boolean

order

Campo	Tipo	Nota
`number`, `origin`, `language`, `currency`	string
`lines[]`	linhas	Cada uma com `line_id`, `name`, `quantity`, `unit_price` e `subtotal`; `variant_external_id` para que a venda seja medida
`subtotal`, `total`	dinheiro
`discounts[]`, `payments[]`, `fulfillments[]`
`statuses`	estados	Se for, leva os seis: pagamento, envio e pedido, normalizados e como o seu sistema os envia
`contact`, `shopper`, `billing`, `shipping`	dados do comprador	Opcionais. Não são escritos em nenhum log
`created_at`, `updated_at`	RFC 3339
`external_references`	objeto	Outros ids do seu sistema

// Sem preço, o campo é omitido; não se envia zero.
const variant = {
  item_id: "1001",                      // o produto pai, com o seu id
  sku: "CAM-PRE-M",
  title: { pt: "Camiseta preta M" },    // por idioma
  ...(price ? { price: { amount: price, currency: "BRL" } } : {}), // texto, nunca um número
};

variant := map[string]any{
    "item_id": "1001",
    "sku":     "CAM-PRE-M",
    "title":   map[string]string{"pt": "Camiseta preta M"},
}
if price, ok := precoDe(v); ok {
    variant["price"] = map[string]string{"amount": price, "currency": "BRL"} // o valor é texto
}

Três tipos que não são o que parecem

Dinheiro é uma string. amount é um decimal como texto: um float binário muda o preço e aparece como um centavo a menos no checkout.
Texto é por idioma. Um idioma que você não tem é omitido: não copie o português no espanhol.
Estoque tem três estados. unlimited, tracked e unknown, e unknown não é zero.

Os pedidos

Não há uma entidade de clientes: os dados do comprador viajam dentro do pedido, e tudo é opcional. O que você enviar ali não escreva em nenhum log. Para que a venda fique medida, o pedido precisa poder ser cruzado com a recomendação:

O external_id do pedido é o mesmo cart_id que a sua loja envia ao pedir recomendações.
Cada linha traz variant_external_id. Uma linha conta como vendida se a sua variante está no pedido.

Quando o pedido mudar (o pagamento, o total), envie de novo: o cruzamento é refeito e dá o mesmo, sem duplicar.

Como chega à sua loja

A CrossUp mantém os seus external_id e atribui ids próprios (itm_…, var_…). Sua loja pode pedir um produto pelo seu id com GET /v1/catalog/items/by-external/{external_id}.

O que você vai ver

Cada entidade aceita aparece no catálogo com os campos que você enviou, e nenhum a mais. Um quarantined diz o campo exato que não validou.

Se não aparecer

O que acontece	O que fazer
`quarantined` numa variante	Quase sempre `price.amount` como número
`quarantined` numa disponibilidade	Falta `stock_mode` ou `sellability`, há `quantity` sem `tracked`, ou o `external_id` não é o da variante
Produtos sem preço nas recomendações (`missing_price`)	A variante chegou sem `price`. É correto se o seu sistema não o tem, mas sem preço a CrossUp não decide
Vendas que não são medidas	O pedido não traz `variant_external_id` nas linhas, ou o `external_id` dele não é o `cart_id` da loja

SDK de conector e protocolo

O contrato destas entidades, em OpenAPI.

O que a CrossUp decide

O que entra, o que sai e o que fica do seu lado.

Conectores

Referência do protocolo

O modelo canônico

As cinco entidades

Os campos

Três tipos que não são o que parecem

Os pedidos

Como chega à sua loja

O que você vai ver

Se não aparecer

SDK de conector e protocolo

O que a CrossUp decide

​As cinco entidades

​Os campos

​Três tipos que não são o que parecem

​Os pedidos

​Como chega à sua loja

​O que você vai ver

​Se não aparecer

SDK de conector e protocolo

O que a CrossUp decide

As cinco entidades

Os campos

Três tipos que não são o que parecem

Os pedidos

Como chega à sua loja

O que você vai ver

Se não aparecer