openapi: 3.0.3
info:
  title: 'DelRes API'
  description: 'REST API DelRes для интеграций. Базовый адрес — поддомен вашего заведения: https://{ваш-поддомен}-api.delres.kz'
  version: 1.0.0
servers:
  -
    url: 'https://{ваш-поддомен}-api.delres.kz'
paths:
  /api/v2/auth/login:
    post:
      summary: 'Получить токен'
      operationId: ''
      description: "Возвращает бессрочный токен доступа. Его нужно передавать во всех\nостальных запросах в заголовке `Authorization: Bearer <токен>`."
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    token: 11|AbCdEf...
                    expires_at: null
                    user:
                      id: 42
                      name: Интеграция
                      email: null
                      phone: null
                      roles:
                        - site-integrator
                      permissions:
                        - order-list
                        - order-create
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      token:
                        type: string
                        example: 11|AbCdEf...
                      expires_at:
                        type: string
                        example: null
                      user:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 42
                          name:
                            type: string
                            example: Интеграция
                          email:
                            type: string
                            example: null
                          phone:
                            type: string
                            example: null
                          roles:
                            type: array
                            example:
                              - site-integrator
                            items:
                              type: string
                          permissions:
                            type: array
                            example:
                              - order-list
                              - order-create
                            items:
                              type: string
        401:
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                  -
                    description: 'Неверный логин или пароль'
                    type: object
                    example:
                      success: false
                      error:
                        code: unauthorized
                        message: 'Неверный логин или пароль'
                    properties:
                      success:
                        type: boolean
                        example: false
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: unauthorized
                          message:
                            type: string
                            example: 'Неверный логин или пароль'
                  -
                    description: 'Учётная запись или организация заблокирована'
                    type: object
                    example:
                      success: false
                      error:
                        code: unauthorized
                        message: 'Учётная запись заблокирована'
                    properties:
                      success:
                        type: boolean
                        example: false
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            example: unauthorized
                          message:
                            type: string
                            example: 'Учётная запись заблокирована'
        422:
          description: 'Ошибка валидации'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: validation_error
                    message: 'Поле login обязательно'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_error
                      message:
                        type: string
                        example: 'Поле login обязательно'
      tags:
        - Авторизация
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                login:
                  type: string
                  description: 'Логин пользователя DelRes.'
                  example: integrator
                  nullable: false
                password:
                  type: string
                  description: 'Пароль, минимум 6 символов.'
                  example: secret123
                  nullable: false
              required:
                - login
                - password
      security: []
  /api/v2/auth/logout:
    post:
      summary: 'Отозвать токен'
      operationId: ''
      description: "Аннулирует токен, которым сделан запрос. Остальные ранее выданные\nтокены продолжают работать."
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data: null
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: string
                    example: null
        401:
          description: 'Нет или неверный токен'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: unauthenticated
                    message: Unauthenticated.
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: unauthenticated
                      message:
                        type: string
                        example: Unauthenticated.
      tags:
        - Авторизация
  /api/v2/auth/me:
    get:
      summary: 'Текущий пользователь'
      operationId: ''
      description: "Кому принадлежит токен: профиль, роли и полный список прав.\nУдобно для проверки, что интеграция авторизована верно."
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    id: 42
                    name: Интеграция
                    email: null
                    phone: null
                    roles:
                      - site-integrator
                    permissions:
                      - order-list
                      - order-create
                      - client-list
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 42
                      name:
                        type: string
                        example: Интеграция
                      email:
                        type: string
                        example: null
                      phone:
                        type: string
                        example: null
                      roles:
                        type: array
                        example:
                          - site-integrator
                        items:
                          type: string
                      permissions:
                        type: array
                        example:
                          - order-list
                          - order-create
                          - client-list
                        items:
                          type: string
        401:
          description: 'Нет или неверный токен'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: unauthenticated
                    message: Unauthenticated.
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: unauthenticated
                      message:
                        type: string
                        example: Unauthenticated.
      tags:
        - Авторизация
  /api/v2/orders:
    get:
      summary: 'Список заказов'
      operationId: ''
      description: "Постранично, свежие сверху. Суммы — в тийынах (1 ₸ = 100),\nколичество позиций — в тысячных (1 шт = 1000)."
      parameters:
        -
          in: query
          name: trade_point_id
          description: 'ID торговой точки.'
          example: 1
          required: true
          schema:
            type: integer
            description: 'ID торговой точки.'
            example: 1
            nullable: false
        -
          in: query
          name: status
          description: 'Статусы через запятую.'
          example: 'in_progress,ready'
          required: false
          schema:
            type: string
            description: 'Статусы через запятую.'
            example: 'in_progress,ready'
            nullable: false
        -
          in: query
          name: from
          description: 'Начало периода, ISO 8601.'
          example: '2026-08-01T00:00:00Z'
          required: false
          schema:
            type: string
            description: 'Начало периода, ISO 8601.'
            example: '2026-08-01T00:00:00Z'
            nullable: false
        -
          in: query
          name: to
          description: 'Конец периода, ISO 8601.'
          example: '2026-08-08T23:59:59Z'
          required: false
          schema:
            type: string
            description: 'Конец периода, ISO 8601.'
            example: '2026-08-08T23:59:59Z'
            nullable: false
        -
          in: query
          name: page
          description: 'Номер страницы, с 1.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Номер страницы, с 1.'
            example: 1
            nullable: false
        -
          in: query
          name: per_page
          description: 'Размер страницы.'
          example: 25
          required: false
          schema:
            type: integer
            description: 'Размер страницы.'
            example: 25
            nullable: false
        -
          in: header
          name: X-Active-Point
          description: ''
          example: '1'
          schema:
            type: string
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    items:
                      -
                        id: 152380
                        trade_point_id: 1
                        client_id: 9
                        status: in_progress
                        payment_status: not_paid
                        sum_original: 450000
                        sum_discounted: 405000
                        comment: 'Не звонить в домофон'
                        table_number: null
                        is_fiscal: false
                        date: '2026-08-08T11:20:00Z'
                        created_at: '2026-08-08T11:20:00Z'
                        updated_at: '2026-08-08T11:25:00Z'
                        items:
                          -
                            id: 1
                            nomenclature_id: 334
                            name: 'Ролл Филадельфия'
                            amount: 2000
                            unit_price: 225000
                            total_price: 450000
                    page_info:
                      page: 1
                      per_page: 25
                      has_next: false
                      total: 1
                      adjusted: false
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        example:
                          -
                            id: 152380
                            trade_point_id: 1
                            client_id: 9
                            status: in_progress
                            payment_status: not_paid
                            sum_original: 450000
                            sum_discounted: 405000
                            comment: 'Не звонить в домофон'
                            table_number: null
                            is_fiscal: false
                            date: '2026-08-08T11:20:00Z'
                            created_at: '2026-08-08T11:20:00Z'
                            updated_at: '2026-08-08T11:25:00Z'
                            items:
                              -
                                id: 1
                                nomenclature_id: 334
                                name: 'Ролл Филадельфия'
                                amount: 2000
                                unit_price: 225000
                                total_price: 450000
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 152380
                            trade_point_id:
                              type: integer
                              example: 1
                            client_id:
                              type: integer
                              example: 9
                            status:
                              type: string
                              example: in_progress
                            payment_status:
                              type: string
                              example: not_paid
                            sum_original:
                              type: integer
                              example: 450000
                            sum_discounted:
                              type: integer
                              example: 405000
                            comment:
                              type: string
                              example: 'Не звонить в домофон'
                            table_number:
                              type: string
                              example: null
                            is_fiscal:
                              type: boolean
                              example: false
                            date:
                              type: string
                              example: '2026-08-08T11:20:00Z'
                            created_at:
                              type: string
                              example: '2026-08-08T11:20:00Z'
                            updated_at:
                              type: string
                              example: '2026-08-08T11:25:00Z'
                            items:
                              type: array
                              example:
                                -
                                  id: 1
                                  nomenclature_id: 334
                                  name: 'Ролл Филадельфия'
                                  amount: 2000
                                  unit_price: 225000
                                  total_price: 450000
                              items:
                                type: object
                                properties:
                                  id:
                                    type: integer
                                    example: 1
                                  nomenclature_id:
                                    type: integer
                                    example: 334
                                  name:
                                    type: string
                                    example: 'Ролл Филадельфия'
                                  amount:
                                    type: integer
                                    example: 2000
                                  unit_price:
                                    type: integer
                                    example: 225000
                                  total_price:
                                    type: integer
                                    example: 450000
                      page_info:
                        type: object
                        properties:
                          page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 25
                          has_next:
                            type: boolean
                            example: false
                          total:
                            type: integer
                            example: 1
                          adjusted:
                            type: boolean
                            example: false
        400:
          description: 'Нет заголовка X-Active-Point'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: bad_request
                    message: 'Заголовок X-Active-Point обязателен для этой операции'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: bad_request
                      message:
                        type: string
                        example: 'Заголовок X-Active-Point обязателен для этой операции'
        401:
          description: 'Нет или неверный токен'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: unauthenticated
                    message: Unauthenticated.
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: unauthenticated
                      message:
                        type: string
                        example: Unauthenticated.
      tags:
        - Заказы
    post:
      summary: 'Создать заказ'
      operationId: ''
      description: "Операция идемпотентная: повторный запрос с тем же `Idempotency-Key`\nи тем же телом вернёт исходный результат, а не создаст дубль. Если по\nтому же ключу прислать другое тело — 409.\n\nКоличество в позициях указывается в тысячных: 1 шт = `1000`, 0.5 кг = `500`."
      parameters:
        -
          in: header
          name: X-Active-Point
          description: ''
          example: '1'
          schema:
            type: string
        -
          in: header
          name: Idempotency-Key
          description: ''
          example: 3f1a7d2e-9c44-4b8e-9a1e-7d5c2b6f0a11
          schema:
            type: string
      responses:
        201:
          description: Создан
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    id: 152381
                    trade_point_id: 1
                    client_id: 9
                    status: new
                    payment_status: not_paid
                    sum_original: 450000
                    sum_discounted: 450000
                    comment: null
                    table_number: null
                    is_fiscal: false
                    date: '2026-08-08T12:00:00Z'
                    created_at: '2026-08-08T12:00:00Z'
                    updated_at: '2026-08-08T12:00:00Z'
                    items:
                      -
                        id: 1
                        nomenclature_id: 334
                        name: 'Ролл Филадельфия'
                        amount: 2000
                        unit_price: 225000
                        total_price: 450000
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 152381
                      trade_point_id:
                        type: integer
                        example: 1
                      client_id:
                        type: integer
                        example: 9
                      status:
                        type: string
                        example: new
                      payment_status:
                        type: string
                        example: not_paid
                      sum_original:
                        type: integer
                        example: 450000
                      sum_discounted:
                        type: integer
                        example: 450000
                      comment:
                        type: string
                        example: null
                      table_number:
                        type: string
                        example: null
                      is_fiscal:
                        type: boolean
                        example: false
                      date:
                        type: string
                        example: '2026-08-08T12:00:00Z'
                      created_at:
                        type: string
                        example: '2026-08-08T12:00:00Z'
                      updated_at:
                        type: string
                        example: '2026-08-08T12:00:00Z'
                      items:
                        type: array
                        example:
                          -
                            id: 1
                            nomenclature_id: 334
                            name: 'Ролл Филадельфия'
                            amount: 2000
                            unit_price: 225000
                            total_price: 450000
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            nomenclature_id:
                              type: integer
                              example: 334
                            name:
                              type: string
                              example: 'Ролл Филадельфия'
                            amount:
                              type: integer
                              example: 2000
                            unit_price:
                              type: integer
                              example: 225000
                            total_price:
                              type: integer
                              example: 450000
        400:
          description: 'Нет Idempotency-Key или он не UUID v4'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: idempotency_key_required
                    message: 'Заголовок Idempotency-Key обязателен и должен быть UUID v4'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: idempotency_key_required
                      message:
                        type: string
                        example: 'Заголовок Idempotency-Key обязателен и должен быть UUID v4'
        409:
          description: 'Тот же ключ с другим телом'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: idempotency_conflict
                    message: 'Idempotency-Key уже использован с другим телом запроса'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: idempotency_conflict
                      message:
                        type: string
                        example: 'Idempotency-Key уже использован с другим телом запроса'
        422:
          description: 'Ошибка валидации'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: validation_error
                    message: 'Поле items обязательно'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_error
                      message:
                        type: string
                        example: 'Поле items обязательно'
      tags:
        - Заказы
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                trade_point_id:
                  type: integer
                  description: 'ID торговой точки.'
                  example: 1
                  nullable: false
                channel:
                  type: string
                  description: 'Канал продаж.'
                  example: delivery
                  nullable: false
                items:
                  type: array
                  description: 'Позиции заказа, минимум одна.'
                  example:
                    - []
                  items:
                    type: object
                    properties:
                      nomenclature_id:
                        type: integer
                        description: 'ID блюда.'
                        example: 334
                        nullable: false
                      amount:
                        type: integer
                        description: 'Количество в тысячных (1 шт = 1000).'
                        example: 2000
                        nullable: false
                    required:
                      - nomenclature_id
                      - amount
                client_id:
                  type: integer
                  description: 'ID клиента, если заказ привязан к нему.'
                  example: 9
                  nullable: false
                comment:
                  type: string
                  description: 'Комментарий к заказу, до 1000 символов.'
                  example: 'Не звонить в домофон'
                  nullable: false
                table_number:
                  type: string
                  description: 'Номер стола для зала.'
                  example: '12'
                  nullable: false
                discount_id:
                  type: integer
                  description: 'ID скидки.'
                  example: 3
                  nullable: false
              required:
                - trade_point_id
                - channel
                - items
  '/api/v2/orders/{id}':
    get:
      summary: 'Получить заказ'
      operationId: ''
      description: ''
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    id: 152380
                    trade_point_id: 1
                    client_id: 9
                    status: in_progress
                    payment_status: not_paid
                    sum_original: 450000
                    sum_discounted: 405000
                    comment: null
                    table_number: null
                    is_fiscal: false
                    date: '2026-08-08T11:20:00Z'
                    created_at: '2026-08-08T11:20:00Z'
                    updated_at: '2026-08-08T11:25:00Z'
                    items:
                      -
                        id: 1
                        nomenclature_id: 334
                        name: 'Ролл Филадельфия'
                        amount: 2000
                        unit_price: 225000
                        total_price: 450000
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 152380
                      trade_point_id:
                        type: integer
                        example: 1
                      client_id:
                        type: integer
                        example: 9
                      status:
                        type: string
                        example: in_progress
                      payment_status:
                        type: string
                        example: not_paid
                      sum_original:
                        type: integer
                        example: 450000
                      sum_discounted:
                        type: integer
                        example: 405000
                      comment:
                        type: string
                        example: null
                      table_number:
                        type: string
                        example: null
                      is_fiscal:
                        type: boolean
                        example: false
                      date:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      created_at:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      updated_at:
                        type: string
                        example: '2026-08-08T11:25:00Z'
                      items:
                        type: array
                        example:
                          -
                            id: 1
                            nomenclature_id: 334
                            name: 'Ролл Филадельфия'
                            amount: 2000
                            unit_price: 225000
                            total_price: 450000
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            nomenclature_id:
                              type: integer
                              example: 334
                            name:
                              type: string
                              example: 'Ролл Филадельфия'
                            amount:
                              type: integer
                              example: 2000
                            unit_price:
                              type: integer
                              example: 225000
                            total_price:
                              type: integer
                              example: 450000
        404:
          description: 'Заказ не найден'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: not_found
                    message: 'Заказ не найден'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Заказ не найден'
      tags:
        - Заказы
    patch:
      summary: 'Изменить заказ'
      operationId: ''
      description: "Меняет только переданные поля. Если прислать `items`, состав заказа\nзаменяется целиком на переданный список."
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    id: 152380
                    trade_point_id: 1
                    client_id: 9
                    status: in_progress
                    payment_status: not_paid
                    sum_original: 450000
                    sum_discounted: 405000
                    comment: 'Не звонить в домофон'
                    table_number: null
                    is_fiscal: false
                    date: '2026-08-08T11:20:00Z'
                    created_at: '2026-08-08T11:20:00Z'
                    updated_at: '2026-08-08T12:05:00Z'
                    items:
                      -
                        id: 1
                        nomenclature_id: 334
                        name: 'Ролл Филадельфия'
                        amount: 2000
                        unit_price: 225000
                        total_price: 450000
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 152380
                      trade_point_id:
                        type: integer
                        example: 1
                      client_id:
                        type: integer
                        example: 9
                      status:
                        type: string
                        example: in_progress
                      payment_status:
                        type: string
                        example: not_paid
                      sum_original:
                        type: integer
                        example: 450000
                      sum_discounted:
                        type: integer
                        example: 405000
                      comment:
                        type: string
                        example: 'Не звонить в домофон'
                      table_number:
                        type: string
                        example: null
                      is_fiscal:
                        type: boolean
                        example: false
                      date:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      created_at:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      updated_at:
                        type: string
                        example: '2026-08-08T12:05:00Z'
                      items:
                        type: array
                        example:
                          -
                            id: 1
                            nomenclature_id: 334
                            name: 'Ролл Филадельфия'
                            amount: 2000
                            unit_price: 225000
                            total_price: 450000
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            nomenclature_id:
                              type: integer
                              example: 334
                            name:
                              type: string
                              example: 'Ролл Филадельфия'
                            amount:
                              type: integer
                              example: 2000
                            unit_price:
                              type: integer
                              example: 225000
                            total_price:
                              type: integer
                              example: 450000
        404:
          description: 'Заказ не найден'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: not_found
                    message: 'Заказ не найден'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Заказ не найден'
        422:
          description: 'Ошибка валидации'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: validation_error
                    message: 'items должен содержать минимум 1 элемент'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_error
                      message:
                        type: string
                        example: 'items должен содержать минимум 1 элемент'
      tags:
        - Заказы
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: integer
                  description: 'ID клиента.'
                  example: 9
                  nullable: false
                items:
                  type: array
                  description: 'Новый состав заказа (полная замена).'
                  example:
                    - []
                  items:
                    type: object
                    properties:
                      nomenclature_id:
                        type: integer
                        description: 'ID блюда.'
                        example: 334
                        nullable: false
                      amount:
                        type: integer
                        description: 'Количество в тысячных.'
                        example: 1000
                        nullable: false
                    required:
                      - nomenclature_id
                      - amount
                comment:
                  type: string
                  description: 'Комментарий к заказу.'
                  example: 'Добавить приборы'
                  nullable: false
                table_number:
                  type: string
                  description: 'Номер стола.'
                  example: '12'
                  nullable: false
    parameters:
      -
        in: path
        name: id
        description: 'ID заказа.'
        example: 152380
        required: true
        schema:
          type: integer
  '/api/v2/orders/{id}/cancel':
    post:
      summary: 'Отменить заказ'
      operationId: ''
      description: "Переводит заказ в статус «отменён». Повторная отмена уже отменённого\nзаказа вернёт ошибку перехода статуса."
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    id: 152380
                    trade_point_id: 1
                    client_id: 9
                    status: canceled
                    payment_status: not_paid
                    sum_original: 450000
                    sum_discounted: 405000
                    comment: null
                    table_number: null
                    is_fiscal: false
                    date: '2026-08-08T11:20:00Z'
                    created_at: '2026-08-08T11:20:00Z'
                    updated_at: '2026-08-08T12:10:00Z'
                    items: []
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 152380
                      trade_point_id:
                        type: integer
                        example: 1
                      client_id:
                        type: integer
                        example: 9
                      status:
                        type: string
                        example: canceled
                      payment_status:
                        type: string
                        example: not_paid
                      sum_original:
                        type: integer
                        example: 450000
                      sum_discounted:
                        type: integer
                        example: 405000
                      comment:
                        type: string
                        example: null
                      table_number:
                        type: string
                        example: null
                      is_fiscal:
                        type: boolean
                        example: false
                      date:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      created_at:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      updated_at:
                        type: string
                        example: '2026-08-08T12:10:00Z'
                      items:
                        type: array
                        example: []
        404:
          description: 'Заказ не найден'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: not_found
                    message: 'Заказ не найден'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Заказ не найден'
        422:
          description: 'Недопустимый переход статуса'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: validation_error
                    message: 'Заказ уже отменён'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_error
                      message:
                        type: string
                        example: 'Заказ уже отменён'
      tags:
        - Заказы
    parameters:
      -
        in: path
        name: id
        description: 'ID заказа.'
        example: 152380
        required: true
        schema:
          type: integer
  '/api/v2/orders/{id}/mark-ready':
    post:
      summary: 'Отметить заказ готовым'
      operationId: ''
      description: 'Ставит статус «готов» — заказ приготовлен и ждёт выдачи или курьера.'
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    id: 152380
                    trade_point_id: 1
                    client_id: 9
                    status: ready
                    payment_status: not_paid
                    sum_original: 450000
                    sum_discounted: 405000
                    comment: null
                    table_number: null
                    is_fiscal: false
                    date: '2026-08-08T11:20:00Z'
                    created_at: '2026-08-08T11:20:00Z'
                    updated_at: '2026-08-08T12:15:00Z'
                    items: []
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 152380
                      trade_point_id:
                        type: integer
                        example: 1
                      client_id:
                        type: integer
                        example: 9
                      status:
                        type: string
                        example: ready
                      payment_status:
                        type: string
                        example: not_paid
                      sum_original:
                        type: integer
                        example: 450000
                      sum_discounted:
                        type: integer
                        example: 405000
                      comment:
                        type: string
                        example: null
                      table_number:
                        type: string
                        example: null
                      is_fiscal:
                        type: boolean
                        example: false
                      date:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      created_at:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      updated_at:
                        type: string
                        example: '2026-08-08T12:15:00Z'
                      items:
                        type: array
                        example: []
        404:
          description: 'Заказ не найден'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: not_found
                    message: 'Заказ не найден'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Заказ не найден'
      tags:
        - Заказы
    parameters:
      -
        in: path
        name: id
        description: 'ID заказа.'
        example: 152380
        required: true
        schema:
          type: integer
  '/api/v2/orders/{id}/change-status':
    post:
      summary: 'Сменить статус заказа'
      operationId: ''
      description: "Универсальная смена статуса. Допустимые переходы определяются машиной\nсостояний заказа — недопустимый переход вернёт 422."
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    id: 152380
                    trade_point_id: 1
                    client_id: 9
                    status: in_progress
                    payment_status: not_paid
                    sum_original: 450000
                    sum_discounted: 405000
                    comment: 'Не звонить в домофон'
                    table_number: null
                    is_fiscal: false
                    date: '2026-08-08T11:20:00Z'
                    created_at: '2026-08-08T11:20:00Z'
                    updated_at: '2026-08-08T12:05:00Z'
                    items:
                      -
                        id: 1
                        nomenclature_id: 334
                        name: 'Ролл Филадельфия'
                        amount: 2000
                        unit_price: 225000
                        total_price: 450000
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 152380
                      trade_point_id:
                        type: integer
                        example: 1
                      client_id:
                        type: integer
                        example: 9
                      status:
                        type: string
                        example: in_progress
                      payment_status:
                        type: string
                        example: not_paid
                      sum_original:
                        type: integer
                        example: 450000
                      sum_discounted:
                        type: integer
                        example: 405000
                      comment:
                        type: string
                        example: 'Не звонить в домофон'
                      table_number:
                        type: string
                        example: null
                      is_fiscal:
                        type: boolean
                        example: false
                      date:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      created_at:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      updated_at:
                        type: string
                        example: '2026-08-08T12:05:00Z'
                      items:
                        type: array
                        example:
                          -
                            id: 1
                            nomenclature_id: 334
                            name: 'Ролл Филадельфия'
                            amount: 2000
                            unit_price: 225000
                            total_price: 450000
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            nomenclature_id:
                              type: integer
                              example: 334
                            name:
                              type: string
                              example: 'Ролл Филадельфия'
                            amount:
                              type: integer
                              example: 2000
                            unit_price:
                              type: integer
                              example: 225000
                            total_price:
                              type: integer
                              example: 450000
        404:
          description: 'Заказ не найден'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: not_found
                    message: 'Заказ не найден'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Заказ не найден'
        422:
          description: 'Недопустимый переход'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: validation_error
                    message: 'Недопустимый переход статуса'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_error
                      message:
                        type: string
                        example: 'Недопустимый переход статуса'
      tags:
        - Заказы
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  description: 'Новый статус.'
                  example: in_progress
                  nullable: false
              required:
                - status
    parameters:
      -
        in: path
        name: id
        description: 'ID заказа.'
        example: 152380
        required: true
        schema:
          type: integer
  '/api/v2/orders/{id}/change-payments':
    post:
      summary: 'Изменить оплаты заказа'
      operationId: ''
      description: "Заменяет список оплат целиком. Суммы — в тийынах (1 ₸ = 100).\nОперация идемпотентная: повтор с тем же `Idempotency-Key` не задвоит оплату."
      parameters:
        -
          in: header
          name: Idempotency-Key
          description: ''
          example: 7c2e5b19-3a4d-4f61-8b0c-19d7a4e6f2b3
          schema:
            type: string
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    id: 152380
                    trade_point_id: 1
                    client_id: 9
                    status: in_progress
                    payment_status: paid
                    sum_original: 450000
                    sum_discounted: 405000
                    comment: null
                    table_number: null
                    is_fiscal: false
                    date: '2026-08-08T11:20:00Z'
                    created_at: '2026-08-08T11:20:00Z'
                    updated_at: '2026-08-08T12:20:00Z'
                    items: []
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 152380
                      trade_point_id:
                        type: integer
                        example: 1
                      client_id:
                        type: integer
                        example: 9
                      status:
                        type: string
                        example: in_progress
                      payment_status:
                        type: string
                        example: paid
                      sum_original:
                        type: integer
                        example: 450000
                      sum_discounted:
                        type: integer
                        example: 405000
                      comment:
                        type: string
                        example: null
                      table_number:
                        type: string
                        example: null
                      is_fiscal:
                        type: boolean
                        example: false
                      date:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      created_at:
                        type: string
                        example: '2026-08-08T11:20:00Z'
                      updated_at:
                        type: string
                        example: '2026-08-08T12:20:00Z'
                      items:
                        type: array
                        example: []
        400:
          description: 'Нет Idempotency-Key'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: idempotency_key_required
                    message: 'Заголовок Idempotency-Key обязателен и должен быть UUID v4'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: idempotency_key_required
                      message:
                        type: string
                        example: 'Заголовок Idempotency-Key обязателен и должен быть UUID v4'
        404:
          description: 'Заказ не найден'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: not_found
                    message: 'Заказ не найден'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Заказ не найден'
        422:
          description: 'Сумма оплат не сходится'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: validation_error
                    message: 'Сумма оплат не совпадает с суммой заказа'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_error
                      message:
                        type: string
                        example: 'Сумма оплат не совпадает с суммой заказа'
      tags:
        - Заказы
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                payments:
                  type: array
                  description: 'Список оплат, минимум одна.'
                  example:
                    - []
                  items:
                    type: object
                    properties:
                      payment_option_id:
                        type: integer
                        description: 'ID способа оплаты.'
                        example: 7
                        nullable: false
                      amount:
                        type: integer
                        description: 'Сумма в тийынах.'
                        example: 405000
                        nullable: false
                    required:
                      - payment_option_id
                      - amount
              required:
                - payments
    parameters:
      -
        in: path
        name: id
        description: 'ID заказа.'
        example: 152380
        required: true
        schema:
          type: integer
  /api/v2/clients:
    get:
      summary: 'Список клиентов'
      operationId: ''
      description: "Постранично. Фильтры можно комбинировать. Баланс бонусов — в тийынах\n(1 ₸ = 100)."
      parameters:
        -
          in: query
          name: phone
          description: 'Телефон в формате E.164.'
          example: '+77011234567'
          required: false
          schema:
            type: string
            description: 'Телефон в формате E.164.'
            example: '+77011234567'
            nullable: false
        -
          in: query
          name: card
          description: 'Номер дисконтной карты.'
          example: '1234'
          required: false
          schema:
            type: string
            description: 'Номер дисконтной карты.'
            example: '1234'
            nullable: false
        -
          in: query
          name: name
          description: 'Поиск по имени.'
          example: Айгуль
          required: false
          schema:
            type: string
            description: 'Поиск по имени.'
            example: Айгуль
            nullable: false
        -
          in: query
          name: page
          description: 'Номер страницы, с 1.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Номер страницы, с 1.'
            example: 1
            nullable: false
        -
          in: query
          name: per_page
          description: 'Размер страницы.'
          example: 25
          required: false
          schema:
            type: integer
            description: 'Размер страницы.'
            example: 25
            nullable: false
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    items:
                      -
                        id: 9
                        phone: '+77011234567'
                        name: Айгуль
                        discount_card: '1234'
                        bonus_balance: 12500
                        created_at: '2026-06-01T09:00:00Z'
                        updated_at: '2026-08-08T12:00:00Z'
                    page_info:
                      page: 1
                      per_page: 25
                      has_next: false
                      total: 1
                      adjusted: false
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      items:
                        type: array
                        example:
                          -
                            id: 9
                            phone: '+77011234567'
                            name: Айгуль
                            discount_card: '1234'
                            bonus_balance: 12500
                            created_at: '2026-06-01T09:00:00Z'
                            updated_at: '2026-08-08T12:00:00Z'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 9
                            phone:
                              type: string
                              example: '+77011234567'
                            name:
                              type: string
                              example: Айгуль
                            discount_card:
                              type: string
                              example: '1234'
                            bonus_balance:
                              type: integer
                              example: 12500
                            created_at:
                              type: string
                              example: '2026-06-01T09:00:00Z'
                            updated_at:
                              type: string
                              example: '2026-08-08T12:00:00Z'
                      page_info:
                        type: object
                        properties:
                          page:
                            type: integer
                            example: 1
                          per_page:
                            type: integer
                            example: 25
                          has_next:
                            type: boolean
                            example: false
                          total:
                            type: integer
                            example: 1
                          adjusted:
                            type: boolean
                            example: false
        401:
          description: 'Нет или неверный токен'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: unauthenticated
                    message: Unauthenticated.
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: unauthenticated
                      message:
                        type: string
                        example: Unauthenticated.
      tags:
        - Клиенты
    post:
      summary: 'Создать клиента'
      operationId: ''
      description: "Телефон обязателен и должен быть в формате E.164 (`+` и до 15 цифр).\nОперация идемпотентная: повтор с тем же `Idempotency-Key` не создаст дубль."
      parameters:
        -
          in: header
          name: Idempotency-Key
          description: ''
          example: 9d3b1f70-5c62-4a8e-b1d4-2e6f8a0c7b55
          schema:
            type: string
      responses:
        201:
          description: Создан
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    id: 9
                    phone: '+77011234567'
                    name: Айгуль
                    discount_card: '1234'
                    bonus_balance: 12500
                    created_at: '2026-06-01T09:00:00Z'
                    updated_at: '2026-08-08T12:00:00Z'
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 9
                      phone:
                        type: string
                        example: '+77011234567'
                      name:
                        type: string
                        example: Айгуль
                      discount_card:
                        type: string
                        example: '1234'
                      bonus_balance:
                        type: integer
                        example: 12500
                      created_at:
                        type: string
                        example: '2026-06-01T09:00:00Z'
                      updated_at:
                        type: string
                        example: '2026-08-08T12:00:00Z'
        400:
          description: 'Нет Idempotency-Key'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: idempotency_key_required
                    message: 'Заголовок Idempotency-Key обязателен и должен быть UUID v4'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: idempotency_key_required
                      message:
                        type: string
                        example: 'Заголовок Idempotency-Key обязателен и должен быть UUID v4'
        422:
          description: 'Ошибка валидации'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: validation_error
                    message: 'Телефон должен быть в формате +7XXXXXXXXXX'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_error
                      message:
                        type: string
                        example: 'Телефон должен быть в формате +7XXXXXXXXXX'
      tags:
        - Клиенты
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  description: 'Телефон в формате E.164.'
                  example: '+77011234567'
                  nullable: false
                name:
                  type: string
                  description: 'Имя клиента, до 255 символов.'
                  example: Айгуль
                  nullable: false
                discount_card:
                  type: string
                  description: 'Номер дисконтной карты.'
                  example: '1234'
                  nullable: false
              required:
                - phone
  '/api/v2/clients/{id}':
    get:
      summary: 'Получить клиента'
      operationId: ''
      description: ''
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    id: 9
                    phone: '+77011234567'
                    name: Айгуль
                    discount_card: '1234'
                    bonus_balance: 12500
                    created_at: '2026-06-01T09:00:00Z'
                    updated_at: '2026-08-08T12:00:00Z'
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 9
                      phone:
                        type: string
                        example: '+77011234567'
                      name:
                        type: string
                        example: Айгуль
                      discount_card:
                        type: string
                        example: '1234'
                      bonus_balance:
                        type: integer
                        example: 12500
                      created_at:
                        type: string
                        example: '2026-06-01T09:00:00Z'
                      updated_at:
                        type: string
                        example: '2026-08-08T12:00:00Z'
        404:
          description: 'Клиент не найден'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: not_found
                    message: 'Клиент не найден'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Клиент не найден'
      tags:
        - Клиенты
    patch:
      summary: 'Изменить клиента'
      operationId: ''
      description: 'Меняет только переданные поля. Телефон через эту ручку не меняется.'
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    id: 9
                    phone: '+77011234567'
                    name: Айгуль
                    discount_card: '1234'
                    bonus_balance: 12500
                    created_at: '2026-06-01T09:00:00Z'
                    updated_at: '2026-08-08T12:00:00Z'
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 9
                      phone:
                        type: string
                        example: '+77011234567'
                      name:
                        type: string
                        example: Айгуль
                      discount_card:
                        type: string
                        example: '1234'
                      bonus_balance:
                        type: integer
                        example: 12500
                      created_at:
                        type: string
                        example: '2026-06-01T09:00:00Z'
                      updated_at:
                        type: string
                        example: '2026-08-08T12:00:00Z'
        404:
          description: 'Клиент не найден'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: not_found
                    message: 'Клиент не найден'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: not_found
                      message:
                        type: string
                        example: 'Клиент не найден'
        422:
          description: 'Ошибка валидации'
          content:
            application/json:
              schema:
                type: object
                example:
                  success: false
                  error:
                    code: validation_error
                    message: 'Имя не должно превышать 255 символов'
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: validation_error
                      message:
                        type: string
                        example: 'Имя не должно превышать 255 символов'
      tags:
        - Клиенты
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'Имя клиента, до 255 символов.'
                  example: 'Айгуль Н.'
                  nullable: false
                discount_card:
                  type: string
                  description: 'Номер дисконтной карты.'
                  example: '5678'
                  nullable: false
    parameters:
      -
        in: path
        name: id
        description: 'ID клиента.'
        example: 9
        required: true
        schema:
          type: integer
  /api/v2/health:
    get:
      summary: 'Проверка доступности'
      operationId: ''
      description: "Публичная ручка без авторизации: показывает, что API отвечает, и время\nсервера в UTC. Удобно для быстрой проверки связи и сетевого доступа."
      parameters: []
      responses:
        200:
          description: Успех
          content:
            application/json:
              schema:
                type: object
                example:
                  success: true
                  data:
                    status: ok
                    time: '2026-08-08T12:00:00Z'
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        example: ok
                      time:
                        type: string
                        example: '2026-08-08T12:00:00Z'
      tags:
        - Служебные
      security: []
tags:
  -
    name: Авторизация
    description: ''
  -
    name: Заказы
    description: ''
  -
    name: Клиенты
    description: ''
  -
    name: Служебные
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'Токен выдаёт <code>POST /api/v2/auth/login</code> (логин и пароль пользователя вашей организации в DelRes). Полученное значение подставляйте в заголовок <code>Authorization: Bearer &lt;токен&gt;</code>. Токен бессрочный; отозвать его можно через <code>POST /api/v2/auth/logout</code>.'
security:
  -
    default: []
