View as Markdown · API catalog (RFC 9727)

# POS SAAS API

Multi-tenant cloud POS API used by native mobile apps (Flutter) and third-party integrations.

## Base URL

- Tenant API: `https://{tenant}.gigapos.cc/api/v1/`
- All endpoints are scoped to the tenant subdomain.

## Authentication

Bearer tokens obtained via `POST /api/v1/auth/login`.

```
POST /api/v1/auth/login
Content-Type: application/json

{ "username": "...", "password": "..." }
```

Returns `{ "token": "..." }`. Include on every subsequent request:

```
Authorization: Bearer <token>
```

Rate limits: login 5/min per IP; other endpoints 120/min per IP.

## Resources

| Resource | Endpoint | Methods |
| --- | --- | --- |
| Products | `/api/v1/products` | GET, POST, PATCH, DELETE |
| Customers | `/api/v1/customers` | GET, POST, PATCH, DELETE |
| Sales | `/api/v1/sales` | GET, POST |
| Purchases | `/api/v1/purchases` | GET, POST |
| Shifts | `/api/v1/shifts` | GET, POST, PATCH |
| Devices | `/api/v1/devices` | GET, POST, DELETE |
| Dashboard | `/api/v1/dashboard` | GET |

## Responses

All responses are JSON. Errors follow the shape:

```json
{ "error": "human readable message" }
```

HTTP status codes follow standard semantics (200/201/400/401/403/404/429/500).

## Health

`GET /api/v1/health` returns `{ "status": "ok" }`.

## ZATCA E-Invoicing

This platform is a ZATCA Phase 2 certified e-invoicing solution for the Kingdom of Saudi Arabia. Invoices created via the Sales API are automatically signed, submitted, and reported to the ZATCA Fatoora platform.