Iiko Cloud API (salesduck/iiko-cloud-api)

Iiko Cloud API

https://github.com/salesduck/iiko-cloud-api
Admin
A TypeScript library providing auto-generated types and schemas for the iiko Cloud API, enabling...

Tokens:11,865
Snippets:41
Trust Score:3.6
Update:2 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# iiko Cloud API TypeScript Types

The `@salesduck/iiko-cloud-api` library provides TypeScript type definitions for the iiko Cloud API, a comprehensive restaurant management and POS system. These types are auto-generated from the official iiko OpenAPI specification using `openapi-typescript`, ensuring full compatibility with the iiko Cloud API endpoints for authentication, deliveries, orders, menu management, loyalty programs, and terminal group operations.

This library is designed to enable type-safe development when building custom REST clients for iiko Cloud. It exports `paths` for API endpoint type definitions and `schemas` for request/response body types. The types cover all major iiko Cloud API v1 and v2 endpoints including organization management, delivery operations, table orders, nomenclature/menu retrieval, employee management, reservations, loyalty/customer programs, and webhook configurations.

## Installation

```bash
yarn add @salesduck/iiko-cloud-api
```

## Authentication - Get Access Token

Retrieve a session key (access token) for authenticating subsequent API calls. The token is required in the Authorization header for all protected endpoints.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
});

// Type definitions
type AccessTokenRequest = components["schemas"]["iikoTransport.PublicApi.Contracts.Auth.GetAccessTokenRequest"];
type AccessTokenResponse = components["schemas"]["iikoTransport.PublicApi.Contracts.Auth.GetAccessTokenResponse"];

// Get access token
const { data, error } = await client.POST("/api/1/access_token", {
  body: {
    apiLogin: "your-api-login-key"
  } as AccessTokenRequest
});

if (data) {
  console.log("Token:", data.token);
  console.log("Correlation ID:", data.correlationId);
}
// Expected output: { token: "eyJ0eXAi...", correlationId: "abc123..." }
```

## Organizations - List Available Organizations

Returns all organizations available to the authenticated API user. This is typically the first call after authentication to get organization IDs for subsequent requests.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type OrganizationsRequest = components["schemas"]["iikoTransport.PublicApi.Contracts.Organizations.GetOrganizationsRequest"];
type OrganizationsResponse = components["schemas"]["iikoTransport.PublicApi.Contracts.Organizations.GetOrganizationsResponse"];

const { data, error } = await client.POST("/api/1/organizations", {
  body: {
    organizationIds: null, // null returns all organizations
    returnAdditionalInfo: true,
    includeDisabled: false
  } as OrganizationsRequest
});

if (data) {
  data.organizations?.forEach(org => {
    console.log(`ID: ${org.id}, Name: ${org.name}, Country: ${org.country}`);
  });
}
// Expected output: ID: 550e8400-e29b-41d4-a716-446655440000, Name: Restaurant ABC, Country: Russia
```

## Menu/Nomenclature - Get Menu Items

Retrieve the complete menu (nomenclature) for an organization including products, groups, sizes, and modifiers.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type NomenclatureRequest = components["schemas"]["iikoTransport.PublicApi.Contracts.Nomenclature.NomenclatureRequest"];
type NomenclatureResponse = components["schemas"]["iikoTransport.PublicApi.Contracts.Nomenclature.NomenclatureResponse"];

const { data, error } = await client.POST("/api/1/nomenclature", {
  body: {
    organizationId: "550e8400-e29b-41d4-a716-446655440000",
    startRevision: 0 // 0 for full menu, or revision number for delta updates
  } as NomenclatureRequest
});

if (data) {
  console.log("Revision:", data.revision);
  console.log("Groups:", data.groups?.length);
  console.log("Products:", data.products?.length);
  data.products?.forEach(product => {
    console.log(`- ${product.name}: ${product.sizePrices?.[0]?.price?.currentPrice} RUB`);
  });
}
// Expected output: Revision: 12345, Groups: 10, Products: 150
```

## External Menu - Get Menu with Price Categories (API v2)

Retrieve external menus with price category support using the newer v2 API endpoint.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type MenusResponse = components["schemas"]["iikoTransport.PublicApi.Contracts.Nomenclature.MenusDataResponse"];
type ExternalMenuPreset = components["schemas"]["ExternalMenuPreset"];

// Get list of external menus
const { data: menusData } = await client.POST("/api/2/menu");

if (menusData) {
  console.log("Available menus:", menusData.externalMenus?.length);
}

// Get specific menu by ID
type MenuRequest = components["schemas"]["iikoTransport.PublicApi.Contracts.Nomenclature.MenuRequest"];

const { data: menuData } = await client.POST("/api/2/menu/by_id", {
  body: {
    externalMenuId: 12345,
    organizationIds: ["550e8400-e29b-41d4-a716-446655440000"],
    priceCategoryId: null
  } as MenuRequest
});

if (menuData) {
  console.log("Menu name:", menuData.name);
  menuData.itemCategories?.forEach(cat => {
    console.log(`Category: ${cat.name}`);
  });
}
```

## Deliveries - Create Delivery Order

Create a new delivery order with customer information, items, and delivery address. This is an async command - use `/api/1/commands/status` to track progress.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type CreateDeliveryRequest = components["schemas"]["iikoTransport.PublicApi.Contracts.Deliveries.Request.CreateOrderRequest"];
type DeliveryResponse = components["schemas"]["iikoTransport.PublicApi.Contracts.Deliveries.Response.OrderResponse"];

const { data, error } = await client.POST("/api/1/deliveries/create", {
  body: {
    organizationId: "550e8400-e29b-41d4-a716-446655440000",
    terminalGroupId: "660e8400-e29b-41d4-a716-446655440001",
    order: {
      phone: "+79001234567",
      orderServiceType: "DeliveryByCourier",
      deliveryPoint: {
        coordinates: { latitude: 55.7558, longitude: 37.6173 },
        address: {
          street: { id: "street-uuid", name: "Main Street" },
          house: "10",
          flat: "5"
        }
      },
      customer: {
        name: "John Doe",
        type: "regular"
      },
      items: [
        {
          productId: "product-uuid-1",
          type: "Product",
          amount: 2,
          comment: "No onions please"
        }
      ],
      payments: [
        {
          paymentTypeKind: "Cash",
          sum: 500,
          paymentTypeId: "payment-type-uuid"
        }
      ]
    }
  } as CreateDeliveryRequest
});

if (data) {
  console.log("Order ID:", data.orderInfo?.id);
  console.log("Correlation ID:", data.correlationId);
}
// Expected output: Order ID: 770e8400-e29b-41d4-a716-446655440002, Correlation ID: abc123
```

## Deliveries - Retrieve Orders by Date and Status

Query delivery orders by date range and status filter.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type GetDeliveriesRequest = components["schemas"]["iikoTransport.PublicApi.Contracts.Deliveries.Request.GetOrdersByDeliveryDateAndStatusRequest"];

const { data, error } = await client.POST("/api/1/deliveries/by_delivery_date_and_status", {
  body: {
    organizationIds: ["550e8400-e29b-41d4-a716-446655440000"],
    deliveryDateFrom: "2024-01-01",
    deliveryDateTo: "2024-01-31",
    statuses: ["Unconfirmed", "WaitCooking", "ReadyForCooking", "CookingStarted", "CookingCompleted", "Waiting", "OnWay", "Delivered"]
  } as GetDeliveriesRequest
});

if (data) {
  console.log("Total orders:", data.ordersByOrganizations?.length);
  data.ordersByOrganizations?.forEach(orgOrders => {
    orgOrders.orders?.forEach(order => {
      console.log(`Order ${order.id}: ${order.order?.status} - ${order.order?.sum} RUB`);
    });
  });
}
```

## Table Orders - Create In-Restaurant Order

Create a table order for in-restaurant dining (available from iiko version 7.4.6+).

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type CreateTableOrderRequest = components["schemas"]["iikoTransport.PublicApi.Contracts.TableOrders.Request.CreateTableOrderRequest"];
type TableOrderResponse = components["schemas"]["iikoTransport.PublicApi.Contracts.TableOrders.Response.TableOrderResponse"];

const { data, error } = await client.POST("/api/1/order/create", {
  body: {
    organizationId: "550e8400-e29b-41d4-a716-446655440000",
    terminalGroupId: "660e8400-e29b-41d4-a716-446655440001",
    order: {
      tableIds: ["table-uuid-1"],
      items: [
        {
          productId: "product-uuid-1",
          type: "Product",
          amount: 1
        },
        {
          productId: "product-uuid-2",
          type: "Product",
          amount: 2,
          modifiers: [
            { productId: "modifier-uuid", amount: 1 }
          ]
        }
      ],
      guests: {
        count: 2
      }
    }
  } as CreateTableOrderRequest
});

if (data) {
  console.log("Table Order ID:", data.orderInfo?.id);
  console.log("Status:", data.orderInfo?.creationStatus);
}
```

## Loyalty - Get Customer Information

Retrieve customer information by phone, email, card number, or customer ID.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type GetCustomerRequest = components["schemas"]["iikoNet.Service.Contracts.Api.iikoTransport.Customer.GetCustomerInfoRequest"];
type GetCustomerResponse = components["schemas"]["iikoNet.Service.Contracts.Api.iikoTransport.Customer.GetCustomerInfoResponse"];

// Get customer by phone
const { data, error } = await client.POST("/api/1/loyalty/iiko/customer/info", {
  body: {
    type: "phone",
    phone: "+79001234567",
    organizationId: "550e8400-e29b-41d4-a716-446655440000"
  }
});

if (data) {
  console.log("Customer ID:", data.id);
  console.log("Name:", data.name, data.surname);
  console.log("Balance:", data.walletBalances?.[0]?.balance);
  console.log("Categories:", data.categories?.map(c => c.name).join(", "));
}
// Expected output: Customer ID: cust-uuid, Name: John Doe, Balance: 1500.00
```

## Loyalty - Create or Update Customer

Create a new customer or update existing customer information in the loyalty program.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type CreateCustomerRequest = components["schemas"]["iikoNet.Service.Contracts.Api.iikoTransport.Customer.CreateOrUpdateCustomerRequest"];
type CreateCustomerResponse = components["schemas"]["iikoNet.Service.Contracts.Api.iikoTransport.Customer.CreateOrUpdateCustomerResponse"];

const { data, error } = await client.POST("/api/1/loyalty/iiko/customer/create_or_update", {
  body: {
    organizationId: "550e8400-e29b-41d4-a716-446655440000",
    phone: "+79001234567",
    name: "John",
    surName: "Doe",
    middleName: "Michael",
    email: "john.doe@example.com",
    birthday: "1990-05-15 00:00:00.000",
    sex: 1, // 0=not specified, 1=male, 2=female
    consentStatus: 1, // 0=unknown, 1=given, 2=revoked
    shouldReceivePromoActionsInfo: true
  } as CreateCustomerRequest
});

if (data) {
  console.log("Customer ID:", data.id);
}
// Expected output: Customer ID: 880e8400-e29b-41d4-a716-446655440003
```

## Loyalty - Calculate Discounts

Calculate applicable discounts and loyalty benefits for an order before submission.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type CalculateRequest = components["schemas"]["iikoNet.Service.Contracts.Api.iikoTransport.LoyaltyResult.CalculateCheckinRequest"];
type CalculateResponse = components["schemas"]["iikoNet.Service.Contracts.Api.iikoTransport.LoyaltyResult.CalculateCheckinResponse"];

const { data, error } = await client.POST("/api/1/loyalty/iiko/calculate", {
  body: {
    organizationId: "550e8400-e29b-41d4-a716-446655440000",
    terminalGroupId: "660e8400-e29b-41d4-a716-446655440001",
    order: {
      id: "order-uuid",
      items: [
        { productId: "product-uuid-1", amount: 2, price: 250 }
      ]
    },
    customer: {
      id: "customer-uuid"
    }
  } as CalculateRequest
});

if (data) {
  console.log("Final amount:", data.loyaltyInfo?.finalAmount);
  console.log("Discount:", data.loyaltyInfo?.discount);
  console.log("Available free products:", data.loyaltyInfo?.freeProducts?.length);
}
```

## Terminal Groups - List Terminal Groups

Retrieve terminal groups (POS terminals) for organizations.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type TerminalGroupsRequest = components["schemas"]["iikoTransport.PublicApi.Contracts.TerminalGroups.Request.GetTerminalGroupsRequest"];
type TerminalGroupsResponse = components["schemas"]["iikoTransport.PublicApi.Contracts.TerminalGroups.Response.GetTerminalGroupsResponse"];

const { data, error } = await client.POST("/api/1/terminal_groups", {
  body: {
    organizationIds: ["550e8400-e29b-41d4-a716-446655440000"],
    includeDisabled: false
  } as TerminalGroupsRequest
});

if (data) {
  data.terminalGroups?.forEach(group => {
    group.items?.forEach(terminal => {
      console.log(`Terminal: ${terminal.name} (${terminal.id})`);
      console.log(`  Address: ${terminal.address}`);
    });
  });
}
```

## Command Status - Check Async Operation Status

Many operations (create delivery, create order) are async commands. Use this endpoint to poll for completion.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type CommandStatusRequest = components["schemas"]["iikoTransport.PublicApi.Contracts.Commands.CommandStatusRequest"];
type CommandStatusResponse = components["schemas"]["iikoTransport.PublicApi.Contracts.Commands.CommandStatusResponse"];

// Poll for command completion
const pollCommandStatus = async (correlationId: string): Promise<CommandStatusResponse | null> => {
  let attempts = 0;
  const maxAttempts = 30;

  while (attempts < maxAttempts) {
    const { data, error } = await client.POST("/api/1/commands/status", {
      body: {
        organizationId: "550e8400-e29b-41d4-a716-446655440000",
        correlationId: correlationId
      } as CommandStatusRequest
    });

    if (error) throw new Error(`Command status error: ${error}`);

    if (data?.state === "Success") {
      console.log("Command completed successfully");
      return data;
    } else if (data?.state === "Error") {
      console.error("Command failed:", data.exception?.message);
      return data;
    }

    console.log(`Status: ${data?.state}, waiting...`);
    await new Promise(resolve => setTimeout(resolve, 1000));
    attempts++;
  }

  throw new Error("Command timed out");
};

// Usage after creating a delivery
const result = await pollCommandStatus("correlation-id-from-create");
```

## Stop Lists - Get Out-of-Stock Items

Retrieve items that are currently out of stock across terminal groups.

```typescript
import createClient from "openapi-fetch";
import { paths, components } from "@salesduck/iiko-cloud-api";

const client = createClient<paths>({
  baseUrl: "https://api-ru.iiko.services",
  headers: { Authorization: `Bearer ${accessToken}` }
});

type StopListsRequest = components["schemas"]["iikoTransport.PublicApi.Contracts.StopLists.GetStopListsRequest"];
type StopListsResponse = components["schemas"]["iikoTransport.PublicApi.Contracts.StopLists.GetStopListsResponse"];

const { data, error } = await client.POST("/api/1/stop_lists", {
  body: {
    organizationIds: ["550e8400-e29b-41d4-a716-446655440000"]
  } as StopListsRequest
});

if (data) {
  data.terminalGroupStopLists?.forEach(tgStopList => {
    console.log(`Terminal Group: ${tgStopList.terminalGroupId}`);
    tgStopList.items?.forEach(item => {
      console.log(`  - Product ${item.productId}: balance = ${item.balance}`);
    });
  });
}
```

## Direct Type Usage Pattern

For custom REST client implementations without openapi-fetch, use types directly to ensure type safety.

```typescript
import { paths, components } from "@salesduck/iiko-cloud-api";

// Define type aliases for cleaner code
export type GetRegionsParams = paths["/api/1/regions"]["post"]["parameters"];
export type GetRegionsBody = components["schemas"]["iikoTransport.PublicApi.Contracts.Address.RegionsRequest"];
export type GetRegionsResponse = components["schemas"]["iikoTransport.PublicApi.Contracts.Address.RegionsResponse"];
export type ErrorResponse = components["schemas"]["iikoTransport.PublicApi.Contracts.Errors.ErrorResponse"];

// Type-safe API wrapper function
const getRegions = async (
  params: GetRegionsParams,
  body: GetRegionsBody
): Promise<GetRegionsResponse> => {
  const response = await fetch("https://api-ru.iiko.services/api/1/regions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": params.header.Authorization,
      ...(params.header.Timeout && { "Timeout": String(params.header.Timeout) })
    },
    body: JSON.stringify(body)
  });

  if (!response.ok) {
    const errorData: ErrorResponse = await response.json();
    throw new Error(errorData.errorDescription || "API request failed");
  }

  return response.json();
};

// Usage with full type safety
const regions = await getRegions(
  { header: { Authorization: "Bearer token123" } },
  { organizationIds: ["550e8400-e29b-41d4-a716-446655440000"] }
);

console.log("Regions:", regions.regions);
console.log("Correlation ID:", regions.correlationId);
```

## Summary

The `@salesduck/iiko-cloud-api` library serves as the foundation for building type-safe integrations with the iiko Cloud restaurant management platform. Primary use cases include: building delivery aggregator integrations, creating custom POS interfaces, developing customer loyalty applications, implementing menu synchronization services, and building order management dashboards. The library supports all major iiko Cloud operations including authentication, organization management, menu/nomenclature retrieval, delivery and table order creation, loyalty program interactions, and terminal group monitoring.

Integration patterns typically follow a flow of: authenticate to get access token, retrieve organizations and terminal groups, fetch menu data, and then perform order operations. The async command pattern (create operation returns correlationId, poll `/api/1/commands/status` for completion) is used for order creation operations. When building with `openapi-fetch`, the library provides automatic request/response typing. For custom implementations, types can be imported directly and used with standard fetch or axios calls. Error handling should account for 400 (bad request), 401 (unauthorized), 408 (timeout), and 500 (server error) responses, all of which return the standard `ErrorResponse` schema.