Automação Harvest

Automação de Harvest

Automatize suas operações de registro de horas no Harvest diretamente do Claude Code. Registre entradas de tempo, gerencie projetos e clientes, crie tarefas e obtenha dados de relatórios — tudo sem sair do terminal.

Documentação do toolkit: composio.dev/toolkits/harvest

---

Configuração

1. Adicione o servidor MCP do Rube à configuração do seu Claude Code com a URL: https://rube.app/mcp
2. Quando solicitado, autentique sua conta do Harvest através do link de conexão fornecido
3. Comece a automatizar seus fluxos de trabalho de registro de horas com linguagem natural

---

Fluxos de Trabalho Principais

1. Registrar e Gerenciar Entradas de Tempo

Crie, liste, atualize e recupere entradas de tempo para faturamento e relatórios precisos.

Ferramentas: HARVEST_CREATE_TIME_ENTRY, HARVEST_LIST_TIME_ENTRIES, HARVEST_GET_TIME_ENTRY, HARVEST_UPDATE_TIME_ENTRY

Registre 3,5 horas de trabalho de desenvolvimento no projeto 12345, tarefa 67890 para hoje

Parâmetros-chave para HARVEST_CREATE_TIME_ENTRY:

• project_id (obrigatório) — o projeto para o qual registrar
• task_id (obrigatório) — a tarefa deve estar atribuída ao projeto
• spent_date (obrigatório) — data no formato AAAA-MM-DD
• hours — total de horas (para contas baseadas em duração)
• started_time / ended_time — para contas baseadas em timestamp
• notes — descrição do trabalho realizado

Parâmetros-chave para HARVEST_LIST_TIME_ENTRIES:

• from_date / to — filtros de intervalo de datas (AAAA-MM-DD)
• project_id, client_id, task_id, user_id — filtros de entidade
• is_billed / is_running — filtros de status
• page / per_page (máx. 2000) — paginação

2. Gerenciar Projetos

Crie novos projetos e liste os existentes com configuração de cliente e faturamento.

Ferramentas: HARVEST_CREATE_PROJECT, HARVEST_LIST_PROJECTS, HARVEST_GET_PROJECT

Crie um projeto faturável chamado "Redesign do Site" para o cliente 456 com faturamento por Tarefas e orçamento de projeto

Parâmetros-chave para HARVEST_CREATE_PROJECT:

• name, client_id, is_billable, bill_by, budget_by (todos obrigatórios)
• Opções de bill_by: "Project", "Tasks", "People", "none"
• Opções de budget_by: "project", "project_cost", "task", "task_fees", "person", "none"
• Opcionais: budget, hourly_rate, starts_on, ends_on, is_fixed_fee

3. Gerenciar Clientes

Crie e liste clientes sob os quais os projetos são organizados.

Ferramentas: HARVEST_CREATE_CLIENT, HARVEST_LIST_CLIENTS

Liste todos os clientes ativos na nossa conta do Harvest

• HARVEST_CREATE_CLIENT requer name; aceita address, currency, is_active
• HARVEST_LIST_CLIENTS suporta filtro is_active e paginação (per_page máx. 2000)

4. Gerenciar Tarefas

Crie e liste tipos de tarefas reutilizáveis para registro de horas.

Ferramentas: HARVEST_CREATE_TASK, HARVEST_LIST_TASKS

Crie uma nova tarefa faturável chamada "Revisão de Código" com uma taxa padrão de R$ 150/h

• HARVEST_CREATE_TASK requer name; aceita billable_by_default, default_hourly_rate, is_active, is_default
• HARVEST_LIST_TASKS suporta filtros is_active, is_default e paginação (per_page máx. 100)
• Os nomes das tarefas devem ser únicos entre todas as tarefas (ativas e arquivadas)

5. Relatórios de Entradas de Tempo

Obtenha entradas de tempo com intervalos de datas e filtros para resumos de faturamento e relatórios de utilização.

Ferramentas: HARVEST_LIST_TIME_ENTRIES, HARVEST_GET_TIME_ENTRY

Mostre-me todas as entradas de tempo não faturadas para o projeto 789 de janeiro de 2026

• Use from_date e to para janelas de datas
• Filtre com is_billed: false para entradas não faturadas
• Combine project_id, user_id, client_id para relatórios multidimensionais
• Pagine com page e per_page para coletar conjuntos completos de dados

6. Atualizar e Corrigir Entradas de Tempo

Modifique entradas de tempo existentes para corrigir horas, reatribuir projetos ou atualizar notas.

Ferramentas: HARVEST_UPDATE_TIME_ENTRY

Atualize a entrada de tempo 123456 para alterar as horas para 4,0 e adicionar a nota "Integração de API concluída"

• Requer time_entry_id
• Suporta atualizações parciais — inclua apenas os campos que deseja alterar
• Pode atualizar hours, notes, project_id, task_id, spent_date, started_time, ended_time

---

Armadilhas Conhecidas

• Atribuição de tarefas é importante: Ao criar entradas de tempo, o task_id deve corresponder a uma tarefa que está realmente atribuída ao project_id especificado. Use o endpoint de atribuições de tarefas do projeto para verificar, não apenas HARVEST_LIST_TASKS (que retorna tarefas globais).
• Rastreamento de duração vs. timestamp: As contas do Harvest são configuradas para rastreamento baseado em duração ou timestamp. hours é ignorado em contas de timestamp; started_time/ended_time são ignorados em contas de duração.
• Limites de paginação variam: HARVEST_LIST_TIME_ENTRIES e HARVEST_LIST_CLIENTS suportam até 2000 por página, mas HARVEST_LIST_PROJECTS e HARVEST_LIST_TASKS limitam a 100 por página.
• Consistência de formato de data: Todos os parâmetros de data devem usar o formato AAAA-MM-DD. ISO 8601 com fuso horário é usado para filtros updated_since.
• Campos obrigatórios para projetos: HARVEST_CREATE_PROJECT requer cinco campos: name, client_id, is_billable, bill_by e budget_by. A falta de qualquer um causará um erro de validação.

---

Referência Rápida

Slug da Ferramenta	Descrição
HARVEST_LIST_TIME_ENTRIES	Listar entradas de tempo com filtros de data, projeto, cliente, usuário
HARVEST_CREATE_TIME_ENTRY	Registrar uma nova entrada de tempo (requer project_id, task_id, spent_date)
HARVEST_GET_TIME_ENTRY	Recuperar uma entrada de tempo específica por ID
HARVEST_UPDATE_TIME_ENTRY	Atualizar uma entrada de tempo existente (requer time_entry_id)
HARVEST_LIST_PROJECTS	Listar projetos com filtro opcional de cliente
HARVEST_CREATE_PROJECT	Criar um novo projeto com configuração de faturamento
HARVEST_GET_PROJECT	Recuperar um projeto específico por ID
HARVEST_LIST_CLIENTS	Listar clientes com filtro ativo/inativo
HARVEST_CREATE_CLIENT	Criar um novo cliente (requer name)
HARVEST_LIST_TASKS	Listar tipos de tarefas reutilizáveis
HARVEST_CREATE_TASK	Criar um novo tipo de tarefa (requer name)

---

Desenvolvido por Composio