# Migrar do QuickBooks para o Beancount: um guia de transição

Escolha uma data de transição, exporte o balancete do QuickBooks do dia anterior a ela e abra seu razão Beancount com um `pad` e um `balance` por conta do balanço patrimonial. Quando `bea check` passar e o saldo do patrimônio líquido corresponder ao do QuickBooks, seus livros foram migrados. Tudo após a transição é registrado no Beancount.

Este guia funciona para o QuickBooks Online e o QuickBooks Desktop. Ele não depende de um importador do QuickBooks, porque nenhum acompanha o Beancount. Você move primeiro os saldos, depois decide quanto histórico trazer junto.

Se você ainda está decidindo se deve trocar, leia primeiro [Beancount vs QuickBooks](/compare/beancount-vs-quickbooks).

## 1. Decida a data de transição e o que manter

Escolha o primeiro dia de um ano fiscal, como `2026-01-01`. Um limite de ano mantém um ano fiscal em um só sistema. Também significa que sua primeira demonstração de resultado no Beancount começa do zero.

Decida agora quanto histórico o Beancount deve conter:

- **Apenas saldos.** Abra na data de transição e mantenha os relatórios do QuickBooks como seu arquivo para os anos anteriores. Este é o caminho mais rápido, e o restante deste guia assume isso.
- **Resumos anuais.** Adicione um lançamento de resumo por ano passado, a partir do balancete de cada ano. Seus relatórios plurianuais então funcionarão no Beancount.
- **Histórico completo de transações.** Converta a exportação do Livro Razão (General Ledger) com um script. Este é o trabalho mais extenso, e a seção 5 explica o que isso envolve.

Termine de reconciliar cada conta bancária e de cartão no QuickBooks até o dia anterior à transição. Um saldo não reconciliado transfere seu erro para o seu novo razão.

## 2. Exporte do QuickBooks

Você precisa de três relatórios, todos terminando no dia anterior à transição (`2025-12-31` neste guia):

| Relatório | O que ele fornece |
| --- | --- |
| Lista de Contas | Cada nome e tipo de conta, para o mapeamento do passo 3 |
| Balancete | O saldo final de cada conta, que se torna seus saldos iniciais |
| Livro Razão | Cada transação, para o histórico e para o seu arquivo |

**QuickBooks Online.** Vá em **Relatórios**, depois **Relatórios padrão**, e abra cada relatório pelo nome. Selecione **Exportar/Imprimir**, depois **Exportar para Excel**. A Lista de Contas é o relatório do plano de contas. A ferramenta **Exportar dados** em **Configurações**, na coluna **Ferramentas**, exporta um conjunto de relatórios e listas como arquivos Excel em um único arquivo zip. A Intuit documenta ambos os caminhos em [Export your QuickBooks Online data](https://quickbooks.intuit.com/learn-support/en-us/help-article/list-management/export-reports-lists-data-quickbooks-online/L1xleDrLp_US_en_US).

Essas exportações do QuickBooks Online são arquivos Excel. Abra cada um em uma planilha e salve uma cópia em CSV se um script for lê-lo.

**Anexos** são exportados separadamente. No QuickBooks Online, vá em **Configurações**, depois **Anexos**, selecione os arquivos e escolha **Ações em lote** e depois **Exportar**. Guarde o zip com o seu arquivo.

**QuickBooks Desktop.** No Windows, abra cada relatório em **Relatórios**, depois **Central de Relatórios**. Selecione **Excel**, depois **Criar nova planilha**. A janela seguinte pode salvar uma pasta de trabalho do Excel ou um arquivo CSV diretamente, conforme descrito em [Export reports as Excel workbooks](https://quickbooks.intuit.com/learn-support/en-us/help-article/export-reports/export-reports-excel-workbooks-quickbooks-desktop/L4cLJEeXt_US_en_US). O Desktop também pode exportar listas, incluindo o plano de contas, como um arquivo IIF: **Arquivo**, depois **Utilitários**, depois **Exportar**, depois **Listas para arquivos IIF**. A exportação IIF cobre apenas listas. A Intuit afirma que você pode importar transações, mas não pode exportá-las, conforme explicado em [Export, import, and edit IIF files](https://quickbooks.intuit.com/learn-support/en-us/help-article/import-export-data-files/export-import-edit-iif-files/L56LT9Z0Q_US_en_US).

Mantenha as exportações originais inalteradas. Elas são sua evidência caso um número seja questionado mais tarde.

## 3. Mapeie as contas para uma hierarquia Beancount

O Beancount tem cinco contas raiz. Cada tipo de conta do QuickBooks se encaixa sob uma delas:

| Tipo de conta do QuickBooks | Conta Beancount |
| --- | --- |
| Bank | `Assets:Bank:Checking`, `Assets:Bank:Savings` |
| Contas a receber (A/R) | `Assets:AccountsReceivable` |
| Outros Ativos Circulantes, Ativos Fixos | `Assets:Prepaid:…`, `Assets:Equipment:…` |
| Cartão de Crédito | `Liabilities:CreditCard:Visa` |
| Contas a pagar (A/P), Outros Passivos Circulantes | `Liabilities:AccountsPayable`, `Liabilities:SalesTax` |
| Passivos de Longo Prazo | `Liabilities:Loans:…` |
| Patrimônio Líquido, Lucros Acumulados, Saldo Inicial do Patrimônio | `Equity:Opening-Balances` |
| Receita, Outras Receitas | `Income:Sales`, `Income:Interest` |
| Custo das Mercadorias Vendidas | `Expenses:COGS:…` |
| Despesas, Outras Despesas | `Expenses:Rent`, `Expenses:Software` |

Os nomes de conta começam com letra maiúscula e não contêm espaços, então "Office Supplies" se torna `Expenses:Office-Supplies`. Subcontas do QuickBooks se tornam segmentos mais profundos, como `Expenses:Vehicle:Fuel`.

Lucros Acumulados e Saldo Inicial do Patrimônio se fundem em uma única conta `Equity:Opening-Balances`. O Beancount calcula os lucros do ano corrente a partir das suas contas de receita e despesa, então nenhuma conta separada de lucros acumulados precisa ser transportada.

## 4. Abra o razão na data de transição

Esta empresa de exemplo tem um balancete de quatro linhas em `2025-12-31`. As linhas de receita e despesa já estão incorporadas aos Lucros Acumulados. O QuickBooks Online faz o mesmo por conta própria quando um novo ano fiscal começa, conforme descrito em [View retained earnings account details](https://quickbooks.intuit.com/learn-support/en-us/help-article/financial-reports/view-retained-earnings-account-details/L7d6Ugx58_US_en_US).

| Conta | Débito | Crédito |
| --- | --- | --- |
| Checking | 12.450,00 | |
| Contas a receber (A/R) | 3.200,00 | |
| Cartão de crédito Visa | | 1.875,40 |
| Lucros Acumulados | | 13.774,60 |
| **Total** | **15.650,00** | **15.650,00** |

Salve isto como `main.bean`:

```beancount
option "operating_currency" "USD"

2025-12-31 open Assets:Bank:Checking USD
2025-12-31 open Assets:AccountsReceivable USD
2025-12-31 open Liabilities:CreditCard:Visa USD
2025-12-31 open Equity:Opening-Balances USD

; Opening balances from the QuickBooks Trial Balance as of 2025-12-31
2025-12-31 pad Assets:Bank:Checking Equity:Opening-Balances
2025-12-31 pad Assets:AccountsReceivable Equity:Opening-Balances
2025-12-31 pad Liabilities:CreditCard:Visa Equity:Opening-Balances

2026-01-01 balance Assets:Bank:Checking 12450.00 USD
2026-01-01 balance Assets:AccountsReceivable 3200.00 USD
2026-01-01 balance Liabilities:CreditCard:Visa -1875.40 USD
2026-01-01 balance Equity:Opening-Balances -13774.60 USD
```

Cada `pad` pede ao Beancount para inserir o lançamento que torna verdadeira a próxima asserção `balance`. O lado compensatório de cada pad vai para `Equity:Opening-Balances`. Uma asserção `balance` é verificada no início de sua data, então os pads são datados do dia anterior à transição.

Débitos se tornam números positivos e créditos se tornam números negativos. É por isso que o saldo da Visa é `-1875.40 USD`.

A última linha é a conciliação. O patrimônio líquido deve totalizar `-13774.60 USD`, o crédito de Lucros Acumulados. Uma cifra de ativo ou passivo digitada errada altera o patrimônio líquido preenchido pelo pad, e essa asserção falha.

Para uma empresa real, adicione um `open`, um `pad` e um `balance` para cada conta do balanço patrimonial no balancete. Divida Contas a Receber e Contas a Pagar em uma subconta por cliente ou fornecedor se você acompanha faturas em aberto por nome.

## 5. Traga o histórico

Após a transição, registre a nova atividade no Beancount. Extratos bancários e de cartão são a principal fonte. Converta uma exportação CSV de banco no navegador com o [conversor CSV para Beancount](/tools/csv-to-beancount), ou use o [guia de importação bancária](https://beancount.io/pt/docs/Solutions/import-bank-exports-cli) para a linha de comando.

Anos anteriores são opcionais. Não há importação com um clique a partir de uma exportação do Livro Razão do QuickBooks. Mover esse histórico é um passo de mapeamento por script ou manual:

1. Salve a exportação do Livro Razão como CSV.
2. Agrupe suas linhas em transações por data e número de transação.
3. Renomeie cada conta com o mapeamento do passo 3.
4. Escreva cada grupo como uma transação Beancount cujos lançamentos somam zero.

Se você trouxer o histórico, abra as contas no início desse histórico em vez da data de transição. Depois mantenha as asserções `balance` de `2026-01-01`. Elas provam que o histórico convertido chega aos mesmos saldos que o QuickBooks reportou.

## 6. Verifique em relação ao QuickBooks

Verifique o razão, depois liste cada saldo:

```bash
bea --file main.bean check
bea --file main.bean query "SELECT account, sum(position) GROUP BY account ORDER BY account"
```

`bea check` não reporta erros. A consulta retorna quatro linhas: `Assets:AccountsReceivable` em `3200.00 USD`, `Assets:Bank:Checking` em `12450.00 USD`, `Equity:Opening-Balances` em `-13774.60 USD`, e `Liabilities:CreditCard:Visa` em `-1875.40 USD`. Compare cada linha com o Balancete do QuickBooks linha por linha, com créditos como números negativos.

Novo na linha de comando? Instale o `bea` com o [início rápido da CLI](https://beancount.io/pt/docs/Basics/bea-cli).

## 7. O que não é transferido

Uma migração de razão move saldos contábeis e histórico. Ela não move as operações que o QuickBooks executa em torno deles:

- **Faturas e links de pagamento.** Faturas em aberto permanecem como saldos de Contas a Receber. Use um serviço de faturamento separado a partir de agora.
- **Folha de pagamento.** Execuções de pagamento, formulários de impostos e registros de funcionários permanecem com o seu provedor de folha de pagamento.
- **Declarações de imposto sobre vendas.** O Beancount registra o passivo. A declaração continua sendo uma tarefa separada.
- **Anexos.** Recibos e documentos saem em sua própria exportação zip, não nos relatórios.
- **Regras de feed bancário e histórico de reconciliação.** Reconstrua a categorização como regras de importação.

A página de comparação diz claramente: não escolha o Beancount partindo do pressuposto de que alguns plugins recriam toda a suíte operacional do QuickBooks. Escolha-o quando o próprio razão é o seu sistema de registro de longa duração.

Administra uma pequena empresa com Beancount? Veja [Beancount.io para pequenas empresas](/for-small-business) para razões hospedados, Sincronização Bancária e colaboração com contadores.
