Client

iikocloudapi.IikoCloud

IikoCloud(
    auth: Auth,
    *,
    base_url: str = API_RU,
    timeout: float = DEFAULT_TIMEOUT,
    http_client: AsyncClient | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: IikoCloudResources

Async client for the iikoCloud API.

Every endpoint of the API is available as a method whose attribute path mirrors the endpoint URL (/api/1/order/create is iiko.order.create(...)).

Parameters:

Name	Type	Description	Default
auth	Auth	Authentication strategy, usually :class:~iikocloudapi.AppAuth.	required
base_url	str	API root, :data:API_RU (default) or :data:API_EU.	API_RU
timeout	float	Default server-side timeout in seconds, sent in the Timeout header. iikoCloud waits up to this long for the restaurant terminal to answer. Each method also accepts timeout= to override it.	DEFAULT_TIMEOUT
http_client	AsyncClient | None	Your own httpx2.AsyncClient (proxies, custom transports...). It is not closed by :meth:aclose.	None
headers	Mapping[str, str] | None	Extra headers sent with every request.	None

Example

async with IikoCloud(auth=AppAuth(api_key=..., app_id=..., client_secret=...)) as iiko:
    organizations = await iiko.organizations()

request async

request(
    path: str,
    body: Any = None,
    *,
    timeout: float | None = None,
) -> Any

Call any endpoint, including ones this library does not know about yet.

Parameters:

Name	Type	Description	Default
path	str	Endpoint path, for example "/api/1/organizations".	required
body	Any	JSON body: plain data, models, Decimals and datetimes are converted automatically.	None
timeout	float | None	Server-side timeout in seconds; defaults to the client setting.	None

Returns:

Type	Description
Any	The decoded JSON response (numbers with a fractional part are returned as Decimal), or None
Any	for an empty response.

wait async

wait(
    command: str | _HasCorrelationId,
    *,
    organization_id: str,
    timeout: float = 60.0,
    poll_interval: float = 1.0,
) -> SuccessCommandStatus

Wait until an asynchronous command finishes.

Methods documented as commands (order creation, payments, closing...) only start an operation and return its correlation_id. This helper polls /api/1/commands/status with a growing interval.

Parameters:

Name	Type	Description	Default
command	str | _HasCorrelationId	The response of the command or its correlation_id.	required
organization_id	str	Organization the command belongs to.	required
timeout	float	Maximum time to wait, in seconds.	60.0
poll_interval	float	Initial delay between status checks, in seconds.	1.0

Raises:

Type	Description
CommandFailed	The command finished with an error.
CommandTimeout	The command did not finish within timeout.

aclose async

aclose() -> None

Close the underlying HTTP client (unless it was passed in by you).

Authentication

iikocloudapi.AppAuth

AppAuth(api_key: str, app_id: str, client_secret: str)

Bases: IikoAuth

Authentication of a registered application (/api/v2/access_token).

1. Register at https://public-api.iikoweb.ru/portal and create an application to get app_id and a one-time client_secret.
2. In iikoWeb, open "Integrations > API Keys" and generate an api_key.

Parameters:

Name	Type	Description	Default
api_key	str	API key generated in iikoWeb.	required
app_id	str	Application ID from the developer portal.	required
client_secret	str	Application client secret from the developer portal.	required

iikocloudapi.ApiLoginAuth

ApiLoginAuth(api_login: str)

Bases: IikoAuth

Legacy authentication with a single API login (/api/1/access_token).

iikoCloud marks this endpoint as deprecated; prefer :class:AppAuth.

Parameters:

Name	Type	Description	Default
api_login	str	API login created in iikoWeb.	required

iikocloudapi.IikoAuth

IikoAuth()

Bases: Auth

Base class for token-based authentication against iikoCloud.

The token is requested lazily, cached until shortly before it expires (the JWT exp claim when available) and refreshed once when a request fails with 401 Unauthorized. Concurrent requests share a single token request.

Subclasses define :attr:token_path and :meth:token_payload. Override :meth:parse_token_response to support another response format, or :meth:token_request to obtain tokens from somewhere else entirely (for example a token shared between several worker processes).

token property

token: str | None

The current access token, if one has been obtained.

token_request

token_request(request: Request) -> Request

Request that obtains a new token.

request is the API request being authenticated: the token request goes to the same host (keeping any path prefix in front of /api/) with the same headers and timeout.

parse_token_response

parse_token_response(response: Response) -> str

invalidate

invalidate() -> None

Forget the current token; the next request obtains a new one.

Errors

Exceptions raised by iikocloudapi.

IikoError

Bases: Exception

Base class for every error raised by iikocloudapi.

IikoNetworkError

Bases: IikoError

The request did not reach iikoCloud or the response was not received (connection error, timeout...).

IikoApiError

IikoApiError(
    response: Response,
    *,
    description: str,
    error: str | None = None,
    correlation_id: str | None = None,
    details: Any = None,
)

Bases: IikoError

iikoCloud answered with an HTTP error status.

Attributes:

Name	Type	Description
status_code	int	HTTP status code.
description		Human-readable error description from the response body.
error		Short error code, if provided (errorDescription/error in iikoTransport API responses).
correlation_id		Operation ID of the failed request, if provided.
details		Additional error details returned by the newer APIs (inventory, finance, ...).
response		The raw httpx2.Response.

BadRequest

BadRequest(
    response: Response,
    *,
    description: str,
    error: str | None = None,
    correlation_id: str | None = None,
    details: Any = None,
)

Bases: IikoApiError

400: the request is invalid.

Unauthorized

Unauthorized(
    response: Response,
    *,
    description: str,
    error: str | None = None,
    correlation_id: str | None = None,
    details: Any = None,
)

Bases: IikoApiError

401: credentials are invalid or the token has expired.

Forbidden

Forbidden(
    response: Response,
    *,
    description: str,
    error: str | None = None,
    correlation_id: str | None = None,
    details: Any = None,
)

Bases: IikoApiError

403: the API login has no access to the requested resource.

NotFound

NotFound(
    response: Response,
    *,
    description: str,
    error: str | None = None,
    correlation_id: str | None = None,
    details: Any = None,
)

Bases: IikoApiError

404: the requested entity does not exist.

RequestTimeout

RequestTimeout(
    response: Response,
    *,
    description: str,
    error: str | None = None,
    correlation_id: str | None = None,
    details: Any = None,
)

Bases: IikoApiError

408: iikoCloud did not get an answer from the terminal in time (see the Timeout header).

Conflict

Conflict(
    response: Response,
    *,
    description: str,
    error: str | None = None,
    correlation_id: str | None = None,
    details: Any = None,
)

Bases: IikoApiError

409: the request conflicts with the current state of the entity.

Gone

Gone(
    response: Response,
    *,
    description: str,
    error: str | None = None,
    correlation_id: str | None = None,
    details: Any = None,
)

Bases: IikoApiError

410: the entity is no longer available (for example, an expired correlationId).

UnprocessableEntity

UnprocessableEntity(
    response: Response,
    *,
    description: str,
    error: str | None = None,
    correlation_id: str | None = None,
    details: Any = None,
)

Bases: IikoApiError

422: the request is well-formed but semantically invalid.

TooManyRequests

TooManyRequests(
    response: Response,
    *,
    description: str,
    error: str | None = None,
    correlation_id: str | None = None,
    details: Any = None,
)

Bases: IikoApiError

429: rate limit exceeded.

Attributes:

Name	Type	Description
retry_after	float | None	Seconds to wait before retrying, if the server sent a Retry-After header.

ServerError

ServerError(
    response: Response,
    *,
    description: str,
    error: str | None = None,
    correlation_id: str | None = None,
    details: Any = None,
)

Bases: IikoApiError

5xx: an error on the iikoCloud side.

ResponseValidationError

ResponseValidationError(message: str, response: Response)

Bases: IikoError

The response body does not match the model this library expects.

The original pydantic.ValidationError is available as __cause__.

CommandFailed

CommandFailed(
    correlation_id: str,
    *,
    exception: Any,
    error_reason: Any,
    status: Any,
)

Bases: IikoError

An asynchronous command (see :meth:IikoCloud.wait) finished with an error.

Attributes:

Name	Type	Description
correlation_id		Operation ID of the command.
exception		Error details reported by iikoCloud.
error_reason		Error reason code reported by iikoCloud.
status		The full command status object.

CommandTimeout

CommandTimeout(correlation_id: str, timeout: float)

Bases: IikoError, TimeoutError

An asynchronous command did not finish within the given time.

Webhooks

Parsing and verifying incoming iikoCloud webhooks.

Configure the receiver with iiko.webhooks.update_settings(...); iikoCloud then POSTs a JSON array of events to webHooksUri and passes the configured authToken in the Authorization header.

parse_webhook

parse_webhook(
    body: bytes | str | list[Any],
) -> list[WebhookEvent]

Parse the body of a webhook request into typed events.

Parameters:

Name	Type	Description	Default
body	bytes | str | list[Any]	Raw request body (bytes/str) or already decoded JSON.	required

Returns:

Type	Description
list[WebhookEvent]	The events, each an instance of one of the *Event models (UnknownWebhookEvent for event types
list[WebhookEvent]	added to iikoCloud after this library was released).

Example

for event in parse_webhook(await request.body()):
    match event:
        case DeliveryOrderUpdateEvent():
            ...

verify_webhook_token

verify_webhook_token(
    authorization: str | None, expected: str
) -> bool

Check the Authorization header of a webhook request against the configured authToken.

Accepts both the bare token and Bearer <token>; compares in constant time.

Types

Base classes and types shared by all generated models.

IikoDateTime module-attribute

IikoDateTime = Annotated[
    datetime.datetime,
    PlainSerializer(
        format_iiko_datetime,
        return_type=str,
        when_used="always",
    ),
]

A datetime that is (de)serialised in iikoCloud's yyyy-MM-dd HH:mm:ss.fff format.

iikoCloud uses the local time of the organization; naive datetimes are sent as is.

IsoDateTime module-attribute

IsoDateTime = Annotated[
    datetime.datetime,
    PlainSerializer(
        datetime.datetime.isoformat,
        return_type=str,
        when_used="always",
    ),
]

A datetime that is serialised in ISO 8601 format (used by a few newer endpoints).

IikoModel

Bases: BaseModel

Base class of every model in :mod:iikocloudapi.models.

Models are strict when you build them (unknown fields and enum values raise ValidationError) and lenient when they are parsed from an API response (unknown fields are kept in model_extra, unknown enum values become pseudo-members), so new fields on the iikoCloud side never break your code.

OpenStrEnum

Bases: StrEnum

String enum that tolerates values added to the API after this library was released.

Unknown values become pseudo-members: they compare equal to the raw string and have is_known == False.

is_known property

is_known: bool

False for values that are not declared in the specification this library was generated from.

OpenIntEnum

Bases: IntEnum

Integer counterpart of :class:OpenStrEnum.

is_known property

is_known: bool

False for values that are not declared in the specification this library was generated from.

OrganizationItems

Bases: IikoModel, Generic[T]

Items that belong to a single organization.

organization_id instance-attribute

organization_id: str

Organization ID.

items instance-attribute

items: list[T]

Items of the organization.