API Request Examples

This page demonstrates common POS API requests across different programming languages.

Creating an Order

Create a new order with customer information and line items.

PHP

<?php
$accessToken = getenv('POS_ACCESS_TOKEN');
$baseUrl = 'https://pos.paysera.com/eapi/v1';

function createOrder($accessToken, $orderData) {
    global $baseUrl;

    $ch = curl_init($baseUrl . '/orders');

    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $accessToken,
            'Content-Type: application/json',
            'Accept: application/json'
        ],
        CURLOPT_POSTFIELDS => json_encode($orderData)
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 201) {
        return json_decode($response, true);
    } else {
        throw new Exception("API Error: $response");
    }
}

// Create order
$orderData = [
    'customer' => [
        'name' => 'Jane Smith',
        'email' => 'jane@example.com',
        'phone' => '+37060012345'
    ],
    'items' => [
        [
            'name' => 'Coffee',
            'quantity' => 2,
            'price' => 2.50,
            'tax_rate' => 21
        ],
        [
            'name' => 'Croissant',
            'quantity' => 1,
            'price' => 3.00,
            'tax_rate' => 9
        ]
    ],
    'notes' => 'To go'
];

$order = createOrder($accessToken, $orderData);

echo "Order created: {$order['number']}\n";
echo "Total: {$order['total']} {$order['currency']}\n";
?>

JavaScript (Node.js)

const axios = require('axios');

const accessToken = process.env.POS_ACCESS_TOKEN;
const baseUrl = 'https://pos.paysera.com/eapi/v1';

async function createOrder(orderData) {
  try {
    const response = await axios.post(
      `${baseUrl}/orders`,
      orderData,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        }
      }
    );

    return response.data;
  } catch (error) {
    console.error('API Error:', error.response?.data || error.message);
    throw error;
  }
}

// Create order
const orderData = {
  customer: {
    name: 'Jane Smith',
    email: 'jane@example.com',
    phone: '+37060012345'
  },
  items: [
    {
      name: 'Coffee',
      quantity: 2,
      price: 2.50,
      tax_rate: 21
    },
    {
      name: 'Croissant',
      quantity: 1,
      price: 3.00,
      tax_rate: 9
    }
  ],
  notes: 'To go'
};

createOrder(orderData).then(order => {
  console.log(`Order created: ${order.number}`);
  console.log(`Total: ${order.total} ${order.currency}`);
});

Python

import os
import requests

access_token = os.getenv('POS_ACCESS_TOKEN')
base_url = 'https://pos.paysera.com/eapi/v1'

def create_order(order_data):
    response = requests.post(
        f'{base_url}/orders',
        json=order_data,
        headers={
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        }
    )

    if response.status_code == 201:
        return response.json()
    else:
        raise Exception(f"API Error: {response.text}")

# Create order
order_data = {
    'customer': {
        'name': 'Jane Smith',
        'email': 'jane@example.com',
        'phone': '+37060012345'
    },
    'items': [
        {
            'name': 'Coffee',
            'quantity': 2,
            'price': 2.50,
            'tax_rate': 21
        },
        {
            'name': 'Croissant',
            'quantity': 1,
            'price': 3.00,
            'tax_rate': 9
        }
    ],
    'notes': 'To go'
}

order = create_order(order_data)

print(f"Order created: {order['number']}")
print(f"Total: {order['total']} {order['currency']}")

---

Listing Orders

Retrieve orders with filtering and pagination.

PHP

<?php
function getOrders($accessToken, $filters = []) {
    $baseUrl = 'https://pos.paysera.com/eapi/v1';
    $query = http_build_query($filters);
    $url = $baseUrl . '/orders' . ($query ? '?' . $query : '');

    $ch = curl_init($url);

    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $accessToken,
            'Accept: application/json'
        ]
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// Get completed orders from last 7 days
$filters = [
    'status' => 'completed',
    'from' => date('Y-m-d', strtotime('-7 days')),
    'to' => date('Y-m-d'),
    'per_page' => 50
];

$result = getOrders($accessToken, $filters);

echo "Total orders: {$result['itemsTotal']}\n";
foreach ($result['data'] as $order) {
    echo "- {$order['number']}: {$order['total']} {$order['currency']}\n";
}
?>

JavaScript (Node.js)

async function getOrders(filters = {}) {
  const response = await axios.get(`${baseUrl}/orders`, {
    params: filters,
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/json'
    }
  });

  return response.data;
}

// Get completed orders from last 7 days
const filters = {
  status: 'completed',
  from: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString().split('T')[0],
  to: new Date().toISOString().split('T')[0],
  per_page: 50
};

getOrders(filters).then(result => {
  console.log(`Total orders: ${result.itemsTotal}`);
  result.data.forEach(order => {
    console.log(`- ${order.number}: ${order.total} ${order.currency}`);
  });
});

Python

def get_orders(filters=None):
    response = requests.get(
        f'{base_url}/orders',
        params=filters or {},
        headers={
            'Authorization': f'Bearer {access_token}',
            'Accept': 'application/json'
        }
    )

    return response.json()

# Get completed orders from last 7 days
from datetime import datetime, timedelta

filters = {
    'status': 'completed',
    'from': (datetime.now() - timedelta(days=7)).strftime('%Y-%m-%d'),
    'to': datetime.now().strftime('%Y-%m-%d'),
    'per_page': 50
}

result = get_orders(filters)

print(f"Total orders: {result['itemsTotal']}")
for order in result['data']:
    print(f"- {order['number']}: {order['total']} {order['currency']}")

---

Getting Cash Register Status

Check the operational status of a cash register.

PHP

<?php
function getCashRegisterStatus($accessToken, $registerId) {
    $baseUrl = 'https://pos.paysera.com/eapi/v1';
    $ch = curl_init($baseUrl . "/cash-registers/{$registerId}/status");

    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $accessToken,
            'Accept: application/json'
        ]
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

$status = getCashRegisterStatus($accessToken, 123);

echo "Register: {$status['name']}\n";
echo "Status: {$status['status']}\n";
echo "Fiscal mode: " . ($status['fiscal_mode'] ? 'Yes' : 'No') . "\n";
echo "Last activity: {$status['last_activity']}\n";
?>

---

Retrieving Financial Documents

Get receipts and other fiscal documents.

PHP

<?php
function getFinancialDocuments($accessToken, $registerId, $filters = []) {
    $baseUrl = 'https://pos.paysera.com/eapi/v1';
    $query = http_build_query($filters);
    $url = $baseUrl . "/cash-registers/{$registerId}/financial-documents";
    if ($query) {
        $url .= '?' . $query;
    }

    $ch = curl_init($url);

    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $accessToken,
            'Accept: application/json'
        ]
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

// Get receipts from today
$filters = [
    'type' => 'receipt',
    'from' => date('Y-m-d'),
    'to' => date('Y-m-d')
];

$result = getFinancialDocuments($accessToken, 123, $filters);

echo "Today's receipts: {$result['itemsTotal']}\n";
$totalSales = 0;
foreach ($result['data'] as $doc) {
    $totalSales += $doc['total'];
    echo "- {$doc['number']}: {$doc['total']} {$doc['currency']}\n";
}
echo "\nTotal sales: {$totalSales} EUR\n";
?>

---

Complete POS Client Example

Full client implementation with error handling.

PHP

<?php
class POSClient {
    private $accessToken;
    private $baseUrl;

    public function __construct($accessToken, $demo = false) {
        $this->accessToken = $accessToken;
        $this->baseUrl = $demo
            ? 'https://pos-demo.paysera.com/eapi/v1'
            : 'https://pos.paysera.com/eapi/v1';
    }

    private function request($method, $endpoint, $data = null) {
        $url = $this->baseUrl . $endpoint;
        $ch = curl_init($url);

        $options = [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $this->accessToken,
                'Accept: application/json'
            ]
        ];

        if ($method === 'POST' || $method === 'PUT') {
            $options[CURLOPT_CUSTOMREQUEST] = $method;
            $options[CURLOPT_POSTFIELDS] = json_encode($data);
            $options[CURLOPT_HTTPHEADER][] = 'Content-Type: application/json';
        } elseif ($method === 'DELETE') {
            $options[CURLOPT_CUSTOMREQUEST] = 'DELETE';
        }

        curl_setopt_array($ch, $options);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode >= 400) {
            throw new Exception($response);
        }

        return json_decode($response, true);
    }

    public function createOrder($orderData) {
        return $this->request('POST', '/orders', $orderData);
    }

    public function getOrders($filters = []) {
        $query = http_build_query($filters);
        return $this->request('GET', '/orders' . ($query ? '?' . $query : ''));
    }

    public function getOrder($id) {
        return $this->request('GET', "/orders/{$id}");
    }

    public function updateOrder($id, $data) {
        return $this->request('PUT', "/orders/{$id}", $data);
    }

    public function cancelOrder($id) {
        return $this->request('DELETE', "/orders/{$id}");
    }

    public function getCashRegisterStatus($registerId) {
        return $this->request('GET', "/cash-registers/{$registerId}/status");
    }

    public function getFinancialDocuments($registerId, $filters = []) {
        $query = http_build_query($filters);
        return $this->request('GET', "/cash-registers/{$registerId}/financial-documents" . ($query ? '?' . $query : ''));
    }

    public function getFiscalDay($registerId, $fiscalDay) {
        return $this->request('GET', "/cash-registers/{$registerId}/fiscal-day/{$fiscalDay}");
    }

    public function getInvoices($filters = []) {
        $query = http_build_query($filters);
        return $this->request('GET', '/invoices' . ($query ? '?' . $query : ''));
    }

    public function getInvoice($id) {
        return $this->request('GET', "/invoices/{$id}");
    }
}

// Usage
$client = new POSClient(getenv('POS_ACCESS_TOKEN'), false);

try {
    // Create order
    $order = $client->createOrder([
        'customer' => [
            'name' => 'John Doe',
            'email' => 'john@example.com'
        ],
        'items' => [
            ['name' => 'Product A', 'quantity' => 1, 'price' => 25.00, 'tax_rate' => 21]
        ]
    ]);

    echo "Order created: {$order['number']}\n";

    // Get cash register status
    $status = $client->getCashRegisterStatus(123);
    echo "Register status: {$status['status']}\n";

    // Get today's sales
    $docs = $client->getFinancialDocuments(123, [
        'type' => 'receipt',
        'from' => date('Y-m-d')
    ]);

    echo "Today's receipts: {$docs['itemsTotal']}\n";

} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

---

Error Handling Example

Robust error handling with retry logic.

JavaScript (Node.js)

async function requestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.response?.status === 429) {
        // Rate limit - wait and retry
        const retryAfter = error.response.data.retry_after || (Math.pow(2, i) * 1000);
        await new Promise(resolve => setTimeout(resolve, retryAfter));
        continue;
      } else if (error.response?.status >= 500) {
        // Server error - retry
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, i) * 1000));
        continue;
      }
      // Other errors - don't retry
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

// Usage
await requestWithRetry(() => createOrder(orderData));

---

Next Steps

• Review Authentication for token management
• Check API Endpoints for complete API reference
• Read Security best practices