QuickBooks Types for Rust

The quickbooks-types crate provides strongly-typed Rust representations of QuickBooks Online (QBO) API entities, enabling seamless integration with QuickBooks accounting software. It is designed to work with the QuickBooks API and is ideal for building financial applications, integrations, and automation tools.

Features

• Complete Coverage: Supports all major QuickBooks entities, including:
  • Accounts
  • Invoices
  • Customers
  • Vendors
  • Payments
  • Sales Receipts
  • Items
  • Bills
  • Estimates
  • Attachments
  • And more!
• Strong Typing: All entities are represented as Rust structs with proper types (e.g., NaiveDate for dates, f64 for monetary values).
• Validation: Built-in validation for required fields and business rules.
• Serialization/Deserialization: Seamless integration with serde for JSON serialization and deserialization.
• Builder Pattern: Optional builder pattern for easy object creation.
• Query Support: Helper methods for constructing SQL-like queries for QuickBooks entities.
• Error Handling: Comprehensive error types for API and validation errors.
• Async Support: Designed for use with async Rust and popular HTTP clients like reqwest.

Installation

Add the crate to your Cargo.toml:

[dependencies]

quickbooks-types = "0.1.0"

Usage

Basic Example

use quickbooks_types::{Invoice, Customer, Line, LineDetail, SalesItemLineDetail, NtRef};
use chrono::NaiveDate;

// Create a customer
let customer = Customer {
    id: Some("123".to_string()),
    display_name: Some("John Doe".to_string()),
    ..Default::default()
};

// Create an invoice
let invoice = Invoice {
    id: Some("456".to_string()),
    customer_ref: Some(NtRef {
        value: customer.id.clone(),
        name: customer.display_name.clone(),
        ..Default::default()
    }),
    line: Some(vec![
        Line {
            amount: Some(100.0),
            line_detail: LineDetail::SalesItemLineDetail(SalesItemLineDetail {
                item_ref: Some(NtRef {
                    value: Some("ITEM123".to_string()),
                    name: Some("Product A".to_string()),
                    ..Default::default()
                }),
                ..Default::default()
            }),
            ..Default::default()
        }
    ]),
    txn_date: Some(NaiveDate::from_ymd(2023, 10, 1)),
    ..Default::default()
};

// Serialize to JSON for API requests
let json = serde_json::to_string(&invoice).unwrap();
println!("{}", json);

Querying Entities

use quickbooks_types::{Customer, QBQueryable};

// Query customers with a specific name
let query = Customer::query("WHERE DisplayName = 'John Doe'");

Builder Pattern (Optional)

Enable the builder feature in Cargo.toml:

[dependencies]

quickbooks-types = { version = "0.1.0", features = ["builder"] }

Then use the builder pattern:

use quickbooks_types::{InvoiceBuilder, LineBuilder, SalesItemLineDetailBuilder};

let invoice = InvoiceBuilder::default()
    .id("123".to_string())
    .customer_ref(NtRef {
        value: Some("CUST123".to_string()),
        name: Some("John Doe".to_string()),
        ..Default::default()
    })
    .line(vec![
        LineBuilder::default()
            .amount(100.0)
            .line_detail(LineDetail::SalesItemLineDetail(
                SalesItemLineDetailBuilder::default()
                    .item_ref(NtRef {
                        value: Some("ITEM123".to_string()),
                        name: Some("Product A".to_string()),
                        ..Default::default()
                    })
                    .build()
                    .unwrap(),
            ))
            .build()
            .unwrap(),
    ])
    .build()
    .unwrap();

Supported Entities

The crate provides types for the following QuickBooks entities:

• Accounting:
  • Account
  • Budget
  • Class
  • Department
  • TaxCode
  • TaxRate
• Sales:
  • Invoice
  • Estimate
  • SalesReceipt
  • Payment
  • CreditMemo
• Purchases:
  • Bill
  • VendorCredit
  • PurchaseOrder
• Customers & Vendors:
  • Customer
  • Vendor
• Items:
  • Item
  • Inventory
  • NonInventory
  • Service
• Payroll:
  • Employee
  • TimeActivity
• Attachments:
  • Attachable
• Reports:
  • BalanceSheet
  • ProfitAndLoss
  • TrialBalance

Error Handling

The crate provides a comprehensive error type QBTypeError for handling validation and API errors:

#[derive(Debug, thiserror::Error)]
pub enum QBTypeError {
    #[error("Validation error: {0}")]
    ValidationError(String),
    #[error("Missing required field: {0}")]
    MissingField(String),
    #[error("API error: {0}")]
    ApiError(String),
    // ...
}

Optional Features

• builder: Enables the builder pattern for entity creation.
• serde: Enables serialization and deserialization (enabled by default).
• chrono: Enables date/time support (enabled by default).

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or additional features.

License

This project is licensed under the MIT License. See LICENSE for details.

Documentation

For detailed documentation, visit docs.rs/quickbooks-types.