Pular para o conteúdo principal
O seu sistema conhece o SKU, o código do procedimento ou o id do produto, não o id do Need Alert. O campo external_reference do item guarda esse código, para você não precisar manter um mapa próprio entre os dois sistemas.

​
Regras

  • Até 100 caracteres, texto livre. Não é traduzido.
  • Única por unidade entre os itens não arquivados. O mesmo código pode existir em unidades diferentes: cada loja tem o seu item.
  • A comparação é exata e diferencia maiúsculas: SKU-123 e sku-123 são referências diferentes.
  • Arquivar o item libera a referência para um item novo.
  • Aceita em POST e PATCH de itens; null remove a referência.

​
Encontrar um item

O filtro é exato, não é busca: data vem com um item ou vazio. Para busca por nome, use o parâmetro search.

​
Conflito

Criar ou editar um item com uma referência que outro item não arquivado da mesma unidade já usa responde 409:
Isso vale também quando dois processos criam o mesmo item ao mesmo tempo: um recebe 201, o outro 409.

​
Padrão: procurar, senão criar

Para sincronizar a sua lista de produtos:
1

Procure pela referência

GET /establishments/{establishment}/items?external_reference=<código>.
2

Se existir, atualize

PATCH /establishments/{establishment}/items/{item} com o que mudou (translations, status, queue_type).
3

Se não existir, crie

POST /establishments/{establishment}/items com external_reference e um Idempotency-Key. Um 409 aqui significa que outro processo criou o item entre a sua busca e a criação: busque de novo.
4

Ao descontinuar o produto, arquive

DELETE /establishments/{establishment}/items/{item} arquiva o item (não apaga) e libera a referência.
No painel, o campo aparece como Referência externa (SKU) no formulário do item. Veja o roteiro completo em Casos de uso.