Tags
?name= casa por nome EXATO, ignorando acento e maiúscula/minúscula — ?name=vip encontra "VIP", "Vip" ou "vip", mas não "VIP Ouro". Útil pra checar se uma tag…
{ "id": "…", "name": "Lead quente", "color": "#EE710E", "applies_to": ["contact", "deal"], "created_at": "…" }| Campo | Obrigatório | Regras |
|---|---|---|
name |
sim | 1–40 |
color |
sim | #rrggbb, ou #rrggbbaa com transparência |
applies_to |
sim | contact, company, deal — pelo menos um |
| Método | Escopo | Descrição |
|---|---|---|
GET/api/tags |
tags:read |
Lista. Filtros: ?applies_to=, ?name= |
POST/api/tags |
tags:write |
Cria (201). Nome repetido devolve a existente com created: false (200) |
PATCH/api/tags/{id} |
tags:write |
Edita name, color, applies_to |
DELETE/api/tags/{id} |
tags:write |
Exclui — veja a resposta especial abaixo |
?name= casa por nome EXATO, ignorando acento e maiúscula/minúscula — ?name=vip encontra
"VIP", "Vip" ou "vip", mas não "VIP Ouro". Útil pra checar se uma tag já existe antes de criar,
sem paginar a lista inteira. Sem casamento, devolve lista vazia — nunca erro.
Aplicar e remover tag — uma rota por tipo de registro, todas com escopo tags:write:
| Método | Descrição |
|---|---|
POST/api/contacts/{id}/tags |
Aplica no contato. Corpo: { "tag_id": "…" } |
DELETE/api/contacts/{id}/tags/{tagId} |
Remove do contato (204) |
POST/api/companies/{id}/tags |
Aplica na empresa. Corpo: { "tag_id": "…" } |
DELETE/api/companies/{id}/tags/{tagId} |
Remove da empresa (204) |
POST/api/deals/{id}/tags |
Aplica no negócio. Corpo: { "tag_id": "…" } |
DELETE/api/deals/{id}/tags/{tagId} |
Remove do negócio (204) |
- Aplicar responde
200, não201(é um vínculo, não um registro novo), com o corpo{ "data": { "entity": "contact", "entity_id": "…", "tag_id": "…", "applied": true } }. - Aplicar é idempotente: reaplicar a mesma tag responde sucesso, não erro.
applies_toé respeitado: aplicar tag de contato num negócio devolve400.- Criar tag com nome existente não é erro — devolve a que existe. Seu fluxo pode chamar "cria
a tag X" toda execução sem tratar conflito. Exceção: se a tag existente não servir para o
applies_toque você pediu, a resposta é409— dizer "sucesso" ali seria mentira útil. - Renomear (
PATCH) para um nome que já é de outra tag devolve409.
O DELETE conta os vínculos antes de apagar e devolve 200 (não 204) com o tamanho do
estrago:
{
"data": {
"id": "7c1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73",
"removed_links": { "contacts": 12, "companies": 0, "deals": 3 }
}
}O campo tags some sem tags:read
Uma chave sem tags:read não recebe "tags": [] em contato, empresa ou negócio — o campo
desaparece da resposta.
É proposital. Em JSON, campo ausente e lista vazia são afirmações diferentes: "tags": [] diz
"consultei, e este registro não tem etiqueta nenhuma" — uma afirmação que a sua chave, sem o
escopo, não tem como fazer honestamente. Se devolvêssemos [] mesmo assim, um fluxo do tipo "se
o contato for VIP, mande para o vendedor sênior" trataria todo mundo como não-VIP, para
sempre, sem nenhum sinal de que a informação nunca foi consultada.
Para detectar por programa, toda resposta com campo omitido traz:
x-salos-omitted-fields: tagsCom tags:read, um registro sem nenhuma etiqueta continua vindo com "tags": [] normalmente.