Tags

Tags são etiquetas livres da conta usadas para agrupar clientes. Um contato pode ter várias tags e uma tag pode ter vários contatos.

Elas são o critério da emissão em massa: uma cobrança com billing_issue_type=bulk aponta para uma tag_id e é expandida em uma cobrança por cliente ativo que tenha aquela tag. Ver cobranças.

Modelo

Campo	Tipo	Regras
`id`	integer
`name`	string	Obrigatório, até 40 chars. Único por conta, sem diferenciar maiúsculas de minúsculas
`color`	string	Opcional, default `info`. Um de `default`, `info`, `primary`, `success`, `warning`, `danger`, `purple`
`created_at`, `updated_at`	ISO-8601

Endpoints

GET`/v1/tags`

Lista as tags da conta. Ordem: name ASC.

Query param	Valores	Efeito
`s`	string	Busca por nome, correspondência parcial e sem diferenciar maiúsculas
`page`, `per_page`	int	Padrão de paginação (ver convenções)

{
  "tags": [
    {
      "id": 12,
      "name": "Mensalistas",
      "color": "success",
      "created_at": "2026-08-09T10:12:33.000-03:00",
      "updated_at": "2026-08-09T10:12:33.000-03:00"
    }
  ]
}

GET`/v1/tags/:id`

Retorna uma tag. 404 se o id não existir ou pertencer a outra conta.

POST`/v1/tags`

Campos aceitos: name, color.

curl -X POST https://api.sacador.com.br/v1/tags \
  -H "Authorization: Bearer sct_seu_token" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "Mensalistas", "color": "success" } }'

Retorna 201 Created com a tag. Nome repetido na mesma conta retorna 422.

PATCH`/v1/tags/:id`

Campos aceitos: name, color. Retorna 200 com a tag atualizada.

Renomear uma tag não altera as cobranças em massa já emitidas — elas continuam apontando para a mesma tag_id.

DELETE`/v1/tags/:id`

Retorna 204 No Content. Os vínculos com os contatos são removidos junto; os contatos em si não são afetados.

Uma tag ainda usada como alvo de uma cobrança (inclusive agendamentos em massa) não pode ser apagada — a resposta é 422 com o motivo. Apague ou reaponte a cobrança antes.

Tags de um contato

O objeto de contato traz as tags aplicadas:

{
  "id": 501,
  "description": "Maria Silva",
  "tags": [
    { "id": 12, "name": "Mensalistas", "color": "success" }
  ]
}

Para definir as tags de um contato, envie tag_ids em POST/v1/contacts ou PATCH/v1/contacts/:id. É uma substituição, não um acréscimo: a lista enviada passa a ser o conjunto completo de tags do contato.

curl -X PATCH https://api.sacador.com.br/v1/contacts/501 \
  -H "Authorization: Bearer sct_seu_token" \
  -H "Content-Type: application/json" \
  -d '{ "contact": { "tag_ids": [12, 34] } }'

"tag_ids": [] (JSON) ou contact[tag_ids][]= (form) removem todas as tags do contato. null tem o mesmo efeito.
Omitir tag_ids mantém as tags como estão.
Um id inexistente ou de outra conta faz a requisição inteira falhar com 422, sem aplicar nenhuma das tags e sem gravar os demais campos enviados junto.
Valores não numéricos são ignorados.

Para listar os contatos de uma tag, use o filtro tag_id:

GET/v1/contacts?tag_id=12&active=true