openapi: 3.0.0
servers:
  - url: "https://{clusterId}.api.esales.apptus.cloud/"
    description: "Your clusterId"
    variables:
      clusterId:
        default: "w00000000"
info:
  version: 2.0.0
  title: Voyado Elevate Web API Playground
  termsOfService: 'https://voyado.com/legal/elevate-terms-conditions/'
  contact:
    email: support@voyado.com

paths:
  '/api/v2/panels/{panelPath}':
    get:
      tags:
        - Panels
      summary: Query configured eSales panels
      description: |
        Panel queries are the main way of fetching results, such as products or ads from eSales. Panels can be queried through the Web API when the panel hierarchy for your site has been published. A successful query returns the panel content in flattened and serialised JSON format.

        Parameters that have not been set in panel configuration or have a default value in pre-defined panels has to be sent as arguments.
      parameters:
        - name: panelPath
          in: path
          description: Panel path
          required: true
          allowReserved: true
          schema:
            type: string
        - name: esales.customerKey
          in: query
          description: Unique customer key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.sessionKey
          in: query
          description: Unique session key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.market
          in: query
          description: Customer market
          required: true
          schema:
            type: string
        - description: Free form query parameters as json object
          in: query
          name: freeForm
          explode: True
          allowEmptyValue: True
          schema:
            type: object
            additionalProperties:
              type: string
          style: form
      responses:
        '200':
          description: Returns panel content flattened and serialized to JSON
        '400':
          description: Invalid or missing arguments for this panel.
        '404':
          description: Panel not found or not public.
        '503':
          description: Service unavailable, no products found in cluster.

  '/api/v2/dynamic-pages':
    post:
      tags:
        - Dynamic Pages
      summary: Query multiple panels without configured zones
      description: |
        Dynamic pages is a concept which makes it possible to retrieve content from several panels at once, without pre-defining a zone for each combination of panels that might be called at once. A dynamic page must be called server side.

        A query to a dynamic page includes arguments to the sub-panels of that page. This enables the re-use of a dynamic page by supplying different arguments to the sub-panel. A successful query returns the dynamic page content in flattened and serialised JSON format. When querying a dynamic page via the Web API, an Api-Key header is required for authentication.
      parameters:
        - name: Api-Key
          in: header
          description: secret api key
          required: true
          schema:
            type: string
        - name: esales.customerKey
          in: query
          description: Unique customer key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.sessionKey
          in: query
          description: Unique session key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.market
          in: query
          description: Customer market
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - panel
                - name
                - subpanels
              properties:
                panel:
                  type: string
                name:
                  type: string
                arguments:
                  type: object
                subpanels:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      panel:
                        type: string
                      arguments:
                        type: object
      responses:
        '200':
          description: Return panel content flattened and serialized to JSON
        '400':
          description: Invalid or missing arguments to any of the requested panels.
        '403':
          description: Api-Key could not be validated
        '404':
          description: Panel not found or not public.

  '/api/v2/notifications/click':
    post:
      tags:
        - Notifications
      summary: Click notification on customer eSales action
      description: |
        The click notification is to be sent with a ticket when the visitor clicks on a product, an ad, or any other eSales entities. The ticket is a unique string for an object generated by eSales.<Paste>
      parameters:
        - name: esales.customerKey
          in: query
          description: Unique customer key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.sessionKey
          in: query
          description: Unique session key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.market
          in: query
          description: Customer market
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Notifications was received successfully.
        '400':
          description: Invalid or missing required arguments.
      requestBody:
        $ref: '#/components/requestBodies/esales-notification'

  '/api/v2/notifications/non-esales-click':
    post:
      tags:
        - Notifications
      summary: Click notification on customer non-eSales action
      description: |
        The non-eSales click notification is to be sent when a visitor has clicked a product that is not returned by eSales (i.e. not having a ticket). Instead of a ticket, a product key (and if applicable, a variant key) is sent.
      parameters:
        - name: esales.customerKey
          in: query
          description: Unique customer key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.sessionKey
          in: query
          description: Unique session key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.market
          in: query
          description: Customer market
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Notifications was received successfully.
        '400':
          description: Invalid or missing required arguments.
      requestBody:
        $ref: '#/components/requestBodies/non-esales-notification'

  '/api/v2/notifications/adding-to-cart':
    post:
      tags:
        - Notifications
      summary: Add to cart notification for eSales product
      description: |
        The adding-to-cart notification is to be sent with a ticket when a visitor adds an eSales product to their cart. The ticket is a unique string for an object generated by eSales.
      parameters:
        - name: esales.customerKey
          in: query
          description: Unique customer key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.sessionKey
          in: query
          description: Unique session key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.market
          in: query
          description: Customer market
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Notifications was received successfully.
        '400':
          description: Invalid or missing required arguments.
      requestBody:
        $ref: '#/components/requestBodies/esales-notification'

  '/api/v2/notifications/non-esales-adding-to-cart':
    post:
      tags:
        - Notifications
      summary: Add to cart notification for non-eSales product
      description: |
        The non-esales adding-to-cart notification is sent when a visitor adds a product not returned by eSales (i.e. not having a ticket) to their cart. Instead of a ticket, a product key (and if applicable, a variant key) is sent.
      parameters:
        - name: esales.customerKey
          in: query
          description: Unique customer key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.sessionKey
          in: query
          description: Unique session key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.market
          in: query
          description: Customer market
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Notifications was received successfully.
        '400':
          description: Ticket is missing.
        '403':
          description: A personal customer key was used, but it could not be validated.
      requestBody:
        $ref: '#/components/requestBodies/non-esales-notification'

  '/api/v2/notifications/payment':
    post:
      tags:
        - Notifications
      summary: Payment notification upon successful transaction
      description: |
        The payment notification is to be sent when the visitor has placed an order of one or more products and completed payment.
      parameters:
        - name: esales.customerKey
          in: query
          description: Unique customer key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.sessionKey
          in: query
          description: Unique session key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.market
          in: query
          description: Customer market
          required: true
          schema:
            type: string
        - name: Api-Key
          in: header
          description: secret api key
          schema:
            type: string
      responses:
        '204':
          description: Notifications was received successfully.
        '400':
          description: There were no order lines in the payment notification, missing or invalid required arguments.
        '403':
          description: Client side payment notifications has been disabled for this cluster.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - lines
              properties:
                lines:
                  type: array
                  items:
                    $ref: '#/components/schemas/payment'
        description: web api click description
        required: true

  '/api/v2/notifications/favorite/add':
    post:
      tags:
        - Notifications
      summary: Add favorite notification for a eSales product
      description: |
        Add favorite notification is to be used when a customer marks a product as favorite.
      parameters:
        - name: esales.customerKey
          in: query
          description: Unique customer key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.sessionKey
          in: query
          description: Unique session key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.market
          in: query
          description: Customer market
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Notifications was received successfully.
        '400':
          description: Invalid or missing required arguments.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/favorite'
        description: Actual imports
        required: true

  '/api/v2/notifications/favorite/remove':
      post:
        tags:
          - Notifications
        summary: Remove favorite notification for a eSales product
        description: |
          Remove favorite notification is to be used when a customer unmarks a product as favorite.
        parameters:
          - name: esales.customerKey
            in: query
            description: Unique customer key (UUID)
            required: true
            schema:
              type: string
              format: uuid
              default: 00000000-0000-0000-0000-000000000000
          - name: esales.sessionKey
            in: query
            description: Unique session key (UUID)
            required: true
            schema:
              type: string
              format: uuid
              default: 00000000-0000-0000-0000-000000000000
          - name: esales.market
            in: query
            description: Customer market
            required: true
            schema:
              type: string
        responses:
          '204':
            description: Notifications was received successfully.
          '400':
            description: Invalid or missing required arguments.
        requestBody:
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/favorite'
          description: Actual imports
          required: true

  '/api/v2/notifications/end':
    post:
      tags:
        - Notifications
      summary: End current session notification
      description: |
        To end a visitor session, an end notification is to be sent to Voyado Elevate. The level of personalisation affects the actions performed when a session ends.
      parameters:
        - name: esales.customerKey
          in: query
          description: Unique customer key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.sessionKey
          in: query
          description: Unique session key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
        - name: esales.market
          in: query
          description: Customer market
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Notifications was received successfully.
        '400':
          description: Invalid or missing required arguments.

  '/api/v2/import/{type}':
    post:
      tags:
        - Imports
      summary: Import products, configuration. etc 
      description: |
        Imports is the method used to add data into eSales by way of posting XML to the Web API. The XML must be encoded using UTF-8 and include the operations that is to be performed and all other data type related information. Allowed operations for imports are add, update, remove, and clear.

        When importing data via the Web API, an Api-Key header is required for authentication.
      parameters:
        - in: header
          name: Api-Key
          description: secret api key
          required: true
          schema:
            type: string
        - name: type
          in: path
          description: Type of import
          required: true
          schema:
            type: array
            items:
              type: string
              enum:
                - products
                - panels
                - ads
                - synonyms
                - configuration
        - name: name
          in: query
          description: Name of import
          schema:
            type: string
        - name: blockingTimeout
          in: query
          description: Max duration to wait for a response.
          schema:
            type: string
            format: iso-8601
            default: PT5M
      responses:
        '204':
          description: The import completed successfully.
        '403':
          description: Incorrect Api-Key.
        '404':
          description: Cluster not found.
      requestBody:
        content:
          application/xml:
            schema:
              type: array
              items:
                properties:
                  product:
                    type: string
        description: Actual imports
        required: true

  '/api/v2/export/{type}':
    get:
      tags:
        - Exports
      summary: Export products, configuration. etc 
      description: |
        Exports is the method used to extract data from eSales. When exporting data via the Web API, an Api-Key header is required for authentication.
      parameters:
        - name: Api-Key
          in: header
          description: secret api key
          required: true
          schema:
            type: string
        - name: type
          in: path
          description: Type of export
          required: true
          schema:
            type: array
            items:
              type: string
              enum:
                - products
                - panels
                - ads
                - synonyms
                - configuration
        - name: name
          in: query
          description: Name of export
          schema:
            type: string
      responses:
        '200':
          description: The export completed successfully.
        '403':
          description: Incorrect Api-Key.
        '404':
          description: Cluster not found.


  '/api/v2/export/product-selection':
    get:
      tags:
        - Product Selection Exports
      summary: Get filtered list of products
      description: |
        Product lists in eSales can return up to 10 000 products. The product selection exports allows for extracting a filtered product
        list from eSales that includes more than 10 000 products. When exporting data via the Web API, an Api-Key header is required for authentication.
      parameters:
        - name: Api-Key
          in: header
          description: secret api key
          required: true
          schema:
            type: string
        - name: filter
          in: query
          description: An expression defining the product and variant set. Default is UNIVERSE.
          schema:
            type: string
        - name: presentationAttributes
          in: query
          description: A comma-separated list of the attributes from the product data to present. Default presentation attributes are used if omitted.
          schema:
            type: string
        - name: limit
          in: query
          description: The maximum number of products to include in the result.
          schema:
            type: integer
      responses:
        '200':
          description: The export completed successfully.
        '403':
          description: Incorrect Api-Key.
        '404':
          description: Cluster not found.

  '/api/v2/event-data/create-export-customer-job':
    post:
      tags:
        - GDPR
      summary: Create export of customer information
      description: |
        Create job to export information regarding a specific customer.
      parameters:
        - name: Api-Key
          in: header
          description: secret api key
          required: true
          schema:
            type: string
        - name: customerKey
          in: query
          description: Customer key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Return event data job, including job id and status
        '400':
          description: Invalid or missing customer key.
  
  '/api/v2/event-data/create-remove-customer-job':
    post:
      tags:
        - GDPR
      summary: Remove customer information
      description: |
        Create a job to remove customer information.
      parameters:
        - name: Api-Key
          in: header
          description: secret api key
          required: true
          schema:
            type: string
        - name: customerKey
          in: query
          description: Customer key (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Return event data job, including job id and status
        '400':
          description: Invalid or missing customer key.

  '/api/v2/event-data/job-status':
    get:
      tags:
        - GDPR
      summary: Check job status
      description: |
        Checks the status of a create job.
      parameters:
        - name: Api-Key
          in: header
          description: secret api key
          required: true
          schema:
            type: string
        - name: jid
          in: query
          description: Job ID (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Return job status
        '400':
          description: Invalid or missing jid.

  '/api/v2/event-data/export-customer-job-result':
    get:
      tags:
        - GDPR
      summary: Export customer information
      description: |
        Gets the result of a job, if done, based on jid. 
      parameters:
        - name: Api-Key
          in: header
          description: secret api key
          required: true
          schema:
            type: string
        - name: jid
          in: query
          description: Job ID (UUID)
          required: true
          schema:
            type: string
            format: uuid
            default: 00000000-0000-0000-0000-000000000000
      responses:
        '200':
          description: Return job status
        '400':
          description: Invalid or missing jid.
          
  '/api/v2/migrations/customer-keys':
    post:
      tags:
        - Migrations
      summary: Customer key migration
      description: |
        Migrate old customer keys to UUID v4 format, and keep behaviour data 
      parameters:
        - name: Api-Key
          in: header
          description: secret api key
          required: true
          schema:
            type: string
        - name: esales.market
          in: query
          description: Customer market
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Migration successful
        '400':
          description: Invalid body
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/migration'
        description: Actual imports
        required: true

components:
  requestBodies:
    non-esales-notification:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/non-esales-notification'
      description: web api click description
      required: true

    esales-notification:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/esales-notification'
      description: web api click description
      required: true

  schemas:
    payment:
      type: object
      required:
        - productKey
        - quantity
        - sellingPrice
      properties:
        productKey:
          type: string
        quantity:
          type: integer
        sellingPrice:
          type: number
        cost:
          type: number

    esales-notification:
      type: object
      required:
        - ticket
      properties:
        ticket:
          type: string

    non-esales-notification:
      type: object
      required:
        - productKey
        - variantKey
      properties:
        productKey:
          type: string
        variantKey:
          type: string

    migration:
      type: object
      required:
        - oldKey
        - newKey
      properties:
        oldKey:
          type: string
        newKey:
          type: string
          format: uuid

    favorite:
      type: object
      required:
        - productKey
        - variantKey
        - remove
      properties:
        productKey:
          type: string
        variantKey:
          type: string
