# CrossUp Docs

> CrossUp suma a cada compra el producto que la completa (cross-selling y upselling en seis momentos de compra) y mide cada venta que genera, orden por orden. Su IA se llama SalesPilot. Señales adentro (catálogo, órdenes, lo que hace el comprador), recomendaciones afuera (qué productos mostrar en cada momento; en la API, el objeto Decision). Se integra de forma nativa (la app de Tiendanube o Shopify) o custom (un conector alimenta el catálogo, hoy armado junto con CrossUp; el Storefront SDK o la API consumen las recomendaciones). Documentación en español (/es/), portugués (/pt/) e inglés (/en/): las mismas páginas, mismos identificadores, misma estructura. Cada índice de abajo lista un idioma.

Cinco cosas que hay que saber antes de escribir código:
- La tienda no viaja: sale de la clave de storefront (spk_). Ningún request lleva store_id.
- results: [] es una respuesta válida; reason_codes dice por qué. No se muestra nada. Cómo se muestra una recomendación es siempre del lado de la tienda: CrossUp no trae componentes de UI.
- Un campo ausente es desconocido, no cero. sellable es un string; title es un objeto por idioma.
- Las señales van atadas a un decision_id (el id de la recomendación) que esta conexión recibió; signal_id estable hace que reintentar sea seguro.
- 60 pedidos por minuto por clave; ante 429, esperar Retry-After y no reintentar en loop.

## Español

### Empezar

- [CrossUp para desarrolladores](https://docs.crossup.ai/es/introduccion.md): CrossUp suma a cada compra el producto que la completa y mide cada venta. Para Tiendanube, Shopify, VTEX o tu tienda propia: con la app, el SDK, la API o tu agente.
- [Qué decide CrossUp](https://docs.crossup.ai/es/empezar/que-decide-crossup.md): Vos mostrás; CrossUp elige qué producto, a quién y en qué momento. Qué entra, qué sale y qué queda de tu lado.
- [Los seis momentos](https://docs.crossup.ai/es/empezar/momentos.md): Seis momentos del recorrido para sumar un producto a la compra: qué necesita cada uno y cómo se pide.
- [Cómo se conecta tu tienda](https://docs.crossup.ai/es/empezar/como-se-conecta-tu-tienda.md): ¿Tu tienda está en Tiendanube o Shopify? Instalás la app y listo. ¿En VTEX o es propia? Armamos el conector con vos.
- [Tu primera recomendación en 20 minutos](https://docs.crossup.ai/es/empezar/primera-recomendacion.md): De la clave generada en el admin a una recomendación en tu tienda, con la primera señal enviada.
- [Señales y atribución](https://docs.crossup.ai/es/empezar/senales-y-atribucion.md): Cada venta que CrossUp genera se prueba con una señal. Qué señales mandar, cuándo, y qué cuenta como venta atribuida.
- [Claves y seguridad](https://docs.crossup.ai/es/empezar/claves-y-seguridad.md): La clave de storefront: de dónde sale, por qué es pública por diseño, qué puede hacer y cómo se rota sin cortar la tienda.

### Storefront SDK (@crossup/storefront)

- [Instalar el Storefront SDK](https://docs.crossup.ai/es/storefront/instalar.md): @crossup/storefront: el cliente que corre en tu tienda para pedir recomendaciones, llevar el visitante y mandar señales.
- [Pedir recomendaciones](https://docs.crossup.ai/es/storefront/pedir-recomendaciones.md): getRecommendations y tryGetRecommendations: el pedido por momento, lo que vuelve, y cómo leer el catálogo.
- [Reportar señales](https://docs.crossup.ai/es/storefront/reportar-senales.md): track.*: las siete señales, cuándo mandar cada una y cómo ver si llegaron.
- [Visitante y contexto](https://docs.crossup.ai/es/storefront/visitante-y-contexto.md): El SDK arma el visitante y la sesión solo y los manda con cada recomendación y cada señal. Qué tenés que hacer vos y para qué los usa CrossUp.
- [Referencia del paquete](https://docs.crossup.ai/es/storefront/referencia.md): Todo lo que exporta @crossup/storefront, en una página.

### API (platform-api v1)

- [La API](https://docs.crossup.ai/es/api/introduccion.md): Dos llamadas alcanzan para integrar: pedir una recomendación y registrar señales. La base, la autenticación, las cinco operaciones y sus convenciones.
- [Cuota y caché](https://docs.crossup.ai/es/api/cuota-y-cache.md): Sesenta pedidos por minuto por clave, el 429 con Retry-After, y cómo no gastar la cuota dos veces en lo mismo.
- [Versionado y compatibilidad](https://docs.crossup.ai/es/api/versionado.md): Qué puede cambiar en la API sin avisar, qué no, y cómo escribir un cliente que sobreviva a los cambios.
- [Errores](https://docs.crossup.ai/es/api/errores.md): Los once Problem Details de la API: su type URI, cuándo aparece cada uno y qué extensiones trae.
- [Pedir una recomendación](https://docs.crossup.ai/es/api/get-recommendations.md): Devuelve la recomendación para un momento del storefront: los productos en orden, cada uno ya proyectado al catálogo canónico.
- [Registrar señales del storefront](https://docs.crossup.ai/es/api/record-storefront-signals.md): Guarda lo que el comprador hizo con una recomendación ya servida y lo reenvía al motor, que sigue siendo el dueño de las interacciones.
- [Leer un ítem del catálogo](https://docs.crossup.ai/es/api/get-catalog-item.md): Devuelve el agregado canónico: ítem, variantes y disponibilidad.
- [Ingerir un evento de catálogo](https://docs.crossup.ai/es/api/ingest-signal.md): Recibe un evento de catálogo ya normalizado y lo deduplica por signal_id.
- [Estado del proceso](https://docs.crossup.ai/es/api/health.md): La única operación sin autenticación: responde si el proceso puede servir pedidos.

### Conectores (protocolo interno, para tiendas custom y plataformas)

- [Qué es un conector custom](https://docs.crossup.ai/es/conectores/que-es-un-conector.md): VTEX, tienda propia, headless o ERP: tu conector empuja catálogo y órdenes a CrossUp y tus tiendas reciben recomendaciones. En tres pasos.
- [Tu primera carga](https://docs.crossup.ai/es/conectores/primera-carga.md): Abrí un snapshot, mandá tu catálogo en páginas de hasta 500 y cerralo: cada entidad vuelve con su resultado y sabés qué entró y qué corregir.
- [Mantenerse al día](https://docs.crossup.ai/es/conectores/ciclo-de-vida.md): Después de la primera carga: mandá cada cambio como observación, reentregá sin miedo a duplicar y usá un snapshot periódico para dar de baja lo que se borró.
- [El modelo canónico](https://docs.crossup.ai/es/conectores/modelo-canonico.md): Las cinco entidades que manda tu conector, sus campos y la regla que evita recomendaciones rotas: lo que tu sistema no tiene se omite, nunca se inventa.
- [SDK de conector y protocolo](https://docs.crossup.ai/es/conectores/sdk.md): Escribí tu conector en el lenguaje que uses: el protocolo es un contrato OpenAPI sobre HTTP, con tipos que salen del mismo contrato.

### Agentes

- [Integrá con tu agente](https://docs.crossup.ai/es/agentes/integra-con-tu-agente.md): Tu agente integra, vos revisás el diff: pasale la clave y esta documentación a Claude, Cursor o Codex. Qué puede hacer hoy y qué no.
- [El MCP de CrossUp](https://docs.crossup.ai/es/agentes/mcp.md): El servidor MCP de CrossUp: dos herramientas de lectura sobre la API, cómo conectarlo a Claude, Cursor o Codex, y qué sigue.
- [llms.txt](https://docs.crossup.ai/es/agentes/llms-txt.md): Toda la documentación en un archivo para tu agente, cada página como Markdown, y el orden en que conviene leerla.
- [La skill de integrador](https://docs.crossup.ai/es/agentes/skill.md): Un archivo que dejás en tu repo para que tu agente integre CrossUp siguiendo el mismo recorrido que esta documentación, con sus verificaciones.
- [La CLI](https://docs.crossup.ai/es/agentes/cli.md): crossup: las mismas lecturas que el MCP, para una persona en una terminal. Diagnóstico, no integración.

### Cambios

- [Cambios](https://docs.crossup.ai/es/cambios.md): Lo nuevo en CrossUp para integradores, con fecha: SDK, API, conectores, claves y agentes.

## Português

### Começar

- [CrossUp para desenvolvedores](https://docs.crossup.ai/pt/introduccion.md): A CrossUp soma a cada compra o produto que a completa e mede cada venda. Para Nuvemshop, Shopify, VTEX ou a sua loja própria: com o app, o SDK, a API ou o seu agente.
- [O que a CrossUp decide](https://docs.crossup.ai/pt/empezar/que-decide-crossup.md): Você mostra; a CrossUp escolhe qual produto, para quem e em que momento. O que entra, o que sai e o que fica do seu lado.
- [Os seis momentos](https://docs.crossup.ai/pt/empezar/momentos.md): Seis momentos da jornada para somar um produto à compra: o que cada um precisa e como se pede.
- [Como a sua loja se conecta](https://docs.crossup.ai/pt/empezar/como-se-conecta-tu-tienda.md): Sua loja está na Nuvemshop ou na Shopify? Você instala o app e pronto. Na VTEX ou é própria? Montamos o conector com você.
- [Sua primeira recomendação em 20 minutos](https://docs.crossup.ai/pt/empezar/primera-recomendacion.md): Da chave gerada no admin a uma recomendação na sua loja, com o primeiro sinal enviado.
- [Sinais e atribuição](https://docs.crossup.ai/pt/empezar/senales-y-atribucion.md): Cada venda que a CrossUp gera é comprovada por um sinal. Quais sinais mandar, quando, e o que conta como venda atribuída.
- [Chaves e segurança](https://docs.crossup.ai/pt/empezar/claves-y-seguridad.md): A chave de storefront: de onde ela sai, por que é pública por design, o que pode fazer e como rotacioná-la sem derrubar a loja.

### Storefront SDK (@crossup/storefront)

- [Instalar o Storefront SDK](https://docs.crossup.ai/pt/storefront/instalar.md): @crossup/storefront: o cliente que roda na sua loja para pedir recomendações, levar o visitante e mandar sinais.
- [Pedir recomendações](https://docs.crossup.ai/pt/storefront/pedir-recomendaciones.md): getRecommendations e tryGetRecommendations: a requisição por momento, o que volta, e como ler o catálogo.
- [Reportar sinais](https://docs.crossup.ai/pt/storefront/reportar-senales.md): track.*: os sete sinais, quando mandar cada um e como ver se chegaram.
- [Visitante e contexto](https://docs.crossup.ai/pt/storefront/visitante-y-contexto.md): O SDK monta o visitante e a sessão sozinho e os envia com cada recomendação e cada sinal. O que você precisa fazer e para que a CrossUp os usa.
- [Referência do pacote](https://docs.crossup.ai/pt/storefront/referencia.md): Tudo o que @crossup/storefront exporta, em uma página.

### API (platform-api v1)

- [A API](https://docs.crossup.ai/pt/api/introduccion.md): Duas chamadas bastam para integrar: pedir uma recomendação e registrar sinais. A base, a autenticação, as cinco operações e suas convenções.
- [Cota e cache](https://docs.crossup.ai/pt/api/cuota-y-cache.md): Sessenta requisições por minuto por chave, o 429 com Retry-After, e como não gastar a cota duas vezes na mesma coisa.
- [Versionamento e compatibilidade](https://docs.crossup.ai/pt/api/versionado.md): O que pode mudar na API sem avisar, o que não, e como escrever um cliente que sobreviva às mudanças.
- [Erros](https://docs.crossup.ai/pt/api/errores.md): Os onze Problem Details da API: seu type URI, quando cada um aparece e quais extensões traz.
- [Pedir uma recomendação](https://docs.crossup.ai/pt/api/get-recommendations.md): Devolve a recomendação para um momento do storefront: os produtos em ordem, cada um já projetado no catálogo canônico.
- [Registrar sinais do storefront](https://docs.crossup.ai/pt/api/record-storefront-signals.md): Guarda o que o comprador fez com uma recomendação já servida e o reenvia ao motor, que continua sendo o dono das interações.
- [Ler um item do catálogo](https://docs.crossup.ai/pt/api/get-catalog-item.md): Devolve o agregado canônico: item, variantes e disponibilidade.
- [Ingerir um evento de catálogo](https://docs.crossup.ai/pt/api/ingest-signal.md): Recebe um evento de catálogo já normalizado e o deduplica por signal_id.
- [Estado do processo](https://docs.crossup.ai/pt/api/health.md): A única operação sem autenticação: responde se o processo pode atender requisições.

### Conectores (protocolo interno, para lojas custom e plataformas)

- [O que é um conector custom](https://docs.crossup.ai/pt/conectores/que-es-un-conector.md): VTEX, loja própria, headless ou ERP: seu conector envia catálogo e pedidos para a CrossUp e suas lojas recebem recomendações. Em três passos.
- [Sua primeira carga](https://docs.crossup.ai/pt/conectores/primera-carga.md): Abra um snapshot, envie seu catálogo em páginas de até 500 e feche: cada entidade volta com seu resultado e você sabe o que entrou e o que corrigir.
- [Manter-se em dia](https://docs.crossup.ai/pt/conectores/ciclo-de-vida.md): Depois da primeira carga: envie cada mudança como observação, reenvie sem medo de duplicar e use um snapshot periódico para remover o que foi apagado.
- [O modelo canônico](https://docs.crossup.ai/pt/conectores/modelo-canonico.md): As cinco entidades que o seu conector envia, seus campos e a regra que evita recomendações quebradas: o que o seu sistema não tem é omitido, nunca inventado.
- [SDK de conector e protocolo](https://docs.crossup.ai/pt/conectores/sdk.md): Escreva seu conector na linguagem que você usa: o protocolo é um contrato OpenAPI sobre HTTP, com tipos que saem do mesmo contrato.

### Agentes

- [Integre com o seu agente](https://docs.crossup.ai/pt/agentes/integra-con-tu-agente.md): O seu agente integra, você revisa o diff: passe a chave e esta documentação ao Claude, ao Cursor ou ao Codex. O que ele pode fazer hoje e o que não.
- [O MCP da CrossUp](https://docs.crossup.ai/pt/agentes/mcp.md): O servidor MCP da CrossUp: duas ferramentas de leitura sobre a API, como conectá-lo ao Claude, ao Cursor ou ao Codex, e o que vem depois.
- [llms.txt](https://docs.crossup.ai/pt/agentes/llms-txt.md): Toda a documentação em um arquivo para o seu agente, cada página como Markdown, e a ordem em que convém lê-la.
- [A skill de integrador](https://docs.crossup.ai/pt/agentes/skill.md): Um arquivo que você deixa no seu repositório para que o seu agente integre a CrossUp seguindo o mesmo percurso que esta documentação, com suas verificações.
- [A CLI](https://docs.crossup.ai/pt/agentes/cli.md): crossup: as mesmas leituras que o MCP, para uma pessoa em um terminal. Diagnóstico, não integração.

### Mudanças

- [Mudanças](https://docs.crossup.ai/pt/cambios.md): O que há de novo na CrossUp para integradores, com data: SDK, API, conectores, chaves e agentes.

## English

### Get started

- [CrossUp for developers](https://docs.crossup.ai/en/introduccion.md): CrossUp adds the product that completes every purchase and measures every sale. For Tiendanube, Shopify, VTEX or your own store: via the app, the SDK, the API or your agent.
- [What CrossUp decides](https://docs.crossup.ai/en/empezar/que-decide-crossup.md): You display; CrossUp picks which product, for whom and at which moment. What goes in, what comes out and what stays on your side.
- [The six moments](https://docs.crossup.ai/en/empezar/momentos.md): Six moments in the shopping journey to add a product to the purchase: what each one needs and how to request it.
- [How your store connects](https://docs.crossup.ai/en/empezar/como-se-conecta-tu-tienda.md): Is your store on Tiendanube or Shopify? Install the app and you're set. On VTEX or your own build? We build the connector with you.
- [Your first recommendation in 20 minutes](https://docs.crossup.ai/en/empezar/primera-recomendacion.md): From the key generated in the admin to a recommendation in your store, with the first signal sent.
- [Signals and attribution](https://docs.crossup.ai/en/empezar/senales-y-atribucion.md): Every sale CrossUp brings in is proven by a signal. Which signals to send, when, and what counts as an attributed sale.
- [Keys and security](https://docs.crossup.ai/en/empezar/claves-y-seguridad.md): The storefront key: where it comes from, why it is public by design, what it can do and how to rotate it without breaking the store.

### Storefront SDK (@crossup/storefront)

- [Install the Storefront SDK](https://docs.crossup.ai/en/storefront/instalar.md): @crossup/storefront: the client that runs in your store to request recommendations, carry the visitor and send signals.
- [Request recommendations](https://docs.crossup.ai/en/storefront/pedir-recomendaciones.md): getRecommendations and tryGetRecommendations: the request per moment, what comes back, and how to read the catalog.
- [Report signals](https://docs.crossup.ai/en/storefront/reportar-senales.md): track.*: the seven signals, when to send each one and how to check they arrived.
- [Visitor and context](https://docs.crossup.ai/en/storefront/visitante-y-contexto.md): The SDK builds the visitor and the session on its own and sends them with every recommendation and every signal. What you need to do and what CrossUp uses them for.
- [Package reference](https://docs.crossup.ai/en/storefront/referencia.md): Everything @crossup/storefront exports, on one page.

### API (platform-api v1)

- [The API](https://docs.crossup.ai/en/api/introduccion.md): Two calls are enough to integrate: request a recommendation and record signals. The base URL, authentication, the five operations and their conventions.
- [Quota and cache](https://docs.crossup.ai/en/api/cuota-y-cache.md): Sixty requests per minute per key, the 429 with Retry-After, and how not to spend the quota twice on the same thing.
- [Versioning and compatibility](https://docs.crossup.ai/en/api/versionado.md): What can change in the API without notice, what can't, and how to write a client that survives the changes.
- [Errors](https://docs.crossup.ai/en/api/errores.md): The eleven Problem Details of the API: their type URI, when each one appears and which extensions it carries.
- [Request a recommendation](https://docs.crossup.ai/en/api/get-recommendations.md): Returns the recommendation for a storefront moment: the products in order, each one already projected onto the canonical catalog.
- [Record storefront signals](https://docs.crossup.ai/en/api/record-storefront-signals.md): Stores what the shopper did with an already served recommendation and forwards it to the engine, which remains the owner of interactions.
- [Read a catalog item](https://docs.crossup.ai/en/api/get-catalog-item.md): Returns the canonical aggregate: item, variants and availability.
- [Ingest a catalog event](https://docs.crossup.ai/en/api/ingest-signal.md): Receives an already normalized catalog event and deduplicates it by signal_id.
- [Process status](https://docs.crossup.ai/en/api/health.md): The only operation without authentication: answers whether the process can serve requests.

### Connectors (internal protocol, for custom stores and platforms)

- [What a custom connector is](https://docs.crossup.ai/en/conectores/que-es-un-conector.md): VTEX, your own store, headless or an ERP: your connector pushes catalog and orders to CrossUp and your stores get recommendations. In three steps.
- [Your first load](https://docs.crossup.ai/en/conectores/primera-carga.md): Open a snapshot, send your catalog in pages of up to 500 and close it: every entity comes back with its result, so you know what went in and what to fix.
- [Staying up to date](https://docs.crossup.ai/en/conectores/ciclo-de-vida.md): After the first load: send each change as an observation, resend without fear of duplicates and use a periodic snapshot to remove what was deleted.
- [The canonical model](https://docs.crossup.ai/en/conectores/modelo-canonico.md): The five entities your connector sends, their fields, and the rule that keeps recommendations from breaking: what your system doesn't have is left out, never made up.
- [Connector SDK and protocol](https://docs.crossup.ai/en/conectores/sdk.md): Write your connector in the language you already use: the protocol is an OpenAPI contract over HTTP, with types generated from the same contract.

### Agents

- [Integrate with your agent](https://docs.crossup.ai/en/agentes/integra-con-tu-agente.md): Your agent integrates, you review the diff: give Claude, Cursor or Codex the key and this documentation. What it can do today and what it can't.
- [The CrossUp MCP](https://docs.crossup.ai/en/agentes/mcp.md): CrossUp's MCP server: two read tools over the API, how to connect it to Claude, Cursor or Codex, and what's next.
- [llms.txt](https://docs.crossup.ai/en/agentes/llms-txt.md): All the documentation in one file for your agent, each page as Markdown, and the order in which it is best read.
- [The integrator skill](https://docs.crossup.ai/en/agentes/skill.md): A file you leave in your repo so your agent integrates CrossUp following the same path as this documentation, with its checks.
- [The CLI](https://docs.crossup.ai/en/agentes/cli.md): crossup: the same reads as the MCP, for a person in a terminal. Diagnostics, not integration.

### Changelog

- [Changelog](https://docs.crossup.ai/en/cambios.md): What's new in CrossUp for integrators, dated: SDK, API, connectors, keys and agents.