API de Projetos

Visão geral

• Autenticação por chave de API ligada ao utilizador (ACL/RBAC dinâmicos).
• Escopos read e write.
• Criar projetos (opcionalmente a partir de um modelo) e editar modelos de projeto: colunas, automações, sprints e cards padrão.
• GET único de andamento: sprint ativa + backlog + demandas + cards/comentários.
• Membros do projeto e etiquetas para atribuir responsáveis e labels nos cards.
• Checklists em cards (criar lista + itens, marcar concluído).
• Ciclo de sprints (criar/ativar/encerrar), planejamento (Gantt/estimativa), automações Kanban e documentos (sync GED).
• CRUD de cards e conversão de demandas; lotes com dry_run.
• Escritas de cards geram snapshot (5 dias); preferir cards/bulk para várias mudanças.

Autenticação

Crie a chave em Projetos → API (requer login). Envie:

Authorization: Bearer erp_proj_…

Nunca cole a chave no prompt da LLM nem nos ficheiros da skill. Use variáveis de ambiente.

Fluxo recomendado

1. Listar projetos com GET /api/v1/projects/.
2. Escolher o projeto e chamar board-state.
3. Antes de atribuir cards: GET …/members/ e GET …/labels/.
4. Checklists: POST …/cards/{id}/checklists/ (com items opcional).
5. Um pedido explícito do utilizador autoriza o POST/PATCH correspondente; confirmar antes de DELETE, restore ou alterações destrutivas/ambíguas.
6. Se necessário, listar snapshots e restaurar dentro de 5 dias.

Endpoints

Especificação máquina: https://taskfy.tec.br/api/v1/projects/openapi.json (OpenAPI 1.7.0)

Criar projeto

POST /api/v1/projects/ com name (obrigatório) e opcionalmente workspace_id (cliente), template_id, gestor_id, project_manager_id, description, status, start_date e end_date. Sem cliente o projeto fica interno. Gestor e PM assumem o dono da chave quando omitidos. Com modelo, o quadro recebe colunas, automações, sprints e cards padrão. Exige escopo write, permissão projects.manage e respeita módulo e limite de projetos do plano.

{
  "name": "Site institucional",
  "workspace_id": "uuid-do-cliente",
  "template_id": "uuid-de-GET-templates"
}

Modelos de projeto

GET …/templates/ lista os modelos ativos disponíveis para criar projeto (filtre por cliente com ?workspace_id=); ?editable=1 lista os editáveis, inclusive inativos. Cada item traz can_edit. GET …/templates/{tid}/ devolve colunas (com automações), sprints e cards padrão. Edição: PATCH dos dados do modelo (escopo e workspace só pela tela), CRUD de colunas, sprints e cards padrão, reordenação por lista completa de ids e PUT …/columns/{cid}/automations/ substituindo as automações da coluna. Escrita exige escopo write e papel owner/admin de workspace admin, a mesma regra de Configurações → Modelos. Alterações valem para projetos criados depois; projetos existentes não mudam.

board-state, colunas e demandas

board-state devolve projeto, sprint ativa, backlog e demandas. Use GET …/columns/ para listar todas as colunas (incluindo vazias). Em projetos existentes também dá para gerir colunas: POST …/columns/ (name, color opcional; entra no fim), PATCH …/columns/{cid}/ (nome e/ou cor), POST …/columns/reorder/ (column_ids com todas as colunas) e DELETE …/columns/{cid}/ (cards vão para a primeira coluna restante, com snapshot; o quadro mantém ao menos uma coluna). Exige escopo write, admin do projeto e role kanban.manage. Para mudar projetos futuros, edite o modelo. Converta demandas com POST …/demands/{id}/convert/ (idempotente).

Membros e etiquetas

GET …/members/ lista membros: use user.id em assignee_ids no PATCH do card. GET …/labels/ lista etiquetas: use id em label_ids. Lista vazia remove todos os responsáveis ou etiquetas.

Checklists

POST …/cards/{id}/checklists/ com title e opcionalmente items. Itens: …/checklists/{clid}/items/; marcar feito com {"is_done": true}. O GET do card inclui checklists.

Sprints e planejamento

POST …/sprints/ cria sprint (name, start_date, duração opcional). activate / close seguem a política do projeto (one_at_a_time, planned_sequence, automatic_sequence). GET …/planning/ devolve Gantt e estimativa de sprints: não atribui cards automaticamente.

Automações

Listar regras e presets com GET …/automations/. Criar com column_id + preset_slug (+ params). Escrita exige admin do projeto e role kanban.manage.

Documentos

CRUD de documentação Markdown do projeto. O detalhe inclui content_markdown. Escrita sincroniza o GED e exige projects.documentation. DELETE envia para a lixeira.

PATCH e lote

PATCH aceita subset de: title, description, priority, due_date, start_date, is_archived, is_blocked, card_type, sprint_id, column_id, order, assignee_ids, label_ids. Coluna “Concluído/Done” preenche completed_at; sair de “Bloqueio” limpa is_blocked.

{
  "dry_run": true,
  "operations": [
    {"action": "move_card", "card_id": "uuid", "column_id": "uuid"}
  ]
}

Com dry_run: false, valida tudo e aplica com um snapshot.

Snapshots

Escritas de cards (e lotes aplicados) gravam o estado anterior (sprint ativa + backlog). TTL 5 dias. Há também GET …/snapshots/{id}/ e …/diff/.

Códigos de erro

• 401: chave ausente ou inválida
• 403: pagamento pendente, escopo write em falta ou sem ACL no projeto
• 404: recurso inexistente
• 429: rate limit / bloqueio temporário

LLM e Agent Skills

Uma LLM precisa de ferramenta HTTP ou terminal. Oferecemos dois pacotes (sem chave embutida):

Exemplos

export TASKFY_BASE_URL="https://taskfy.tec.br"
export TASKFY_PROJECTS_API_KEY="erp_proj_…"

curl -s -H "Authorization: Bearer $TASKFY_PROJECTS_API_KEY" \
  "$TASKFY_BASE_URL/api/v1/projects/"

python scripts/taskfy_projects_api.py projects
python scripts/taskfy_projects_api.py board-state <project_id>
python scripts/taskfy_projects_api.py sprints <project_id>
python scripts/taskfy_projects_api.py planning <project_id>
python scripts/taskfy_projects_api.py documents <project_id>