Etiquetas
Organize as operações da sua conta com etiquetas coloridas e filtre a listagem por elas.
Etiquetas servem para organizar as operações do seu jeito: por cliente, por área, por tipo de contrato, por etapa do seu processo interno. Elas aparecem no painel da ForSign, servem de filtro na listagem e podem ser aplicadas pela API.
Todos os usuários e API keys da conta veem e usam as mesmas etiquetas.
Nome de até 50 caracteres e cor em hexadecimal (#RRGGBB).
Uma operação pode ter várias etiquetas ao mesmo tempo.
Busque as operações que têm uma ou mais etiquetas.
Etiqueta é organização interna. O assinante não vê etiqueta nenhuma: ela não aparece na página de assinatura, nos emails nem no documento.
Como funciona
- O nome é único na conta, sem diferenciar maiúsculas.
Jurídicoejurídicosão a mesma etiqueta. Espaços nas pontas são removidos. - Criar uma etiqueta que já existe não dá erro. A API devolve a etiqueta
existente, com o
ide a cor dela. A cor enviada é ignorada nesse caso. - Renomear para um nome que já existe dá erro (
400). Assim duas etiquetas diferentes nunca viram uma só. - Editar ou excluir vale para todas as operações. Renomear muda o nome em todas as operações que usam a etiqueta. Excluir a remove de todas elas.
- Etiquetar não mexe na "Última atualização" da operação. A mudança fica registrada no histórico da operação, mas não reordena a listagem.
- Etiquetas não vão no webhook. O payload dos webhooks não traz as etiquetas da operação. Se precisar delas ao tratar um evento, consulte a operação pela API.
Gerenciar as etiquetas da conta
Todos os endpoints aceitam X-Api-Key.
| Ação | Método e rota | Body |
|---|---|---|
| Listar | GET /api/v2/operation-label | — |
| Criar | POST /api/v2/operation-label | { "name": "...", "color": "#RRGGBB" } |
| Editar | PUT /api/v2/operation-label/{id} | { "name": "...", "color": "#RRGGBB" } |
| Excluir | DELETE /api/v2/operation-label/{id} | — |
A listagem e a criação devolvem cada etiqueta neste formato:
{ "id": 12, "name": "Jurídico", "color": "#1E88E5" }Exemplo de criação:
curl -X POST "https://api.forsign.digital/api/v2/operation-label" \
-H "X-Api-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Jurídico", "color": "#1E88E5" }'A criação responde 201 com a etiqueta em data. A exclusão responde 204,
sem body.
Excluir é irreversível. A etiqueta sai de todas as operações. Se você criar
outra com o mesmo nome depois, ela recebe um id novo e não volta para as
operações antigas.
Erros comuns
| Status | Causa | Como resolver |
|---|---|---|
400 | name vazio ou com mais de 50 caracteres | Envie um nome entre 1 e 50 caracteres. |
400 | color fora do formato #RRGGBB | Use seis dígitos hexadecimais com #, como #1E88E5. |
400 | Renomeação para um nome que outra etiqueta já usa | Escolha outro nome ou use a etiqueta existente. |
401 | API key ausente ou inválida | Confira o header X-Api-Key. |
404 | id não existe na sua conta | Liste as etiquetas para pegar o id certo. |