API — Tarefas

Os campos da API são em português. Datas aceitam AAAA-MM-DD HH:MM:SS ou ISO 8601.

Antes de começar

Toda tarefa nova precisa do par processo_id + tipo_id. Descubra os valores disponíveis em GET /api/v1/processos — veja Processos e tipos.

Criar ou atualizar uma tarefa

POST /api/v1/tasks

Cria uma tarefa. Se você informar origem + referencia_externa e já existir uma tarefa com esse par, ela é atualizada em vez de duplicada (veja idempotência).

Campos

Envie sempre processo_id e tipo_id ao criar, e escolha um tipo que pertença ao processo informado — a criação sem esse par é recusada com 422. Na reentrega de uma tarefa que já existe (mesma origem + referencia_externa) não é preciso reenviá-los: a classificação atual é preservada, com uma exceção descrita em O que a reentrega regrava, mais abaixo.

O login do responsável

Um login que ainda não passou pelo sistema é cadastrado na hora, e a tarefa vai para ele. Isso é o que permite direcionar a tarefa para quem ainda não entrou — mas também significa que um login digitado errado não é recusado: ele vira uma conta nova, e a tarefa fica com alguém que não existe, sem nenhum aviso.

Envie o login exatamente como a pessoa o usa para entrar. Se ele vier de um cadastro do seu lado, confira-o contra a lista de usuários antes de enviar. Para deixar a tarefa sem responsável e entregá-la pelos tópicos, omita o campo.

Nomes alternativos aceitos

Se o seu sistema já trabalha com nomes em inglês, alguns campos aceitam um apelido equivalente. A forma preferida é a em português — o apelido existe para poupar tradução de quem integra a partir de um contrato pronto.

Os apelidos valem tanto em POST /api/v1/tasks quanto em PATCH /api/v1/tasks/by-ref. Enviando os dois nomes no mesmo corpo, vale o nome em português. Os demais campos (titulo, origem, descricao, status, prioridade, motivo, parametros) têm um nome só.

Exemplo

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": 2,
  "tipo_id": 7,
  "descricao": "Divergência no valor do imposto.",
  "prioridade": "alta",
  "prazo": "2026-06-30 18:00:00",
  "url_origem": "https://sistema-de-origem/notas/12345",
  "responsavel": "maria.silva",
  "topicos": ["fiscal"],
  "etiquetas": ["revisão"],
  "parametros": {
    "nota_id": 12345,
    "cliente": "ACME",
    "valor": 1530.42
  }
}

Resposta

201 Created quando cria, 200 OK quando atualiza uma existente:

{
  "id": 87,
  "status": "aberta",
  "criado": true,
  "processo_id": 2,
  "tipo_id": 7,
  "topicos": ["fiscal"]
}

Criar uma tarefa já com um status de encerramento (concluida, cancelada, resolvido ou nao_se_aplica) funciona e não pede motivo: ela é criada encerrada, com a data do desfecho, e o histórico fica sem a explicação. Quando o desfecho precisa ficar registrado, crie a tarefa aberta e encerre-a pelo PATCH /api/v1/tasks/by-ref, com o motivo.

Envie os tópicos que descrevem a tarefa — são eles que a levam até a equipe certa. Uma equipe enxerga a tarefa que tiver todos os tópicos do recorte dela, então quanto mais preciso o conjunto, mais direcionada a entrega. Tarefa enviada sem tópico nenhum fica com o responsável, sem chegar às equipes (veja Tópicos e visibilidade).

O que a reentrega regrava

No reenvio da mesma origem + referencia_externa, mande a tarefa inteira: o conteúdo enviado substitui o anterior, e os campos omitidos (descricao, prazo, url_origem) ficam vazios; prioridade omitida volta para media. O processo, o tipo e os parametros são preservados quando você não os envia.

Há uma exceção no tipo, e ela é intencional: como cada tipo vive dentro de um processo, uma reentrega que muda o processo_id sem mandar tipo_id deixa a tarefa sem tipo — o tipo que estava lá é de outro processo e não vale mais. Sempre que trocar o processo, mande também o tipo_id novo, escolhido entre os tipos daquele processo.

Já o status e o responsavel não mudam por reentrega — para alterá-los use PATCH /api/v1/tasks/by-ref.

As listas substituem o conjunto inteiro: enviar topicos ou etiquetas troca os que estavam lá pelos que vieram; omitir a lista mantém o que já estava salvo.

Uma exceção: na reentrega, topicos com a lista vazia não limpa os tópicos — mantém os que já estavam. É proteção para a origem que reentrega a tarefa sem saber classificá-la, e assim ela não perde o roteamento que alguém já ajustou. Para remover todos os tópicos de uma tarefa, use PATCH /api/v1/tasks/by-ref com "topicos": []. Em etiquetas a lista vazia limpa nos dois caminhos.

Parâmetros (parametros)

O campo parametros aceita um objeto JSON livre — qualquer estrutura que o sistema de origem queira anexar à tarefa (identificadores, valores, contexto). Ele é armazenado junto com a tarefa e exibido no detalhe dela. Na reentrega (mesmo origem + referencia_externa), enviar parametros substitui o valor anterior; omiti-lo preserva o que já estava salvo.

Atualizar ou finalizar pela referência externa

PATCH /api/v1/tasks/by-ref

Atualiza uma tarefa identificada por origem + referencia_externa — sem precisar saber o id. Aplica apenas os campos enviados. Para finalizar, envie status: "concluida" acompanhado de motivo.

Ao levar a tarefa para concluida, cancelada, resolvido ou nao_se_aplica, envie também motivo. Sem ele a chamada é recusada com 422 e a tarefa permanece como estava. Isso vale também no reenvio: mandar concluida numa tarefa que já está concluída, sem motivo, volta 422. Se a sua integração repete a chamada por segurança, mantenha o motivo no corpo de todas as tentativas — assim a repetição termina em 200 e não em recusa.

Ao trocar o processo_id de uma tarefa, mande também o tipo_id novo: o tipo anterior é de outro processo e sai, deixando a tarefa sem tipo.

Exemplo — finalizar

PATCH /api/v1/tasks/by-ref
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "origem": "faturamento",
  "referencia_externa": "NF-12345",
  "status": "concluida",
  "motivo": "Divergência corrigida pelo setor fiscal."
}

Retorna a tarefa atualizada (campos em português). Se nenhuma tarefa casar com a referência, responde 404.

Listar tarefas

GET /api/v1/tasks

Parâmetros de consulta opcionais: status, prioridade, topico (slug do tópico), origem, busca, processo e tipo (os identificadores que vêm em GET /api/v1/processos).

A busca procura o trecho no título e na referência externa da tarefa — então dá para reencontrar uma tarefa pela chave do seu próprio sistema. Se o termo for só números, ele casa também o número da tarefa, exato. A descrição fica fora da busca.

A resposta vem em páginas: pagina (padrão 1) e por_pagina (padrão 50, máximo 200) escolhem o lote.

{
  "tarefas": [
    { "id": 87, "titulo": "Revisar nota fiscal 12345", "status": "aberta",
      "prioridade": "alta", "origem": "faturamento", "topicos": ["fiscal"] }
  ],
  "total": 312,
  "pagina": 1,
  "por_pagina": 50,
  "paginas": 7
}

total é quantas tarefas casam com os filtros — não quantas vieram nesta resposta. Compare-o com o tamanho de tarefas: enquanto pagina for menor que paginas, ainda há o que buscar. Peça as seguintes com ?pagina=2, ?pagina=3 e assim por diante, e use os filtros (status, origem, topico, processo, tipo) para estreitar o resultado quando quiser menos idas e voltas.

Consultar uma tarefa

GET /api/v1/tasks/{id}

Retorna a tarefa com seus topicos, etiquetas e o historico de atividades.

Atualizar o status pelo id

PATCH /api/v1/tasks/{id}/status

{ "status": "em_andamento" }

Resposta:

{ "id": 87, "status": "em_andamento" }

Ao levar a tarefa para concluida, cancelada, resolvido ou nao_se_aplica, envie também motivo:

{ "status": "concluida", "motivo": "Divergência corrigida pelo setor fiscal." }

A mudança fica registrada no histórico da tarefa. Reenviar o mesmo status também exige o motivo, mesmo que a tarefa já esteja naquele estado — mantenha o campo no corpo de toda tentativa.

Continue por aqui

• Processos e tipos — como descobrir e cadastrar processo_id e tipo_id.
• Erros e respostas da API — o que significa cada recusa.