ComposioHQ/Automação-FreshBooks

Automação FreshBooks

Automatize operações do FreshBooks, incluindo listar empresas, gerenciar projetos, controlar horas e monitorar orçamentos para contabilidade de pequenas e médias empresas.

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

---

Configuração

Esta skill requer o servidor Rube MCP conectado em https://rube.app/mcp.

Antes de executar qualquer ferramenta, certifique-se de que existe uma conexão ativa para o toolkit freshbooks. Se nenhuma conexão estiver ativa, inicie uma via RUBE_MANAGE_CONNECTIONS.

---

Fluxos de Trabalho Principais

1. Listar Empresas

Recupere todas as empresas associadas ao usuário autenticado. O business_id desta resposta é necessário para a maioria das outras chamadas da API do FreshBooks.

Ferramenta: FRESHBOOKS_LIST_BUSINESSES

Parâmetros: Nenhum necessário.

Exemplo:

Tool: FRESHBOOKS_LIST_BUSINESSES
Arguments: {}

Saída: Retorna informações de associação empresarial, incluindo todas as empresas às quais o usuário tem acesso, juntamente com sua função em cada empresa.

Importante: Sempre chame esta ferramenta primeiro para obter um business_id válido antes de realizar operações específicas de projeto.

---

2. Listar e Filtrar Projetos

Recupere todos os projetos de uma empresa com opções abrangentes de filtragem e ordenação.

Ferramenta: FRESHBOOKS_LIST_PROJECTS

Parâmetros Principais:

• business_id (obrigatório) -- ID da empresa obtido em FRESHBOOKS_LIST_BUSINESSES
• active -- Filtrar por status ativo: true (apenas ativos), false (apenas inativos), omitir para todos
• complete -- Filtrar por conclusão: true (concluídos), false (incompletos), omitir para todos
• sort_by -- Ordem de classificação: "created_at", "due_date" ou "title"
• updated_since -- Data/hora UTC no formato RFC3339, ex.: "2026-01-01T00:00:00Z"
• include_logged_duration -- true para incluir o tempo total registrado (em segundos) por projeto
• skip_group -- true para omitir dados de membros da equipe/convites (reduz o tamanho da resposta)

Exemplo:

Tool: FRESHBOOKS_LIST_PROJECTS
Arguments:
  business_id: 123456
  active: true
  complete: false
  sort_by: "due_date"
  include_logged_duration: true

Casos de Uso:

• Obter todos os projetos para controle de horas ou faturamento
• Encontrar projetos por cliente, status ou intervalo de datas
• Monitorar a conclusão do projeto e o acompanhamento do orçamento
• Recuperar atribuições de equipe e grupos de projetos

---

3. Monitorar Projetos Ativos

Acompanhe o progresso do projeto e os orçamentos filtrando por projetos ativos e incompletos.

Passos:

1. Chame FRESHBOOKS_LIST_BUSINESSES para obter o business_id
2. Chame FRESHBOOKS_LIST_PROJECTS com active: true, complete: false, include_logged_duration: true
3. Analise a duração registrada versus o orçamento de cada projeto

---

4. Revisar Projetos Atualizados Recentemente

Verifique a atividade recente do projeto usando o filtro updated_since.

Passos:

1. Chame FRESHBOOKS_LIST_BUSINESSES para obter o business_id
2. Chame FRESHBOOKS_LIST_PROJECTS com updated_since definido para a data/hora de corte
3. Revise os projetos retornados para alterações recentes

Exemplo:

Tool: FRESHBOOKS_LIST_PROJECTS
Arguments:
  business_id: 123456
  updated_since: "2026-02-01T00:00:00Z"
  sort_by: "created_at"

---

Plano de Execução Recomendado

1. Obter o ID da empresa chamando FRESHBOOKS_LIST_BUSINESSES
2. Listar projetos usando FRESHBOOKS_LIST_PROJECTS com o business_id obtido
3. Filtrar conforme necessário usando os parâmetros active, complete, updated_since e sort_by

---

Armadilhas Conhecidas

Armadilha	Detalhe
business_id obrigatório	A maioria das operações do FreshBooks exige um business_id. Sempre chame FRESHBOOKS_LIST_BUSINESSES primeiro para obtê-lo.
Formato de data	O parâmetro updated_since deve estar no formato RFC3339: "2026-01-01T00:00:00Z". Outros formatos falharão.
Resultados paginados	As respostas da lista de projetos são paginadas. Verifique se há páginas adicionais na resposta.
Resultados vazios	Retorna uma lista vazia se nenhum projeto existir ou corresponder aos filtros aplicados. Isso não é um erro.
Unidades de duração registrada	Quando include_logged_duration é true, a duração é retornada em segundos. Converta para horas (divida por 3600) para exibição.

---

Referência Rápida

Slug da Ferramenta	Descrição
FRESHBOOKS_LIST_BUSINESSES	Listar todas as empresas para o usuário autenticado
FRESHBOOKS_LIST_PROJECTS	Listar projetos com filtragem e ordenação para uma empresa

---

Desenvolvido por Composio