# QuickBooks REST API

## Introduction

The **HMIS QuickBooks REST API** exposes financial data through HTTP endpoints that external accounting systems can call programmatically. QuickBooks Online, custom ERP integrations, and automated accounting pipelines use this API to pull revenue, payment, and stock data directly — without manual file export and import.

## Base URL and Authentication

- **Base path:** `/api/qb`
- **Authentication:** Pass your API key in the `Finance` HTTP header.

```
GET /api/qb/dailyReturn?date=2026-05-15
Finance: your-api-key-here
```

API keys are issued and managed through the HMIS API Key Management console. Keys must be active, not expired, and not retired.

## Available Endpoints

| Method | Endpoint | Description |
|---|---|---|
| GET | `/api/qb/dailyReturn` | Daily OPD billing and payment summary |
| GET | `/api/qb/inwardJournal` | Inpatient billing journal entries |
| GET | `/api/qb/pharmacyGrn` | Pharmacy goods received (stock purchases) |
| GET | `/api/qb/itemList` | Full item/service list with QB account mappings |
| GET | `/api/qb/doctors` | Doctor/consultant list with payment details |
| GET | `/api/qb/professionalFees` | Doctor professional fee payments |
| GET | `/api/qb/creditCompany` | Credit company receivables |
| GET | `/api/qb/cashierSummary` | Cashier collection summary |
| GET | `/api/qb/paymentMethods` | Collections by payment method |
| GET | `/api/qb/stockValuation` | Current pharmacy stock valuation |

## Common Query Parameters

| Parameter | Description | Example |
|---|---|---|
| `date` | Single date (for daily data) | `2026-05-15` |
| `from` | Start date for range queries | `2026-05-01` |
| `to` | End date for range queries | `2026-05-31` |
| `department` | Filter by department code | `OPD`, `PHARMACY` |
| `format` | Response format | `json` (default), `iif` |

Date format: `yyyy-MM-dd`

## Response Format

All endpoints return JSON:

```json
{
  "status": "success",
  "code": 200,
  "data": {
    "date": "2026-05-15",
    "entries": [
      {
        "account": "OPD Revenue",
        "amount": 125000.00,
        "paymentMethod": "Cash",
        "docNum": "B-12345",
        "qbClass": "OPD"
      }
    ],
    "total": 125000.00
  }
}
```

Error responses:

```json
{
  "status": "error",
  "code": 401,
  "message": "Invalid or expired API key"
}
```

## IIF Format via API

To retrieve IIF-formatted output (for systems that prefer the file format):

```
GET /api/qb/dailyReturn?date=2026-05-15&format=iif
Finance: your-api-key-here
```

The response body is the IIF file content (tab-delimited), suitable for direct import into QuickBooks Desktop.

## Integration Setup

To configure an external system to use the HMIS QB API:

1. Obtain an API key from the HMIS administrator.
2. Configure the external system with the HMIS base URL and API key.
3. Set up a scheduled job (daily, nightly, or real-time) to call the relevant endpoints.
4. Map the returned accounts and classes to the external system's chart of accounts.

## Rate Limiting and Best Practices

- Call daily endpoints once per day after the business day closes (recommended: midnight or early morning).
- Do not call real-time endpoints more than once per minute.
- Cache the item list endpoint — it changes infrequently and does not need to be polled daily.

## Technical Reference

| Item | Detail |
|---|---|
| REST class | `@Path("qb")` in the REST API layer |
| Authentication | `Finance` header → `ApiKeyController.findApiKey()` — checks expiry, retired, activated |
| Date format | `yyyy-MM-dd HH:mm:ss` in Gson serialisation |
| Registration | Must be listed in `ApplicationConfig.addRestResourceClasses()` |
| Related | [QB Integration Overview](Finance-QB-Integration-Overview.md), [REST API Development Guide](https://github.com/hmislk/hmis/wiki/Rest-API-Development-Guide) |