LBHM Tasks

Processos e tipos

Toda tarefa criada pela API nasce classificada. Além do título e da origem, informe a que processo a tarefa pertence e qual tipo de tarefa ela é dentro desse processo. São dois identificadores numéricos — processo_id e tipo_id — que vêm do cadastro da sua organização.

Comece descobrindo os valores disponíveis; só depois envie a tarefa.

Descubra os processos e tipos disponíveis

GET /api/v1/processos
Authorization: Bearer SEU_TOKEN

A resposta traz os processos cadastrados e, dentro de cada um, os tipos ativos daquele processo — os dois numa chamada só, para você não precisar consultar de novo a cada troca de processo.

{
  "processos": [
    {
      "id": 3,
      "nome": "Faturamento",
      "descricao": "Pendências do fechamento mensal",
      "ativo": 1,
      "tarefas": 42,
      "tipos": [
        { "id": 7, "nome": "Divergência de valor" },
        { "id": 9, "nome": "Erro de emissão" }
      ]
    }
  ]
}
Campo Descrição
id (do processo) Use como processo_id ao criar a tarefa.
nome Nome do processo, como aparece na tela.
descricao Texto de apoio do cadastro (pode vir vazio).
ativo 1 quando o processo está em uso; 0 quando foi desativado.
tarefas Quantas tarefas já estão classificadas nesse processo.
tipos Tipos ativos do processo. O id de um deles é o tipo_id da tarefa.

Um tipo desativado não vem na lista tipos, e as tarefas já classificadas com ele continuam como estão. Desativar tira o tipo das escolhas — não fecha a porta da API: o tipo_id de um tipo desativado continua sendo aceito na criação de tarefas. Por isso, monte a sua integração a partir do que esta lista devolve, em vez de guardar um tipo_id que alguém escolheu uma vez.

O mesmo vale para os processos, com uma diferença: a lista traz todos, ativos e desativados, cada um com o campo ativo (1 ou 0). Use-o para não oferecer um processo que a organização já aposentou.

Cadastre um processo

Quando o processo que você precisa ainda não existe, crie-o:

POST /api/v1/processos
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "nome": "Faturamento",
  "descricao": "Pendências do fechamento mensal"
}
Campo Obrigatório Descrição
nome sim Nome do processo. É o que a equipe vê na tela.
descricao não Texto curto de apoio.

Resposta 200 OK com o identificador a usar dali em diante:

{ "id": 3, "nome": "Faturamento" }

O cadastro é pelo nome: reenviar a chamada com um nome que já existe devolve o identificador do cadastro atual, sem duplicar — uma reentrega da sua integração é segura. Nesse caso a descricao enviada é ignorada e a que já estava lá continua valendo; para mudar o texto de um processo existente, edite-o em Processos, no menu lateral.

Cadastre os tipos de cada processo

Os tipos de tarefa são cadastrados na tela, dentro do processo a que pertencem:

  1. Abra Processos no menu lateral e clique no processo.
  2. No painel Tipos de tarefa, escolha Adicionar tipo.
  3. Dê um nome, escolha a cor do rótulo e decida se a criação de uma tarefa desse tipo avisa por e-mail — e, se avisar, com qual modelo de texto.

Para tirar um tipo das escolhas sem mexer no que já foi classificado, edite-o e desmarque Ativo. Excluir um tipo que já está em uso não é permitido pela tela, justamente para que nenhuma tarefa fique sem classificação.

Cada campo do cadastro está em Processos, tipos e ações.

Use os valores ao criar a tarefa

Com o par em mãos, envie a tarefa:

POST /api/v1/tasks
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "titulo": "Revisar nota fiscal 12345",
  "origem": "faturamento",
  "referencia_externa": "NF-12345",
  "processo_id": 3,
  "tipo_id": 7,
  "topicos": ["fiscal"]
}

O tipo precisa pertencer ao processo informado — combinações de processos diferentes são recusadas.

O par é exigido ao criar. Ao reenviar uma tarefa que já existe (mesma origem e mesma referencia_externa), a classificação atual é preservada quando você não manda outra — com uma exceção: se a reentrega muda o processo_id e não manda o tipo_id, a tarefa fica sem tipo, porque o tipo anterior pertence ao processo antigo. Ao trocar o processo, mande sempre o tipo junto.

Se a criação for recusada, a resposta diz exatamente qual dos dois valores falta ou não confere — veja Erros e respostas da API.

Continue por aqui