Kuehne+Nagel Administration Layer API

openapi: 3.2.0
info:
  title: eSOPPurchaseOrderConfiguration Administration Layer API
  description: 'This API is part of the Kuehne+Nagel API layer. Processing of purchase order data depends

    on the customer''s eSOP order configuration in K+N ESP. This API allows customers to read

    their order configuration. To use this API you must be registered and set up in ESP platform.

    '
  contact:
    name: Kuehne+Nagel ESP Public APIs
    url: https://home.kuehne-nagel.com/en/service-request-api
    email: webdev-esp-public-apis@kuehne-nagel.com
  version: v1
  x-api-id: efd8853e-ab50-402d-95b9-2b1be0e16175
  x-api-guideline-version: 1.9.4
  x-api-version: 1.0.1
servers:
- url: https://internal.api.kuehne-nagel.com/order-management/purchase-order/customer-configuration/v1
security:
- default: []
tags:
- name: administration-layer
paths:
  /order-configurations/{customerCode}:
    get:
      tags:
      - administration-layer
      summary: Read a customer's eSOP order configuration for purchase orders.
      description: 'The order configuration describes the selection of order attributes that are used

        by a customer in their purchase order. It assigns attributes to be either part of

        the order header or to be part of the order lines. The configuration also describes

        which attributes are used to identify order lines and which of the attributes are

        optional or mandatory.

        '
      operationId: readOrderConfiguration
      parameters:
      - $ref: '#/components/parameters/CustomerCodeParam'
      responses:
        '200':
          description: Order configuration found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderConfiguration'
        default:
          $ref: '#/components/responses/default'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: 500_PerMin
components:
  schemas:
    CustomerAttribute:
      type: object
      description: "In addition to the well-known order attributes, the customer can use a set of attributes\nwith freely chosen meaning in purchase orders. The set of these attributes is limited both\nin number and type. This object describes the configuration of these customer-specific\nattributes. \n\nThe ten possible attributes of type string have the names string1 to string10. The ten\npossible Boolean attributes have the names bool1 to bool10. Customer-specific attributes\ncannot be used as key attributes.\n"
      allOf:
      - $ref: '#/components/schemas/CommonAttributeProperties'
      - type: object
        properties:
          referenceLabel:
            minLength: 1
            type: string
            description: 'The reference label makes it possible to name customer-specific attributes in the ESP

              user interface.

              '
    CustomerCode:
      pattern: ^[A-Z]{5}[0-9]{2}$
      type: string
      description: Unique identifier assigned to a customer
    OrderConfiguration:
      type: object
      properties:
        regularAttributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
        customerSpecificAttributes:
          type: array
          items:
            $ref: '#/components/schemas/CustomerAttribute'
      description: 'Purchase orders may contain a variety of information depending on the requirements of the

        business parties involved, especially the customer. ESP supports the customer''s individual

        requirements with an explicit configuration of the order attributes used by the customer.

        Purchase order data must not only comply with the respective OpenAPI specification, but also

        with the restrictions from the customer''s individual order configuration. Therefore, it is

        important for the customer to be able to retrieve his order configuration.

        '
      example:
        regularAttributes:
        - id: itemNumber
          use: true
          reference: IID
          mandatory: true
          partOfHeader: false
          partOfKey: true
          category: itemIdentification
        - id: color
          use: true
          reference: COL
          mandatory: true
          partOfHeader: true
          partOfKey: false
          category: itemAttributes
        - id: size
          use: true
          reference: SZ
          mandatory: false
          partOfHeader: false
          partOfKey: false
          category: itemAttributes
    CommonAttributeProperties:
      required:
      - use
      type: object
      properties:
        id:
          type: string
          description: 'This property represents the identifier of the attribute

            '
        use:
          type: boolean
          description: 'This property indicates whether an attribute is used in a customer''s order

            configuration. If it is not used (false), no further information about the attribute is

            provided. Nevertheless, this gives the customer a comprehensive overview of the set of

            attributes that can be configured for use in purchase orders. If the attribute is used

            (true), the other attributes provide further information.

            '
        reference:
          pattern: ^[A-Z0-9]{2,3}$
          type: string
          description: 'This optional property specifies a unique identifier that can be used to establish

            interoperability with other interfaces offered by Kuehne+Nagel.

            '
        mandatory:
          type: boolean
          description: 'If this property is true, then the attribute must always be specified at the intended

            position in the purchase order, header or lines. Otherwise, the attribute is optional.

            '
        partOfHeader:
          type: boolean
          description: 'This property specifies whether the attribute is to be used either in the header (true)

            or in the lines (false) of a purchase order.

            '
        category:
          type: string
          description: 'In order to clearly organize the large number of possible order attributes, the attributes

            are divided into categories.

            '
    Attribute:
      type: object
      description: 'The Attribute object describes the use of an order attribute in the customer''s

        order configuration.

        '
      allOf:
      - $ref: '#/components/schemas/CommonAttributeProperties'
      - type: object
        properties:
          partOfKey:
            type: boolean
            description: 'Each line of an order can be identified by a specified subset of its attributes, called

              key attributes. Exactly for such attributes partOfKey is true. Key attributes are always

              mandatory and must be part of the order lines.

              '
    Problem:
      required:
      - detail
      - title
      type: object
      properties:
        type:
          type: string
          description: 'A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferencable and point to a human-readable documentation nor globally unique for the problem type.

            '
          format: uri-reference
          example: /problem/connection-error
          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.

            '
          example: Service Unavailable
        status:
          minimum: 100
          type: integer
          description: 'The HTTP status code generated by the origin server for this occurrence of the problem.

            '
          format: int32
          example: 503
          exclusiveMaximum: 600
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.

            '
          example: Connection to database timed out
        instance:
          type: string
          description: 'A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.

            '
          format: uri-reference
          example: /problem/connection-error#token-info-read-timed-out
  responses:
    default:
      description: Default Response for Error Cases
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  parameters:
    CustomerCodeParam:
      name: customerCode
      in: path
      description: The unique key identifying the customer
      required: true
      style: simple
      explode: false
      schema:
        $ref: '#/components/schemas/CustomerCode'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: apikey
      in: header
    default:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://internal.api.kuehne-nagel.com/authorize
          scopes: {}