# SmartKasa API Documentation

SmartKasa API (v1.0.18) is a comprehensive REST API for Ukrainian retail businesses that provides complete point-of-sale (POS) management functionality. The system enables fiscal cash register operations compliant with Ukrainian State Tax Service requirements, while offering robust inventory management, employee administration, and sales reporting capabilities. Built for integration with retail software, mobile applications, and e-commerce platforms, SmartKasa serves as the backbone for modern retail operations in Ukraine.

The API operates at `https://core.smartkasa.ua` and uses JSON for all data exchange. Authentication is handled through two-tier headers: an `X-API-KEY` for API access and a JWT-based `Authorization` token for user-specific operations. The platform manages 13 core functional areas including authentication, terminal configuration, shop management, product cataloging, inventory tracking, POS transactions, shift management, and comprehensive fiscal reporting including mandatory Z-reports for tax compliance.

## API Endpoints and Functions

### User Authentication and Session Management

Create a new authenticated session using phone number and password credentials to obtain access and refresh tokens for subsequent API calls.

```bash
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 '{
    "phone_number": "380960000006",
    "password": "123456789"
  }'

# Success Response (201 Created)
{
  "data": {
    "id": null,
    "access": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MTY0MTc0OTcsInVzZXJfdHlwZV9pZCI6MSwib3duZXJfaWQiOjEwMzc1Nywicm9sZV9pZCI6bnVsbCwic2Vzc2lvbl90b2tlbiI6ImYxY2JmNWE1LTJkNDUtNGRjNi1hZDJhLTk0ZmUyZTZjM2ZkZSIsInVzZXJfaWQiOjEwMzc1NywidWlkIjoiZDU2OTM4YmMtMjU4Mi00YTJiLWFmZDgtMDk1ZmYyMjdmYjhkIiwiZXhwIjoxNjE2NTAwMjk3fQ.Y87pAVTWIGE7EWMdSgOSt4LSHaV4Ry_YQDfeL7RkKos",
    "access_expires_at": "2021-03-23T13:51:37.000+02:00",
    "csrf": "aPhV1ZNQyuoTStIlnw7PlSGU8jRMzhsu3voUrIxYmnJqZmzDGzYizlHIjGqGBbrTVfxJOQU98g+EAkcv9wRsJg==",
    "refresh": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MTY0MTc0OTcsInNlc3Npb25fdG9rZW4iOiJmMWNiZjVhNS0yZDQ1LTRkYzYtYWQyYS05NGZlMmU2YzNmZGUiLCJ1c2VyX2lkIjoxMDM3NTcsInVpZCI6Ijc5NWY0YWYzLWQ4MjUtNDUwYi1iZmJhLTVkZjFkZWRkNDg1MyIsImV4cCI6MTYxOTA0MzY0M30.oWTtZguR4e1LkAhWen8W8iKPWiit5xHW3cyu98EXtqg",
    "refresh_expires_at": "2021-04-22T01:20:43.000+03:00"
  },
  "meta": {}
}

# Error Response (422 Unprocessable Entity)
{
  "errors": {
    "base": [
      {"error": "phone_number_or_password_invalid"}
    ]
  }
}
```

### Refresh Authentication Token

Renew an expired access token using the refresh token to maintain continuous authenticated access without requiring user login.

```bash
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 "Authorization: Bearer your_refresh_token_here" \
  -d '{}'

# Success Response (201 Created)
{
  "data": {
    "id": null,
    "access": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2NzY5ODI3NjMsInVzZXJfdHlwZV9pZCI6MCwib3duZXJfaWQiOjk1LCJyb2xlX2lkIjpudWxsLCJzZXNzaW9uX3Rva2VuIjoiZjViNmJjODUtODI1My00MTdmLWJiMmMtMzMyYTZhOGU1NGE5IiwidXNlcl9pZCI6OTUsInVpZCI6ImRiYzhmYWMwLTBjMjctNDgwOS1hZGUxLTA2OGM0NTZmM2ZhNiIsImV4cCI6MTY3OTYwODkwOX0.HOjLHycrS62i7UqMPcXB4EMI2qpOdqINLHkbj92wXSo",
    "access_expires_at": "2023-03-23T22:01:49.000+00:00",
    "csrf": "xMt3hxr41k+snNPbQnKYF1FwAYA+PmRn7OrJh/tRVypD3mFX9/F/FtzIER55VXAwWpwHI6dxcpt083v0rKqYAw==",
    "refresh": "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2NzY5ODI3NjMsInNlc3Npb25fdG9rZW4iOiJmNWI2YmM4NS04MjUzLTQxN2YtYmIyYy0zMzJhNmE4ZTU0YTkiLCJ1c2VyX2lkIjo5NSwidWlkIjoiNDgwNTk1ZTItZmI3Yi00OGJmLWI0ZjUtZmViMThmOWZiODdkIiwiZXhwIjoxNjc5NjA4OTA5fQ.Kj7rUy9nFrljQjDJVifPSQnNZienDaSTV-CGj1QsPSg",
    "refresh_expires_at": "2023-03-23T22:01:49.000+00:00"
  },
  "meta": {}
}
```

### Logout and Terminate Session

Close the current user session and invalidate all associated authentication tokens for security purposes.

```bash
curl -X DELETE https://core.smartkasa.ua/api/v1/auth/sessions/logout \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token_here"

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

### Retrieve POS Terminal List

Query all POS terminals with optional filtering by shop, name, or terminal ID, with pagination support for large datasets.

```bash
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_here"

# Success 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
  }
}
```

### Update Terminal Configuration

Modify terminal settings including name and shop assignment with proper validation and error handling.

```bash
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_here" \
  -d '{
    "name": "Updated Terminal Name",
    "shop_id": 37964
  }'

# Success Response (200 OK)
{
  "data": {
    "id": 20012,
    "activated_at": null,
    "core_terminal_id": 1,
    "created_at": "2021-03-22T13:52:06.675+02:00",
    "name": "Updated Terminal Name",
    "picture": {
      "id": "5889920bac63c1660e25da2592a61889",
      "filename": "test.png",
      "mime_type": "image/png",
      "size": 8132,
      "url": "/uploads/store/5889920bac63c1660e25da2592a61889"
    },
    "properties": null,
    "serial_number": "863684811804753",
    "shop_id": 37964,
    "state": 1,
    "updated_at": "2021-03-22T13:52:06.675+02:00"
  },
  "meta": {}
}

# Error Response (422 Unprocessable Entity)
{
  "errors": "[Pos::TerminalForm.new] \"wrong\" (String) has invalid type for :shop_id violates constraints (invalid value for Integer(): \"wrong\" failed)"
}
```

### Create New Shop Location

Register a new retail shop with complete address, contact information, and fiscal configuration settings for tax compliance.

```bash
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_here" \
  -d '{
    "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": "Київ",
      "content": "вул. Хрещатик, 1"
    }
  }'

# Success Response (201 Created)
{
  "data": {
    "id": 37968,
    "address": {
      "id": 38196,
      "address_type_id": 0,
      "city_name": "Київ",
      "content": "вул. Хрещатик, 1",
      "created_at": "2021-03-22T13:52:08.158+02:00",
      "updated_at": "2021-03-22T13:52:08.158+02:00",
      "zip_code": "01001"
    },
    "business_category_id": 1,
    "created_at": "2021-03-22T13:52:08.148+02:00",
    "email": "downtown@store.com",
    "employees_count": 0,
    "fiscal_numbers": [],
    "fiscalization_enabled": false,
    "is_excise_taxation": false,
    "is_vat_taxation": true,
    "owner_id": 1,
    "phone_number": "380971234567",
    "state": 0,
    "terminals_count": 0,
    "title": "Downtown Store",
    "updated_at": "2021-03-22T13:52:08.148+02:00",
    "website_url": "https://www.downtown-store.com"
  },
  "meta": {}
}
```

### Create Product in Catalog

Add a new product to the inventory system with pricing, tax configuration, barcode classification, and category assignment.

```bash
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_here" \
  -d '{
    "number": "6930426566",
    "title": "Premium Coffee Beans 1kg",
    "unit_type_id": 0,
    "portion_amount": 1000,
    "portion_type_id": 0,
    "price": 299.99,
    "procurement_price": 150.00,
    "classifier_type_id": 2,
    "classifier_code": "543210123456789",
    "tax_group_id": 1,
    "category_id": "992670be-c998-4169-a62c-63bfe2a4e1a0",
    "category_type_id": 2201372,
    "sold_by_weight": false,
    "bookmark_ids": [],
    "user_id": 103930,
    "owner_id": 103929
  }'

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

# Error Response (422 Unprocessable Entity)
{
  "errors": {
    "title": [
      {"error": "blank"}
    ]
  }
}
```

### Get Product Details with Inventory

Retrieve comprehensive product information including associated inventory cards across multiple shop locations with current stock levels.

```bash
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_here"

# Success Response (200 OK)
{
  "data": {
    "id": "f747fbc5-4782-4489-92b4-51691dea1f63",
    "alter_number": null,
    "alter_title": null,
    "bookmark_ids": [],
    "cards": [
      {
        "id": 10789,
        "count": "100.0",
        "counting_enabled": true,
        "created_at": "2021-03-22T13:51:50.148+02:00",
        "owner_id": null,
        "product_id": "f747fbc5-4782-4489-92b4-51691dea1f63",
        "shop_id": 37933,
        "updated_at": "2021-03-22T13:51:50.148+02:00"
      }
    ],
    "category": {
      "id": "72c1f7f7-751d-4caf-a0c7-5c8b0314a9f2",
      "color_id": 0,
      "created_at": "2021-03-22T13:51:50.110+02:00",
      "parent_id": null,
      "partner_id": 7711,
      "products_count": 0,
      "title": "Beverages",
      "updated_at": "2021-03-22T13:51:50.110+02:00"
    },
    "category_id": "72c1f7f7-751d-4caf-a0c7-5c8b0314a9f2",
    "category_type_id": 9000681,
    "classifier_code": "123456789012345",
    "classifier_type_id": 1,
    "created_at": "2021-03-22T13:51:50.114+02:00",
    "is_free_price": false,
    "is_without_number": false,
    "number": "1481689397",
    "owner_id": 103937,
    "picture": {
      "id": "6dc1f53c8138e3001bb3099f8d04dc8d",
      "filename": "product.png",
      "mime_type": "image/png",
      "size": 8132,
      "url": "/uploads/store/6dc1f53c8138e3001bb3099f8d04dc8d"
    },
    "portion_amount": 800,
    "portion_type_id": 0,
    "price": "7829.0",
    "procurement_price": "100.0",
    "sold_by_weight": false,
    "subgroup_id": null,
    "tax_amount": {
      "А": 540
    },
    "tax_group_id": 1,
    "title": "Premium Item",
    "unit_type_id": 0,
    "unit_type_name": null,
    "updated_at": "2021-03-22T13:51:50.114+02:00",
    "user_id": 103938
  },
  "meta": {}
}
```

### Create Sales Receipt

Generate a new sales receipt with line items, calculate taxes, apply discounts, and record fiscal information for tax compliance.

```bash
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_here" \
  -d '{
    "title": "Customer Purchase #1234",
    "total_amount": 145.00,
    "state": 2,
    "type": 0,
    "discount_amount": 15.00,
    "seller_id": 1,
    "shift_id": null,
    "fiscal_number": "123456789012345",
    "registrar_fiscal_number": "123456789054321",
    "cashier_name": "Jane Doe",
    "description": "Regular sale transaction",
    "tax_amount": {
      "А": 23.50
    },
    "is_hidden": false,
    "items": [
      {
        "name": "Coffee Premium Blend",
        "price": 70.50,
        "amount": 246.75,
        "quantity": 3.5,
        "sku": "COFFEE-001",
        "tax_group_id": 1,
        "is_product": true,
        "product_id": "db8b8402-cd2a-4ad1-947f-bc521ca5f13f",
        "stock_item_id": 1,
        "unit_type_id": 0,
        "description": "Premium coffee blend 250g"
      }
    ]
  }'

# Success Response (201 Created)
{
  "data": {
    "id": "f1b49979-5d30-4110-b6a4-bdfaba716394",
    "cashier_name": "Jane Doe",
    "created_at": "2021-03-22T13:52:04.694+02:00",
    "description": "Regular sale transaction",
    "discount_amount": "15.0",
    "discount_percentage": null,
    "fiscal_number": "123456789012345",
    "is_hidden": false,
    "items": [
      {
        "id": "604efa83-e492-416b-9979-eca560d98c09",
        "amount": "246.75",
        "classifier_code": null,
        "classifier_type_id": 0,
        "created_at": "2021-03-22T13:52:04.694+02:00",
        "description": "Premium coffee blend 250g",
        "discount_amount": null,
        "is_free_price": false,
        "is_product": true,
        "name": "Coffee Premium Blend",
        "price": "70.5",
        "product_id": "db8b8402-cd2a-4ad1-947f-bc521ca5f13f",
        "quantity": "3.5",
        "receipt_id": "f1b49979-5d30-4110-b6a4-bdfaba716394",
        "sku": "COFFEE-001",
        "stock_item_id": 1,
        "tax_group_id": 1,
        "unit_type_id": 0,
        "unit_type_name": null,
        "updated_at": "2021-03-22T13:52:04.694+02:00"
      }
    ],
    "offline_id": null,
    "offline_local_number": null,
    "offline_seed": null,
    "previous_receipt_hash": null,
    "registrar_fiscal_number": "123456789054321",
    "registrar_local_number": null,
    "related_fiscal_number": null,
    "rounding_amount": null,
    "seller_id": 1,
    "shift_id": null,
    "shop_id": null,
    "state": 2,
    "tax_amount": {
      "А": 23.5
    },
    "terminal_id": null,
    "terminal_shift_id": null,
    "title": "Customer Purchase #1234",
    "total_amount": "145.0",
    "type": 0,
    "updated_at": "2021-03-22T13:52:04.694+02:00"
  },
  "meta": {}
}
```

### Query Receipt History with Payments

Search receipts with payment transaction details, supporting filters by shop, terminal, fiscal number, state, and date range.

```bash
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_here"

# Success Response (200 OK)
{
  "data": [
    {
      "id": "4683e036-598e-44a5-9d89-00a92c9728c9",
      "cashier_name": "John Doe",
      "created_at": "2021-07-06T20:26:14.730+00:00",
      "description": null,
      "discount_amount": "0.0",
      "discount_percentage": "0.0",
      "discount_type_id": 0,
      "fiscal_number": "16773376",
      "is_hidden": false,
      "items": [
        {
          "id": "e3a4acdd-49af-4346-ad9a-8bd4e5860d0d",
          "amount": "1438.0",
          "classifier_code": "123",
          "classifier_type_id": 1,
          "created_at": "2021-07-06T23:26:14.728+00:00",
          "description": "",
          "discount_amount": null,
          "is_free_price": false,
          "is_product": true,
          "name": "Алкоголь",
          "price": "1438.0",
          "product_id": "f3ba907b-c718-4949-91ee-4dfdfa88d12c",
          "quantity": "1.0",
          "receipt_id": "4683e036-598e-44a5-9d89-00a92c9728c9",
          "sku": null,
          "sold_by_weight": false,
          "stock_item_id": 1,
          "tax_group_id": 6,
          "unit_type_id": 2009,
          "unit_type_name": "шт",
          "updated_at": "2021-07-06T23:26:14.728+00:00"
        }
      ],
      "offline_id": 0,
      "offline_local_number": null,
      "offline_seed": "",
      "payment_transactions": [
        {
          "id": "7d523a18-e812-43f3-beb5-85a0029f5f86",
          "amount": "1438.0",
          "approval_code": null,
          "batch": null,
          "change_amount": "0.0",
          "created_at": "2021-07-06T20:26:16.151+00:00",
          "deposit_amount": "1438.0",
          "description": null,
          "pan": null,
          "pan_hash": null,
          "payload": null,
          "payment_type_id": 0,
          "receipt_id": "4683e036-598e-44a5-9d89-00a92c9728c9",
          "result_code": null,
          "rrn": "162Q560ZQ3I174JY431",
          "signature": false,
          "stan": null,
          "state": 1,
          "timestamp": "2021-07-06T20:26:14.433+00:00",
          "transaction_type_id": 0,
          "updated_at": "2021-07-06T20:26:16.151+00:00"
        }
      ],
      "previous_receipt_hash": null,
      "registrar_fiscal_number": "4000026885",
      "registrar_local_number": null,
      "related_fiscal_number": null,
      "rounding_amount": "0.0",
      "seller_id": 0,
      "shift_id": "77890312-1312-4c57-a0fe-c57352678f45",
      "shop_id": 13,
      "state": 2,
      "tax_amount": {
        "А": 22825,
        "З": 6848
      },
      "terminal_id": null,
      "terminal_shift_id": null,
      "title": "",
      "total_amount": "1438.0",
      "type": 0,
      "updated_at": "2021-07-06T20:26:14.730+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 2,
    "limit_value": 10,
    "offset_value": 0
  }
}
```

### Retrieve Shift Information

Access cash register shift details including open/close times, cash balance, fiscal numbers, and associated employee information.

```bash
curl -X GET "https://core.smartkasa.ua/api/v1/pos/shifts?terminal_id=19987&state=0&page=1" \
  -H "X-API-KEY: your_api_key_here" \
  -H "Authorization: Bearer your_access_token_here"

# Success 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": "Current Shift",
      "opened_at": "2021-03-22T11:52:05.594+02:00",
      "opened_by": "John Dow",
      "registrar_fiscal_number": null,
      "remote_shift_id": "67969f57-f512-4a46-b6eb-df71020008bb",
      "state": 0,
      "terminal_id": 19987,
      "terminal_user_id": null
    },
    {
      "id": "d968a02d-7164-4660-9834-13ca752dd5ce",
      "cash_balance": "0.99",
      "closed_at": "2021-03-22T13:47:05.596+02:00",
      "closed_by": "John Dow",
      "device_uid": "78b341e8-a400-4c5d-a5ad-2d4ab7b816a2",
      "employee_id": null,
      "fiscal_number": "Previous Shift",
      "opened_at": "2021-03-22T11:52:05.596+02:00",
      "opened_by": "John Dow",
      "registrar_fiscal_number": null,
      "remote_shift_id": "14361e4f-c05e-4f01-84e1-8af2b2cca2aa",
      "state": 1,
      "terminal_id": 19987,
      "terminal_user_id": null
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 4,
    "limit_value": 25,
    "offset_value": 0
  }
}
```

### Get Fiscal Z-Reports

Retrieve daily fiscal closure reports (Z-reports) containing sales summaries, tax calculations, payment breakdowns, and shift information for tax authority compliance.

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

# Success 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
        },
        "timestamp": "1618495142092",
        "cash_amount": 0,
        "cashierName": "Андрій Миколайович Солопчук",
        "fiscalNumber": "7069483",
        "service_input": 0,
        "service_output": 0,
        "turnover_amount": 0,
        "registrarLocalNumber": "1",
        "registrarFiscalNumber": "4000026885"
      },
      "refund_cash_total": 0,
      "refund_cashless_total": 0,
      "refund_receipts_count": 0,
      "refund_tax_a_total": 0,
      "refund_tax_b_total": 0,
      "refund_tax_d_total": 0,
      "refund_tax_v_total": 0,
      "refund_tax_z_total": 0,
      "refund_total": 0,
      "registrar_fiscal_number": "4000026885",
      "sale_cash_total": 0,
      "sale_cashless_total": 0,
      "sale_receipts_count": 0,
      "sale_tax_a_total": 0,
      "sale_tax_b_total": 0,
      "sale_tax_d_total": 0,
      "sale_tax_v_total": 0,
      "sale_tax_z_total": 0,
      "sale_total": 0,
      "service_input": 0,
      "service_output": 0,
      "shift": {
        "id": "55dc9a5e-9308-4bfc-a3b7-382a67667aa9",
        "cash_balance": "0.99",
        "closed_at": null,
        "closed_by": null,
        "device_uid": "8133c494-7c2f-4441-b913-20cfd06e1eda",
        "employee_id": null,
        "fiscal_number": "Current Shift",
        "opened_at": "2021-08-09T08:23:08.995+00:00",
        "opened_by": "John Dow",
        "registrar_fiscal_number": null,
        "remote_shift_id": "5b3ab3a8-7ddf-4d7a-a45a-109745043314",
        "state": 0,
        "terminal_id": null,
        "terminal_user_id": 46
      },
      "shift_id": "55dc9a5e-9308-4bfc-a3b7-382a67667aa9",
      "shop": {
        "id": 155,
        "business_category_id": 1,
        "created_at": "2021-08-09T13:23:09.000+00:00",
        "email": "maynard@renner.info",
        "employees_count": 0,
        "fiscal_numbers": [],
        "fiscalization_enabled": false,
        "is_excise_taxation": false,
        "is_vat_taxation": true,
        "owner_id": 1025,
        "phone_number": "0971234567",
        "state": 0,
        "terminals_count": 0,
        "title": "Test shop",
        "updated_at": "2021-08-09T13:23:09.000+00:00",
        "website_url": "https://www.example.com"
      },
      "shop_id": 155,
      "terminal_id": 297,
      "terminal_user_name": "Щастислав Павленко",
      "turnover_amount": 0
    }
  ],
  "meta": {
    "current_page": 1,
    "next_page": null,
    "prev_page": null,
    "total_pages": 1,
    "total_count": 1,
    "limit_value": 25,
    "offset_value": 0
  }
}
```

### Batch Product Import

Create multiple products simultaneously with a single API call for efficient bulk catalog updates and inventory initialization.

```bash
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_here" \
  -d '{
    "products": [
      {
        "number": "6930426566",
        "title": "Premium Coffee Beans 1kg",
        "unit_type_id": 0,
        "portion_amount": 1000,
        "portion_type_id": 0,
        "price": 299.99,
        "procurement_price": 150.00,
        "classifier_type_id": 2,
        "classifier_code": "543210123456789",
        "tax_group_id": 1,
        "category_id": "b3c286e0-1823-4c2b-a850-12f7fd921020",
        "category_type_id": 2938762,
        "sold_by_weight": false,
        "bookmark_ids": []
      },
      {
        "number": "6930426567",
        "title": "Organic Green Tea 500g",
        "unit_type_id": 0,
        "portion_amount": 500,
        "portion_type_id": 0,
        "price": 189.50,
        "procurement_price": 95.00,
        "classifier_type_id": 2,
        "classifier_code": "543210123456790",
        "tax_group_id": 1,
        "category_id": "b3c286e0-1823-4c2b-a850-12f7fd921020",
        "category_type_id": 2938762,
        "sold_by_weight": false,
        "bookmark_ids": []
      },
      {
        "number": "6930426568",
        "title": "Espresso Blend 250g",
        "unit_type_id": 0,
        "portion_amount": 250,
        "portion_type_id": 0,
        "price": 149.00,
        "procurement_price": 75.00,
        "classifier_type_id": 2,
        "classifier_code": "543210123456791",
        "tax_group_id": 1,
        "category_id": "b3c286e0-1823-4c2b-a850-12f7fd921020",
        "category_type_id": 2938762,
        "sold_by_weight": false,
        "bookmark_ids": []
      }
    ]
  }'

# Success Response (201 Created)
{
  "data": [
    {"id": "be7fd16e-25b4-4389-996d-08b80f69d6c5"},
    {"id": "6e7b9e4d-d47d-481b-ae53-b5e751454a2d"},
    {"id": "a9c3f8e1-7b2d-4c19-8e44-d3f590ae7c12"}
  ],
  "meta": {}
}

# Error Response (422 Unprocessable Entity)
{
  "errors": {
    "products": [
      {
        "error": "invalid",
        "messages": "title: Не може бути пустим"
      }
    ]
  }
}
```

## Summary and Integration Patterns

The SmartKasa API serves as a complete backend infrastructure for retail operations in Ukraine, providing businesses with the tools needed to manage multi-location retail chains, process transactions with full fiscal compliance, and maintain accurate inventory across their operations. Primary use cases include integrating e-commerce platforms with physical POS systems to maintain synchronized inventory, building custom mobile POS applications for field sales, creating automated reporting dashboards for business analytics, implementing loyalty programs with real-time transaction tracking, and connecting accounting software to automatically reconcile daily sales with fiscal requirements. The API's comprehensive shift management and Z-report generation ensure businesses meet Ukrainian State Tax Service mandates while streamlining end-of-day procedures.

Integration follows a standard OAuth-style flow where applications first authenticate with `X-API-KEY` credentials, then obtain user-specific JWT tokens through the sessions endpoint for all subsequent operations. The API uses consistent JSON request/response patterns with standardized error handling across all endpoints, making it straightforward to build robust integrations with proper retry logic and error recovery. Pagination is uniform across list endpoints using `page` and `per_page` parameters with comprehensive metadata for navigation. Key integration patterns include webhook-style polling for receipt status updates, batch operations for inventory synchronization during off-peak hours, hierarchical data modeling where shops contain terminals which contain shifts which contain receipts, and careful transaction sequencing where products must exist before inventory cards can be created before receipts can reference them. The fiscal_number and registrar_fiscal_number fields throughout the API ensure all operations maintain audit trails for tax compliance purposes.