Faturas

Código Aberto — O GitScrum MCP Server é código aberto sob a licença MIT. Disponível no npm e no GitHub. Servidor Model Context Protocol para GitScrum — Claude, GitHub Copilot, Cursor e qualquer cliente compatível com MCP têm acesso operacional completo à sua stack de gerenciamento de projetos.

A ferramenta invoice fornece 8 ações cobrindo o ciclo completo de faturamento — desde a criação de faturas em rascunho até o envio, acompanhamento de pagamento e tratamento de cancelamentos. Toda operação de faturamento disponível no aplicativo web GitScrum é acessível através de conversa em linguagem natural com seu assistente de IA.

Faturas no GitScrum seguem um ciclo de vida de status rigoroso. Cada fatura progride por estados definidos, e o MCP Server aplica essas transições automaticamente. Seu assistente de IA pode criar faturas detalhadas, enviá-las a clientes, registrar pagamentos e gerar análises de faturamento — tudo sem sair da sua IDE ou cliente de IA.

Visão Geral das Ações

Ciclo de Vida de Status

Toda fatura segue uma progressão de status definida. O MCP Server aplica transições válidas — você não pode marcar uma fatura em rascunho como paga sem enviá-la primeiro, e faturas canceladas não podem ser reabertas.

  ┌──────────┐     send      ┌──────────┐   mark_paid    ┌──────┐
  │ Rascunho │ ─────────────► │ Enviada  │ ──────────────► │ Paga │
  └──────────┘                └──────────┘                 └──────┘
      │                           │
      │       cancel              │        (auto)
      │◄──────────────────        │──────────────────►  ┌──────────┐
      │                           │    past due_date    │ Atrasada │
      ▼                           ▼                     └──────────┘
  ┌───────────┐             ┌───────────┐                    │
  │ Cancelada │             │ Cancelada │                    │ cancel
  └───────────┘             └───────────┘                    ▼
                                                       ┌───────────┐
                                                       │ Cancelada │
                                                       └───────────┘

• Rascunho — Estado inicial. Editável. Pode ser enviada ou cancelada.
• Enviada — Entregue ao cliente. Transiciona para paga, atrasada ou cancelada.
• Paga — Pagamento registrado. Estado terminal.
• Atrasada — Definida automaticamente quando uma fatura enviada ultrapassa a data de vencimento.
• Cancelada — Encerrada. Estado terminal.

Listando Faturas

A ação list retorna faturas dentro de um workspace. Filtre por status ou cliente para restringir resultados.

Parâmetros Obrigatórios

Parâmetros Opcionais

Exemplos de Prompts

You:  "Mostre todas as faturas"
AI:   Chama invoice action=list → retorna lista de faturas com status e valores

You:  "Liste faturas não pagas"
AI:   Chama invoice action=list com status="sent"

You:  "Mostre faturas atrasadas"
AI:   Chama invoice action=list com status="overdue"

You:  "Liste todas as faturas da Acme Corp"
AI:   Encontra UUID do cliente → chama invoice action=list com client_uuid

Obtendo Detalhes da Fatura

A ação get retorna a fatura completa — título, cliente, itens de linha, valores, impostos, datas, status e histórico de pagamento.

Parâmetros Obrigatórios

You:  "Mostre os detalhes da fatura do projeto de site da Acme Corp"
AI:   Encontra a fatura → chama invoice action=get → retorna fatura completa com itens de linha

You:  "Qual é o total da nossa última fatura?"
AI:   Lista faturas recentes → chama invoice action=get → extrai o valor total

Criando Faturas

A ação create constrói uma nova fatura em rascunho. Você pode incluir itens de linha, alíquotas de impostos, associação com cliente e moeda em uma única chamada. A fatura começa no status Rascunho, permitindo revisão e edições antes do envio.

Parâmetros Obrigatórios

Parâmetros Opcionais

Estrutura dos Itens de Linha

Cada item no array items segue esta estrutura:

Exemplos de Prompts

You:  "Crie uma fatura para a Acme Corp: Redesign do Site, $5.000, vencimento 15 de março"
AI:   Encontra UUID do cliente → chama invoice action=create com title="Website Redesign",
      client_uuid, items=[{description: "Website Redesign", quantity: 1, unit_price: 5000}],
      due_date="2026-03-15"

You:  "Fature a TechStart por 40 horas de desenvolvimento a $150/hora mais 10% de imposto"
AI:   Chama invoice action=create com title, client_uuid,
      items=[{description: "Development Services", quantity: 40, unit_price: 150}],
      tax_rate=10

You:  "Crie uma fatura com três itens de linha:
       - UX Design: 20 horas a $120
       - Desenvolvimento Frontend: 60 horas a $150
       - Testes QA: 15 horas a $100"
AI:   Chama invoice action=create com array de items contendo as três entradas

Atualizando Faturas

A ação update modifica uma fatura em rascunho. Apenas faturas no status Rascunho podem ser atualizadas — uma vez enviadas, a fatura é bloqueada.

Parâmetros Obrigatórios

Todos os parâmetros opcionais de create estão disponíveis em update.

You:  "Adicione 10% de imposto na fatura da Acme Corp"
AI:   Chama invoice action=update com tax_rate=10

You:  "Mude a data de vencimento para 1 de abril"
AI:   Chama invoice action=update com due_date="2026-04-01"

You:  "Atualize as notas da fatura: 'Prazo de pagamento: 30 dias'"
AI:   Chama invoice action=update com notes="Prazo de pagamento: 30 dias"

Enviando Faturas

A ação send transiciona uma fatura de Rascunho para Enviada. Isso entrega a fatura ao cliente e bloqueia edições. A mudança de status é registrada com um timestamp.

Parâmetros Obrigatórios

You:  "Envie a fatura da Acme Corp"
AI:   Chama invoice action=send → fatura transiciona de Rascunho para Enviada

You:  "Envie todas as faturas em rascunho"
AI:   Lista faturas em rascunho → chama invoice action=send para cada uma

Registrando Pagamento

A ação mark_paid registra o pagamento de uma fatura enviada ou atrasada. Você pode opcionalmente especificar a data de pagamento e o método para registros contábeis.

Parâmetros Obrigatórios

Parâmetros Opcionais

You:  "Marque a fatura da Acme Corp como paga"
AI:   Chama invoice action=mark_paid → fatura transiciona para Paga

You:  "Registre pagamento da fatura, recebido ontem via transferência bancária"
AI:   Chama invoice action=mark_paid com payment_date="2026-02-05",
      payment_method="Transferência bancária"

You:  "Marque todas as faturas atrasadas da TechStart como pagas"
AI:   Lista faturas atrasadas do cliente → chama mark_paid para cada uma

Cancelando Faturas

A ação cancel encerra uma fatura. Funciona em faturas com status Rascunho, Enviada ou Atrasada. Você pode opcionalmente fornecer um motivo para o cancelamento.

Parâmetros Obrigatórios

Parâmetros Opcionais

You:  "Cancele a fatura em rascunho da Global Media"
AI:   Chama invoice action=cancel → fatura transiciona para Cancelada

You:  "Cancele a fatura com motivo: 'Escopo do projeto mudou, nova fatura a seguir'"
AI:   Chama invoice action=cancel com reason

Estatísticas de Faturamento

A ação stats retorna métricas de faturamento no nível do workspace — total faturado, pago vs pendente, totais atrasados, tempo médio de pagamento e tendências de receita. Esses números alimentam o dashboard de faturamento no aplicativo web GitScrum.

Parâmetros Obrigatórios

You:  "Mostre as estatísticas de faturamento"
AI:   Chama invoice action=stats → retorna total faturado, pago, pendente, atrasado

You:  "Quanto de receita está pendente?"
AI:   Chama invoice action=stats → extrai total de faturas pendentes

You:  "Qual é nosso tempo médio de pagamento?"
AI:   Chama invoice action=stats → retorna média de dias para pagamento

Fluxo de Trabalho de Faturamento

Para agências gerenciando múltiplos engajamentos com clientes, este fluxo cobre o ciclo completo de faturamento:

1. Crie a fatura

Construa uma fatura detalhada vinculada a um cliente.

You:  "Crie uma fatura para a Acme Corp: Entrega da Fase 1 — 80 horas frontend a $150,
       20 horas design a $120, 10% de imposto, vencimento 30 de março"
AI:   Uma única chamada de create com todos os itens de linha, imposto e data de vencimento

2. Revise e ajuste

Confira o rascunho antes de enviar.

You:  "Mostre a fatura da Acme Corp"
AI:   Chama invoice action=get → exibe fatura completa para revisão

You:  "Adicione uma nota: 'Pagamento via transferência bancária para conta final 4521'"
AI:   Chama invoice action=update com notes

3. Envie ao cliente

Entregue a fatura.

You:  "Envie a fatura da Acme Corp"
AI:   Chama invoice action=send → fatura é entregue e bloqueada

4. Acompanhe o pagamento

Monitore o pagamento e registre quando recebido.

You:  "Tem alguma fatura atrasada?"
AI:   Chama invoice action=list com status="overdue" → mostra itens atrasados

You:  "A Acme Corp pagou a fatura via transferência bancária"
AI:   Chama invoice action=mark_paid com payment_method="Transferência bancária"

5. Revise a saúde do faturamento

Monitore o desempenho geral de faturamento.

You:  "Mostre a visão geral de faturamento"
AI:   Chama invoice action=stats → resume receita, pendentes e tendências de pagamento

Próximos Passos

• Clientes: Gerencie registros de clientes vinculados às suas faturas.
• Propostas: Crie propostas que se convertem em projetos faturados.
• Dashboards ClientFlow: Acesse análises de faturamento e relatórios entre workspaces.
• Projetos: Gerencie entregas de projetos junto com o faturamento.