Pular para o conteúdo
SquadOS SquadOS Docs

Tags

As Tags são rótulos coloridos e reutilizáveis aplicados a contatos externos. Esta seção cobre os endpoints para gerenciar o catálogo de tags da organização e para aplicar e remover tags de um contato. Para o conceito no produto (chips no inbox, painel do contato, filtro), veja Tags de Contato.

Todos os endpoints exigem o header Authorization: Bearer pk_.... Quando houver corpo JSON, inclua também Content-Type: application/json.

Base URL: https://api.squados.io/v1

Consulte Autenticação para obter sua chave, e Erros para a referência de códigos.

O modelo ContactTag

Section titled “O modelo ContactTag”

Toda tag é representada por:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "lead quente",
  "color": "orange"
}
CampoTipoDescrição
iduuidIdentificador da tag.
namestringNome da tag (único na organização).
colorstringUma de: purple, blue, green, orange, red, pink, teal, gray.

GET /tags

Section titled “GET /tags”

Lista o catálogo de tags da organização, ordenado por nome.

Terminal window
curl -X GET "https://api.squados.io/v1/tags" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{
  "tags": [
    { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "aguardando pagamento", "color": "blue" },
    { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "cliente", "color": "red" },
    { "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789", "name": "lead quente", "color": "orange" }
  ]
}

PATCH /tags/{tagId}

Section titled “PATCH /tags/{tagId}”

Renomeia e/ou recolora uma tag do catálogo. A mudança vale para todos os contatos que têm a tag.

Parâmetros de caminho

NomeTipoDescrição
tagIduuidID da tag.

Corpo da requisição (envie ao menos um campo)

CampoTipoDescrição
namestringNovo nome da tag. Não pode ser vazio nem colidir com outra tag.
colorstringNova cor: purple, blue, green, orange, red, pink, teal ou gray.
Terminal window
curl -X PATCH "https://api.squados.io/v1/tags/TAG_ID" \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"name": "lead qualificado", "color": "green"}'

Resposta — 200 OK

{
  "success": true,
  "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789"
}

Erros relevantes: 400 se o nome for vazio ou a cor inválida; 404 se a tag não existir na sua organização; 409 se já existir outra tag com o nome informado.

DELETE /tags/{tagId}

Section titled “DELETE /tags/{tagId}”

Exclui a tag do catálogo e a remove de todos os contatos que a tinham. Não pode ser desfeito.

Parâmetros de caminho

NomeTipoDescrição
tagIduuidID da tag.
Terminal window
curl -X DELETE "https://api.squados.io/v1/tags/TAG_ID" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{ "success": true }

Erros relevantes: 404 se a tag não existir na sua organização.

GET /contacts/{contactId}/tags

Section titled “GET /contacts/{contactId}/tags”

Lista as tags aplicadas a um contato externo.

Parâmetros de caminho

NomeTipoDescrição
contactIduuidID do contato externo.
Terminal window
curl -X GET "https://api.squados.io/v1/contacts/CONTACT_ID/tags" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{
  "tags": [
    { "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789", "name": "lead quente", "color": "orange" },
    { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "cliente", "color": "red" }
  ]
}

Erros relevantes: 400 se o contactId for inválido; 404 se o contato não existir ou não pertencer à sua organização.

POST /contacts/{contactId}/tags

Section titled “POST /contacts/{contactId}/tags”

Aplica uma tag ao contato pelo nome. Se a tag ainda não existir no catálogo da organização, ela é criada automaticamente (com uma cor atribuída de forma determinística a partir do nome).

Parâmetros de caminho

NomeTipoDescrição
contactIduuidID do contato externo.

Corpo da requisição

CampoTipoObrigatórioDescrição
namestringSimNome da tag a aplicar (criada se não existir).
Terminal window
curl -X POST "https://api.squados.io/v1/contacts/CONTACT_ID/tags" \
  -H "Authorization: Bearer pk_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{"name": "lead quente"}'

Resposta — 200 OK

{
  "tag": { "id": "8a1b2c3d-4e5f-6789-abcd-ef0123456789", "name": "lead quente", "color": "orange" }
}

Erros relevantes: 400 se name for vazio ou o contactId inválido; 404 se o contato não existir ou não pertencer à sua organização.

DELETE /contacts/{contactId}/tags/{tagId}

Section titled “DELETE /contacts/{contactId}/tags/{tagId}”

Remove a tag do contato. A tag permanece no catálogo da organização e em outros contatos.

Parâmetros de caminho

NomeTipoDescrição
contactIduuidID do contato externo.
tagIduuidID da tag a remover.
Terminal window
curl -X DELETE "https://api.squados.io/v1/contacts/CONTACT_ID/tags/TAG_ID" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta — 200 OK

{ "success": true }

Erros relevantes: 400 se algum ID for inválido; 404 se o contato não existir ou não pertencer à sua organização.