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

Tags de plano. Contas com o módulo de associações usam tags de um segundo tipo, com carência, limite de dependentes e sincronização de situação do associado. Elas aparecem nas listagens da API como qualquer outra tag, mas a API não expõe nem altera essas configurações, e toda tag criada por aqui é uma tag comum. Para criar ou editar uma tag de plano, use a tela.

Endpoints

GET/v1/tags

Lista as tags da conta. Ordem: name ASC.

{
  "tags": [
    {
      "id": 12,
      "name": "Mensalistas",
      "color": "success",
      "allows_on_account": false,
      "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, allows_on_account.

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 (sem diferenciar maiúsculas) retorna 422.

PATCH/v1/tags/:id

Campos aceitos: name, color, allows_on_account. 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 por uma cobrança não pode ser apagada — a resposta é 422 com o motivo. Isso vale tanto para a tag alvo de uma emissão em massa (inclusive agendamentos) quanto para uma tag usada como exclusão em excluded_tag_ids. Apague ou reaponte a cobrança antes.

Fiado restrito por tag

allows_on_account restringe o fiado e o uso de créditos no PDV aos clientes que têm a tag. Vale para qualquer tag, comum ou de plano.

• Sem nenhuma tag marcada na conta, nada muda: todo cliente pode comprar fiado, dentro do limite de fiado dele.
• Com ao menos uma tag marcada, só o cliente que tem uma das tags marcadas pode finalizar uma venda com valor em aberto. Os demais são recusados no PDV.
• A tag libera, o limite define o teto: para quem tem a tag, on_account_limit continua valendo como antes.
• A regra barra só fiado novo. Fiado já em aberto, recebimentos, baixa por repasse e devoluções não mudam.
• Créditos seguem a mesma regra. Sem uma tag marcada, o contato não paga com créditos no PDV nem recebe devolução em créditos. O saldo dele fica intocado e volta a valer quando a tag voltar. A inclusão de crédito pela API continua aceita.

Marcar a primeira tag da conta muda a regra para todos os clientes de uma vez: quem ainda não tem a tag deixa de comprar fiado e de usar créditos. Aplique a tag aos clientes antes (com tag_ids em contatos) ou logo depois de marcá-la.

O contato traz o resultado em on_account_allowed. Ver Fiado restrito por tag em contatos.

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