Saha POS Interface (SPI) - Example Implementations

This repository contains reference implementations of the Saha POS Interface (SPI) in multiple programming languages. These examples demonstrate how to integrate your POS system with Saha's robotics platform.

Overview

The Saha POS Interface (SPI) is a REST API specification that enables external POS providers to integrate with the Saha robotics system. These implementations show how to build a compliant API that supports:

• Product synchronization with categories and options
• Order creation and management
• Order status tracking
• Order cancellation
• Location management

Available Examples

This repository includes working implementations in the following languages:

Language	Framework	Location	Status
Node.js/TypeScript	Native HTTP	examples/nodejs/	✅ Complete
Python	Standard Library	examples/python/	✅ Complete
Go	Standard Library	examples/go/	✅ Complete
.NET	.NET 9 Minimal APIs	examples/dotnet/	✅ Complete
Java	Spring Boot 3.4	examples/java-springboot/	✅ Complete

Quick Start

Each example implementation can be run independently. Choose the language you're most comfortable with:

Node.js/TypeScript

cd examples/nodejs
npm install
npm run dev

Server runs on http://localhost:5000

Python

cd examples/python
python3 server.py

Server runs on http://localhost:5000

Go

cd examples/go
go run .

Server runs on http://localhost:5000

.NET

cd examples/dotnet
dotnet run

Server runs on http://localhost:5000

Java (Spring Boot)

cd examples/java-springboot
./mvnw spring-boot:run

Server runs on http://localhost:5000

API Endpoints

All implementations support the following endpoints:

Method	Endpoint	Description
GET	/products	Retrieve product catalog with pagination
POST	/orders	Create a new order
GET	/orders/{id}	Get order status
POST	/orders/{id}/cancel	Cancel an order
GET	/locations	Get available locations (tables/rooms)

Authentication

All examples use header-based authentication. By default, they expect an Authorization header:

curl -H "Authorization: Bearer your-secret-token" http://localhost:5000/products

The examples log warnings for missing authentication but accept any token for demonstration purposes.

Testing

📦 Using Postman (Recommended)

A complete Postman collection is included at resources/Saha_POS_Interface.postman_collection.json.

Import it into Postman to test all endpoints with pre-configured requests.

Using cURL

Get Products:

curl -H "Authorization: Bearer secret" http://localhost:5000/products

Create Order:

curl -X POST http://localhost:5000/orders \
  -H "Authorization: Bearer secret" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_id": "prod-1",
        "quantity": 2,
        "options": [
          {
            "name": "opt-size",
            "values": ["val-large"]
          }
        ]
      }
    ],
    "location": "loc-table-1",
    "note": "Extra napkins please",
    "number_of_people": 2
  }'

Get Order Status:

curl -H "Authorization: Bearer secret" http://localhost:5000/orders/order-1

Cancel Order:

curl -X POST http://localhost:5000/orders/order-1/cancel \
  -H "Authorization: Bearer secret" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Customer requested"}'

Get Locations:

curl -H "Authorization: Bearer secret" http://localhost:5000/locations

Documentation

• SPI Specification - Complete API specification with data models and requirements
• Node.js Example - TypeScript implementation details
• Python Example - Python implementation details
• Go Example - Go implementation details
• .NET Example - .NET 9 implementation details

1. Product Synchronization

• Pagination with cursor-based navigation
• Multi-language support (translatable fields)
• Product categories and hierarchies
• Product options and variants
• Cross-sell recommendations
• Custom pricing per option

2. Order Management

• Order creation with multiple items
• Support for product options and modifiers
• Order notes and special instructions
• Location-based ordering (table/room assignments)
• Guest count tracking
• Adding items to existing orders

3. Order Status Tracking

• Real-time order status updates
• Standard status values: accepted, pending, in_progress, ready, completed, cancelled, failed
• Status-based robot dispatch triggers

4. Multi-language Support

All text fields support either:

• Simple strings (uses default language)
• Language maps: {"en": "Burger", "tr": "Burger", "de": "Burger"}

Supported translatable fields:

• Product/category names and descriptions
• Ingredients
• Units
• Option labels

Data Models

Product Structure

{
  "id": "prod-102",
  "name": {"en": "Cheeseburger", "tr": "Peynirli Burger"},
  "description": "Delicious burger with cheese",
  "price": 150.0,
  "currency": "TRY",
  "category": {
    "id": "cat-1",
    "name": "Burgers"
  },
  "options": [
    {
      "name": "opt-size",
      "label": {"en": "Size", "tr": "Boyut"},
      "required": true,
      "multiple": false,
      "options": [
        {
          "value": "val-small",
          "label": "Small",
          "additional_price": 0
        },
        {
          "value": "val-large",
          "label": "Large",
          "additional_price": 20.0
        }
      ]
    }
  ]
}

Order Structure

{
  "items": [
    {
      "product_id": "prod-102",
      "quantity": 2,
      "note": "No onions",
      "options": [
        {
          "name": "opt-size",
          "values": ["val-large"]
        }
      ]
    }
  ],
  "location": "loc-table-1",
  "note": "Rush order",
  "number_of_people": 4,
  "existing_order_id": "order-999"
}

Implementation Notes

Error Handling

Add proper error responses:

• 400 Bad Request - Invalid input
• 401 Unauthorized - Missing/invalid authentication
• 404 Not Found - Resource not found
• 409 Conflict - Order already exists
• 500 Internal Server Error - Server errors

Integration Configuration

To integrate with Saha, you'll need to provide:

1. Base URL: Your API root (e.g., https://api.yourpos.com/saha/v1)
2. Auth Header Name: Header for authentication (e.g., Authorization)
3. Auth Header Secret: The secret value (e.g., Bearer your-secret-key)
4. Default Language: Language code for string translations (default: en)
5. Default Currency: ISO 4217 currency code (default: TRY)

License

See LICENSE for details.

---

Note: These are reference implementations for demonstration purposes. They should be adapted with proper security, error handling, and production-ready practices before deployment.