ts-quickbooks

Biblioteca de integração com o software QuickBooks Online, com suporte completo ao fluxo OAuth2 e métodos para manipulação dos principais recursos da API.

Instalação

npm i @sinapselabso/ts-quickbooks

Significado dos Endpoints

• Customers: Representa os clientes cadastrados na empresa no QuickBooks Online.
• Invoices: Refere-se às faturas emitidas para clientes.
• Payments: Pagamentos recebidos de clientes, normalmente relacionados a faturas.
• Products/Items: Produtos e serviços oferecidos e cadastrados na empresa.
• Credit Memos: Notas de crédito emitidas para clientes (ex: devoluções, descontos).
• Bills: Contas a pagar, geralmente lançadas por fornecedores.
• Bill Payments: Pagamentos realizados para quitar contas a pagar (Bills).
• Accounts: Contas do plano de contas da empresa (financeiro e contábil).
• Attachables: Anexos e documentos vinculados a outros registros (ex: PDFs, imagens).
• Company: Informações cadastrais e gerais da empresa autenticada.
• Vendors: Fornecedores cadastrados na empresa.
• Vendor Credits: Créditos de fornecedor, normalmente usados para registrar devoluções ou ajustes.

Recursos Disponíveis

A biblioteca encapsula todos os principais endpoints do QuickBooks Online em classes organizadas, acessíveis via a classe principal QuickBooksIntegration. Cada endpoint possui métodos para criação e consulta de recursos, conforme a API oficial.

Endpoints e Métodos Disponíveis

Customers (quickBooks.customers)

• getAllCustomers(): Promise<CustomersQueryResponse>
• createCustomer(data: Customer): Promise<any>

Invoices (quickBooks.invoices)

• getAllInvoices(): Promise<InvoicesQueryResponse>
• createInvoice(data: Invoice): Promise<any>

Payments (quickBooks.payments)

• findPayments(criteria?: string): Promise<PaymentQueryResponse>
• createPayment(data: Payment): Promise<any>

Products/Items (quickBooks.products)

• getAllProducts(): Promise<ItemsQueryResponse>
• createItem(data: Item): Promise<any>

Credit Memos (quickBooks.creditMemos)

• getAllCreditMemos(): Promise<CreditMemosQueryResponse>
• createCreditMemo(data: CreditMemo): Promise<any>

Bills (quickBooks.bills)

• getAllBills(): Promise<BillsQueryResponse>
• createBill(data: Bill): Promise<any>

Bill Payments (quickBooks.billsPayments)

• getAllBillPayments(): Promise<BillPaymentsQueryResponse>
• createBillPayment(data: BillPayment): Promise<any>

Accounts (quickBooks.accounts)

• getAllAccounts(): Promise<AccountsQueryResponse>
• createAccount(data: Account): Promise<any>
• updateAccount(data: Account): Promise<any>
• deleteAccount(accountId: string, syncToken: string): Promise<any>

Attachables (quickBooks.attachables)

• getAllAttachables(): Promise<AttachablesQueryResponse>
• createAttachable(data: Attachable): Promise<any>
• updateAttachable(data: Attachable): Promise<any>
• deleteAttachable(attachableId: string): Promise<any>

Company (quickBooks.company)

• getCompanyInfo(): Promise<CompanyInfo>

Vendors (quickBooks.vendors)

• findVendors(criteria?: string): Promise<VendorsQueryResponse>
• createVendor(data: Vendor): Promise<Vendor>
• updateVendor(data: Vendor): Promise<Vendor>
• deleteVendor(data: Vendor): Promise<Vendor>

Vendor Credits (quickBooks.vendorCredits)

• findVendorCredits(criteria?: string): Promise<VendorCreditsQueryResponse>
• createVendorCredit(data: VendorCredit): Promise<VendorCredit>
• getVendorCredit(id: string): Promise<VendorCredit>
• updateVendorCredit(data: VendorCredit): Promise<VendorCredit>
• deleteVendorCredit(id: string, syncToken: string): Promise<VendorCredit>

Fluxo de Autenticação OAuth2

A autenticação é feita via OAuth2, utilizando a biblioteca oficial intuit-oauth. O fluxo é totalmente automatizado e seguro.

Exemplo de Uso

import { QuickBooksIntegration } from "ts-quickbooks";
import express from "express";

const quickBooks = new QuickBooksIntegration({ clientId, clientSecret });
const redirectUri = "http://localhost:3000/callback";

// 1. Gere a URL de autorização
const authUrl = quickBooks.getAuthorizationUri(redirectUri);
console.log("Acesse esta URL para autorizar o app:", authUrl);

// 2. Endpoint para receber o callback
app.get("/callback", async (req, res) => {
  const code = req.query.code as string;
  const realmId = req.query.realmId as string;
  await quickBooks.exchangeAuthorizationCode(code, redirectUri, realmId);
  res.send("Tokens obtidos e integração pronta!");
});

// 3. Usando a API após autenticação
const customers = await quickBooks.customers.getAllCustomers();
console.log(customers);

Exemplos de Uso dos Métodos

Criar Cliente

await quickBooks.customers.createCustomer({
  DisplayName: "João Silva",
  PrimaryEmailAddr: { Address: "[email protected]" },
  // ...outros campos...
});

Criar Fatura

await quickBooks.invoices.createInvoice({
  CustomerRef: { value: "1" },
  Line: [
    {
      Amount: 100.00,
      DetailType: "SalesItemLineDetail",
      SalesItemLineDetail: {
        ItemRef: { value: "2" },
        UnitPrice: 100.00,
        Qty: 1
      }
    }
  ],
  // ...outros campos...
});

Criar Pagamento

await quickBooks.payments.createPayment({
  CustomerRef: { value: "1" },
  TotalAmt: 100.00,
  // ...outros campos...
});

Criar Produto/Serviço

await quickBooks.products.createItem({
  Name: "Produto A",
  Type: "Service",
  IncomeAccountRef: { value: "79" },
  // ...outros campos...
});

Criar Crédito de Nota Fiscal

await quickBooks.creditMemos.createCreditMemo({
  CustomerRef: { value: "1" },
  Line: [
    {
      Amount: -50.00,
      DetailType: "SalesItemLineDetail",
      SalesItemLineDetail: {
        ItemRef: { value: "2" },
        UnitPrice: -50.00,
        Qty: 1
      }
    }
  ],
  // ...outros campos...
});

Criar Conta

await quickBooks.accounts.createAccount({
  Name: "Caixa",
  AccountType: "Bank",
  // ...outros campos...
});

Criar Bill

await quickBooks.bills.createBill({
  VendorRef: { value: "1" },
  TotalAmt: 100.00,
  // ...outros campos...
});

Criar Pagamento de Bill

await quickBooks.billsPayments.createBillPayment({
  VendorRef: { value: "1" },
  TotalAmt: 100.00,
  // ...outros campos...
});

Criar Anexo

await quickBooks.attachables.createAttachable({
  FileName: "Nota_Fiscal.pdf",
  Category: "Statement",
  ContentType: "application/pdf",
  Size: 2048,
  // ...outros campos...
});

Criar Fornecedor

await quickBooks.vendors.createVendor({
  DisplayName: "Fornecedor X",
  PrimaryEmailAddr: { Address: "[email protected]" },
  // ...outros campos...
});

Criar Vendor Credit

await quickBooks.vendorCredits.createVendorCredit({
  VendorRef: { value: "1" },
  TotalAmt: 200.00,
  Line: [
    {
      Amount: 200.00,
      DetailType: "AccountBasedExpenseLineDetail",
      // ...outros campos...
    }
  ],
  // ...outros campos...
});

Atualizar Conta

await quickBooks.accounts.updateAccount({
  Id: "123",
  SyncToken: "1",
  Name: "Conta Atualizada",
  // ...outros campos...
});

Atualizar Anexo

await quickBooks.attachables.updateAttachable({
  Id: "456",
  FileName: "NovoNome.pdf",
  // ...outros campos...
});

Deletar Conta (inativa)

await quickBooks.accounts.deleteAccount("123", "1");

Deletar Anexo

await quickBooks.attachables.deleteAttachable("456");

Observações

• Todos os métodos retornam Promises.
• Os métodos de atualização e deleção só estão disponíveis para Accounts e Attachables.
• Para métodos de update/delete, consulte a documentação do QuickBooks para saber os campos obrigatórios (ex: SyncToken para contas).
• O fluxo OAuth2 exige interação do usuário apenas na primeira autorização.
• Tokens devem ser armazenados de forma segura em produção.

Referências

• Documentação Oficial QuickBooks
• API Reference QuickBooks Online