openapi: 3.0.3
security: []
info:
  title: Keeta Store Management API
  version: v.1.0.0
  contact:
    name: Keeta Developer Website
    email: https://developers.mykeeta.com/
  description: >-
    This API provides comprehensive store management capabilities for Keeta
    platform integration.
servers:
  - url: https://open.mykeeta.com/api/open
paths:
  /scm/shop/base/get:
    post:
      operationId: getStoreDetails
      tags:
        - Endpoints
      summary: Get Store Details
      description: >
        This endpoint allows developer to request comprehensive store details,
        including:

        1. **Store Name**

        2. **Store Images**: Includes both **effective images** (currently
        displayed) and **images in process** (pending approval)

        3. **Address Information**

        4. **Geolocation Data**: Latitude and longitude values

        5. **Business Categories**: the **primary business classification
        system** for stores registered by merchants on the Keeta platform,
        structured into two tiers: **Primary category** (main business focus)
        and **Secondary categories** (supplementary services)

        6. **Store Contact Phone Numbers**

        7. **Store Status**

        8. **Store Business Hours**
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shopId
              properties:
                shopId:
                  type: integer
                  format: int64
                  description: Unique identifier of the Keeta store
                  example: 466663
      responses:
        '200':
          description: Successful returns store details.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CommonResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/ShopBaseInfo'
  /scm/shop/picture/main/update:
    post:
      operationId: updateStoreProfileImage
      tags:
        - Endpoints
      summary: Update Store Profile Image
      description: >
        Update Store Profile Image


        **Notes:**

        1. **Image Usage Scenarios** Images are displayed in store exposure
        contexts including search results pages, homepage recommendations, and
        store header banners to increase user visibility.

        2. **Technical Specifications** Images must exceed 900×900 pixels in
        dimension and be under 5MB in file size. *Note: This endpoint performs
        no format validation - callers must ensure compliance.*

        3. **Content Requirements** Images should represent store quality and
        characteristics, featuring either high-quality signature dishes or brand
        logos (for locally renowned establishments).

        4. **URL Format Rules** Image URLs must begin with http:// or https://
        and end with .jpg, .png, .jpeg, or .webp extensions.

        5. **Approval Workflow** Changes don't take effect immediately after API
        call; all modifications require approval review before activation.

        6. **Duplicate Call Restriction** Keeta rejects duplicate requests when
        images are in "Pending Review" status.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shopId
                - pictureUrl
              properties:
                shopId:
                  type: integer
                  format: int64
                  description: Store ID
                  example: 466663
                pictureUrl:
                  type: string
                  example: >-
                    https://img-ap-hongkong.mykeeta.net/sailorproduct/9c760595674b395e330cf967hj430119511.jpg
                  description: >-
                    The URL returned by the product image upload API endpoint
                    /api/open/base/image/upload
      responses:
        '200':
          $ref: '#/components/responses/Success'
  /scm/shop/contact/update:
    post:
      operationId: updateStoreContactPhone
      tags:
        - Endpoints
      summary: Update Store Contact Phone Number
      description: >
        This endpoint allows updating a store's contact phone numbers.


        **Notes:**

        1. The updated contact numbers will be displayed on the **Keeta app** to
        facilitate customer communication with the merchant.

        2. The interface validates phone number quantity (**Minimum**: 1 phone
        number, **Maximum**: 3 phone numbers)

        3. Phone numbers must follow the strict format: International Area Code
        - Mobile Number (e.g., 86-13800138000)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shopId
                - phones
              properties:
                shopId:
                  type: integer
                  format: int64
                  description: Store ID
                  example: 466663
                phones:
                  type: array
                  description: >-
                    A list of contact number (format: International Area Code -
                    Mobile Number)
                  items:
                    type: string
                  minItems: 1
                  maxItems: 3
                  example:
                    - 852-12345678
                    - 86-18700121234
      responses:
        '200':
          $ref: '#/components/responses/Success'
  /scm/shop/business/hour/effective/get:
    post:
      operationId: queryStoreBusinessHours
      tags:
        - Endpoints
      summary: Query Store Business Hours
      description: This endpoint allows querying a store business hours.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shopId
              properties:
                shopId:
                  type: integer
                  format: int64
                  description: Store ID
                  example: 466663
      responses:
        '200':
          description: Successful returns business hours.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CommonResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        description: >
                          Merchant's business hours, returned as a map
                          structure.

                          Keys represent days of the week (e.g., "mon", "tue",
                          "wed", "thu", "fri", "sat", "sun").

                          Values are the business hours for each day.
                        additionalProperties:
                          type: array
                          items:
                            $ref: '#/components/schemas/BusinessHourDTO'
                        example:
                          mon:
                            - startTime: 36000
                              endTime: 86400
                          tue:
                            - startTime: 36000
                              endTime: 86400
                          wed:
                            - startTime: 36000
                              endTime: 86400
                          thu:
                            - startTime: 36000
                              endTime: 86400
                          fri:
                            - startTime: 36000
                              endTime: 86400
                          sat:
                            - startTime: 36000
                              endTime: 86400
                          sun:
                            - startTime: 36000
                              endTime: 86400
  /scm/shop/business/hour/effective/update:
    post:
      operationId: updateStoreBusinessHours
      tags:
        - Endpoints
      summary: Update Store Business Hours
      description: >
        This endpoint allows updating a store's business hours.


        **Notes:**

        1. To indicate a full-day closure, set both startTime and endTime to 0
        in the BusinessHourDTO structure for that day.

        2. Within the businessHourOfTheWeek field, business hours must not
        overlap for any single day.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shopId
                - businessHourOfTheWeek
              properties:
                shopId:
                  type: integer
                  format: int64
                  description: Store ID
                  example: 466663
                businessHourOfTheWeek:
                  type: object
                  description: >
                    Merchant's business hours, performed as a map structure.

                    Keys represent days of the week (e.g., "mon", "tue", "wed",
                    "thu", "fri", "sat", "sun").

                    Values are the business hours for each day.
                  additionalProperties:
                    type: array
                    items:
                      $ref: '#/components/schemas/BusinessHourDTO'
                  example:
                    mon:
                      - startTime: 3000
                        endTime: 17400
                    tue:
                      - startTime: 3000
                        endTime: 17400
                    wed:
                      - startTime: 3000
                        endTime: 17400
                    thu:
                      - startTime: 3000
                        endTime: 17400
                    fri:
                      - startTime: 3000
                        endTime: 17400
                    sat:
                      - startTime: 3000
                        endTime: 17400
                    sun:
                      - startTime: 0
                        endTime: 0
      responses:
        '200':
          $ref: '#/components/responses/Success'
  /scm/shop/status/rest:
    post:
      operationId: suspendStore
      tags:
        - Endpoints
      summary: Suspend Store
      description: >-
        Use this endpoint to suspend store operations. Suspended stores remain
        hidden from customers until manually reactivated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shopId
              properties:
                shopId:
                  type: integer
                  format: int64
                  description: Store ID
                  example: 466663
      responses:
        '200':
          $ref: '#/components/responses/Success'
  /scm/shop/status/open:
    post:
      operationId: reactivateStore
      tags:
        - Endpoints
      summary: Store Reactivation
      description: >-
        This endpoint reactivates suspended stores, transitioning them from a
        non-operational state back to operational status for order acceptance
        and customer visibility.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shopId
              properties:
                shopId:
                  type: integer
                  format: int64
                  description: Store ID
                  example: 466663
      responses:
        '200':
          $ref: '#/components/responses/Success'
  /scm/shop/special/business/hour/effective/get:
    post:
      operationId: querySpecialBusinessHours
      tags:
        - Endpoints
      summary: Query Special Business Hours
      description: >
        This endpoint retrieves a store's currently active special business
        hours, which temporarily override regular operating hours for specific
        dates (e.g., holidays, events).


        **Notes:**

        1. Special business hours refer to temporarily adjusted operating
        schedules for stores on specific dates, such as holidays, special
        events, or operational changes that differ from regular weekly hours

        2. When configured, these hours automatically override standard
        schedules during their effective period and seamlessly revert to normal
        hours after expiration without manual intervention, ensuring continuous
        and accurate operational information.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shopId
              properties:
                shopId:
                  type: integer
                  format: int64
                  description: Store ID
                  example: 466663
      responses:
        '200':
          description: Successful returns special business hours.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CommonResponse'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/SpecialBusinessHourDTO'
  /scm/shop/special/business/hour/effective/update:
    post:
      operationId: updateSpecialBusinessHours
      tags:
        - Endpoints
      summary: Update Special Business Hours
      description: >
        This endpoint updates a store's special business hours, enforcing
        non-overlapping date ranges and supporting full-day closures or complete
        configuration clearance.


        **Notes:**

        1. Multiple SpecialBusinessHourDTO entries must have non-overlapping
        date ranges (startDate to endDate) to prevent scheduling conflicts and
        ensure operational clarity.

        2. To indicate 24-hour closure during a period, submit one
        SpecialBusinessHourDTO with startTime=0 and endTime=0.

        3. To completely clear all special business hours configurations, set
        the specialBusinessHour field to either null or an empty array [] in
        your request payload.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shopId
                - specialBusinessHour
              properties:
                shopId:
                  type: integer
                  format: int64
                  description: Store ID
                  example: 466663
                specialBusinessHour:
                  type: array
                  description: Special business hours list
                  items:
                    $ref: '#/components/schemas/SpecialBusinessHourDTO'
      responses:
        '200':
          $ref: '#/components/responses/Success'
x-webhooks:
  businessHourUpdateNotification:
    post:
      operationId: businessHourUpdateNotification
      tags:
        - Webhooks
      summary: Store Business Hour Update Notification
      description: >
        Keeta pushes real-time notifications when either regular business hours
        or special business hours are modified.


        **Event ID:** 1101


        **Notes:** Both 'business hour' and 'special business hour' applied this
        endpoint for any updates.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shopId:
                  type: integer
                  format: int64
                  description: Store ID
                  example: 466663
                businessHourOfTheWeek:
                  type: object
                  example:
                    thu:
                      - startTime: 46800
                        endTime: 84600
                    tue:
                      - startTime: 46800
                        endTime: 84600
                    wed:
                      - startTime: 46800
                        endTime: 84600
                    sat:
                      - startTime: 46800
                        endTime: 84600
                    fri:
                      - startTime: 46800
                        endTime: 84600
                    mon:
                      - startTime: 46800
                        endTime: 84600
                    sun:
                      - startTime: 46800
                        endTime: 84600
                  description: Updated business hour
                  additionalProperties:
                    type: array
                    items:
                      $ref: '#/components/schemas/BusinessHourDTO'
                specialBusinessHour:
                  type: array
                  description: Updated special business hour
                  items:
                    $ref: '#/components/schemas/SpecialBusinessHourDTO'
      responses:
        '200':
          $ref: '#/components/responses/Success'
  storeStatusUpdateNotification:
    post:
      operationId: storeStatusUpdateNotification
      summary: Store Status Update Notification
      tags:
        - Webhooks
      description: >
        Keeta pushes real-time notifications when a store's operational status
        changes, enabling immediate order availability updates based on status
        codes and business hours.


        **Event ID:** 1102


        **Notes:** A store accepts orders only when its status is 3 (Operating)
        and the current time falls within configured business hours; if the
        status is 4 (Suspended), orders are blocked immediately regardless of
        business hours.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                shopId:
                  type: integer
                  format: int64
                  description: Store ID
                  example: 466663
                fromStatus:
                  type: integer
                  description: Previous store status
                  example: 4
                toStatus:
                  type: integer
                  description: |
                    New store status
                  enum:
                    - 3
                    - 4
                  x-enumDescriptions:
                    '3': >-
                      Indicates the store is actively conducting business. Keeta
                      will only permit order submissions when both conditions
                      are satisfied, the status equals 3 and the current time
                      falls within published operating hours.
                    '4': >-
                      represents a complete operational pause, automatically
                      disabling all order placement capabilities regardless of
                      scheduled business hours.
      responses:
        '200':
          $ref: '#/components/responses/Success'
components:
  responses:
    Success:
      description: Request executed successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonResponse'
  schemas:
    CommonResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: integer
          description: >
            A numeric status identifier indicating the result of the interface
            call, used to determine whether the operation executed
            successfully. 
          x-enumDescriptions:
            '0': The request was executed successfully.
            Non-zero value: >-
              The request execution failed. Specific error details can be viewed
              in the message field.
          example: 0
        message:
          type: string
          description: >-
            Text description corresponding to the status code, explaining the
            operation result or error cause to users.
          example: Success
    ShopBaseInfo:
      type: object
      properties:
        shopId:
          type: integer
          format: int64
          description: Unique identifier of the Keeta store
          example: 466663
        name:
          type: string
          description: The official display name of the specific branch location.
        enName:
          type: string
          description: >-
            The official display name in English of the specific branch
            location.
        mainPictures:
          type: array
          description: >
            The store primary image list includes both effective (approved) and
            in-process (pending/rejected) images. When no in-process images
            exist, only effective images are returned.

            **Primary Use Cases:**

            - Search result pages

            - Homepage recommendations

            - Store header banners

            - All merchant visibility scenarios
          items:
            $ref: '#/components/schemas/MainPicture'
        logoUrl:
          type: string
          example: >-
            http://img-ap-hongkong.mykeeta.net/sailorproduct/a1232319d53a2fa1e704d2a2ea016cbb167763.jpg
          description: >-
            The logo image will be displayed as the profile avatar on store page
            and merchant profile cards.
        address:
          type: string
          example: 新界屯門時代廣場南翼3樓25號舖
          description: Store address
        enAddress:
          type: string
          example: Times Square South Wing, 3/F, Shop 25, Tuen Mun, New Territories
          description: Store address in English
        longitude:
          type: number
          format: double
          example: 113.9758571
          description: Longitude coordinate
        latitude:
          type: number
          format: double
          example: 22.3922083
          description: Latitude coordinate
        primaryCategoryList:
          type: array
          description: Primary Business Category consists of three levels
          items:
            $ref: '#/components/schemas/Category'
        supportCategoryList:
          type: array
          description: Secondary Business Category consists of three levels
          items:
            $ref: '#/components/schemas/Category'
        phones:
          type: array
          description: List of the store contact phone number
          items:
            type: string
            example: 852-99988202
        status:
          type: integer
          description: |
            Store status:
          x-enumDescriptions:
            '3': >-
              Indicates the store is actively conducting business. Keeta will
              only permit order submissions when both conditions are satisfied,
              the status equals 3 and the current time falls within published
              operating hours.
            '4': >-
              represents a complete operational pause, automatically disabling
              all order placement capabilities regardless of scheduled business
              hours.
          example: 3
    MainPicture:
      type: object
      properties:
        url:
          type: string
          example: >-
            http://img-ap-hongkong.mykeeta.net/sailorproduct/59903319d53a2fa1e704d2a2aa3416cbb167763.jpg
          description: Image URL
        status:
          type: integer
          description: >
            After uploading images to the Keeta platform, all visual assets must
            undergo mandatory content review before becoming available for use.
            The system maintains clear status indicators throughout this
            verification process:
          x-enumDescriptions:
            '25': >-
              indicates that the image has been successfully uploaded and is
              currently in the review queue.
            '30': indicates that the image failed compliance checks.
            '60': confirms the image has passed all quality and compliance checks.
          example: 60
        rejectReason:
          type: string
          description: The reason why the image was rejected
          example: The reason why the image was rejected
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1004
          description: The unique identifier of a category
        level:
          type: integer
          example: 1
          description: Level of the category
        name:
          type: string
          example: Fast Food/Snacks
          description: Category name
        leaf:
          type: integer
          example: 0
          description: >-
            This field indicates that if the current category level is on the
            terminal node in Keeta hierarchical category system.
    BusinessHourDTO:
      type: object
      required:
        - startTime
        - endTime
      properties:
        startTime:
          type: integer
          description: |
            Start time of business period in seconds:
            - Range: 0 (midnight) to 86400 (next midnight)
            - For full-day closure: Set to 0 along with endTime=0
            - Time periods must not overlap within the same day
          example: 27000
        endTime:
          type: integer
          description: |
            End time of business period in seconds:
            - Must be >= startTime except for cross-day periods
            - For full-day closure: Set to 0 along with startTime=0
          example: 28000
    SpecialBusinessHourDTO:
      type: object
      required:
        - startDate
        - endDate
        - businessHour
      properties:
        startDate:
          type: integer
          format: int64
          description: >-
            Start date timestamp (milliseconds) for **00:00:00.000** of the day
            timestamp example: 1690214400000 (2023-07-24 00:00:00 UTC)
          example: 1690214400000
        endDate:
          type: integer
          format: int64
          description: >-
            End date timestamp (milliseconds) for **23:59:59.999** of the day
            timestamp example: 1690646399999 (2023-07-28 23:59:59.999 UTC)
          example: 1690646399999
        businessHour:
          type: array
          description: |
            Operating hours during [startDate, endDate] period
            Full-day closure: Single DTO with startTime=0 and endTime=0
          items:
            $ref: '#/components/schemas/BusinessHourDTO'
tags:
  - name: Endpoints
    description: >-
      Request APIs - All endpoints for requesting store information and making
      updates
  - name: Webhooks
    description: Webhooks - Webhook notifications sent by Keeta to third-party systems
