ComposioHQ/Zoho-Books-Automation

Automação do Zoho Books

Automatize fluxos de trabalho contábeis do Zoho Books – crie e gerencie faturas, acompanhe contas e pagamentos, consulte contatos, exporte PDFs e lide com configurações de múltiplas organizações – tudo por meio de linguagem natural.

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

---

Configuração

1. Adicione o servidor MCP Rube ao seu ambiente: https://rube.app/mcp
2. Conecte sua conta do Zoho Books quando solicitado (fluxo OAuth via Composio)
3. Comece a emitir comandos em linguagem natural para automação do Zoho Books

---

Fluxos de Trabalho Principais

1. Descobrir Organizações

Recupere todas as organizações do usuário autenticado. Isso é um pré-requisito, pois organization_id é exigido por quase todos os outros endpoints.

Ferramenta: ZOHO_BOOKS_LIST_ORGANIZATIONS

Nenhum parâmetro necessário. Retorna IDs, nomes e metadados das organizações.

Sempre chame esta ferramenta primeiro para obter o organization_id necessário para todas as outras ferramentas do Zoho Books.

Exemplo de prompt:

"Liste minhas organizações do Zoho Books"

---

2. Criar e Gerenciar Faturas

Crie faturas com itens, gerencie faturas existentes e exporte-as como PDFs.

Criar: ZOHO_BOOKS_CREATE_INVOICE

Parâmetros principais:

• organization_id – organização de destino (obrigatório)
• customer_id – cliente a ser faturado (obrigatório)
• line_items – array de itens (obrigatório), cada um com:
  • item_id ou name – referencie um item existente ou crie uma linha avulsa
  • quantity, rate – detalhes de quantidade e valor
  • description, tax_id, discount – detalhes opcionais
• date / due_date – datas no formato YYYY-MM-DD
• invoice_number – número personalizado (defina ignore_auto_number_generation=true)
• discount / discount_type – desconto no nível da fatura (entity_level ou item_level)
• notes / terms – impressos na fatura
• send – enviar a fatura por e-mail imediatamente após a criação
• payment_terms – número de dias para pagamento

Listar: ZOHO_BOOKS_LIST_INVOICES

Parâmetros principais:

• organization_id (obrigatório)
• status – sent, draft, overdue, paid, void, unpaid, partially_paid, viewed
• customer_id / customer_name – filtrar por cliente
• date_start / date_end – filtro de intervalo de datas (YYYY-MM-DD)
• search_text – pesquisar número da fatura, referência ou nome do cliente
• sort_column / sort_order – ordenar por date, due_date, total, balance, etc.
• page / per_page – paginação (máx. 200 por página)

Obter detalhes: ZOHO_BOOKS_GET_INVOICE – busca por invoice_id com formato accept: json, pdf ou html

Excluir: ZOHO_BOOKS_DELETE_INVOICE – remover por invoice_id

Exportação em lote: ZOHO_BOOKS_BULK_EXPORT_INVOICES_PDF – mesclar até 25 faturas em um único PDF

Impressão em lote: ZOHO_BOOKS_BULK_PRINT_INVOICES – gerar um PDF combinado pronta para impressão para até 25 faturas

Exemplo de prompt:

"Crie uma fatura para o cliente 1234567890 com 2 itens: 10 unidades do Widget A a US$ 25 cada e 5 unidades do Widget B a US$ 50 cada, vencimento em 30 dias"

---

3. Acompanhar e Gerenciar Contas

Liste, visualize e atualize contas de fornecedores com filtragem abrangente.

Listar: ZOHO_BOOKS_LIST_BILLS

Parâmetros principais:

• organization_id (obrigatório)
• status – paid, open, overdue, void, partially_paid
• vendor_id / vendor_name_contains – filtrar por fornecedor
• bill_number / bill_number_contains – filtrar por número da conta
• date_start / date_end – filtro de intervalo de datas
• total_greater_than / total_less_than – filtros de faixa de valor
• sort_column / sort_order – ordenar por vendor_name, bill_number, date, due_date, total, etc.
• page / per_page – paginação (máx. 200)

Obter detalhes: ZOHO_BOOKS_GET_BILL – busca completa da conta por bill_id e organization_id

Atualizar: ZOHO_BOOKS_UPDATE_BILL – modificar conta existente (requer bill_id, organization_id, vendor_id, bill_number)

Exemplo de prompt:

"Liste todas as contas vencidas da minha organização, ordenadas por data de vencimento"

---

4. Consultar Contatos

Pesquise e filtre contatos (clientes e fornecedores) para uso em faturas e contas.

Ferramenta: ZOHO_BOOKS_LIST_CONTACTS

Parâmetros principais:

• organization_id (obrigatório)
• contact_type – customer ou vendor
• contact_name_contains / contact_name_startswith – filtros de nome
• email_contains / email_startswith – filtros de e-mail
• company_name_contains – filtro de nome da empresa
• filter_by – filtro de status: Status.Active, Status.Inactive, Status.Duplicate, etc.
• search_text – pesquisar por nome do contato ou notas (máx. 100 caracteres)
• sort_column – ordenar por contact_name, email, outstanding_receivable_amount, created_time, etc.
• page / per_page – paginação (máx. 200)

Exemplo de prompt:

"Encontre todos os clientes ativos cujo nome da empresa contenha 'Acme'"

---

5. Acompanhar Pagamentos de Faturas

Liste todos os pagamentos registrados contra uma fatura específica.

Ferramenta: ZOHO_BOOKS_LIST_INVOICE_PAYMENTS

Parâmetros principais:

• invoice_id – a fatura a ser verificada (obrigatório)
• organization_id – a organização (obrigatório)

Retorna todas as transações de pagamento aplicadas à fatura, incluindo valores, datas e métodos de pagamento.

Exemplo de prompt:

"Mostre todos os pagamentos registrados contra a fatura 451025000000123045"

---

6. Fluxo Completo de Faturamento

Combine ferramentas para gerenciamento de faturas de ponta a ponta:

1. Organização: ZOHO_BOOKS_LIST_ORGANIZATIONS – obter organization_id
2. Contatos: ZOHO_BOOKS_LIST_CONTACTS – encontrar ou verificar customer_id
3. Criar: ZOHO_BOOKS_CREATE_INVOICE – criar fatura com itens
4. Revisar: ZOHO_BOOKS_GET_INVOICE – obter detalhes da fatura ou PDF
5. Acompanhar: ZOHO_BOOKS_LIST_INVOICE_PAYMENTS – monitorar status de pagamento
6. Exportar: ZOHO_BOOKS_BULK_EXPORT_INVOICES_PDF – exportação em lote para registros

Exemplo de prompt:

"Encontre o ID do cliente para 'Acme Corp', crie uma fatura para ele com serviços de consultoria e depois obtenha o PDF"

---

Armadilhas Conhecidas

Armadilha	Detalhes
Organization ID sempre obrigatório	Quase todo endpoint requer organization_id – sempre chame ZOHO_BOOKS_LIST_ORGANIZATIONS primeiro
Itens obrigatórios para faturas	ZOHO_BOOKS_CREATE_INVOICE requer pelo menos um item com item_id ou name
Formato do Invoice ID	Use o invoice_id numérico do objeto da fatura (ex.: 7472322000000264123), não o ID codificado do invoice_url
Limites de lote	Tanto ZOHO_BOOKS_BULK_EXPORT_INVOICES_PDF quanto ZOHO_BOOKS_BULK_PRINT_INVOICES aceitam no máximo 25 IDs de fatura
Paginação máxima de 200	Todos os endpoints de listagem limitam a 200 registros por página – iterar páginas para resultados completos
Atualização de conta requer todos os campos	ZOHO_BOOKS_UPDATE_BILL requer bill_id, organization_id, vendor_id e bill_number mesmo para atualizações parciais
Formato da data	Todos os parâmetros de data usam o formato YYYY-MM-DD
response_option não documentado	ZOHO_BOOKS_LIST_INVOICES tem um parâmetro response_option não documentado (0=completo, 1=completo+totais, 2=apenas contagens) que pode mudar sem aviso

---

Referência Rápida

Ação	Slug da Ferramenta	Parâmetros Principais
Listar organizações	ZOHO_BOOKS_LIST_ORGANIZATIONS	(nenhum)
Criar fatura	ZOHO_BOOKS_CREATE_INVOICE	organization_id, customer_id, line_items
Listar faturas	ZOHO_BOOKS_LIST_INVOICES	organization_id, status, date_start
Obter fatura	ZOHO_BOOKS_GET_INVOICE	invoice_id, organization_id, accept
Excluir fatura	ZOHO_BOOKS_DELETE_INVOICE	invoice_id, organization_id
Exportar PDF em lote	ZOHO_BOOKS_BULK_EXPORT_INVOICES_PDF	organization_id, invoice_ids
Imprimir em lote	ZOHO_BOOKS_BULK_PRINT_INVOICES	organization_id, invoice_ids
Listar contas	ZOHO_BOOKS_LIST_BILLS	organization_id, status, vendor_id
Obter conta	ZOHO_BOOKS_GET_BILL	bill_id, organization_id
Atualizar conta	ZOHO_BOOKS_UPDATE_BILL	bill_id, organization_id, vendor_id
Listar contatos	ZOHO_BOOKS_LIST_CONTACTS	organization_id, contact_type, search_text
Listar pagamentos	ZOHO_BOOKS_LIST_INVOICE_PAYMENTS	invoice_id, organization_id

---

Desenvolvido por Composio