openapi: 3.0.0
info:
  version: "1.1"
  title: "OpenAPI Specification: Products API"
  description: This specification describes the Products API of the Zalando Merchant
    Platform.
  x-audience: external-merchant
  x-api-id: 49e51b92-1b36-447f-adb1-be1305faaea6
paths:
  /merchants/{merchant_id}/products/identifiers/{ean}:
    put:
      summary: |
        Creates a new simple already known by Zalando by registering the Merchant identifiers in the Zalando system.
      tags:
        - Product Association
      security:
        - OAuth2: [lemur.prototype.write]
      parameters:
        - $ref: '#/components/parameters/merchant_id'
        - $ref: '#/components/parameters/ean'
      requestBody:
        $ref: '#/components/requestBodies/ProductAssociationBody'
      responses:
        '204':
          description: |
            Your sku is successfully associated with the existing product
        '400':
          $ref: '#/components/responses/InvalidBodyError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
        default:
          $ref: '#/components/responses/GenericError'

  /products/identifiers/{ean}:
    get:
      summary: |
        Look up the existing product details in Zalando platform
      tags:
        - Discovery API
      security:
        - OAuth2: [lemur.prototype.read]
      parameters:
        - $ref: '#/components/parameters/ean'
      responses:
        '200':
          $ref: '#/components/responses/LookUpResponse'
        '409':
          $ref: '#/components/responses/ConflictError'
        default:
          $ref: '#/components/responses/GenericError'

components:
  schemas:
    ProductAssociationSchema:
      description: Information of the product to associate with
      type: object
      required:
        - merchant_product_simple_id
      properties:
        merchant_product_simple_id:
          $ref: "#/components/schemas/MerchantProductId"
        merchant_product_config_id:
          $ref: "#/components/schemas/MerchantConfigId"
        merchant_product_model_id:
          $ref: "#/components/schemas/MerchantModelId"
    EAN:
      description: The International Article Number or also known as European Article Number.
      type: string
      format: gtin13
      example: "9780679762881"
    MerchantProductId:
      description: |
        Merchant product simple identifier. Simples is a bottom level tier of a product, contains sizes, metrics, etc.
      type: string
      example: "ED-7-09349-5443-L"
    MerchantConfigId:
      description: |
        Merchant product config identifier. Config is a second tier of a product, contains colors, materials, etc.
      type: string
      example: "A213-1232SF-SDG62G-213G"
    MerchantModelId:
      description: |
        Merchant product model identifier. Model is a top level tier of a product, contains target age groups, brand, size charts, etc.
      type: string
      example: "MODEL-ID-ABC"
    LookUp:
      properties:
        items:
          type: array
          items:
            properties:
              ean:
                $ref: '#/components/schemas/EAN'
      example:
        {
          "items": [
            { "ean": "9780679762881" }
          ]
        }
    Problem:
      properties:
        type:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the problem type. When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          default: 'about:blank'
        title:
          type: string
          description: |
            A short, summary of the problem type. Written in English and readable
            for engineers (usually not suited for non technical stakeholders and
            not localized);
        status:
          type: integer
          format: int32
          description: |
            The HTTP status code generated by the origin server for this occurrence
            of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
        detail:
          type: string
          description: |
            A human readable explanation specific to this occurrence of the
            problem.
        instance:
          type: string
          format: uri
          description: |
            An absolute URI that identifies the specific occurrence of the problem.
            It may or may not yield further information if dereferenced.
      example:
        {
          "type": "https://zalando.github.io/problem/constraint-violation",
          "title": "Service Unavailable",
          "status": 503,
          "detail": "Connection to database timed out"
        }
  parameters:
    ean:
      name: ean
      in: path
      description: The International Article Number or also known as European Article Number.
      required: true
      schema:
        $ref: "#/components/schemas/EAN"
    merchant_id:
      name: merchant_id
      in: path
      description: Id of the merchant
      required: true
      schema:
        type: string
        format: string
    merchant-simple-id:
      name: merchant-simple-id
      in: path
      description: Merchant simple identifier
      required: true
      schema:
        type: string
        format: string
  requestBodies:
    ProductAssociationBody:
      description: Information of the product to associate with
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProductAssociationSchema'
  responses:
    ConflictError:
      description: The request is semantically correct, but it cannot be processed due to business reasons. e.g. A product with same id was already submitted. Please refer to the response.
      content:
        "application/problem+json":
          schema:
            $ref: '#/components/schemas/Problem'
    InvalidBodyError:
      description: No product with the given EAN could be found for this merchant
      content:
        "application/problem+json":
          schema:
            $ref: '#/components/schemas/Problem'
    ForbiddenError:
      description: Accessing the data you were trying to reach is forbidden
      content:
        "application/problem+json":
          schema:
            $ref: '#/components/schemas/Problem'
    NotFoundError:
      description: No product with the given EAN could be found for this merchant
      content:
        "application/problem+json":
          schema:
            $ref: '#/components/schemas/Problem'
    TooManyRequestsError:
      description: Too Many Requests. Server busy, please retry later.
      content:
        "application/problem+json":
          schema:
            $ref: '#/components/schemas/Problem'
    GenericError:
      description: Error occurred - see status code and problem object for more information.
      content:
        "application/problem+json":
          schema:
            $ref: '#/components/schemas/Problem'
    LookUpResponse:
      description: |
        Successfully looked up product detail information
      content:
        "application/json;charset=utf-8":
          schema:
            $ref: '#/components/schemas/LookUp'
  securitySchemes:
    merchant_platform:
      type: oauth2
      description: The Products service uses the OpenID Connect (OIDC) authentication layer
        of OAuth 2 to handle the client credentials process flow.
      flows:
        clientCredentials:
          tokenUrl: https://api-sandbox.merchants.zalando.com/auth/token
          scopes:
            products/read: scope to read a product
            products/write: scope to create or update a product
