Etiquetar operações

Há dois momentos para etiquetar uma operação: na criação ou depois, a qualquer hora. Esta página mostra os dois caminhos e como filtrar a listagem pelas etiquetas. Para entender o que é uma etiqueta e como gerenciá-las, veja Etiquetas.

Na criação

Envie os ids das etiquetas no campo labels de Criar operação:

{
  "name": "Contrato de prestação de serviços",
  "labels": [12, 31],
  "files": [ ... ],
  "members": [ ... ]
}

Na criação só dá para usar etiquetas que já existem. Para criar uma etiqueta nova junto com a aplicação, use o endpoint abaixo.

Depois da criação

PUT /api/v2/operation/{operationId}/labels

O operationId na URL é o ID da operação, o campo id retornado em Criar operação.

Body

{
  "labelIds": [12, 31],
  "newLabels": [
    { "name": "Renovação 2026", "color": "#43A047" }
  ]
}

Com newLabels você não precisa criar a etiqueta antes nem guardar o id dela: mande sempre o mesmo nome e a API resolve para a mesma etiqueta.

Exemplo

curl -X PUT "https://api.forsign.digital/api/v2/operation/4821/labels" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "labelIds": [12], "newLabels": [{ "name": "Renovação 2026", "color": "#43A047" }] }'

await fetch(`https://api.forsign.digital/api/v2/operation/${operationId}/labels`, {
  method: 'PUT',
  headers: {
    'X-Api-Key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    labelIds: [12],
    newLabels: [{ name: 'Renovação 2026', color: '#43A047' }],
  }),
});

var resp = await http.PutAsJsonAsync(
    $"/api/v2/operation/{operationId}/labels",
    new
    {
        labelIds = new[] { 12L },
        newLabels = new[] { new { name = "Renovação 2026", color = "#43A047" } },
    });
resp.EnsureSuccessStatusCode();

Resposta de sucesso (200)

{ "success": true, "statusCode": 200, "messages": [{ "value": "Etiquetas da operacao atualizadas com sucesso." }] }

A resposta não traz as etiquetas. Para conferir o resultado, consulte a operação na listagem (abaixo).

Regras

• Até 20 etiquetas por operação. Acima disso, a chamada retorna 400 e nada muda.
• Tudo ou nada. Se um id de labelIds não existir na sua conta, a chamada retorna 404 e nada muda. Nenhuma etiqueta de newLabels é criada.
• A API key precisa de permissão para editar a operação. É a mesma permissão usada para cancelar.
• Funciona em qualquer status, inclusive em operação finalizada ou cancelada.
• A mudança entra no histórico da operação, mas não altera a "Última atualização" e não dispara webhook.

Filtrar a listagem por etiqueta

A listagem de operações aceita um filtro pelo campo Labels, com o operador Contains e um ou mais ids de etiqueta:

curl -G "https://api.forsign.digital/api/v2/operation" \
  -H "X-Api-Key: $API_KEY" \
  --data-urlencode "Filters[0].Field=Labels" \
  --data-urlencode "Filters[0].Operator=Contains" \
  --data-urlencode "Filters[0].Values[0]=12" \
  --data-urlencode "Filters[0].Values[1]=31"

Com mais de um id, o filtro traz as operações que têm qualquer uma das etiquetas (OU, não E). Cada operação da listagem traz o campo labels, com id, name e color de cada etiqueta, em ordem alfabética.

Erros comuns

Veja também