Seu conector mantém a CrossUp em dia enviando cada mudança quando acontece. Se o seu sistema apaga sem avisar, um snapshot uma vez por dia limpa o que já não existe.

As duas rotinas do seu conector

1 · Cada mudança, quando acontece

Mudou um preço, entrou estoque, um produto foi apagado, um pedido foi pago: seu conector envia só isso.

2 · Tudo, uma vez por dia (opcional)

Só se o seu sistema não consegue avisar o que apaga: envia o catálogo completo e o que não veio é removido.
Se o seu conector também envia os delete, a rotina 1 basta.

Rotina 1: enviar o que mudou

A CrossUp te dá um endpoint e seu conector faz um POST cada vez que algo muda. Como o seu conector fica sabendo da mudança depende do seu sistema: a CrossUp não precisa saber.
1

Algo muda no seu sistema

Um preço, um estoque, um produto novo ou apagado, um pedido novo ou que mudou de status.
2

Passe para o formato da CrossUp

Cada entidade leva seu external_id (o id no seu sistema) e uma operação: upsert se foi criada ou mudou, delete se foi apagada. Os campos de cada uma estão em O modelo canônico.
3

Envie

Um POST para /observations, com até 500 entidades. Cada uma volta com seu resultado, igual à sincronização inicial.
Um delete não leva document. Pedidos novos, ou que mudam de status, vão por aqui como order.

Rotina 2 (opcional): o snapshot diário

Use só se o seu sistema não consegue enviar os delete. É a mesma sequência da sincronização inicial: você abre um run por entidade, envia tudo em páginas e fecha. Ao fechar, o que não veio daquele tipo é removido. Programe uma vez por dia, no horário de menos movimento da sua loja.
Enquanto o run está aberto, não envie observações dessa entidade. Um produto que entre pela rotina 1 durante o run seria removido ao fechar, e uma página antiga poderia sobrescrever uma mudança mais nova.
O snapshot diário é para o catálogo, não para os pedidos. Um snapshot é “tudo”: se você fechar um run de order com os pedidos de hoje, os anteriores são removidos. Depois da sincronização inicial, os pedidos vão sempre pela rotina 1.

Se algo falhar, tente de novo

Reenviar o mesmo nunca duplica nada, então diante de uma queda ou de um timeout você pode enviar o lote inteiro de novo.
  • Com revision: um inteiro que só cresce, como um updated_at em milissegundos. É aplicada só se for maior que a última; se não, volta stale e não sobrescreve nada.
  • Sem revision: a CrossUp compara o conteúdo. Se for idêntico ao último, volta unchanged.
Se o seu sistema não tem nada que só cresça, omita revision.

O que não valida: quarentena

Uma entidade que não cumpre o contrato volta quarantined. O reason nomeia o campo: document.quantity: required. As outras do lote entram. Corrija essa entidade e reenvie só ela. O que volta accepted já é da CrossUp. Fica arquivado e chega ao catálogo mesmo que algo do outro lado esteja fora do ar. Seu conector não precisa reenviar.

Glossário

  • Conexão: sua loja na CrossUp. O id é o connection_id (cn_…).
  • Observação: uma entidade que mudou, com upsert ou delete.
  • Snapshot: “aqui está tudo” de um tipo de entidade. Ao fechá-lo, o que não veio é removido.
  • Run: um snapshot aberto (snp_…). Sem fechar, expira em 24 horas.
  • Revisão: um inteiro que só cresce e diz qual versão é a mais nova.
  • Quarentena: o que não validou; reason diz por quê.

O que você vai ver

Cada mudança que você envia volta accepted. Um reenvio volta unchanged ou stale, e seu catálogo fica com a versão mais nova.

Se não aparecer

O modelo canônico

Quais campos cada entidade leva e quais se omitem.

SDK de conector e protocolo

O contrato, e como falá-lo na sua linguagem.