openapi: 3.0.4
info:
  title: CHIBBIS Partner Notifications API
  version: v1
  description: |
    Публичная спецификация для партнеров CHIBBIS.

    В документ включены только методы, которые должен использовать партнер:
    - передача статусов заказа;
    - передача статусов магазина;
    - запуск интеграций зон доставки, меню и стоп-листа.

servers:
  - url: https://integration.chibbis.dev
    description: CHIBBIS Integration API

tags:
  - name: OrderStatus
    description: Уведомления об изменении статуса заказа.
  - name: StoreStatus
    description: Уведомления об изменении статуса магазина.
  - name: Triggers
    description: Ручной запуск интеграций зон доставки, меню и стоп-листа.

paths:
  /partner-triggers/order-status-change:
    post:
      tags:
        - OrderStatus
      summary: Уведомление об изменении статуса заказа
      description: |
        Партнер сообщает CHIBBIS о новом статусе заказа.

        Все данные передаются только в теле запроса `application/json`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeOrderStatusRequest'
            example:
              externalStoreId: STORE-001
              externalOrderId: EXT-12345
              newStatus: 7
              completeBefore: '2025-03-05T14:00:00+03:00'
              comment: Готовится
      responses:
        '204':
          description: No Content

  /partner-triggers/store-status-change:
    post:
      tags:
        - StoreStatus
      summary: Уведомление об изменении статуса магазина
      description: |
        Партнер сообщает CHIBBIS об изменении статуса магазина.

        Все данные передаются только в теле запроса `application/json`.

        Важные правила для интегратора:
        - `comment` обязателен при `newStatus = 1` (`TemporaryClosed`) и `newStatus = 2` (`Blocked`).
        - `closeAfter` и `openAfter` используются только при `newStatus = 1` (`TemporaryClosed`).
        - Если `closeAfter` не передать, магазин закроется сразу.
        - Если `closeAfter` передан, магазин закроется в указанное время.
        - Если `openAfter` не передать, магазин не откроется автоматически.
        - Если магазин переведен в `newStatus = 2` (`Blocked`), дальнейшие попытки изменить статус должны выполняться через поддержку CHIBBIS.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeStoreStatusRequest'
            example:
              externalStoreId: STORE-001
              newStatus: 1
              comment: Ремонт
              openAfter: '2025-03-06T09:00:00+03:00'
      responses:
        '204':
          description: No Content

  /partner-triggers/delivery-areas:
    post:
      tags:
        - Triggers
      summary: Запуск интеграции зон доставки
      description: |
        Запускает синхронизацию зон доставки.

        Опциональный параметр `externalStoreId` позволяет ограничить запуск одним магазином партнера.
        Если параметр не передан, обновление будет выполнено по всем доступным партнеру магазинам.
      parameters:
        - name: externalStoreId
          in: query
          description: Необязательный параметр. Ограничивает синхронизацию одним магазином партнера. Если не передан, обновление выполняется по всем доступным партнеру магазинам.
          schema:
            type: string
          example: STORE-001
      responses:
        '204':
          description: No Content

  /partner-triggers/menu:
    post:
      tags:
        - Triggers
      summary: Запуск интеграции меню
      description: |
        Запускает синхронизацию меню.

        Опциональный параметр `externalStoreId` позволяет ограничить запуск одним магазином партнера.
        Если параметр не передан, обновление будет выполнено по всем доступным партнеру магазинам.
      parameters:
        - name: externalStoreId
          in: query
          description: Необязательный параметр. Ограничивает синхронизацию одним магазином партнера. Если не передан, обновление выполняется по всем доступным партнеру магазинам.
          schema:
            type: string
          example: STORE-001
      responses:
        '204':
          description: No Content

  /partner-triggers/stop-list:
    post:
      tags:
        - Triggers
      summary: Запуск интеграции стоп-листа
      description: |
        Запускает синхронизацию стоп-листа.

        Опциональный параметр `externalStoreId` позволяет ограничить запуск одним магазином партнера.
        Если параметр не передан, обновление будет выполнено по всем доступным партнеру магазинам.
      parameters:
        - name: externalStoreId
          in: query
          description: Необязательный параметр. Ограничивает синхронизацию одним магазином партнера. Если не передан, обновление выполняется по всем доступным партнеру магазинам.
          schema:
            type: string
          example: STORE-001
      responses:
        '204':
          description: No Content

components:
  securitySchemes:
    AuthorizationHeader:
      type: apiKey
      description: API key в заголовке Authorization.
      name: Authorization
      in: header

  schemas:
    PartnerOrderStatus:
      type: integer
      format: int32
      enum:
        - 0
        - 1
        - 2
        - 3
        - 7
        - 8
        - 10
      description: |
        Статус заказа.

        Возможные значения:
        - `0` — `BeingProcessed`
        - `1` — `Accepted`
        - `2` — `Delivered`
        - `3` — `Cancelled`
        - `7` — `Cooking`
        - `8` — `Delivering`
        - `10` — `Ready`

    DesiredStoreStatus:
      type: integer
      format: int32
      enum:
        - 0
        - 1
        - 2
      description: |
        Целевой статус магазина.

        Возможные значения:
        - `0` — `Open`
        - `1` — `TemporaryClosed`
        - `2` — `Blocked`

        Если магазин переведен в `Blocked`, дальнейшие попытки изменить его статус должны выполняться через поддержку CHIBBIS.

    ChangeOrderStatusRequest:
      type: object
      additionalProperties: false
      description: |
        Запрос на изменение статуса заказа.

        Параметр `comment` обязателен при `newStatus = 3` (`Cancelled`).
      oneOf:
        - required:
            - externalStoreId
            - externalOrderId
            - newStatus
          properties:
            newStatus:
              type: integer
              enum:
                - 0
                - 1
                - 2
                - 7
                - 8
                - 10
        - required:
            - externalStoreId
            - externalOrderId
            - newStatus
            - comment
          properties:
            newStatus:
              type: integer
              enum:
                - 3
      required:
        - externalStoreId
        - externalOrderId
        - newStatus
      properties:
        externalStoreId:
          type: string
          description: Внешний идентификатор магазина у партнера.
        externalOrderId:
          type: string
          description: Внешний идентификатор заказа у партнера.
        newStatus:
          $ref: '#/components/schemas/PartnerOrderStatus'
        completeBefore:
          type: string
          format: date-time
          description: Дата и время в формате ISO 8601.
        comment:
          type: string
          nullable: true
          description: |
            Комментарий к смене статуса.

            Обязателен при `newStatus = 3`.

    ChangeStoreStatusRequest:
      type: object
      additionalProperties: false
      description: |
        Запрос на изменение статуса магазина.

        Параметр `comment` обязателен при `newStatus = 1` (`TemporaryClosed`) и `newStatus = 2` (`Blocked`).
        Параметры `closeAfter` и `openAfter` используются только при `newStatus = 1` (`TemporaryClosed`).
      oneOf:
        - required:
            - externalStoreId
            - newStatus
          properties:
            newStatus:
              type: integer
              enum:
                - 0
        - required:
            - externalStoreId
            - newStatus
            - comment
          properties:
            newStatus:
              type: integer
              enum:
                - 1
                - 2
      required:
        - externalStoreId
        - newStatus
      properties:
        externalStoreId:
          type: string
          description: Внешний идентификатор магазина у партнера.
        newStatus:
          $ref: '#/components/schemas/DesiredStoreStatus'
        comment:
          type: string
          nullable: true
          description: |
            Комментарий к изменению статуса.

            Обязателен при `newStatus = 1` и `newStatus = 2`.
        closeAfter:
          type: string
          format: date-time
          description: |
            Планируемое время закрытия в формате ISO 8601.

            Используется только при `newStatus = 1`.
            Если параметр не передан, магазин закроется сразу.
            Если параметр передан, магазин закроется в указанное время.
        openAfter:
          type: string
          format: date-time
          description: |
            Планируемое время открытия в формате ISO 8601.

            Используется только при `newStatus = 1`.
            Если параметр не передан, магазин не откроется автоматически.

security:
  - AuthorizationHeader: []
