Heratio Help Center article. Category: Technical / Integration.

Heratio -- Library Order System REST API

Version: 1.0 Author: The Archive and Heritage Group (Pty) Ltd Plugin: ahgLibraryPlugin Base URL: https://psis.theahg.co.za Content-Type: application/json

Table of Contents

• Quick Start
• Authentication
• Response Format
• HTTP Status Codes
• Error Codes
• Endpoints
  • Orders
    • List Orders
    • Create Order
    • Get Order
    • Update Order
    • Cancel Order
  • Order Lines
    • Add Line
    • Update Line
    • Delete Line
    • Receive Line
  • Budgets
    • List Budgets
    • Create Budget
  • Batch Operations
    • Batch ISBN Lookup
    • Batch Capture
• Rate Limiting
• Versioning

Quick Start

1. Obtain an API key from keys.theahg.co.za.
2. Include the key in every request as the X-API-Key header.
3. Send JSON in the request body for POST and PUT requests.
4. All responses are JSON with a consistent envelope: success, data, meta, error, code.

# Test connectivity -- list orders
curl -s -H "X-API-Key: YOUR_KEY" \
  https://psis.theahg.co.za/api/library/orders | python3 -m json.tool

Authentication

All endpoints require the X-API-Key HTTP header. Keys are managed at keys.theahg.co.za.

A missing or invalid key returns HTTP 401:

{
  "success": false,
  "error": "Unauthorized",
  "code": "AUTH_REQUIRED"
}

Response Format

Every response follows a consistent JSON envelope:

{
  "success": true,
  "data": { ... },
  "meta": {
    "total": 42,
    "page": 1,
    "pages": 2
  }
}

On error:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

HTTP Status Codes

Error Codes

Endpoints

Orders

List Orders

Retrieve a paginated list of orders with optional search and filters.

Query Parameters:

Example:

curl -s -H "X-API-Key: YOUR_KEY" \
  "https://psis.theahg.co.za/api/library/orders?status=pending&page=1&limit=10"

Response (200):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "vendor_name": "Juta & Co",
      "order_date": "2026-03-01",
      "order_type": "purchase",
      "order_status": "pending",
      "total_amount": 1250.00,
      "currency": "ZAR"
    }
  ],
  "meta": {
    "total": 47,
    "page": 1,
    "pages": 5
  }
}

Create Order

Create a new acquisition order.

Request Body:

Example:

curl -s -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_name": "Juta & Co",
    "vendor_account": "JUTA-001",
    "order_date": "2026-03-09",
    "order_type": "purchase",
    "budget_id": 5,
    "currency": "ZAR",
    "notes": "Annual legal reference order"
  }' \
  https://psis.theahg.co.za/api/library/orders

Response (201):

{
  "success": true,
  "data": {
    "order": {
      "id": 42,
      "vendor_name": "Juta & Co",
      "vendor_account": "JUTA-001",
      "order_date": "2026-03-09",
      "order_type": "purchase",
      "order_status": "pending",
      "total_amount": 0,
      "currency": "ZAR",
      "notes": "Annual legal reference order",
      "created_at": "2026-03-09 10:30:00",
      "updated_at": "2026-03-09 10:30:00"
    },
    "lines": []
  }
}

Error (422):

{
  "success": false,
  "error": "vendor_name is required",
  "code": "VALIDATION_ERROR"
}

Get Order

Retrieve a single order with all its line items.

Path Parameters:

Example:

curl -s -H "X-API-Key: YOUR_KEY" \
  https://psis.theahg.co.za/api/library/orders/42

Response (200):

{
  "success": true,
  "data": {
    "order": {
      "id": 42,
      "vendor_name": "Juta & Co",
      "vendor_account": "JUTA-001",
      "order_date": "2026-03-09",
      "order_type": "purchase",
      "order_status": "pending",
      "total_amount": 750.00,
      "currency": "ZAR",
      "notes": "Annual legal reference order"
    },
    "lines": [
      {
        "id": 101,
        "order_id": 42,
        "title": "Constitutional Law of South Africa",
        "isbn": "9780702199684",
        "author": "Currie, I.",
        "publisher": "Juta",
        "quantity": 2,
        "unit_price": 375.00,
        "line_total": 750.00,
        "quantity_received": 0,
        "material_type": "book",
        "fund_code": "LAW-2026",
        "notes": null
      }
    ]
  }
}

Error (404):

{
  "success": false,
  "error": "Order not found",
  "code": "NOT_FOUND"
}

Update Order

Update an existing order. Only provided fields are changed.

Path Parameters:

Request Body (all fields optional):

Example:

curl -s -X PUT -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Updated: expedite delivery requested",
    "currency": "ZAR"
  }' \
  https://psis.theahg.co.za/api/library/orders/42

Response (200):

{
  "success": true,
  "data": {
    "order": {
      "id": 42,
      "vendor_name": "Juta & Co",
      "notes": "Updated: expedite delivery requested",
      "currency": "ZAR",
      "updated_at": "2026-03-09 11:00:00"
    },
    "lines": [ ... ]
  }
}

Error (409) -- cancelled order:

{
  "success": false,
  "error": "Cannot update a cancelled order",
  "code": "ORDER_CANCELLED"
}

Cancel Order

Cancel an order by setting its status to cancelled. This is a soft delete -- the order record is preserved.

Path Parameters:

Example:

curl -s -X DELETE -H "X-API-Key: YOUR_KEY" \
  https://psis.theahg.co.za/api/library/orders/42

Response (200):

{
  "success": true,
  "data": {
    "id": 42,
    "order_status": "cancelled"
  }
}

Error (409) -- already cancelled:

{
  "success": false,
  "error": "Order is already cancelled",
  "code": "ALREADY_CANCELLED"
}

Order Lines

Add Line

Add a line item to an existing order. Cannot add lines to cancelled orders.

Path Parameters:

Request Body:

Example:

curl -s -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Constitutional Law of South Africa",
    "isbn": "9780702199684",
    "author": "Currie, I.",
    "publisher": "Juta",
    "quantity": 2,
    "unit_price": 375.00,
    "material_type": "book",
    "fund_code": "LAW-2026"
  }' \
  https://psis.theahg.co.za/api/library/orders/42/lines

Response (201):

{
  "success": true,
  "data": {
    "id": 101,
    "order_id": 42,
    "title": "Constitutional Law of South Africa",
    "isbn": "9780702199684",
    "author": "Currie, I.",
    "publisher": "Juta",
    "quantity": 2,
    "unit_price": 375.00,
    "line_total": 750.00,
    "quantity_received": 0,
    "material_type": "book",
    "fund_code": "LAW-2026",
    "notes": null,
    "created_at": "2026-03-09 10:35:00",
    "updated_at": "2026-03-09 10:35:00"
  }
}

Update Line

Update an existing line item. Only provided fields are changed. Changing quantity or unit_price automatically recalculates line_total and the parent order's total_amount.

Path Parameters:

Request Body (all fields optional):

Example:

curl -s -X PUT -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 5,
    "unit_price": 350.00
  }' \
  https://psis.theahg.co.za/api/library/orders/42/lines/101

Response (200):

{
  "success": true,
  "data": {
    "id": 101,
    "order_id": 42,
    "title": "Constitutional Law of South Africa",
    "quantity": 5,
    "unit_price": 350.00,
    "line_total": 1750.00,
    "quantity_received": 0,
    "updated_at": "2026-03-09 11:15:00"
  }
}

Delete Line

Permanently remove a line item from an order. The order's total_amount is recalculated.

Path Parameters:

Example:

curl -s -X DELETE -H "X-API-Key: YOUR_KEY" \
  https://psis.theahg.co.za/api/library/orders/42/lines/101

Response (200):

{
  "success": true,
  "data": {
    "id": 101,
    "deleted": true
  }
}

Receive Line

Record receipt of items for a line. Increments quantity_received on the line item.

Path Parameters:

Request Body:

Example:

curl -s -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity_received": 2
  }' \
  https://psis.theahg.co.za/api/library/orders/42/lines/101/receive

Response (200):

{
  "success": true,
  "data": {
    "line": {
      "id": 101,
      "order_id": 42,
      "title": "Constitutional Law of South Africa",
      "quantity": 5,
      "quantity_received": 2,
      "unit_price": 350.00,
      "line_total": 1750.00
    },
    "status": "partially_received",
    "quantity_received": 2
  }
}

Error (400) -- receive failed:

{
  "success": false,
  "error": "Quantity received exceeds quantity ordered",
  "code": "RECEIVE_FAILED"
}

Budgets

List Budgets

Retrieve all budgets, optionally filtered by fiscal year.

Query Parameters:

Example:

curl -s -H "X-API-Key: YOUR_KEY" \
  "https://psis.theahg.co.za/api/library/budgets?fiscal_year=2026"

Response (200):

{
  "success": true,
  "data": [
    {
      "id": 5,
      "budget_code": "LAW-2026",
      "budget_name": "Legal Reference Materials",
      "fiscal_year": "2026",
      "allocated_amount": 50000.00,
      "spent_amount": 12500.00,
      "remaining_amount": 37500.00,
      "currency": "ZAR",
      "category": "acquisitions"
    }
  ],
  "meta": {
    "total": 1
  }
}

Create Budget

Create a new budget allocation. Budget codes must be unique within a fiscal year.

Request Body:

Example:

curl -s -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "budget_code": "HIST-2026",
    "fund_name": "Historical Research Materials",
    "fiscal_year": "2026",
    "allocated_amount": 25000.00,
    "currency": "ZAR",
    "category": "acquisitions",
    "notes": "Approved by library committee 2026-02-15"
  }' \
  https://psis.theahg.co.za/api/library/budgets

Response (201):

{
  "success": true,
  "data": {
    "id": 8,
    "budget_code": "HIST-2026",
    "budget_name": "Historical Research Materials",
    "fiscal_year": "2026",
    "allocated_amount": 25000.00,
    "spent_amount": 0,
    "remaining_amount": 25000.00,
    "currency": "ZAR",
    "category": "acquisitions",
    "notes": "Approved by library committee 2026-02-15"
  }
}

Error (409) -- duplicate:

{
  "success": false,
  "error": "Budget code already exists for this fiscal year",
  "code": "DUPLICATE_BUDGET"
}

Batch Operations

Batch ISBN Lookup

Look up metadata for multiple ISBNs in a single request. Uses the framework's IsbnLookupService (Open Library, Google Books).

Request Body:

Example:

curl -s -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "isbns": ["9780702199684", "9780199541171", "0000000000000"]
  }' \
  https://psis.theahg.co.za/api/library/batch/isbn-lookup

Response (200):

{
  "success": true,
  "data": [
    {
      "isbn": "9780702199684",
      "found": true,
      "data": {
        "title": "Constitutional Law of South Africa",
        "author": "Currie, Iain; De Waal, Johan",
        "publisher": "Juta",
        "publication_date": "2013",
        "pages": 832
      }
    },
    {
      "isbn": "9780199541171",
      "found": true,
      "data": {
        "title": "The Oxford Handbook of Archival Science",
        "author": "Eastwood, Terry; MacNeil, Heather",
        "publisher": "Oxford University Press",
        "publication_date": "2017",
        "pages": 576
      }
    },
    {
      "isbn": "0000000000000",
      "found": false,
      "error": "ISBN not found"
    }
  ],
  "meta": {
    "total": 3,
    "found": 2
  }
}

Batch Capture

Create multiple library items in a single request. Optionally link all items to an existing order as new order lines.

Request Body:

Item object fields:

Example:

curl -s -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": 42,
    "items": [
      {
        "title": "Archival Principles and Practice",
        "isbn": "9781856049382",
        "author": "Shepherd, Elizabeth",
        "publisher": "Facet Publishing",
        "material_type": "book",
        "quantity": 1,
        "unit_price": 420.00
      },
      {
        "title": "Preserving Digital Materials",
        "isbn": "9781856048347",
        "author": "Harvey, Ross",
        "publisher": "Facet Publishing",
        "material_type": "book",
        "quantity": 3,
        "unit_price": 380.00
      },
      {
        "title": "",
        "isbn": "0000000000"
      }
    ]
  }' \
  https://psis.theahg.co.za/api/library/batch/capture

Response (200):

{
  "success": true,
  "data": {
    "created": [
      {
        "index": 0,
        "id": 501,
        "title": "Archival Principles and Practice"
      },
      {
        "index": 1,
        "id": 502,
        "title": "Preserving Digital Materials"
      }
    ],
    "errors": [
      {
        "index": 2,
        "error": "title is required"
      }
    ]
  },
  "meta": {
    "total_submitted": 3,
    "total_created": 2,
    "total_errors": 1,
    "order_id": 42
  }
}

Rate Limiting

There is currently no rate limiting enforced on the API. Clients should implement reasonable request throttling on their side to avoid overloading the server. Future versions may introduce rate limiting with standard X-RateLimit-* headers.

Recommended client-side limits:

Versioning

The current API version is v1, implied by the /api/library/ path prefix. There is no explicit version segment in the URL at this time.

When breaking changes are introduced in a future release, the API will move to a versioned path scheme (e.g., /api/v2/library/). The v1 endpoints will remain available during a deprecation period.

Backward compatibility guarantees for v1:

• Existing fields will not be removed or renamed.
• New optional fields may be added to request and response objects.
• New endpoints may be added under the same prefix.
• Error codes will not change meaning.