ComposioHQ/QuickBooks-Automation

Automação do QuickBooks

Automatize operações do QuickBooks Online, incluindo criação de faturas, gerenciamento de clientes, consulta de contas e listagem de faturas para relatórios financeiros.

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

---

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 quickbooks. Se nenhuma conexão estiver ativa, inicie uma via RUBE_MANAGE_CONNECTIONS.

---

Fluxos de Trabalho Principais

1. Criar uma Fatura

Crie uma nova fatura para um cliente com itens de linha.

Ferramenta: QUICKBOOKS_CREATE_INVOICE

Parâmetros-chave:

• customer_id (obrigatório) -- ID do cliente (CustomerRef.value)
• lines (obrigatório) -- Array de objetos de itens de linha. Cada um deve incluir:
  • DetailType -- ex., "SalesItemLineDetail"
  • Amount -- Total do item de linha
  • SalesItemLineDetail -- Objeto com ItemRef contendo value (ID do item)
• minorversion -- Parâmetro opcional de versão da API

Exemplo:

Ferramenta: QUICKBOOKS_CREATE_INVOICE
Argumentos:
  customer_id: "21"
  lines: [
    {
      "DetailType": "SalesItemLineDetail",
      "Amount": 150.00,
      "SalesItemLineDetail": {
        "ItemRef": {"value": "1", "name": "Serviços"}
      }
    }
  ]

Pré-requisitos: Resolva o ID do cliente usando QUICKBOOKS_READ_CUSTOMER ou crie um com QUICKBOOKS_CREATE_CUSTOMER. Resolva IDs de itens/contas usando QUICKBOOKS_QUERY_ACCOUNT.

---

2. Gerenciar Clientes

Crie e leia registros de clientes.

Ferramentas:

• QUICKBOOKS_CREATE_CUSTOMER -- Cria um novo cliente
• QUICKBOOKS_READ_CUSTOMER -- Lê um cliente por ID

Parâmetros-chave para QUICKBOOKS_CREATE_CUSTOMER:

• display_name -- Nome de exibição (deve ser único entre clientes, fornecedores e funcionários; máx. 500 caracteres)
• given_name -- Primeiro nome (máx. 100 caracteres)
• family_name -- Sobrenome (máx. 100 caracteres)
• middle_name -- Nome do meio (máx. 100 caracteres)
• title -- Título, ex., "Sr.", "Dr." (máx. 16 caracteres)
• suffix -- Sufixo do nome, ex., "Jr." (máx. 16 caracteres)

Pelo menos um dos campos display_name, title, given_name, middle_name, family_name ou suffix é obrigatório.

Parâmetros-chave para QUICKBOOKS_READ_CUSTOMER:

• customer_id (obrigatório) -- ID do cliente a ser lido

Exemplo:

Ferramenta: QUICKBOOKS_CREATE_CUSTOMER
Argumentos:
  display_name: "Acme Corporation"
  given_name: "João"
  family_name: "Silva"

---

3. Consultar e Ler Contas

Recupere informações de contas para uso em itens de linha de faturas e relatórios financeiros.

Ferramentas:

• QUICKBOOKS_QUERY_ACCOUNT -- Executa uma consulta em contas
• QUICKBOOKS_READ_ACCOUNT -- Lê uma conta específica por ID

Parâmetros-chave para QUICKBOOKS_QUERY_ACCOUNT:

• query (obrigatório) -- String de consulta estilo SQL, ex., "SELECT * FROM Account WHERE AccountType = 'Income'"

Exemplo:

Ferramenta: QUICKBOOKS_QUERY_ACCOUNT
Argumentos:
  query: "SELECT * FROM Account WHERE AccountType = 'Income' MAXRESULTS 10"

---

4. Listar e Filtrar Faturas

Recupere faturas com paginação e filtragem opcionais.

Ferramenta: QUICKBOOKS_LIST_INVOICES

Passos:

1. Chame QUICKBOOKS_LIST_INVOICES com parâmetros de paginação
2. Use start_position e max_results para percorrer os resultados
3. Filtre por critérios específicos conforme necessário

---

Plano de Execução Recomendado

1. Resolva o cliente usando QUICKBOOKS_READ_CUSTOMER (se tiver um ID de cliente) ou crie um com QUICKBOOKS_CREATE_CUSTOMER
2. Resolva contas de itens/receitas usando QUICKBOOKS_QUERY_ACCOUNT e QUICKBOOKS_READ_ACCOUNT para obter IDs de contas ou itens para os itens de linha da fatura
3. Crie a fatura usando QUICKBOOKS_CREATE_INVOICE com o customer_id resolvido e itens de linha bem formados
4. Verifique a criação usando QUICKBOOKS_LIST_INVOICES para localizar a nova fatura por ID ou DocNumber

---

Armadilhas Conhecidas

Armadilha	Detalhe
Referências inválidas	QUICKBOOKS_CREATE_INVOICE falha se customer_id ou ItemRef.value apontarem para registros inexistentes ou inativos. Sempre resolva os IDs primeiro.
Validação de itens de linha	DetailType incorreto ou campos SalesItemLineDetail ausentes causam erros de esquema/validação durante a criação da fatura.
Paginação	QUICKBOOKS_LIST_INVOICES usa start_position e max_results. Configurações de paginação incompletas podem perder faturas em livros maiores.
Tokens de sincronização	Qualquer edição posterior requer o SyncToken mais recente de uma leitura fresca da fatura. Tokens de sincronização desatualizados causam rejeições de atualização.
Limites de taxa	O QuickBooks impõe limites de API por minuto e diários. Execuções de alto volume devem incluir backoff para evitar erros de limitação.
Exclusividade do DisplayName	O display_name do cliente deve ser único entre todos os objetos Customer, Vendor e Employee. Duplicatas causam falhas na criação.

---

Referência Rápida

Slug da Ferramenta	Descrição
QUICKBOOKS_CREATE_INVOICE	Cria uma nova fatura com itens de linha
QUICKBOOKS_READ_CUSTOMER	Lê um registro de cliente por ID
QUICKBOOKS_CREATE_CUSTOMER	Cria um novo registro de cliente
QUICKBOOKS_QUERY_ACCOUNT	Consulta contas com sintaxe estilo SQL
QUICKBOOKS_READ_ACCOUNT	Lê uma conta específica por ID
QUICKBOOKS_LIST_INVOICES	Lista faturas com paginação

---

Desenvolvido por Composio