Tarefas vindas de outro sistema

Um chamado no helpdesk, uma oportunidade ganha no CRM ou um alerta do monitoramento viram trabalho para alguém. Em vez de copiar à mão, o seu sistema cria a tarefa direto no quadro da equipe, com responsável e prazo, e a acompanha pelas colunas até a conclusão.

Quando usar	Algo que nasce fora da TAI precisa virar tarefa num quadro, ou um fato da própria TAI deve gerar trabalho para uma equipe
Porta	REST · Webhook (o andamento) · Automação · Agente (MCP)
Você vai precisar	Módulo GESTAO_PROJETOS; permissão TAREFA com nível de edição; token JWT

Como funciona

seu sistema ── GET  /board/ativos ─────────────────▶ TAI  (escolhe o quadro)
            ── GET  /coluna/board/{boardId} ───────▶ TAI  (escolhe a coluna de entrada)
            ── POST /tarefa ───────────────────────▶ TAI  (cria; o responsável recebe e-mail)
            ── PUT  /tarefa/mover/{id}/para-coluna/{colunaId} ──▶ TAI  (avança)
            ── POST /tarefa-comentario ────────────▶ TAI  (registra andamento)

TAI ── TAREFA_CRIADA, TAREFA_MOVIDA ──▶ webhook ──▶ seu sistema  (a equipe moveu a tarefa no quadro)

Um quadro (board) pertence a um subdepartamento e tem colunas do tipo TODO, DOING ou DONE. A tarefa mora numa coluna; o tipo da coluna é o que diz se ela está a fazer, em andamento ou concluída.

Passo a passo

1. Escolha o quadro.

   GET /board/ativos
   Authorization: Bearer $TAI_TOKEN

   Guarde o id do quadro da equipe.

2. Escolha a coluna de entrada. A primeira coluna “a fazer” do quadro:

   GET /coluna/board/12/tipo/TODO/primeira

   Ou todas, na ordem: GET /coluna/board/12. Guarde os ids das colunas que o seu sistema usa (entrada, andamento, concluído) — eles não mudam enquanto o quadro existir.

3. Crie a tarefa.

   POST /tarefa
   Content-Type: application/json
   
   {
     "titulo": "[HD-48213] Impressora do 2º andar sem rede",
     "descricao": "Aberto por Ana Ribeiro no helpdesk. Equipamento PAT-00731.",
     "coluna": { "id": 31 },
     "colaborador": { "id": 205 },
     "prioridade": "ALTA",
     "dataLimite": "2026-10-06"
   }

   titulo e coluna são obrigatórios. colaborador é o responsável e recebe um e-mail de atribuição; prioridade aceita CRITICA, ALTA, MEDIA e BAIXA. A tarefa entra no fim da coluna. Guarde o id ao lado do registro no seu sistema.

4. Mova conforme o andamento.

   PUT /tarefa/mover/9921/para-coluna/32?observacao=Técnico%20a%20caminho

   A movimentação fica registrada (é dela que saem lead time e cycle time). Coluna com limite de tarefas cheio recusa a entrada com 400.

5. Comente o que acontecer.

   POST /tarefa-comentario
   Content-Type: application/json
   
   { "tarefaId": 9921, "conteudo": "Cabo de rede substituído; aguardando teste do usuário." }

Ler de volta

Para	Rota
O quadro inteiro, coluna a coluna	GET /tarefa/kanban/board/{boardId}
As tarefas de um quadro	GET /tarefa/board/{boardId}
As tarefas de uma coluna (por exemplo, a de concluídas)	GET /tarefa/coluna/{colunaId}
As tarefas atrasadas	GET /tarefa/atrasadas
O histórico de colunas de uma tarefa	GET /tarefa-movimentacao/tarefa/{tarefaId}

A coluna atual vem em coluna e a data de conclusão em dataConclusao.

Saber quando a equipe move a tarefa

Em vez de consultar o quadro de tempos em tempos, crie um webhook em Processos › Central de Automações › Webhooks assinando Uma tarefa muda de coluna (TAREFA_MOVIDA) — e, se o seu sistema também precisa das tarefas criadas na TAI, Uma tarefa é criada (TAREFA_CRIADA). Quando alguém arrasta a tarefa para a coluna de concluídas, chega:

{
  "id": "evt_71402",
  "tipo": "TAREFA_MOVIDA",
  "descricao": "Uma tarefa muda de coluna",
  "versao": 1,
  "ocorridoEm": "2026-10-06T16:45:09.771Z",
  "empresa": { "id": 12, "nome": "Sua Empresa Ltda" },
  "dados": {
    "tarefaId": 9921,
    "titulo": "[HD-48213] Impressora do 2º andar sem rede",
    "boardId": 12,
    "colunaId": 33,
    "colunaNome": "Concluído",
    "colunaTipo": "DONE",
    "colunaOrigemNome": "Em andamento",
    "concluida": true,
    "colaboradorId": 205
  }
}

Case pelo tarefaId que você guardou — ou pelo código no titulo — e feche o chamado quando concluida for true. O webhook manda as tarefas de todos os quadros: descarte as de boardId que não interessam. TAREFA_CRIADA traz tarefaId, titulo, boardId, colunaId, colunaNome, prioridade, dataLimite, colaboradorId e criadorId — e chega também para as tarefas que o seu próprio sistema criou: descarte as que você já conhece pelo tarefaId.

Automatize

Fatos da própria TAI podem criar tarefas sem código, pela operação de criar tarefa da plataforma:

• num fluxo automatizado (Processos › Fluxos › Novo processo › Fluxo automatizado) que começa por Quando algo acontece, com o bloco Fazer algo na plataforma — por exemplo, PARCELA_VENCIDA vira a tarefa “Cobrar o cliente” no quadro do financeiro;
• numa automação de quadro de Processos, com a ação Executar uma operação da plataforma — por exemplo, um card que entra na fase “Execução” vira tarefa no quadro da equipe.

Busque a operação de criar tarefa e informe os parâmetros, com as variáveis do evento (gatilho.*, no fluxo automatizado) ou do card:

{
  "body": {
    "titulo": "Cobrar {{gatilho.contraparte}} — saldo R$ {{gatilho.saldo}}",
    "descricao": "Parcela vencida em {{gatilho.vencimento}}. Título {{gatilho.tituloId}}.",
    "coluna": { "id": 31 },
    "prioridade": "ALTA"
  }
}

A operação roda com a permissão de quem publicou o fluxo (ou salvou a automação do quadro), e na trilha o autor aparece como Tali · automações. Os eventos disponíveis estão no catálogo e em cada guia de módulo — por exemplo, Financeiro.

Quando o fato nasce no seu sistema e ele só sabe disparar um webhook — sem token da TAI nem lógica para escolher quadro e coluna —, um endereço de entrada faz o mesmo papel: o seu sistema envia os dados, um fluxo automatizado que começa por Quando outro sistema chamar recebe a chamada, e o bloco Fazer algo na plataforma cria a tarefa com o que chegou em gatilho.corpo.

Pelo seu agente de IA

“Crie uma tarefa no quadro Suporte TI para a Ana trocar o cabo da impressora do 2º andar, prazo segunda-feira, prioridade alta.”

Com escopo de escrita, o agente acha o quadro, a coluna e a colaboradora e cria a tarefa — seu cliente de IA pede aprovação antes. Somente leitura: “o que está atrasado no quadro Suporte TI?”.

Cuidados

• Duplicidade: POST /tarefa não confere se a mesma tarefa já existe. Guarde o id da TAI; se precisar procurar, a busca de GET /tarefa/page?search= cobre o título — por isso vale pôr o código do seu sistema nele, como [HD-48213].
• Ids da sua conta: coluna e responsável de outra conta respondem 404.
• Alterar só alguns campos: PATCH /tarefa com o id e o que mudou; o PUT substitui o registro inteiro. Para mudar de coluna, use a rota de mover — ela registra a movimentação e publica TAREFA_MOVIDA.
• Datas como yyyy-MM-dd. Veja Datas e formatos.