README

A hardened, production-ready PHP SDK designed to integrate web applications (such as WebPOS.az) with the Caspos (SUNMI) Mobile API fiscal cash register service. Developed by WebServis.

This package abstractly decouples your core backend architecture from the hardware network layer and provides strict input validation, preventing costly fiscal errors and sync issues.

Key Features

Strict Precision Formatting: Automatically converts floats to the device's mandatory format (0.000 for quantities, 0.00 for pricing and discounts).
Client-Side Financial Auditing: Validates that total cash/card/bonus payments perfectly match itemized subtotals before transmitting data, neutralizing Caspos Error 607 (Invalid Total Sum) and Error 611.
Input Sanitization & Length Guard: Cleans dangerous characters (", ', \, etc.) from item names and clips them to 40 characters to avoid Error 1206 (Illegal Characters) and Error 635.
Idempotency Protection: Forces the use of explicit documentUUID identifiers to block duplicate transactions during local network packet drops.
Full Shift & Diagnostics Management: Supports shift state tracking (getShiftStatus), opening/closing shifts (Z-Reports), and pulling physical hardware info.

Requirements

PHP: ^8.0
Extensions: ext-curl, ext-json

Installation

Since this library is managed as a localized enterprise package, add it to your main project's composer.json using a local path reference during development:

{
    "repositories": [
        {
            "type": "path",
            "url": "../caspos-client"
        }
    ],
    "require": {
        "webservis/caspos-client": "@dev"
    }
}

Then execute the installation command:

composer update webservis/caspos-client

Quick Start & Usage

1. Initializing the Client

use WebServis\CasposClient;

$client = new CasposClient(
    ipAddress: '1192.168.1.150', // The static local IP displayed on the SUNMI device screen
    username: 'WebPOS_User',
    password: 'secure_integration_password',
    port: 5544 // Default integration port
);

2. Processing a Fiscal Receipt (Sale)

use WebServis\CasposItem;
use WebServis\CasposSaleRequest;
use RuntimeException;
use LogicException;

try {
    // 1. Setup the receipt wrapper with a fixed unique UUID bound to your database order ID
    $saleRequest = new CasposSaleRequest(
        documentUuid: 'c8b4f17a-8f5b-4cde-a112-823cdde39104',
        cardPayment: 17.80, // Total paid via terminal card
        cashierName: 'Waiter: Elvin M.',
        note: 'Service Type: Delivery | Order #10943'
    );

    // 2. Append individual item lines
    $saleRequest->addItem(new CasposItem(
        name: 'Pizza "Margarita" (Large)', // Quotes will be sanitized automatically
        code: '400123456789',
        quantity: 1.000,
        salePrice: 15.00,
        discountAmount: 1.52
    ));

    $saleRequest->addItem(new CasposItem(
        name: 'Coca-Cola 330ml',
        code: '5449000000996',
        quantity: 1.000,
        salePrice: 3.00,
        discountAmount: 0.30
    ));

    // 3. Service fees must be appended as a standard line item
    $saleRequest->addItem(new CasposItem(
        name: 'Service Charge (10%)',
        code: 'SRV10',
        quantity: 1.000,
        salePrice: 1.80,
        discountAmount: 0.18
    ));

    // 4. Send the request to the physical terminal
    // Note: mapping array conversion implicitly fires the internal balance validator
    $response = $client->sendSale($saleRequest);
    
    echo "Success! Fiscal Document ID: " . $response['fiscal_id'] ?? 'Printed';

} catch (LogicException $e) {
    // Fired if payment math does not match item totals locally (0.01 margin protection)
    echo "Validation Error: " . $e->getMessage();
} catch (RuntimeException $e) {
    // Fired on network dropouts, API timeouts, or hardware communication errors
    echo "Terminal Connection Error: " . $e->getMessage();
}

3. Shift Management Operations

// Check if the current work day is active
$status = $client->getShiftStatus();

if ($status['data']['isShiftOpen'] === false) {
    // Open a new work day shift
    $client->openShift(cashierName: 'Manager Name', initialDeposit: 50.00);
}

// Close shift at midnight (Prints rəsmi Z-Report)
$client->closeShift(
    cashierName: 'Manager Name', 
    documentUuid: bin2hex(random_bytes(16))
);

Security & Network Isolation Notice

The Caspos Mobile API operates entirely over unencrypted cleartext HTTP due to device OS constraints. Because username and password credentials are broadcast across the local network in plaintext:

VLAN Isolation: Ensure the SUNMI terminal devices and your local WebPOS processing nodes are restricted to a highly secured, non-public Wi-Fi/VLAN network layer.

Persistent UUID Policy: In the event of an edge network timeout (RuntimeException), do not re-generate a new UUID. Re-attempt the submission with the same identifier; the hardware API uses this token to reject duplicate submissions natively.

License

This project is licensed under the MIT License - see the LICENSE file for details.

webpos / caspos-client

Maintainers

Package info

Statistics

Security