openapi: 3.0.3
security: []
info:
  title: Keeta Basic API Reference
  version: v.1.0.0
  contact:
    name: Keeta Developer Website
    email: https://developers.mykeeta.com/
  description: >
    This API provides basic functionality for Keeta platform integration,
    including webhook configuration, authorization management, and OAuth token
    operations.
servers:
  - url: https://open.mykeeta.com/api/open
paths:
  /base/callback/url/set:
    post:
      operationId: configureWebhookUrl
      summary: Webhook URL Configuration
      description: >
        This API enables developers to configure webhook URLs for receiving
        real-time notifications from the Keeta platform regarding orders,
        stores, menus, and other relevant business events.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - eventId
                - url
                - isTest
              properties:
                eventId:
                  type: integer
                  description: Represents the message type code for push notifications
                  example: 1001
                url:
                  type: string
                  description: >-
                    The webhook URL provided by developers where Keeta system
                    will send notifications
                  example: https://open.mykeeta.com/api/open/base/image/upload
                isTest:
                  type: integer
                  description: |
                    Indicates whether this request comes from a test store:

                    - 0: Production store (non-test)

                    - 1: Test store (default value if not specified)
                  example: 1
      responses:
        '200':
          description: Webhook URL configuration result.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CommonResponse'
  /base/authorized/resource/get:
    post:
      operationId: getAuthorizedResources
      summary: Get Merchant Authorization Information
      description: >
        This API retrieves merchant information and authorized store lists based
        on the authentication token provided in the request, enabling developers
        to validate access permissions and obtain essential business context.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - pageNum
                - pageSize
                - appId
                - accessToken
              properties:
                pageNum:
                  type: integer
                  example: 1
                  description: >-
                    Pagination parameter: indicates the current page number
                    (starting from 1)
                pageSize:
                  type: integer
                  example: 1
                  description: 'Pagination parameter: indicates the number of items per page'
                appId:
                  type: integer
                  example: 834563
                  description: Unique application ID assigned by Keeta
                accessToken:
                  type: string
                  example: b989f155b3304da19a324021eb9e9aaa
                  description: The primary credentia from Keeta For identify your identity
      responses:
        '200':
          description: Successful retrieval of authorized resources.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CommonResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/AuthorizedResourceResponse'
  /base/oauth/token:
    post:
      operationId: oauthToken
      summary: OAuth Token Operations
      description: >
        This endpoint handles both access token acquisition and token refresh
        operations based on the grantType parameter.


        **For Access Token Acquisition (grantType = "authorization_code"):**

        This endpoint enables developers to acquire access token from Keeta.


        **For Token Refresh (grantType = "refresh_token"):** 

        This endpoint enables developers to refresh access token validity period
        from Keeta platform.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/AccessTokenRequest'
                - $ref: '#/components/schemas/RefreshTokenRequest'
              discriminator:
                propertyName: grantType
                mapping:
                  authorization_code: '#/components/schemas/AccessTokenRequest'
                  refresh_token: '#/components/schemas/RefreshTokenRequest'
      responses:
        '200':
          description: OAuth token operation result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
  /base/batchDecrypt:
    post:
      operationId: batchDecrypt
      summary: Batch Decrypt
      description: >
        > 1. For **merchant self-delivery or third-party logistics (3PL)**
        orders, this endpoint can be called to decrypt the user's phone number
        and address.

        > 2. A maximum of **50** data items can be decrypted at once.

        > 3. The encrypted data generally uses `ENC_` as a prefix.


        The following data returned by the order details endpoints will be
        encrypted data (ciphertext data prefixed with `ENC_`):

        > 1. recipientInfo.addressLocation

        > 2. delirecipientInfovery.addressViewInfo

        > 3. recipientInfo.houseNumber

        > 4. recipientInfo.phone

        > 5. recipientInfo.detailAddressStruct

        > 6. recipientInfo.addressStruct
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - appId
                - cipherInfos
              properties:
                appId:
                  type: integer
                  description: appId
                  example: 3585234
                shopId:
                  type: integer
                  description: shopId
                  example: 35465234
                cipherInfos:
                  type: array
                  description: The ciphertext that needs to be decrypted
                  items:
                    $ref: '#/components/schemas/CipherText'
      responses:
        '200':
          description: The decryption result corresponding to the ciphertext.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/CommonResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        $ref: '#/components/schemas/DecryptResponse'
components:
  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
    AuthorizedResourceResponse:
      type: object
      properties:
        userId:
          type: string
          example: '593890666'
          description: Merchant Account ID
        brandId:
          type: integer
          format: int64
          example: 4323
          description: Brand ID of the store
        brandName:
          type: string
          example: GUI JI
          description: Brand name of the store
        authorizedShops:
          type: array
          description: List of authorized stores
          items:
            $ref: '#/components/schemas/AuthorizedShop'
        page:
          allOf:
            - description: Pagination information container
            - $ref: '#/components/schemas/PageInfo'
    AuthorizedShop:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 593890
          description: Unique identifier of the store
        name:
          type: string
          example: GUIJI
          description: Name of the store
        address:
          type: string
          example: Shop 266, 2nd Floor, Kwai Fong New Metropolis Plaza
          description: Physical address of the store
        longitude:
          type: string
          example: '114.127006'
          description: Geographic longitude coordinate of the store
        latitude:
          type: string
          example: '22.357059'
          description: Geographic latitude coordinate of the store
    PageInfo:
      type: object
      description: Pagination information container
      properties:
        pageNum:
          type: integer
          example: 1
          description: Current page number (1-based index)
        pageSize:
          type: integer
          example: 10
          description: Number of items displayed per page
        totalPage:
          type: integer
          example: 1
          description: Total number of pages available
        totalCount:
          type: integer
          example: 1
          description: Total number of items across all pages
    CipherText:
      type: object
      description: cipher text object
      properties:
        cipherText:
          type: string
          example: ENC_NzURv/tedeRcBhtxidwjwcxOoljZsmaOB72uNv3RDL4=
    DecryptResponse:
      type: object
      properties:
        plainInfos:
          type: array
          items:
            $ref: '#/components/schemas/DecryptPlainInfos'
    DecryptPlainInfos:
      type: object
      properties:
        errorMsg:
          type: string
          example: success
        plainText:
          type: string
          example: Rua xxxxx, 427, Tsiroanomandidy, Bongolava
        errorCode:
          type: integer
          example: 0
        cipherText:
          type: string
          example: ENC_XSwD1JYiBb5x5g6/vOhTf+U+fHz57vdHU5KBVGX
    AccessTokenRequest:
      type: object
      required:
        - appId
        - timestamp
        - sig
        - grantType
        - code
      properties:
        appId:
          type: integer
          format: int64
          example: 3340612437
          description: Unique application ID assigned by Keeta
        timestamp:
          type: integer
          example: 1740151097
          description: Unix timestamp (seconds since 1970-01-01)
        sig:
          type: string
          example: 7713bf15971faf402341bd0a372af7af5d788c25a8b08d7f238314b43a46f768
          description: Result of the sig calculation
        grantType:
          type: string
          description: >-
            This field represents the mode of the authorization code, and its
            value should be fixed as "authorization_code".
          enum:
            - authorization_code
          example: authorization_code
        code:
          type: string
          example: '885000242'
          description: Authorization code
    RefreshTokenRequest:
      type: object
      required:
        - appId
        - timestamp
        - sig
        - grantType
        - refreshToken
      properties:
        appId:
          type: integer
          format: int64
          example: 9940612437
          description: Unique application ID assigned by Keeta
        timestamp:
          type: integer
          example: 1740151097
          description: Unix timestamp (seconds since 1970-01-01)
        sig:
          type: string
          example: 7773bf15971faf402341bd0a372af7af5d788c25a8b08d7f238314b43a46f768
          description: Result of the sig calculation
        grantType:
          type: string
          description: >-
            This field represents the mode of the authorization code, and its
            value should be fixed as "refresh_token".
          enum:
            - refresh_token
          example: refresh_token
        refreshToken:
          type: string
          example: 011e258c2715400d9160e9a1820af3d9
          description: Refresh token obtained from previous token acquisition
    TokenResponse:
      type: object
      properties:
        accessToken:
          type: string
          example: 911b56fbc7c14ef397261f5efd1d1b99
          description: >-
            The access token serves as the primary credential for authenticating
            API requests.
        tokenType:
          type: string
          description: >-
            This field specifies the type of token issued, with the fixed value
            "bearer" indicating that the token is a bearer token.
          example: bearer
        expiresIn:
          type: integer
          description: >-
            The expiration period of the access token, measured in seconds.
            Tokens remain valid for precisely 90 days (7,776,000 seconds)
          example: 7776000
        refreshToken:
          type: string
          example: q11bd86271e844cca7dbc139bb3f00f7
          description: >-
            A credential used to obtain new access tokens when the current token
            nears expiration. Each refresh token may only be used once and
            becomes invalid immediately after use. The system automatically
            issues a new refresh token with each access token refresh.
        scope:
          type: string
          description: >-
            Defines the permissions granted to the token, corresponding to the
            scopes requested by the client application. The default value "all"
            grants complete access.
          example: all
        issuedAtTime:
          type: integer
          format: int64
          example: 1740151097721
          description: >-
            The precise timestamp of token issuance represented as Unix epoch
            time in milliseconds.
