> ## Documentation Index
> Fetch the complete documentation index at: https://docs.needalert.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Referência externa

> Use o código do seu sistema, como o SKU, para encontrar e sincronizar itens.

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

```bash theme={null}
curl "$API/establishments/12/items?external_reference=SKU-123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

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**:

```json theme={null}
{
  "message": "Outro item desta unidade já usa esta referência externa.",
  "code": "item_external_reference_taken"
}
```

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](https://docs.needalert.app/api/use-cases.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.