openapi: 3.0.3
info:
  title: Product Connector Contract - Product Upsert
  description:
    Recommended pattern for building the product upsert flow of a connector between a Product respository and the Fluent platform.
  version: 1.0.0
paths:
  /api/v4.1/event/async:
    post:
      summary: Product Upsert Event
      tags:
        - Fluent Commerce
      security:
        - BearerAuth: [admin]   # Use OAuth with a different scope
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/product-upsert-request'
      responses:
        200:
          description: "Successful Operation"
        401:
          description: "Authorization Error - Invalid Bearer Token / No permission"
        400:
          description: "Client Error - Bad Request"
      servers:
        - description: Fluent Commerce Sandbox
          url: https://{account}.sandbox.api.fluentretail.com
          variables:
            account:
              default: fluent
              description: The name of the Fluent account
        - description: Fluent Commerce Production
          url: https://{account}.api.fluentretail.com
          variables:
            account:
              default: fluent
              description: The name of the Fluent account
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    event-base:
      title: Event
      type: object
      required: [name, retailerId, entityType, entityId, entityRef, rootEntityType, rootEntityId, rootEntityRef]
      properties:
        name:
          type: string
        retailerId:
          type: string
        entityType:
          type: string
          pattern: 'PRODUCT_CATALOGUE'
        entityId:
          type: string
        entityRef:
          type: string
        rootEntityType:
          type: string
          pattern: 'PRODUCT_CATALOGUE'
        rootEntityId:
          type: string
        rootEntityRef:
          type: string
    product-upsert-request:
      type: object
      title: Product Upsert Request
      description: Describes the payload of payment authorise request
      allOf:
        - $ref: '#/components/schemas/event-base'
      properties:
        name:
          type: string
          pattern: fc\.connect\.product\.upsert
        attributes:
          type: object
          properties:
            product:
              $ref: '#/components/schemas/product'
            variant:
              $ref: '#/components/schemas/variant'

    product:
      title: Standard Product
      description: Fluent base product
      type: object
      required: [
        "name", "ref", "type", "gtin"
      ]
      properties:
        ref:
          type: string
          description: The unique reference identifier for the product
          nullable: false
          maxLength: 100
        name:
          type: string
          description: The name of the product
          nullable: false
          maxLength: 255
        type:
          type: string
          description: Type of the standard product
          nullable: false
          maxLength: 50
        status:
          type: string
          description: Status of the standard product
          maxLength: 50
        gtin:
          type: string
          description: The Global Trade Item Number (GTIN) for the product
          nullable: false
          maxLength: 20
        summary:
          type: string
          description: A short description of the product
          maxLength: 255
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/attribute'
        category-refs:
          type: array
          maxLength: 100
          items:
            type: string
        prices:
          type: array
          items:
            $ref: '#/components/schemas/price'
        tax-type:
          $ref: '#/components/schemas/tax-type'

    variant:
      title: Variant Product
      description: Fluent product variant
      allOf:
        - $ref: '#/components/schemas/product'
      required: [
        "name", "ref", "type", "gtin", "standard-product-ref"
      ]
      type: object
      properties:
        standard-product-ref:
          type: string
          nullable: false
          description: Associated base standard product of this variant product
          maxLength: 100

    attribute:
      title: Entity Attribute
      type: object
      required: [
        "value", "name", "type"
      ]
      properties:
        name:
          type: string
          nullable: false
        type:
          type: string
          nullable: false
        value:
          type: string
          nullable: false

    tax-type:
      title: Tax Type
      type: object
      properties:
        country:
          type: string
          maxLength: 100
        group:
          type: string
          maxLength: 100
        tariff:
          type: string
          maxLength: 100

    price:
      title: Price
      type: object
      properties:
        type:
          type: string
          description: Type of product price
          maxLength: 255
        currency:
          type: string
          maxLength: 255
          description: Currency of product price
        value:
          type: number
          format: double
          description: Value of product price
