SmartKasa API Specification (1212bogdan/smartkasa-openapi3)

SmartKasa API Specification

https://github.com/1212bogdan/smartkasa-openapi3
Admin
The SmartKasa API Specification defines the comprehensive REST API for SmartKasa, a Ukrainian fiscal...

Tokens:48,684
Snippets:127
Trust Score:4.9
Update:2 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# SmartKasa API Documentation

SmartKasa API is a comprehensive REST API for Ukrainian retail POS (Point of Sale) systems with fiscal compliance. It provides a complete platform for managing fiscal cash register operations compliant with Ukrainian State Tax Service (DPS) requirements, including inventory management, employee administration, shift management, receipt processing, and sales reporting. The API serves businesses operating retail stores and requires proper authentication through API keys and JWT tokens.

The API is organized into 13 functional areas covering authentication, POS terminals, shops, employees, unit types, categories, products, inventory cards, product subgroups, import operations, shifts, receipts/transactions, and reports. All endpoints use JSON for request and response bodies, with consistent pagination and error handling patterns throughout the API.

## Authentication

### POST /api/v1/auth/sessions

Creates an authenticated session using phone number and password credentials. Returns access and refresh JWT tokens for subsequent API requests.

```bash
# Login with phone number and password
curl -X POST https://core.smartkasa.ua/api/v1/auth/sessions \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -d '{
    "session": {
      "phone_number": "380960000006",
      "password": "123456789"
    }
  }'

# Response (201 Created):
{
  "data": {
    "id": null,
    "access": "eyJhbGciOiJIUzI1NiJ9...",
    "access_expires_at": "2021-03-23T13:51:37.000+02:00",
    "csrf": "aPhV1ZNQyuoTStIlnw7PlSGU8jRMzhsu...",
    "refresh": "eyJhbGciOiJIUzI1NiJ9...",
    "refresh_expires_at": "2021-04-22T01:20:43.000+03:00"
  },
  "meta": {}
}
```

### POST /api/v1/auth/refresh

Renews an expired access token using a valid refresh token. Include the refresh token in the X-Refresh-Token header.

```bash
# Refresh access token
curl -X POST https://core.smartkasa.ua/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "X-Refresh-Token: eyJhbGciOiJIUzI1NiJ9..."

# Response (201 Created):
{
  "data": {
    "id": null,
    "access": "eyJhbGciOiJIUzI1NiJ9...",
    "access_expires_at": "2023-03-23T22:01:49.000+00:00",
    "csrf": "xMt3hxr41k+snNPbQnKYF1FwAYA+PmRn...",
    "refresh": "eyJhbGciOiJIUzI1NiJ9...",
    "refresh_expires_at": "2023-03-23T22:01:49.000+00:00"
  },
  "meta": {}
}
```

### DELETE /api/v1/auth/sessions/logout

Terminates the current session and invalidates all associated tokens.

```bash
# Logout and invalidate tokens
curl -X DELETE https://core.smartkasa.ua/api/v1/auth/sessions/logout \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

# Response (200 OK):
{
  "data": {
    "id": "49cb6c02-9951-4c6b-9e55-e2d2b615f5bb"
  },
  "meta": {}
}
```

## POS Terminals

### GET /api/v1/pos/terminals

Lists all POS terminals with optional filtering by ID, name, shop, and pagination support.

```bash
# List all terminals
curl -X GET "https://core.smartkasa.ua/api/v1/pos/terminals" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Filter by shop ID
curl -X GET "https://core.smartkasa.ua/api/v1/pos/terminals?shop_id=37958&page=1&per_page=25" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": [
    {
      "id": 20007,
      "activated_at": null,
      "core_terminal_id": 1,
      "created_at": "2021-03-22T13:52:06.216+02:00",
      "name": "Test terminal",
      "picture": {
        "id": "cd8479459fe1e42d67d4be153101cbdc",
        "filename": "test.png",
        "mime_type": "image/png",
        "size": 8132,
        "url": "/uploads/store/cd8479459fe1e42d67d4be153101cbdc"
      },
      "properties": null,
      "serial_number": "108210974046530",
      "shop_id": 37958,
      "state": 1,
      "updated_at": "2021-03-22T13:52:06.216+02:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1,
    "limit_value": 25,
    "offset_value": 0
  }
}
```

### PUT /api/v1/pos/terminals/{id}

Updates terminal configuration including name and shop assignment.

```bash
# Update terminal
curl -X PUT "https://core.smartkasa.ua/api/v1/pos/terminals/20012" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "terminal": {
      "id": 20012,
      "name": "Updated Terminal Name",
      "shop_id": 37964
    }
  }'

# Response (200 OK):
{
  "data": {
    "id": 20012,
    "name": "Updated Terminal Name",
    "shop_id": 37964,
    "serial_number": "863684811804753",
    "state": 1
  },
  "meta": {}
}
```

## Shops

### GET /api/v1/rsn/shops

Lists all shop locations with comprehensive filtering options including title, phone, email, and fiscal settings.

```bash
# List all shops
curl -X GET "https://core.smartkasa.ua/api/v1/rsn/shops" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": [
    {
      "id": 37969,
      "address": {
        "id": 38197,
        "address_type_id": 0,
        "city_name": "Kyiv",
        "content": "prov. Vicheva, 17",
        "zip_code": "08800"
      },
      "business_category_id": 1,
      "email": "shop@example.com",
      "employees_count": 0,
      "fiscal_numbers": [],
      "fiscalization_enabled": false,
      "is_excise_taxation": false,
      "is_vat_taxation": true,
      "owner_id": 1,
      "phone_number": "0971234567",
      "state": 0,
      "terminals_count": 0,
      "title": "Test shop",
      "website_url": "https://www.example.com"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_count": 1
  }
}
```

### POST /api/v1/rsn/shops

Creates a new shop location with address, fiscal settings, and contact information.

```bash
# Create new shop
curl -X POST "https://core.smartkasa.ua/api/v1/rsn/shops" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "shop": {
      "title": "Downtown Store",
      "email": "downtown@store.com",
      "phone_number": "0971234567",
      "state": 0,
      "website_url": "https://www.downtown-store.com",
      "business_category_id": 1,
      "fiscal_numbers": [],
      "fiscalization_enabled": false,
      "is_vat_taxation": true,
      "is_excise_taxation": false,
      "address": {
        "zip_code": "01001",
        "city_name": "Kyiv",
        "content": "vul. Khreshchatyk, 1"
      }
    }
  }'

# Response (201 Created):
{
  "data": {
    "id": 37968,
    "title": "Downtown Store",
    "phone_number": "380971234567",
    "email": "downtown@store.com",
    "address": {
      "id": 38196,
      "city_name": "Kyiv",
      "content": "vul. Khreshchatyk, 1",
      "zip_code": "01001"
    }
  },
  "meta": {}
}
```

## Employees

### GET /api/v1/rsn/employees

Lists employees with comprehensive filtering by personal information, role, and POS access credentials.

```bash
# List all employees
curl -X GET "https://core.smartkasa.ua/api/v1/rsn/employees" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Filter by role
curl -X GET "https://core.smartkasa.ua/api/v1/rsn/employees?role_id=856" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": [
    {
      "id": 1300,
      "additional_phone_number": null,
      "birthday": "1980-01-01T00:00:00.000+00:00",
      "email": "employee@example.com",
      "first_name": "Bohdan",
      "gender_type_id": 1,
      "inn": "1234567891",
      "last_name": "Paliy",
      "middle_name": null,
      "notes": "Notes about employee",
      "passport_number": "123456",
      "passport_serial": "SN",
      "phone_number": "380970000016",
      "pin_code": "1234",
      "role": {
        "id": 856,
        "name": "Cashier",
        "state": 0
      },
      "role_id": 856,
      "state": 0
    }
  ],
  "meta": {
    "total_count": 1
  }
}
```

### POST /api/v1/rsn/employees

Creates a new employee with personal information, addresses, and POS access credentials.

```bash
# Create new employee
curl -X POST "https://core.smartkasa.ua/api/v1/rsn/employees" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "employee": {
      "email": "new@employee.com",
      "first_name": "Viktor",
      "middle_name": "Hordiychuk",
      "last_name": "Lahoyda",
      "phone_number": "0971234567",
      "inn": "1234567891",
      "pin_code": "1123",
      "passport_serial": "SN",
      "passport_number": "123456",
      "role_id": 854,
      "address_actual": {
        "zip_code": "08800",
        "content": "prov. Vicheva, 5"
      },
      "address_legal": {
        "zip_code": "08132",
        "content": "pr. Nyzhankivskoho, 196"
      },
      "birthday": "1980-01-01",
      "joined_at": "2012-01-01",
      "gender_type_id": 1,
      "notes": "Employee notes"
    }
  }'

# Response (201 Created):
{
  "data": {
    "id": 1299,
    "first_name": "Viktor",
    "last_name": "Lahoyda",
    "phone_number": "380971234567",
    "role_id": 854,
    "state": 0
  },
  "meta": {}
}
```

## Unit Types

### GET /api/v1/inventory/unit_types

Retrieves all available units of measurement for products including codes and weight indicators.

```bash
# List all unit types
curl -X GET "https://core.smartkasa.ua/api/v1/inventory/unit_types" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": [
    {"id": 12, "code": 175, "is_visible": true, "is_weighted": false, "name": "Hour", "short_name": "hr"},
    {"id": 9, "code": 303, "is_visible": true, "is_weighted": true, "name": "Gram", "short_name": "g"},
    {"id": 10, "code": 301, "is_visible": true, "is_weighted": true, "name": "Kilogram", "short_name": "kg"},
    {"id": 0, "code": 2009, "is_visible": true, "is_weighted": false, "name": "Piece", "short_name": "pc"}
  ],
  "meta": {
    "total_count": 11
  }
}
```

## Categories

### GET /api/v1/inventory/categories

Lists product categories with support for hierarchical structures via parent_id.

```bash
# List all categories
curl -X GET "https://core.smartkasa.ua/api/v1/inventory/categories" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": [
    {
      "id": "72c1f7f7-751d-4caf-a0c7-5c8b0314a9f2",
      "color_id": 0,
      "parent_id": null,
      "partner_id": 7711,
      "products_count": 15,
      "shop_ids": [],
      "title": "Beverages"
    }
  ],
  "meta": {
    "total_count": 1
  }
}
```

### POST /api/v1/inventory/categories

Creates a new product category, optionally as a child of an existing category.

```bash
# Create root category
curl -X POST "https://core.smartkasa.ua/api/v1/inventory/categories" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "category": {
      "title": "New Category",
      "color_id": 2,
      "parent_id": null,
      "shop_ids": []
    }
  }'

# Create child category
curl -X POST "https://core.smartkasa.ua/api/v1/inventory/categories" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "category": {
      "title": "Sub Category",
      "color_id": 3,
      "parent_id": "72c1f7f7-751d-4caf-a0c7-5c8b0314a9f2"
    }
  }'

# Response (201 Created):
{
  "data": {
    "id": "836d06aa-0097-4377-afd6-6ea051f077ec",
    "title": "New Category",
    "color_id": 2,
    "parent_id": null,
    "products_count": 0
  },
  "meta": {}
}
```

## Products

### GET /api/v1/inventory/products

Lists products with full-text search, barcode filtering, and category/shop filtering.

```bash
# List all products
curl -X GET "https://core.smartkasa.ua/api/v1/inventory/products" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Search products by keyword
curl -X GET "https://core.smartkasa.ua/api/v1/inventory/products?q=coffee&page=1&per_page=25" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Filter by barcode
curl -X GET "https://core.smartkasa.ua/api/v1/inventory/products?number=1944840247" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": [
    {
      "id": "6ba87885-a4af-47ac-a31a-50de0d6b93ce",
      "alter_number": "9909720899",
      "alter_title": "Short title",
      "bookmark_ids": [],
      "category_id": "6718d176-b9d2-42d2-a22d-afb7728f0303",
      "classifier_code": "123456789012345",
      "classifier_type_id": 1,
      "is_free_price": false,
      "number": "1944840247",
      "picture": {
        "id": "fdd86b0b8767eb6397988ce910253990",
        "filename": "product.png",
        "url": "/uploads/store/fdd86b0b8767eb6397988ce910253990"
      },
      "price": "3064.0",
      "procurement_price": "100.0",
      "sold_by_weight": false,
      "tax_amount": {"A": 1520},
      "tax_group_id": 1,
      "title": "Product Name",
      "unit_type_id": 0
    }
  ],
  "meta": {
    "total_count": 2
  }
}
```

### POST /api/v1/inventory/products

Creates a new product with pricing, tax settings, and classification.

```bash
# Create new product
curl -X POST "https://core.smartkasa.ua/api/v1/inventory/products" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "product": {
      "number": "6930426566",
      "title": "Premium Coffee Beans 1kg",
      "unit_type_id": 0,
      "portion_amount": 800,
      "portion_type_id": 0,
      "price": 71.89,
      "procurement_price": 50.0,
      "classifier_type_id": 2,
      "classifier_code": "543210123456789",
      "tax_group_id": 1,
      "category_id": "992670be-c998-4169-a62c-63bfe2a4e1a0",
      "sold_by_weight": false,
      "bookmark_ids": []
    }
  }'

# Response (201 Created):
{
  "data": {
    "id": "7f527f59-bcdb-4bbd-a187-00b6ee7b68f5"
  },
  "meta": {}
}
```

### GET /api/v1/inventory/products/{id}

Retrieves detailed product information including inventory cards showing stock per shop.

```bash
# Get product details with inventory
curl -X GET "https://core.smartkasa.ua/api/v1/inventory/products/f747fbc5-4782-4489-92b4-51691dea1f63" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": {
    "id": "f747fbc5-4782-4489-92b4-51691dea1f63",
    "title": "Product Name",
    "price": "7829.0",
    "cards": [
      {
        "id": 10789,
        "count": "100.0",
        "counting_enabled": true,
        "product_id": "f747fbc5-4782-4489-92b4-51691dea1f63",
        "shop_id": 37933
      },
      {
        "id": 10790,
        "count": "10.0",
        "counting_enabled": true,
        "product_id": "f747fbc5-4782-4489-92b4-51691dea1f63",
        "shop_id": 37934
      }
    ],
    "category": {
      "id": "72c1f7f7-751d-4caf-a0c7-5c8b0314a9f2",
      "title": "Beverages"
    }
  },
  "meta": {}
}
```

## Inventory Cards

### GET /api/v1/inventory/cards

Lists inventory cards showing stock quantities per shop with filtering options.

```bash
# List all inventory cards
curl -X GET "https://core.smartkasa.ua/api/v1/inventory/cards" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Filter by shop
curl -X GET "https://core.smartkasa.ua/api/v1/inventory/cards?shop_id=37916" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": [
    {
      "id": 10767,
      "count": "3.5",
      "counting_enabled": true,
      "owner_id": 103881,
      "product": {
        "id": "a327c691-1542-4b65-b8cd-05c51847bcad",
        "title": "Product Name",
        "price": "5483.0"
      },
      "product_id": "a327c691-1542-4b65-b8cd-05c51847bcad",
      "shop": {
        "id": 37916,
        "title": "Test shop"
      },
      "shop_id": 37916
    }
  ],
  "meta": {
    "total_count": 4
  }
}
```

### POST /api/v1/inventory/cards

Creates an inventory card to track product stock at a specific shop.

```bash
# Create inventory card
curl -X POST "https://core.smartkasa.ua/api/v1/inventory/cards" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "card": {
      "product_id": "a327c691-1542-4b65-b8cd-05c51847bcad",
      "shop_id": 37916,
      "count": 100.0,
      "counting_enabled": true
    }
  }'

# Response (201 Created):
{
  "data": {
    "id": 10776,
    "count": "100.0",
    "counting_enabled": true,
    "product_id": "a327c691-1542-4b65-b8cd-05c51847bcad",
    "shop_id": 37916
  },
  "meta": {}
}
```

## Product Subgroups

### POST /api/v1/inventory/product_subgroups

Creates a product subgroup for classification purposes.

```bash
# Create product subgroup
curl -X POST "https://core.smartkasa.ua/api/v1/inventory/product_subgroups" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "subgroup": {
      "title": "Premium Products"
    }
  }'

# Response (201 Created):
{
  "data": {
    "id": 7279,
    "title": "Premium Products"
  },
  "meta": {}
}
```

## Batch Operations

### POST /api/v1/inventory/categories/batch

Creates multiple categories in a single request for efficient bulk operations.

```bash
# Batch create categories
curl -X POST "https://core.smartkasa.ua/api/v1/inventory/categories/batch" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "batch": {
      "categories": [
        {"title": "Category 1", "color": 2},
        {"title": "Category 2", "color": 3},
        {"title": "Category 3", "color": 4}
      ]
    }
  }'

# Response (201 Created):
{
  "data": [
    {"id": "3fa7df7a-c7e6-4f40-833b-e49e7ae5dc79", "title": "Category 1"},
    {"id": "26bb1a4c-f28b-4900-b7eb-34e4e8547144", "title": "Category 2"},
    {"id": "4f8c8f9d-de32-4e82-8629-2dbe8d3c1489", "title": "Category 3"}
  ],
  "meta": {}
}
```

### POST /api/v1/inventory/products/batch

Creates multiple products in a single request.

```bash
# Batch create products
curl -X POST "https://core.smartkasa.ua/api/v1/inventory/products/batch" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "batch": {
      "products": [
        {
          "number": "6930426566",
          "title": "Coffee 1kg",
          "price": 299.99,
          "unit_type_id": 0,
          "tax_group_id": 1,
          "category_id": "b3c286e0-1823-4c2b-a850-12f7fd921020"
        },
        {
          "number": "6930426567",
          "title": "Tea 500g",
          "price": 189.50,
          "unit_type_id": 0,
          "tax_group_id": 1,
          "category_id": "b3c286e0-1823-4c2b-a850-12f7fd921020"
        }
      ]
    }
  }'

# Response (201 Created):
{
  "data": [
    {"id": "be7fd16e-25b4-4389-996d-08b80f69d6c5"},
    {"id": "6e7b9e4d-d47d-481b-ae53-b5e751454a2d"}
  ],
  "meta": {}
}
```

## Import

### POST /api/v1/inventory/import_products

Starts a product import job from an external file URL.

```bash
# Start product import
curl -X POST "https://core.smartkasa.ua/api/v1/inventory/import_products" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "import": {
      "url": "https://example.com/products.csv",
      "category_id": "992670be-c998-4169-a62c-63bfe2a4e1a0"
    }
  }'

# Response (201 Created):
{
  "data": {
    "id": 584,
    "created_count": 0,
    "filename": "products.csv",
    "products_count": 0,
    "state": 0,
    "updated_count": 0
  },
  "meta": {}
}
```

### GET /api/v1/inventory/import_products/{id}

Retrieves the status of an import job including progress and results.

```bash
# Check import status
curl -X GET "https://core.smartkasa.ua/api/v1/inventory/import_products/584" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": {
    "id": 584,
    "created_count": 150,
    "products_count": 150,
    "state": 1,
    "updated_count": 0,
    "results": {}
  },
  "meta": {}
}
```

## Shifts

### GET /api/v1/pos/shifts

Lists fiscal and trade shifts with comprehensive filtering including terminal, state, and date ranges.

```bash
# List all shifts
curl -X GET "https://core.smartkasa.ua/api/v1/pos/shifts" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Filter by terminal
curl -X GET "https://core.smartkasa.ua/api/v1/pos/shifts?terminal_id=19987&state=0" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": [
    {
      "id": "03bc8594-bf71-4ee0-b3ee-27f35379cf8d",
      "cash_balance": "0.99",
      "closed_at": null,
      "closed_by": null,
      "device_uid": "78b341e8-a400-4c5d-a5ad-2d4ab7b816a2",
      "employee_id": null,
      "fiscal_number": "Shift fiscal number",
      "opened_at": "2021-03-22T11:52:05.594+02:00",
      "opened_by": "John Doe",
      "registrar_fiscal_number": null,
      "remote_shift_id": "67969f57-f512-4a46-b6eb-df71020008bb",
      "state": 0,
      "terminal_id": 19987,
      "terminal_user_id": null
    }
  ],
  "meta": {
    "total_count": 4
  }
}
```

## Receipts

### GET /api/v1/pos/receipts

Lists sales receipts with extensive filtering options including shift, shop, terminal, state, and fiscal numbers.

```bash
# List all receipts
curl -X GET "https://core.smartkasa.ua/api/v1/pos/receipts" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Filter by shop and state
curl -X GET "https://core.smartkasa.ua/api/v1/pos/receipts?shop_id=13&state=2&page=1&per_page=10" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": [
    {
      "id": "4683e036-598e-44a5-9d89-00a92c9728c9",
      "cashier_name": "John Doe",
      "created_at": "2021-07-06T20:26:14.730+00:00",
      "discount_amount": "0.0",
      "fiscal_number": "16773376",
      "is_hidden": false,
      "items": [
        {
          "id": "e3a4acdd-49af-4346-ad9a-8bd4e5860d0d",
          "amount": "1438.0",
          "name": "Product Name",
          "price": "1438.0",
          "quantity": "1.0",
          "tax_group_id": 6,
          "unit_type_name": "pc"
        }
      ],
      "payment_transactions": [
        {
          "id": "7d523a18-e812-43f3-beb5-85a0029f5f86",
          "amount": "1438.0",
          "deposit_amount": "1438.0",
          "payment_type_id": 0,
          "transaction_type_id": 0,
          "state": 1
        }
      ],
      "registrar_fiscal_number": "4000026885",
      "shop_id": 13,
      "state": 2,
      "tax_amount": {"A": 22825, "Z": 6848},
      "total_amount": "1438.0",
      "type": 0
    }
  ],
  "meta": {
    "total_count": 2
  }
}
```

### POST /api/v1/pos/receipts

Creates a new sales receipt with line items and payment information.

```bash
# Create new receipt
curl -X POST "https://core.smartkasa.ua/api/v1/pos/receipts" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "receipt": {
      "title": "Sale Receipt",
      "total_amount": 145,
      "state": 2,
      "type": 0,
      "discount_amount": 15,
      "seller_id": 1,
      "shift_id": null,
      "fiscal_number": "123456789012345",
      "registrar_fiscal_number": "123456789054321",
      "cashier_name": "John Doe",
      "description": "Sale description",
      "tax_amount": {"A": 23.5},
      "is_hidden": false,
      "items": [
        {
          "name": "Product Name",
          "price": 70.5,
          "amount": 246.75,
          "quantity": 3.5,
          "sku": "SKU-001",
          "tax_group_id": 1,
          "is_product": true,
          "product_id": "db8b8402-cd2a-4ad1-947f-bc521ca5f13f",
          "stock_item_id": 1,
          "unit_type_id": 0,
          "description": "Item description"
        }
      ]
    }
  }'

# Response (201 Created):
{
  "data": {
    "id": "f1b49979-5d30-4110-b6a4-bdfaba716394",
    "cashier_name": "John Doe",
    "total_amount": "145.0",
    "state": 2,
    "type": 0,
    "items": [
      {
        "id": "604efa83-e492-416b-9979-eca560d98c09",
        "amount": "246.75",
        "name": "Product Name",
        "price": "70.5",
        "quantity": "3.5"
      }
    ]
  },
  "meta": {}
}
```

### POST /api/v1/pos/receipts/batch

Creates multiple receipts in a single request for bulk transaction processing.

```bash
# Batch create receipts
curl -X POST "https://core.smartkasa.ua/api/v1/pos/receipts/batch" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "batch": {
      "receipts": [
        {
          "title": "Receipt 1",
          "total_amount": 100,
          "state": 2,
          "type": 0,
          "items": [{"name": "Item 1", "price": 100, "amount": 100, "quantity": 1}]
        },
        {
          "title": "Receipt 2",
          "total_amount": 200,
          "state": 2,
          "type": 0,
          "items": [{"name": "Item 2", "price": 200, "amount": 200, "quantity": 1}]
        }
      ]
    }
  }'

# Response (201 Created):
{
  "data": [
    {"id": "5e815780-27f8-4d39-a3f7-72a3675199b7", "total_amount": "100.0"},
    {"id": "29c5507b-c757-472a-8ae3-26820ed99c35", "total_amount": "200.0"}
  ],
  "meta": {}
}
```

## Reports

### GET /api/v1/reports/z-reports

Retrieves Z-reports (daily fiscal closure reports) required for Ukrainian tax compliance.

```bash
# Get Z-reports for date range
curl -X GET "https://core.smartkasa.ua/api/v1/reports/z-reports?date_start=2021-08-01&date_end=2021-08-31&shop_id=155" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": [
    {
      "id": 51,
      "cash_amount": 0,
      "cash_receipts_count": 4,
      "cash_total": 12276.25,
      "created_at": "2021-08-06T13:23:09.020+00:00",
      "fiscal_number": "7069483",
      "payload": {
        "cash": {"total": 12276.25, "commission": 0, "receipts_count": 4},
        "cashierName": "Andriy Mykolayovych Solopchuk",
        "fiscalNumber": "7069483",
        "registrarFiscalNumber": "4000026885"
      },
      "refund_total": 0,
      "registrar_fiscal_number": "4000026885",
      "sale_total": 0,
      "service_input": 0,
      "service_output": 0,
      "shift": {
        "id": "55dc9a5e-9308-4bfc-a3b7-382a67667aa9",
        "cash_balance": "0.99",
        "opened_by": "John Doe",
        "state": 0
      },
      "shift_id": "55dc9a5e-9308-4bfc-a3b7-382a67667aa9",
      "shop_id": 155,
      "terminal_id": 297,
      "terminal_user_name": "Shchastyslay Pavlenko"
    }
  ],
  "meta": {
    "total_count": 1
  }
}
```

### GET /api/v1/stats/product_daily_sales/alter

Retrieves daily product sales statistics with popularity rankings.

```bash
# Get product sales statistics
curl -X GET "https://core.smartkasa.ua/api/v1/stats/product_daily_sales/alter?date_start=2021-01-01&date_end=2021-12-31&shop_id=155" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token"

# Response (200 OK):
{
  "data": {
    "id": 0,
    "products": [
      {
        "id": "53dc610f-f9c2-4c96-a9bf-663c3fe2f780",
        "category_id": "c73aeff8-b54a-42be-a498-f3b31d40eb77",
        "number": "1516986502",
        "popularity": "100.0",
        "price": "8677.0",
        "title": "Product Name",
        "total_amount": "75.6",
        "total_count": "1.5",
        "unit_type_id": 0
      }
    ],
    "total_amount": 75.6,
    "total_count": 1.5
  },
  "meta": {}
}
```

## Data Types Reference

### Tax Groups (tax_group_id)

| Value | Code | Rate | Description |
|-------|------|------|-------------|
| 0 | - | - | Default/no tax group |
| 1 | A | 20% | VAT 20% |
| 2 | B | 7% | VAT 7% |
| 3 | V | 0% | VAT 0% |
| 4 | G | - | No VAT |
| 5 | D | 5% | Excise 5% |
| 6 | - | - | Excise 5% + VAT 20% |

### Receipt States

| Value | Description |
|-------|-------------|
| 1 | Draft (pending) |
| 2 | Completed (paid) |
| 3 | Refund |

### Receipt Types

| Value | Description |
|-------|-------------|
| 0 | Sale |
| 1 | Service input |
| 2 | Service output |
| 3 | Refund |
| 4 | Cancel |
| 5 | Cash withdrawal |

### Transaction Types

| Value | Description |
|-------|-------------|
| 0 | Cash |
| 1 | Card |
| 2 | Acquiring |
| 3 | Bank transfer (IBAN) |
| 4 | Card transfer |

## Summary

SmartKasa API is designed for Ukrainian retail businesses requiring fiscal compliance with the State Tax Service. The primary use cases include managing multiple retail locations (shops), tracking inventory across locations with inventory cards, processing sales transactions with proper tax calculations, managing employees with POS access controls, and generating fiscal reports (Z-reports) required for tax compliance. The API supports both individual operations and batch processing for efficient bulk data management.

Integration patterns typically involve authenticating with API key and user credentials, managing shop and terminal configurations, importing or creating products with proper tax classifications, processing sales through receipts with line items and payment transactions, and generating reports for accounting and tax compliance. All list endpoints support pagination with consistent metadata, and error responses follow a standard format making error handling straightforward. The API uses UUIDs for most resource identifiers and supports filtering and searching across all major resource types.