ComposioHQ/Xero-Automation

Automação Xero

Automatize operações contábeis no Xero, incluindo gerenciamento de faturas, contatos, pagamentos, transações bancárias e plano de contas para escrituração contábil de pequenas empresas.

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

---

Configuração

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

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

Multilocatário: Se você gerencia várias organizações Xero, primeiro chame XERO_GET_CONNECTIONS para listar os tenants ativos e obter o tenant_id correto para chamadas subsequentes.

---

Fluxos de Trabalho Principais

1. Listar e Filtrar Faturas

Recupere faturas com filtragem por status, contato, intervalo de datas e paginação.

Ferramenta: XERO_LIST_INVOICES

Parâmetros Principais:

• Statuses -- Filtro de status separado por vírgulas: "DRAFT", "SUBMITTED", "AUTHORISED", "PAID"
• ContactIDs -- IDs de Contato separados por vírgulas para filtrar
• InvoiceIDs -- IDs de Fatura separados por vírgulas para filtrar
• where -- Filtro no estilo OData, ex.: "Status==\"AUTHORISED\" AND Total>100"
• order -- Expressão de ordenação, ex.: "Date DESC", "InvoiceNumber ASC"
• page -- Número da página para paginação
• If-Modified-Since -- Timestamp UTC; retorna apenas faturas modificadas desde esta data
• tenant_id -- ID da organização Xero (usa o primeiro tenant se omitido)

Exemplo:

Tool: XERO_LIST_INVOICES
Arguments:
  Statuses: "AUTHORISED,PAID"
  order: "Date DESC"
  page: 1

---

2. Gerenciar Contatos

Recupere e pesquise contatos para uso em faturas e transações.

Ferramenta: XERO_GET_CONTACTS

Parâmetros Principais:

• searchTerm -- Pesquisa sem diferenciação de maiúsculas/minúsculas em Nome, PrimeiroNome, ÚltimoNome, Email, NúmeroContato
• ContactID -- Busca um único contato por ID
• where -- Filtro OData, ex.: "ContactStatus==\"ACTIVE\""
• page, pageSize -- Controles de paginação
• order -- Ordenação, ex.: "UpdatedDateUTC DESC"
• includeArchived -- Inclui contatos arquivados quando true
• summaryOnly -- Resposta leve quando true

Exemplo:

Tool: XERO_GET_CONTACTS
Arguments:
  searchTerm: "acme"
  page: 1
  pageSize: 25

Nota: Em contas de alto volume, alguns filtros where (ex.: IsCustomer, IsSupplier) podem ser rejeitados pelo Xero. Recorra a searchTerm ou paginação.

---

3. Criar Pagamentos

Vincule uma fatura a uma conta bancária criando um registro de pagamento.

Ferramenta: XERO_CREATE_PAYMENT

Parâmetros Principais:

• InvoiceID (obrigatório) -- ID da Fatura Xero à qual o pagamento se aplica
• AccountID (obrigatório) -- ID da conta bancária para o pagamento
• Amount (obrigatório) -- Valor do pagamento (número)
• Date -- Data do pagamento no formato YYYY-MM-DD
• Reference -- Referência ou descrição do pagamento
• CurrencyRate -- Taxa de câmbio para pagamentos em moeda estrangeira

Exemplo:

Tool: XERO_CREATE_PAYMENT
Arguments:
  InvoiceID: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  AccountID: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  Amount: 1500.00
  Date: "2026-02-11"
  Reference: "Pagamento para INV-0042"

---

4. Criar Transações Bancárias

Registre transações bancárias de despesa (pagamento de saída) ou recebimento (dinheiro de entrada).

Ferramenta: XERO_CREATE_BANK_TRANSACTION

Parâmetros Principais:

• Type (obrigatório) -- "SPEND" (pagamento de saída) ou "RECEIVE" (dinheiro de entrada)
• ContactID (obrigatório) -- ID do Contato Xero
• BankAccountCode (obrigatório) -- Código da conta bancária do plano de contas
• LineItems (obrigatório) -- Array de itens de linha, cada um com:
  • Description (obrigatório) -- Descrição do item
  • UnitAmount (obrigatório) -- Preço unitário
  • AccountCode (obrigatório) -- Código da conta para categorização
  • Quantity -- Quantidade (padrão 1)
  • TaxType -- Tipo de imposto: "OUTPUT", "INPUT", "NONE"
• Date -- Data da transação no formato YYYY-MM-DD
• Reference -- Referência da transação
• Status -- "AUTHORISED" ou "DELETED"
• CurrencyCode -- ex.: "USD", "EUR"

Exemplo:

Tool: XERO_CREATE_BANK_TRANSACTION
Arguments:
  Type: "SPEND"
  ContactID: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  BankAccountCode: "090"
  LineItems: [
    {
      "Description": "Material de escritório",
      "UnitAmount": 75.00,
      "AccountCode": "429",
      "Quantity": 1,
      "TaxType": "INPUT"
    }
  ]
  Date: "2026-02-11"
  Reference: "Material de escritório fevereiro"

---

5. Listar Pagamentos e Transações Bancárias

Revise pagamentos existentes e histórico de transações bancárias.

Ferramentas:

• XERO_LIST_PAYMENTS -- Lista pagamentos vinculando faturas a transações bancárias
• XERO_LIST_BANK_TRANSACTIONS -- Lista transações bancárias de despesa/recebimento

Parâmetros Comuns:

• where -- Filtro OData, ex.: "Status==\"AUTHORISED\""
• order -- Expressão de ordenação, ex.: "Date DESC"
• page -- Número da página para paginação
• If-Modified-Since -- Atualizações incrementais desde o timestamp
• tenant_id -- ID da organização

---

6. Visualizar Plano de Contas e Conexões

Ferramentas:

• XERO_LIST_ACCOUNTS -- Recupera todos os códigos de conta para categorizar transações
• XERO_GET_CONNECTIONS -- Lista conexões de tenant Xero ativas
• XERO_LIST_ATTACHMENTS -- Lista anexos em uma entidade (fatura, contato, etc.)

---

Armadilhas Conhecidas

Armadilha	Detalhe
Roteamento multilocatário	Se tenant_id for omitido, o primeiro tenant conectado é usado. Sempre verifique o tenant correto com XERO_GET_CONNECTIONS ao gerenciar várias organizações.
Rejeição de filtro em alto volume	Em contas grandes, alguns filtros where como IsCustomer/IsSupplier podem ser rejeitados. Recorra a searchTerm com paginação.
Sintaxe de filtro OData	Use dois iguais (==) em filtros OData, ex.: Status==\"AUTHORISED\". = simples causa erros.
Paginação necessária	A maioria dos endpoints de listagem paginam resultados. Sempre verifique se há páginas adicionais e continue buscando até completar.
Formato de data	Todas as datas devem estar no formato YYYY-MM-DD. Timestamps para If-Modified-Since devem ser datetime UTC ISO 8601 completo.
Códigos de contas bancárias	BankAccountCode em transações bancárias deve corresponder a um código válido do plano de contas. Use XERO_LIST_ACCOUNTS para descobrir códigos válidos.

---

Referência Rápida

Slug da Ferramenta	Descrição
XERO_LIST_INVOICES	Lista faturas com filtragem e paginação
XERO_GET_CONTACTS	Recupera e pesquisa contatos
XERO_CREATE_PAYMENT	Cria um pagamento vinculando fatura a conta bancária
XERO_CREATE_BANK_TRANSACTION	Registra uma transação bancária de despesa ou recebimento
XERO_LIST_PAYMENTS	Lista registros de pagamentos
XERO_LIST_BANK_TRANSACTIONS	Lista transações bancárias
XERO_LIST_ACCOUNTS	Recupera o plano de contas
XERO_GET_CONNECTIONS	Lista conexões de tenant Xero ativas
XERO_LIST_ATTACHMENTS	Lista anexos em uma entidade

---

Desenvolvido por Composio