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.

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"]
}

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.

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.

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 (trecho do título), processo e tipo (os identificadores que vêm em GET /api/v1/processos).

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

A consulta devolve as 50 tarefas mais recentes que casam com os filtros, e total é a quantidade devolvida nessa resposta. Para acompanhar um volume maior, use os filtros (status, origem, topico, processo, tipo) para estreitar o resultado.

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.

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.