Order Prototype

openapi: 3.0.0
info:
  title: Order API
  version: '0.9.2'
  description: |-
    The Order API is implemented by the reference components `Bestelomgeving leermiddelen` and `Ordersysteem leermiddelen`.

    The `Bestelomgeving leermiddelen` is able to send an OrderRequest or CreditOrderRequest to the `Ordersysteem leermiddelen`.

    Requests are send and received via asynchronous transactions. Therefore the `Ordersysteem leermiddelen` need to implement endpoints to receive requests. Moreover the `Bestelomgeving leermiddelen` needs to implement confirmation endpoints to receive confirmations from the `Ordersysteem leermiddelen` that requests have been processed.
  contact:
    name: Edu-V
    url: www.edu-v.org/afsprakenstelsel
    email: info@edu-v.org
components:
  schemas:
  
    schemaVersion:
      type: string
      description: |
        Schema version of this API using semantic versioning 2.0.0.
        The API version number is communicated in the header.
        The major version is communicated in the URI.
        For more information see the [Edu-V versioning guidelines](https://edu-v.atlassian.net/wiki/spaces/AFSPRAKENS/pages/9437200/Versiebeheer).
      default: 0.9.2
    
    OrderRequest:
      title: OrderRequest
      type: object
      x-tags:
        - Order
      description: |
        Request send by the `Bestelomgeving leermiddelen` to the `Ordersysteem leermiddelen` to place an order with a quantity for a single Product.
      properties:
        requestReferenceId:
          type: string
          format: uuid
          description: |
            Unique requestReferenceId for this request. This referenceId is used by the Event Mediator of the `Bestelomgeving leermiddelen` to match the OrderConfirmation confirmation message(s) send by the `Ordersysteem leermiddelen`.
            If a party receives another request with the same requestReferenceId value, the receiving party should not process the request again. It should send the confirmation again.
        purchaseOrderId:
          type: string
          description: 'Purchase order number as defined by the `Bestelomgeving leermiddelen`. This number is linked to the financial system of the `Bestelomgeving leermiddelen`.'
        purchaseOrderType:
          type: string
          description: 'Optional orderType field which can be used by suppliers to optimize processing of requests and confirmations.'
          example: 'Tender'
        contractId:
          type: string
          description: 'An optional unique identifier for a contract between `Ordersysteem leermiddelen` and `Bestelomgeving leermiddelen` where this request belongs to.'
        deliveryLocation:
          type: object
          description: 'An optional address at which warehouse location the Product (physical learning materials) should be delivered'
          properties:
            name:
              type: string
              description: 'To the attention of...'
            street:
              type: string
            houseNumber:
              type: integer
              description: 'the house number'
            houseNumberSuffix:
              type: string
              description: 'additions to the house number, e.g. A or -104'
            zipCode:
              type: string
            city:
              type: string
            countryCode:
              type: string
              description: 'According to Alpha-2 code from ISO 3166, e.g. NL'
            country:
              type: string
          required:
            - street
            - houseNumber
            - zipCode
            - city
            - country
        deliveryDate:
          type: string
          format: date
          description: 'Optional desired deliveryDate for delivery of the Product (physical learning materials). Format: YYYY-MM-DD (according to RFC3339).'
          example: '2022-07-31'
        orderLines:
            type: array
            items:
              type: object
              properties:
                purchaseOrderLineId:
                  type: string
                  description: 'Optional line item identifier.'
                productId:
                  type: string
                  description: 'The Product the `Bestelomgeving leermiddelen` orders. The productId can be retrieved from the Catalogue API from the `Ordersysteem leermiddelen`.'
                quantity:
                  type: integer
                  example: 1
                  description: 'The quantity of the Product the `Bestelomgeving leermiddelen` orders.'
              required:
                - productId
                - quantity
      required:
        - requestReferenceId
        - purchaseOrderId
        - orderLines
    
    OrderConfirmation:
      title: OrderConfirmation
      type: object
      x-tags:
        - Order
      description: |
        The confirmation that is send back by the `Ordersysteem leermiddelen` as an asynchronous reply to the request of the `Bestelomgeving leermiddelen`.

        The `Ordersysteem leermiddelen` will send a confirmation message back to the `Bestelomgeving leermiddelen` approving or declining the order request. In case the `Ordersysteem leermiddelen` declines, a functional status code and message is replied. 
        responseReferenceId:
          type: string
          description: 'A reference to this confirmation message send by the `Ordersysteem leermiddelen` to the `Bestelomgeving leermiddelen`.'
        Confirmations are only handled once. If a confirmation with the similar requestReferenceId is received the processing is only done the first time. The confirmation may be send multiple times, but always with the same responseReferenceId. In this way the `Bestelomgeving leermiddelen` can validate that the response is processed only once.
        
        Functional status codes and messages are described in the Documentation.
      properties:
        responseReferenceId:
          type: string
          format: uuid
          description: 'A reference to this confirmation message send by the `Ordersysteem leermiddelen` to the `Bestelomgeving leermiddelen`.'
        requestReferenceId:
          type: string
          format: uuid
          description: 'The requestReferenceId that was send by the `Bestelomgeving leermiddelen` as part of the OrderRequest request'
        purchaseOrderId:
          type: string
          description: 'Purchase order number as defined by the `Bestelomgeving leermiddelen`. This number is linked to the financial system of the `Bestelomgeving leermiddelen`.'
        salesOrderId:
          type: string
          description: 'Sales order number as defined by the `Ordersysteem leermiddelen`. This number is linked to the financial system of the `Ordersysteem leermiddelen`.'
        purchaseOrderLineId:
          type: string
          description: 'Optional line number in case of an order with more than one product.'
        processedTimestamp:
          type: string
          format: date-time
          description: |
            The moment that the order was processed by the `Ordersysteem leermiddelen`. As requests and confirmation messages are send asynchronous, this is not the moment the confirmation message was send by the `Ordersysteem leermiddelen` to the `Bestelomgeving leermiddelen`.

            Format: openapi in ZULU time as specified in RFC 3339, section 5.6
          example: "2017-07-21T17:32:28Z"
        orderStatus:
          type: string
          description: 'The status of pending allows the `Ordersysteem leermiddelen` to communicate to the `Bestelomgeving leermiddelen` that the approval process has started, but has not yet been completed.'
          enum:
            - pending
            - approved
            - declined
        success:
          type: boolean
          description: |
            Boolean indicating the OrderRequest was processed successfully.
            When the `Ordersysteem leermiddelen` declines the request a false will be returned, along with a status code and a status message.
        status:
          type: integer
          description: 'See functional status codes within the Documentation.'
        statusMessage:
          type: string
          description: 'See functional status messages within the Documentation.'
        orderConfirmationLines:
          type: array
          items:
            type: object
            properties:
              salesOrderLineId:
                type: string
                description: 'An identifier from the `Ordersysteem leermiddelen` to reference this order confirmation line.'
              purchaseOrderLineId:
                type: string
                description: 'To echo the `purchaseOrderLineId` of the Order that is being confirmed.'
              productId:
                type: string
                description: 'To echo the `productId` from the Order for confirmation.'
              quantity:
                type: integer
                example: 1
                description: 'To echo the `quantity` from the Order for confirmation.'
              status:
                type: integer
                description: 'See functional status codes within the Documentation.'
              statusMessage:
                type: string
                description: 'See functional status codes within the Documentation.'
            required:
              - productId
              - status
      required:
        - responseReferenceId
        - requestReferenceId
        - processedTimestamp
        - orderStatus
        - success
        - status
    
    CreditOrderRequest:
      title: CreditOrderRequest
      type: object
      x-tags:
        - Order
      description: |
        Request send by the `Bestelomgeving leermiddelen` to the `Ordersysteem leermiddelen` with a request to credit an order. The request has the flexibility to include references known within systems of the `Ordersysteem leermiddelen`.
      properties:
        requestReferenceId:
          type: string
          format: uuid
          description: |
            Unique requestReferenceId for this request. This referenceId is used by the Event Mediator of the `Bestelomgeving leermiddelen` to match the CreditOrderConfirmation confirmation message(s) send by the `Ordersysteem leermiddelen`.
            If a party receives another request with the same requestReferenceId value, the receiving party should not process the request again. It should send the confirmation again.
        purchaseOrderId:
          type: string
          description: 'Purchase order number of the order to be credited as defined by the `Bestelomgeving leermiddelen`. This number is linked to the financial system of the `Bestelomgeving leermiddelen`.'
        salesOrderId:
          type: string
          description: 'Sales order number of the order to be credited as defined by the `Ordersysteem leermiddelen`. This number is linked to the financial system of the `Ordersysteem leermiddelen`.'
        responseReferenceId:
          type: string
          format: uuid
          description: "Optional reference to the responseReferenceID of the confirmation message in which the `Ordersysteem leermiddelen` approved the order to the `Bestelomgeving leermiddelen`."
        orderLines:
          type: array
          description: 'Optional specification of the products in the OrderRequest to be be cancelled.'
          items:
            type: object
            properties:
              purchaseOrderLineId:
                type: string
                description: 'Optional reference to the `purchaseOrderLineId` of the OrderRequest for the product to be cancelled.'
              salesOrderLineId:
                type: string
                description: 'Optional reference to the `salesOrderLineId` of the OrderConfirmation for the product to be cancelled.'
              productId:
                type: string
                description: 'The Product that is to be cancelled.'
              quantity:
                type: integer
                example: 1
                description: 'The quantity of Product that is to be cancelled.'
            required:
              - productId
              - quantity
      required:
        - requestReferenceId
        - purchaseOrderId
    
    CreditOrderConfirmation:
      title: CreditOrderConfirmation
      type: object
      x-tags:
        - Order
      description: |
        The confirmation that is send back by the `Ordersysteem leermiddelen` as an asynchronous reply to the request of the `Bestelomgeving leermiddelen`.

        The `Ordersysteem leermiddelen` will send a confirmation message back to the `Bestelomgeving leermiddelen` including a success parameter indicating if the `Ordersysteem leermiddelen` approves or declines the credit request. In case of a decline, the `Ordersysteem leermiddelen` replies with a functional status code and message. 

        Confirmations are only handled once. If a confirmation with the similar requestReferenceId is received the processing is only done the first time. The confirmation may be send multiple times, but always with the same responseReferenceId. In this way the `Bestelomgeving leermiddelen` can validate that the response is processed only once.
        
        Functional status codes and messages are described in the Documentation.
      properties:
        requestReferenceId:
          type: string
          format: uuid
          description: 'The requestReferenceId that was send by the `Bestelomgeving leermiddelen` as part of the CreditOrderRequest request'
        responseReferenceId:
          type: string
          format: uuid
          description: 'A reference to this confirmation message send by the `Ordersysteem leermiddelen` to the `Bestelomgeving leermiddelen`.'
        purchaseOrderId:
          type: string
          description: 'Purchase order number of the order to be credited as defined by the `Bestelomgeving leermiddelen`. This number is linked to the financial system of the `Bestelomgeving leermiddelen`.'
        salesOrderId:
          type: string
          description: 'Sales order number of the order to be credited as defined by the `Ordersysteem leermiddelen`. This number is linked to the financial system of the `Ordersysteem leermiddelen`.'
        salesOrderLineId:
          type: string
          description: 'Optional line number in case of an order with more than one product.'
        processedTimestamp:
          type: string
          format: date-time
          description: |
            The moment that the credit order was processed by the `Ordersysteem leermiddelen`. As requests and confirmation messages are send asynchronous, this is not the moment the confirmation message was send by the `Ordersysteem leermiddelen` to the `Bestelomgeving leermiddelen`.
            
            Format: openapi in ZULU time as specified in RFC 3339, section 5.6
          example: "2017-07-21T17:32:28Z"
        creditOrderStatus:
          type: string
          description: 'The status of pending allows the `Ordersysteem leermiddelen` to communicate to the `Bestelomgeving leermiddelen` that the approval process has started, but has not yet been completed.'
          enum:
            - pending
            - approved
            - declined
        success:
          type: boolean
          description: |
            Boolean indicating the CreditOrderRequest was processed successfully.
            When the `Ordersysteem leermiddelen` declines the request a false will be returned, along with a status code and a status message.
        status:
          type: integer
          description: 'See functional status codes within the Documentation.'
        statusMessage:
          type: string
          description: 'See functional status messages within the Documentation.'
        creditOrderConfirmationLines:
          type: array
          items:
            type: object
            properties:
              purchaseOrderLineId:
                type: string
                description: 'Reference to the `purchaseOrderLineId` that has been cancelled.'
              salesOrderLineId:
                type: string
                description: 'Reference to the `salesOrderLineId` that has been cancelled.'
              productId:
                type: string
                description: 'Echo of the `productId` from the CreditOrderRequest for confirmation.'
              quantity:
                type: integer
                example: 1
                description: 'Echo of the `quantity` from the CreditOrderRequest for confirmation.'
              status:
                type: integer
                description: 'See functional status codes within the Documentation.'
              statusMessage:
                type: string
                description: 'See functional status codes within the Documentation.'
            required:
              - productId
              - status
      required:
        - requestReferenceId
        - responseReferenceId
        - purchaseOrderId
        - processedTimestamp
        - creditOrderStatus
        - success
        - status
    
    StatusResponse:
        title: StatusResponse
        type: object
        description: 'Functional status code and status message.'
        properties:
          status:
            type: integer
            description: 'See functional status codes within the Documentation.'
          statusMessage:
            type: string
            description: 'See functional status messages within the Documentation.'
        required:
          - status
  
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.example.com/oauth2/token
          refreshUrl: https://api.example.com/oauth2/token
          scopes:
            eduv.order: 'scope needed to send and receive Order and CreditOrder requests and confirmations'
      description: ''

paths:
  
  /orders:
    put:
      summary: Accept order request
      operationId: accept-order-request
      tags:
        - Ordersysteem leermiddelen
      x-tags:
        - Order
      description: |-
        As a `Bestelomgeving leermiddelen` place an OrderRequest at the `Ordersysteem leermiddelen` to purchase learning materials.
        
        The `Ordersysteem leermiddelen` is the provider of this endpoint.
        The `Bestelomgeving leermiddelen` should give a 405 HTTP status as result when called.
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '405':
          description: Method Not Allowed - Ordersysteem leermiddelen is provider of this endpoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      security:
        - OAuth2:
            - eduv.order
  
  /creditorders:
    put:
      summary: Accept credit order request
      operationId: accept-credit-order-request
      tags:
        - Ordersysteem leermiddelen
      x-tags:
        - Order
      description: |-
        As a `Bestelomgeving leermiddelen` place a CreditOrderRequest at the `Ordersysteem leermiddelen` to cancel an earlier OrderRequest to purchase learning materials.
        
        The `Ordersysteem leermiddelen` is the provider of this endpoint.
        The `Bestelomgeving leermiddelen` should give a 405 HTTP status as result when called.
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '405':
          description: Method Not Allowed - Ordersysteem leermiddelen is provider of this endpoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditOrderRequest'
      security:
        - OAuth2:
            - eduv.order
  
  /orders/confirmations:
    put:
      summary: Confirm order request
      operationId: confirm-order-request
      tags:
        - Bestelomgeving leermiddelen
      x-tags:
        - Order
      description: |-
        As a `Ordersysteem leermiddelen` confirm the OrderRequest to the `Bestelomgeving leermiddelen`.
        
        The `Bestelomgeving leermiddelen` is the provider of this endpoint. 
        The `Ordersysteem leermiddelen` should give a 405 HTTP status as result when called.
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '405':
          description: Method Not Allowed - Bestelomgeving leermiddelen is provider of this endpoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderConfirmation'
      security:
        - OAuth2:
            - eduv.order
    
  /creditorders/confirmations:
    put:
      summary: Confirm credit order request
      operationId: confirm-credit-order-request
      tags:
        - Bestelomgeving leermiddelen
      x-tags:
        - Order
      description: |-
        As a `Ordersysteem leermiddelen` confirm the CreditOrderRequest to the `Bestelomgeving leermiddelen`.
        
        The `Bestelomgeving leermiddelen` is the provider of this endpoint. 
        The `Ordersysteem leermiddelen` should give a 405 HTTP status as result when called.
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '405':
          description: Method Not Allowed - Bestelomgeving leermiddelen is provider of this endpoint
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditOrderConfirmation'
      security:
        - OAuth2:
            - eduv.order

x-tags:
  - name: Order