> ## Documentation Index
> Fetch the complete documentation index at: https://help.kuverbooks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

The POS External API Gateway enables secure, automated machine-to-machine (M2M) integrations between third-party systems (such as ERPs, accounting systems, and logistics providers) and the POS backend.

With the gateway, you can:

* Sync inventory and product listings in real-time.
* Query stock status and monitor low stock alerts.
* Synchronize invoices and void bills.

***

## Gateway Architecture

The diagram below illustrates how external applications interact with the POS Gateway, pass security validation, and route queries directly into isolated tenant databases.

```mermaid theme={null}
graph TD
    Client[External App / Third-Party System] -->|1. HTTP Request with Auth Headers| Gateway[POS External API Gateway]
    Gateway -->|2. Validate API Key & IP| Guard[ExternalIntegrationGuard]
    Guard -->|Invalid / Unauthorized| AuthErr[401 / 403 HTTP Error Response]
    Guard -->|3. Validated| Context[Tenant Context Service]
    Context -->|4. Resolve Connection Scope| DB[(Tenant Isolated Database)]
    DB -->|5. Data Query Result| Gateway
    Gateway -->|6. JSON Response| Client
```

***

## Key Features

* **Strict Tenant Isolation**: All requests are dynamically routed to the corresponding tenant's isolated database.
* **Machine-to-Machine Security**: Access is protected using SHA-256 hashed API keys and HMAC signatures.
* **Standardized Response Envelope**: All API endpoints return uniform JSON envelopes for both success and error states.

***

## Standard Response Format

All API responses follow a consistent wrapper format to simplify integration parsing.

### 1. Success Response Structure

```json theme={null}
{
  "success": true,
  "data": { ... },
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 10
  }
}
```

### 2. Error Response Structure

When an error or exception occurs, the system returns a `success: false` payload containing the exact HTTP status code and a descriptive error message:

```json theme={null}
{
  "success": false,
  "status": 400,
  "message": "Row 1: Items quantity must be a positive number"
}
```

***

## Standard HTTP Status Codes

| Status Code             | Description                   | Scenario                                                                      |
| :---------------------- | :---------------------------- | :---------------------------------------------------------------------------- |
| `200 OK`                | Request succeeded             | Successful GET, PUT, PATCH calls                                              |
| `201 Created`           | Resource created              | Successful POST creation calls                                                |
| `400 Bad Request`       | Invalid payload or parameters | DTO validation errors, invalid UUID format, missing nonces/timestamps         |
| `401 Unauthorized`      | Authentication failed         | Missing/invalid `X-Client-Id`, expired `x-timestamp`, reused `x-nonce`        |
| `403 Forbidden`         | Access denied                 | Caller IP address not listed in integration whitelist                         |
| `404 Not Found`         | Resource not found            | Invalid product, invoice, customer, or warehouse UUID                         |
| `409 Conflict`          | Resource state conflict       | Operation illegal for current state (e.g., voiding an already voided invoice) |
| `429 Too Many Requests` | Rate limit exceeded           | Request rate exceeded threshold (100 req/min)                                 |
| `500 Internal Error`    | Server error                  | Unexpected system error                                                       |