# QuickBooks and ERP Integration Overview

## Introduction

HMIS integrates with QuickBooks (and compatible accounting systems) through two complementary mechanisms:

1. **IIF File Export** — generates QuickBooks IIF-format files that can be imported manually into QuickBooks Desktop. Used for daily revenue journals, pharmacy GRN journals, and item list synchronisation.

2. **REST API Integration** — a live HTTP API that external accounting systems (QuickBooks Online, other ERP platforms) can call to pull financial data programmatically. Eliminates manual file export/import.

Both mechanisms export the same underlying financial data — the difference is in how the data moves: manual file import versus automated API pull.

## When to Use Each Integration Method

| Method | Best For |
|---|---|
| IIF Export | QuickBooks Desktop, periodic batch import (daily/weekly) |
| REST API | QuickBooks Online, ERP systems with API capability, automated pipelines |

## Financial Data Available for Integration

| Data Category | Available via IIF | Available via REST API |
|---|---|---|
| Daily revenue journal | Yes | Yes |
| OPD billing summary | Yes | Yes |
| Inpatient billing journal | Yes | Yes |
| Pharmacy GRN (stock purchases) | Yes | Yes |
| Item / service list | Yes | Yes |
| Doctor/professional payments | Yes | Yes |
| Credit company receivables | Partial | Yes |

## Key Concepts

### IIF Format

The IIF (Intuit Interchange Format) is a tab-delimited text format that QuickBooks Desktop uses for bulk imports. Each row in an IIF file has a **row type**:

| Row Type | Meaning |
|---|---|
| `TRNS` | Transaction header (date, total, document number) |
| `SPL` | Split line (individual account entry) |
| `ENDTRNS` | End of transaction marker |

Each row includes accounting codes (`accnt`), transaction type (`trnsType`), amounts, QuickBooks class (`qbClass`), and up to 6 custom fields (`custFld1`–`custFld6`).

### REST API Authentication

The REST API uses the `Finance` header with an API key issued via the HMIS API key management console. All API calls require a valid, unexpired, active API key.

## Navigation to Integration Functions

### IIF Exports
Main Menu → Financial Reports → **QuickBooks Export**
OR
Main Menu → Finance → **ERP Export**

### REST API
Endpoint base: `/api/qb`
Documentation: `reports/financialReports/qb_*.xhtml`

## Cross-Checking Financial Data

All financial data exported through QB integration can be cross-checked against:
- **Cashier Summary Reports** — payment method totals
- **Department Income Reports** — service revenue by department
- **Stock Valuation Reports** — inventory cost movement (for pharmacy GRN)

This triangulation ensures that accounting entries match operational records.

## Technical Reference

| Item | Detail |
|---|---|
| IIF controller | `QuickBookReportController` |
| REST API | `@Path("qb")` in REST layer |
| IIF entity | `QuickBookFormat` (rowType, trnsType, date, accnt, name, amount, docNum, qbClass, custFld1-6) |
| Authentication | `Finance` header → `ApiKeyController.findApiKey()` |
| Related articles | [QB Daily Return Import](Finance-QB-Daily-Return-Import.md), [QB Pharmacy GRN Export](Finance-QB-Pharmacy-GRN-Export.md), [QB REST API](Finance-QB-REST-API.md), [QB Item List Export](Finance-QB-Item-List-Export.md) |