> For the complete documentation index, see [llms.txt](https://ereemby.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ereemby.gitbook.io/docs/desenvolvedores/documentacao-api-publica/tags.md).

# Tags

Gerencie tags e associações do catálogo pela API.

Gerencie as tags do catálogo via API. Uma tag pode ser associada a produtos, variantes e categorias.

Envie `x-api-key` em todas as requisições. A chave precisa da permissão `EREEMBY_TAG`. Veja como gerar em [Chave de API](/docs/desenvolvedores/chave-de-api.md).

{% hint style="warning" %}
**Rate limit:** listagem: `5` requisições por `2s`. Criação, atualização e remoção: `10` requisições por `10s`.
{% endhint %}

## Listar tags

> Lista todas as tags da loja da API key.

```json
{"openapi":"3.0.0","info":{"title":"Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Endpoints de gerenciamento de tags. Requer API key com a permissão EREEMBY_TAG habilitada."}],"servers":[{"url":"https://api.ereemby.app/api/v1","description":"Servidor de Produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API da loja, enviada no header x-api-key em todas as requisições. A permissão EREEMBY_TAG precisa estar habilitada na chave."}},"schemas":{"Tag":{"type":"object","description":"Tag como retornada na listagem.","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string","description":"Cor em hexadecimal #RRGGBB."},"icon":{"type":"string","nullable":true,"description":"URL do ícone (ou null)."},"private_view_chat":{"type":"boolean"},"add_to_chat":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Não autorizado: o header x-api-key está ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Acesso negado: a API key não possui a permissão EREEMBY_TAG.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimit":{"description":"Muitas requisições - limite de taxa excedido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/tags":{"get":{"tags":["Tags"],"summary":"Listar tags","description":"Lista todas as tags da loja da API key.","operationId":"listTags","responses":{"200":{"description":"Lista de tags retornada com sucesso.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimit"}}}}}}
```

## Criar tag

> Cria uma tag na loja da API key e, opcionalmente, associa produtos, variantes e categorias. IDs que não pertencem à loja (ou inexistentes) são ignorados em silêncio.

```json
{"openapi":"3.0.0","info":{"title":"Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Endpoints de gerenciamento de tags. Requer API key com a permissão EREEMBY_TAG habilitada."}],"servers":[{"url":"https://api.ereemby.app/api/v1","description":"Servidor de Produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API da loja, enviada no header x-api-key em todas as requisições. A permissão EREEMBY_TAG precisa estar habilitada na chave."}},"schemas":{"TagCreateInput":{"type":"object","required":["name","color"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100,"description":"Nome da tag (obrigatório). Deve ser único na loja."},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","description":"Cor em hexadecimal #RRGGBB (obrigatório)."},"icon":{"type":"string","nullable":true,"maxLength":500,"description":"URL do ícone (opcional)."},"products":{"type":"array","maxItems":500,"description":"IDs de produto para associar (opcional, máx 500). IDs fora da loja são ignorados em silêncio.","items":{"type":"string"}},"variants":{"type":"array","maxItems":500,"description":"IDs de variante para associar (opcional, máx 500).","items":{"type":"integer"}},"categories":{"type":"array","maxItems":500,"description":"IDs de categoria para associar (opcional, máx 500).","items":{"type":"string"}},"private_view_chat":{"type":"boolean"},"add_to_chat":{"type":"boolean"}}},"TagWithAssociations":{"type":"object","description":"Tag como retornada na criação. Os arrays refletem apenas o que foi realmente associado (IDs de outra loja ou inexistentes já saíram da lista).","properties":{"id":{"type":"integer"},"name":{"type":"string"},"color":{"type":"string"},"products":{"type":"array","items":{"type":"string"}},"variants":{"type":"array","items":{"type":"integer"}},"categories":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Body inválido (validação) ou nome de tag duplicado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Não autorizado: o header x-api-key está ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Acesso negado: a API key não possui a permissão EREEMBY_TAG.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimit":{"description":"Muitas requisições - limite de taxa excedido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/tag":{"post":{"tags":["Tags"],"summary":"Criar tag","description":"Cria uma tag na loja da API key e, opcionalmente, associa produtos, variantes e categorias. IDs que não pertencem à loja (ou inexistentes) são ignorados em silêncio.","operationId":"createTag","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagCreateInput"}}}},"responses":{"201":{"description":"Tag criada com sucesso. Os arrays retornados refletem apenas as associações efetivadas — IDs que não são da loja (ou inexistentes) saem vazios, sem erro.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagWithAssociations"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimit"}}}}}}
```

## Atualizar tag

> Atualização parcial de uma tag da loja. Para associações, a semântica é por lista: enviar uma lista substitui o conjunto; \`\[]\` remove todas; campo ausente não altera. As regras valem de forma independente para \`products\`, \`variants\` e \`categories\`.

```json
{"openapi":"3.0.0","info":{"title":"Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Endpoints de gerenciamento de tags. Requer API key com a permissão EREEMBY_TAG habilitada."}],"servers":[{"url":"https://api.ereemby.app/api/v1","description":"Servidor de Produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API da loja, enviada no header x-api-key em todas as requisições. A permissão EREEMBY_TAG precisa estar habilitada na chave."}},"schemas":{"TagUpdateInput":{"type":"object","description":"Atualização parcial. Todos os campos são opcionais. Para associações, a semântica é por lista: enviar uma lista substitui o conjunto; `[]` remove todas; campo ausente não altera. As regras valem de forma independente para `products`, `variants` e `categories`.","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"color":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"icon":{"type":"string","nullable":true,"maxLength":500},"products":{"type":"array","maxItems":500,"items":{"type":"string"}},"variants":{"type":"array","maxItems":500,"items":{"type":"integer"}},"categories":{"type":"array","maxItems":500,"items":{"type":"string"}},"private_view_chat":{"type":"boolean"},"add_to_chat":{"type":"boolean"}}},"OkResponse":{"type":"object","properties":{"ok":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Body inválido (validação) ou nome de tag duplicado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Não autorizado: o header x-api-key está ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Acesso negado: a API key não possui a permissão EREEMBY_TAG.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimit":{"description":"Muitas requisições - limite de taxa excedido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/tag/{id}":{"patch":{"tags":["Tags"],"summary":"Atualizar tag","description":"Atualização parcial de uma tag da loja. Para associações, a semântica é por lista: enviar uma lista substitui o conjunto; `[]` remove todas; campo ausente não altera. As regras valem de forma independente para `products`, `variants` e `categories`.","operationId":"updateTag","parameters":[{"name":"id","in":"path","description":"ID da tag.","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagUpdateInput"}}}},"responses":{"200":{"description":"Tag atualizada com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OkResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Tag não encontrada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimit"}}}}}}
```

## Remover tag

> Remove a tag da loja. As junções com produtos, variantes e categorias são removidas em cascata.

```json
{"openapi":"3.0.0","info":{"title":"Tags API","version":"1.0.0"},"tags":[{"name":"Tags","description":"Endpoints de gerenciamento de tags. Requer API key com a permissão EREEMBY_TAG habilitada."}],"servers":[{"url":"https://api.ereemby.app/api/v1","description":"Servidor de Produção"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave de API da loja, enviada no header x-api-key em todas as requisições. A permissão EREEMBY_TAG precisa estar habilitada na chave."}},"responses":{"Unauthorized":{"description":"Não autorizado: o header x-api-key está ausente ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Acesso negado: a API key não possui a permissão EREEMBY_TAG.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimit":{"description":"Muitas requisições - limite de taxa excedido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"/tag/{id}":{"delete":{"tags":["Tags"],"summary":"Remover tag","description":"Remove a tag da loja. As junções com produtos, variantes e categorias são removidas em cascata.","operationId":"deleteTag","parameters":[{"name":"id","in":"path","description":"ID da tag.","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Tag removida com sucesso (sem conteúdo)."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Tag não encontrada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimit"}}}}}}
```

### Teste rápido (cURL)

Listar tags:

```bash
curl -sS \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  "https://api.ereemby.app/api/v1/tags"
```

Criar tag:

```bash
curl -sS -X POST \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{"name":"tag_exemplo","color":"#4ADE80"}' \
  "https://api.ereemby.app/api/v1/tag"
```

Atualizar tag:

```bash
curl -sS -X PATCH \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  -H "Content-Type: application/json" \
  -d '{"products":["prod_1","prod_3"],"categories":[]}' \
  "https://api.ereemby.app/api/v1/tag/SEU_TAG_ID"
```

Remover tag:

```bash
curl -sS -X DELETE \
  -H "x-api-key: SUA_CHAVE_DE_API" \
  "https://api.ereemby.app/api/v1/tag/SEU_TAG_ID"
```

{% hint style="info" %}
No `PATCH`, cada lista substitui as associações daquele tipo. Envie `[]` para remover todas. Campos ausentes permanecem inalterados.
{% endhint %}

{% hint style="info" %}
Se receber `429`, reduza a frequência e tente novamente com backoff.
{% endhint %}

### Erros comuns

* `400 Bad Request`: payload inválido ou nome de tag duplicado.
* `401 Unauthorized`: faltou `x-api-key` ou ela é inválida.
* `403 Forbidden`: a chave não tem a permissão `EREEMBY_TAG`.
* `404 Not Found`: a tag não existe ou não pertence à sua loja.
* `429 Too Many Requests`: você excedeu o rate limit.

### Rotas relacionadas

* [Gestão de catálogo](/docs/desenvolvedores/documentacao-api-publica/gestao-de-catalogo.md)
* [Produtos](/docs/desenvolvedores/documentacao-api-publica/gestao-de-catalogo/produtos.md)
* [Categorias](/docs/desenvolvedores/documentacao-api-publica/gestao-de-catalogo/categorias.md)

### Boas práticas

* Guarde o `id` retornado ao criar a tag.
* Confirme os arrays retornados após criar associações.
* Use backoff exponencial para erros `429` e `5xx`.