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.

---

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

{
  "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:

{
  "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