Tarefas

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

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

Campo	Obrigatório	Descrição
`titulo`	sim	Título da tarefa.
`origem`	sim	Identificador do sistema/processo de origem (ex.: `faturamento`).
`referencia_externa`	não	Referência única no sistema de origem (chave de idempotência).
`descricao`	não	Texto descritivo.
`status`	não	Status inicial (padrão `aberta`).
`prioridade`	não	`baixa`, `media`, `alta` ou `urgente` (padrão `media`).
`prazo`	não	Data/hora limite.
`url_origem`	não	Link para o registro de origem (atalho exibido na tarefa).
`responsavel`	não	Login RM do responsável.
`topicos`	não	Lista de tópicos (slugs) que roteiam a tarefa. Tópicos novos são criados.
`etiquetas`	não	Lista de etiquetas livres.
`parametros`	não	Objeto JSON livre com dados próprios do sistema de origem (ver abaixo).

Exemplo

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

{
  "titulo": "Revisar nota fiscal 12345",
  "origem": "faturamento",
  "referencia_externa": "NF-12345",
  "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,
  "topicos": ["fiscal"]
}

Uma tarefa sem topicos fica visível a todas as equipes. Para direcioná-la, envie os tópicos correspondentes (veja Tópicos e visibilidade).

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".

Campo	Obrigatório	Descrição
`origem`	sim	Mesma `origem` usada na criação.
`referencia_externa`	sim	A referência única da tarefa.
`status`	não	Novo status (use `concluida` para finalizar).
`titulo`, `descricao`, `prioridade`, `prazo`, `url_origem`, `responsavel`, `topicos`, `etiquetas`, `parametros`	não	Atualizados quando enviados.

Exemplo — finalizar

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

{ "origem": "faturamento", "referencia_externa": "NF-12345", "status": "concluida" }

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), origem, busca (no título).

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

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

A mudança fica registrada no histórico da tarefa.