QuickBooks Online Integration

QBO_CLIENT_ID=*** From Intuit Developer Dashboard
QBO_CLIENT_SECRET= # From Intuit Developer Dashboard
QBO_REDIRECT_URI= # e.g., https://your-domain.com/qbo/callback
QBO_ENVIRONMENT= # "sandbox" or "production"
QBO_COMPANY_ID= # Realm ID (set after first auth)

# Create customer (from CRM lead)
POST /v3/company/{realmId}/customer
{
  "DisplayName": "John Smith",
  "PrimaryEmailAddr": {"Address": "john@email.com"},
  "PrimaryPhone": {"FreeFormNumber": "555-555-0123"},
  "BillAddr": {"Line1": "123 Main St", "City": "[CITY]", "CountrySubDivisionCode": "[STATE]", "PostalCode": "[ZIP]"},
  "Notes": "Lead from referral"
}

# Query customer
GET /v3/company/{realmId}/query?query=SELECT * FROM Customer WHERE DisplayName='John Smith'

# Create estimate (from estimator-engine output)
POST /v3/company/{realmId}/estimate
{
  "CustomerRef": {"value": "123"},
  "TxnDate": "2026-01-15",
  "ExpirationDate": "2026-02-14",
  "Line": [
    {
      "DetailType": "SalesItemLineDetail",
      "Amount": 3125.00,
      "Description": "Service - 2500 sqft, vaulted ceilings, moderate tobacco",
      "SalesItemLineDetail": {"ItemRef": {"value": "1", "name": "Base Treatment"}, "Qty": 2500, "UnitPrice": 1.25}
    },
    {"DetailType": "SalesItemLineDetail", "Amount": 350.00, "Description": "Cigarette >5yrs extended treatment", "SalesItemLineDetail": {"ItemRef": {"value": "2"}, "Qty": 1, "UnitPrice": 350}},
    {"DetailType": "SalesItemLineDetail", "Amount": 75.00, "Description": "Travel surcharge - Premium Region", "SalesItemLineDetail": {"ItemRef": {"value": "3"}, "Qty": 1, "UnitPrice": 75}}
  ],
  "CustomerMemo": {"value": "Valid 30 days. 50% deposit to schedule."}
}

# Send estimate email
POST /v3/company/{realmId}/estimate/{estimateId}/send?sendTo={email}

# Create invoice from accepted estimate
POST /v3/company/{realmId}/invoice
{
  "CustomerRef": {"value": "123"},
  "TxnDate": "2026-01-20",
  "DueDate": "2026-02-03",
  "Line": [...same line items...],
  "Deposit": 1562.50,  # 50% deposit collected via Stripe
  "CustomerMemo": {"value": "Balance due upon completion"}
}

# Get invoice PDF
GET /v3/company/{realmId}/invoice/{invoiceId}/pdf

# Record payment (from Stripe webhook)
POST /v3/company/{realmId}/payment
{
  "CustomerRef": {"value": "123"},
  "TotalAmt": 1562.50,
  "PaymentRefNum": "pi_3StripePaymentIntentId",
  "PaymentMethodRef": {"value": "5"},  # Credit Card
  "DepositToAccountRef": {"value": "35"},  # Undeposited Funds
  "Line": [{"Amount": 1562.50, "LinkedTxn": [{"TxnId": "456", "TxnType": "Invoice"}]}]
}

# Ensure service items exist (run once on setup)
# Base Treatment (per sqft)
# Cigarette Extended Treatment (each)
# Travel Surcharge (each)
# HVAC Duct Treatment (each)
# High Rise Surcharge (each)
# Region Surcharge (each)

# 1. Look up or create customer in QB
# 2. Call estimator-engine with property details
# 3. Transform estimator output → QB estimate line items
# 4. Create estimate in QB
# 5. Email PDF to customer
# 6. Create CRM estimate record (status=sent)
# 7. Create follow-up task (3 days)

# 1. Update CRM estimate status=accepted
# 2. Create invoice in QB (copy line items)
# 3. Generate Stripe Payment Link for 50% deposit
# 4. Text customer deposit link
# 5. Create job scheduled task for the owner

# 1. Verify webhook signature
# 2. Find invoice by payment_intent metadata
# 3. Create QB Payment linked to invoice
# 4. Update CRM invoice status=paid
# 5. Notify owners via Telegram

customer = qbo.upsert_customer(
    name="Jane Doe",
    email="jane@email.com",
    phone="555-555-0199",
    address="456 Palm Ave, [CITY], [STATE] [ZIP]",
    notes="Referral - Example Realty"
)

estimate = qbo.create_estimate(
    customer_id=customer.id,
    line_items=estimator_output.line_items,  # [{desc, qty, unit_price, total}]
    txn_date="2026-01-15",
    expiration_date="2026-02-14",
    memo="Valid 30 days. 50% deposit to schedule."
)
qbo.send_estimate(estimate.id, customer.email)

report = qbo.get_weekly_report(realm_id)
# Returns: {outstanding_estimates: [...], ar_aging: {...}, revenue_mtd: 45000, payments_this_week: [...]}