openapi: "3.0.1"
info:
  version: 1.5.0
  title: Tobacco Track&Trace ID Issuer API
  description: >-
    This API is offered by the ID Issuer to economic operators (EO). By means of this API EOs may submit, review, or revoke orders for organizations (3rd party registration), facilities, machines, unit level UIs, or aggregation level UIs.

    ## Authentication

    The API is protected by mutual authentication based on X.509 TLS certificates as well as by OpenIdConnect. In order to access an endpoint a valid token must be obtained from the OpenIdConnect token endpoint before. The token request takes the following parameters:

    * *username*: obtained via Selfmanagement Portal API credential dialog

    * *password*: obtained via Selfmanagement Portal API credential dialog

    * *client_id*: fixed value 'self-management-gui'

    * *grant_type* : fixed value 'password'

    * *client_secret*: obtained via Selfmanagement Portal API credential dialog

    * *scope*: fixed value 'openid'

    ### Example request

    `POST /auth/realms/idissuer/protocol/openid-connect/token`

    `Content-Type: application/x-www-form-urlencoded`

    `cache-control: no-cache`

    `User-Agent: PostmanRuntime/7.6.1`

    `Accept: */*`

    `Host: keycloak.test.de.id-issuer.eu`

    `accept-encoding: gzip, deflate`

    `content-length: 151`

    `username=********&password=********&client_id=self-management-gui&grant_type=password&client_secret=*****&scope=openid`

    ### Example reply

    `HTTP/1.1 200`

    `status: 200`

    `Server: nginx`

    `Date: Thu, 14 Mar 2019 10:23:59 GMT`

    `Content-Type: application/json`

    `Content-Length: 3614`

    `Connection: keep-alive`

    `Cache-Control: no-store`

    `Set-Cookie: KC_RESTART=; Version=1; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Max-Age=0; Path=/auth/realms/idissuer/; HttpOnly`

    `Pragma: no-cache`


    `{"access_token":"*****", "expires_in":18000, "refresh_expires_in":1800, "refresh_token":"*****", "token_type":"bearer", "id_token":"*****", "not-before-policy":1541410129, "session_state":"*****", "scope":"openid email profile"}`


    The access token shall be than used as a bearer token on subsequent requests to the API.

    ### Example request with token

    `GET /v1/order/482`

    `cache-control: no-cache`

    `Authorization: Bearer *<access_token>* `

    `User-Agent: PostmanRuntime/7.6.1`

    `Accept: */*`

    `Host: idissuer.test.de.id-issuer.eu`


    ## EO identfication

    In most messages TPD foresees the field <i>EO_ID</i> to hold the identifier of the invoking economic operator. Since the invoking operator is identified by the *access_token*, normally mentioning the EO_ID is not needed with this API. In order to cover also the 3rd party operations, the EO-ID must be mentioned only in those operations, where EO-ID properties shall be updated or an EO-ID shall be deactivated.
#
# Version History
# 1.5.0     - Introduce new option eMailNotification property for the operations POST /upui and POST /aui
#           - fix the url-values for PubDemo
# 1.4.3     - Operation GET /order returns the entire list of orders ever placed by an EO. A new
#             optional query parameter restricts the returned list to orders, the
#             corresponding UI files haven't been downloaded by an EO yet.
# 1.4.2     - On optional note property (mNote) was added to the machine resource. mNote
#             can be set by POST and PUT operation.
# 1.4.1     - Operation GET /order/{orderId} supports now a new header field 'location'
# 1.4.0     - Support of German Steuernummer in the operations POST /operator
#             and PUT /operator
#           - Correction and enhancement in type OrderStatus
#             - new enum values: failed, inCancellationPeriod, suspended
#             - correction of typo: ending-at-secondary -> pending-at-secondary
# 1.3.0     - Two new convenience operations GET /operator/{id} and
#             GET/facility/{id} have been introduced to query the registration
#             status of EO or F-IDs issued by the German ID Issuer.
# 1.2.0     - New status code for upUI orders being rejected, because VAT/TIN
#             is not validated yet and EO is therefor not entitled to order upUIs
# 1.1.0     - New type DentsuRecallCode included in types UpUiList and AUiList
# 1.0.10    - endpoint DELETE /machine
#             - fix fault with parameter fId. Instead of type path parameter this
#               parameter is of type query
# 1.0.9     - endpoint POST /upui:
#              - new property customerOrderId in type UpUiOrderParameter
#           - all endpoints' responses:
#             - new header property X-Api-Version denoting the implemented API version
#           - all responses:
#             - remove default response, since not needed and too unspecific
#             - utilization of common response types defined in the
#               components section
# 1.0.8     - fix error in example for type EoIdCorrectionOrderParameter
#             - property vatN : true
#           - fix in type EuCegTobaccoProductNumber
#             - format directive removed, as this property shall accept alphanum content
# 1.0.7     - fix in type EoIdCorrectionOrderParameter:
#             - add missing property invoicingCountry as optional parameter
#           - introduce new types ArbitraryEoId, ArbitraryFid, and ArbitraryMid acc. to
#             Sec. Repo definition to cope with IDs issued by 3rd Member State ID Issuers
#           - fix in type UpUiOrderParameter:
#             - add missing properties buendeOrderId and buendeOrderPosition used for
#               UpUIs order printed on revenue tax stamps
# 1.0.6     - typo in enum value 'canceled' in type OrderStatus: enum value corrected
#             to 'canceled'
#           - fixes in type EoIdCorrectionOrderParameter:
#             - remove redundant property eoId (expressed by endpoint's path parameter)
#             - remove property invoicingMethod
#             - add property invoicingEmail
#             - add property invoicingCompanyName
#             - add property invoicingLanguage
#             - add property invoiceLanguage and type InvoiceLanguageKey
#           - fixes in type UpUiOrderParameter
#             - add property deliveryMethod of type DeliveryMethod
#           - add new values 'pending-at-secondary' and 'rejected-by-secondary'
#             to type OrderStatus
#           - split type MultiItemError in two types MultiItemErrorEo and
#             MultiItemErrorFM
#           - corrections on type AuiOrderParameter
#             - add properties orderProcessing and webHookBase
#           - Changed format description for type ConfirmationCode
#           - fixes in type fIdOrderResultType: property fId renamed to fid
#           - fixes in type mIdOrderResultType: property mId renamed to mid
#           - fix in type Address: zipCode became optional
#           - change in type CombinedNomenclatureCode
#             - min length: 4
#             - format: ^[\d]{4}(\s[\d]{2}(\s[\d]{2})?)?$
#           - change in type EoName: maxLength: 100
#           - change in type Email: maxLength: 80
#           - change in type EuCegTobaccoProductNumber: maxLength: 30
#           - change in types MachineProducer, MachineModel,MachineNumber: maxLength: 20
#           - endpoint DELETE /operator{id}: remove query parameter eoId
#           - endpoint DELETE /facility{id}: remove query parameter eoId
# 1.0.5     - added missing type deliveryMethod for upUI order
# 1.0.4     - add return code 207 for post operations on EO, F, and M
#           - add return code 204 for download request on UIs for physical delivery
# 1.0.3     - new url value
#           - type GTIN: length changed from 13 to 14
#           - type GLN completely removed
#           - real ID Issuer prefix included in examples
#           - corrected example value of field vatR from true to false for types
#               3rdPartyEoIdOrderDetails EoIdCorrectionOrderParameter
#           - added types and endpoint for UI download
#           - changed definition of types EoId, Fid, Mid
#
# 1.0.2     - extension of type Error by details-array
#
servers:
  - url: https://{environment}.de.id-issuer.eu/v1
    variables:
      environment:
        default: api    # Production server
        enum:
          - api             # Production server
          - api.test        # Public test server

paths:
  /api:
    get:
      summary: Provides OpenAPI Specification on this API in YAML format
      operationId: apiProperties
      tags:
        - api-information
      responses:
        200:
          description: API definition specified in OpenAPI Specification
            notation (this file)
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            text/plain:
              schema:
                type: string
                example: "openapi: 3.0.1\n\tinfo:\n\t\tversion: 1.0.1
                \n\t\ttitle: Tobacco Track&Trace ID Issuer API\n..."
  /order:
    get:
      summary: List all orders created by the invoking EO
      operationId: getAllOpenOrders
      tags:
        - orders
      parameters:
        - name: onlyOpen
          description: When setting this parameter to true, only those orders are returned,  
            the corresponding UI files haven't been downloaded by the EOs yet
          in: query
          required: false
          schema:
            type: boolean
      responses:
        200:
          description: List of orders. May be null.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenOrderList'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
  /order/{orderId}:
    get:
      summary: Provides information on an ID order in an arbitrary
        processing state
      operationId: GetOrderById
      tags:
        - orders
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/OrderId"
      responses:
        200:
          description: Information on the order
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
            location:
              description: The URL to download the UI list, if available
              schema:
                type: string
                example: 'https://api.de.id-issuer.eu/v1/downloads/18000093616/download'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderInfoObject'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        404:
          $ref: '#/components/responses/OrderNotFound'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
    delete:
      summary: Delete an order
      tags:
        - orders
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/OrderId"
        - name: recallCode
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/RecallCode'
        - name: recallReason1
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/RecallReasons'
        - name: recallReason2
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/RecallReasonOther'
          description: Mandatory, if recallReason1=Other
        - name: recallReason3
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/RecallReasonOther'
      responses:
        200:
          description: Order deleted. Id of the deleted order is returned
            in the message body
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderId'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        404:
          $ref: '#/components/responses/OrderNotFound'
        410:
          description: The recall period for this order has been elapsed. The
            order can't be recalled any more.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
  /upui:
    post:
      summary: Submit a new order for unit packet level unique identifiers.
        Only one order per operation is allowed.
      tags:
        - unique identifiers
      requestBody:
        description: The information specified in TPD Implementation act, Annex II for
          UI orders have to be submitted in the request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpUiOrderParameter'
      responses:
        202:
          description: Order accepted, the order ID for this order is enclosed
            in the response body. The UIs will be created at a later point in time.
            Once the creation is done the requestor is notified, either by webhook,
            if supplied in the order, or by email (default)
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UiOrderResponse'
          links:
            GetOrderById:
              description: >
                The returned OrderId can be used as parameter ´orderId´ in
                ´GET /order/{orderId}´ operation
              operationId: GetOrderById
              parameters:
                orderId: $response.body#/orderId
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        451:
          $ref: '#/components/responses/UnavailableForLegalReasons'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
  /aui:
    post:
      summary: Submit a new order for aggregated level unique identifiers.
        Only one order per operation is allowed.
      tags:
        - unique identifiers
      requestBody:
        description: The information specified in TPD Implementation act, Annex II for
          UI orders have to be submitted in the request body.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuiOrderParameter'
      responses:
        202:
          description: Order accepted, the order ID for this order is enclosed
            in the response body. The UIs will be created at a later point in time.
            Once the creation is done the requestor is notified, either by webhook,
            if supplied in the order, or by email (default)
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UiOrderResponse'
          links:
            GetOrderById:
              description: >
                The returned OrderId can be used as parameter ´orderId´ in
                ´GET /order/{orderId}´ operation
              operationId: GetOrderById
              parameters:
                orderId: $response.body#/orderId
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
  /downloads/{orderId}/download:
    get:
      summary: This endpoint is used to download upUIs/aUIs order before.
      tags:
        - unique identifiers
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/OrderId"
      responses:
        200:
          description: The response body contains information on the orderID, the UI type and the amount of UIs delivered followed by an array of UIs
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UiList"
        204:
          description: A request was made to download upUIs that have been ordered for physical delivery, i.e. printed on revenue stamps. upUIs ment for physical delivery can't be downloaded electronically.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        404:
          $ref: '#/components/responses/OrderNotFound'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
  /operator:
    post:
      summary: Submit an order for a 3rd party economic operator registration.
        Multiple EOs may be registered within one order.
      tags:
        - economic operator IDs
      requestBody:
        description: A not empty array of ID orders. Each id order item must
          hold the information specified in TPD Implementation act, Annex II
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/3rdPartyEoIdOrderParameter'
      responses:
        200:
          description: Order accepted. The created identifiers are enclosed
            in the body of the response.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EoIdOrderResult'
        207:
          description: The operation succeeded partially. The error result provides details.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiItemErrorEo'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
  /operator/{identifier}:
    get:
      summary: Query the status of one EO-ID. A boolean value is returned,
        where 'true' means EO-ID is confirmed to be registered with status
        active. 'false' is returned in ANY other case, e.g. EO-ID is unknown
        or EO-ID is deactivated.
        This query can be applied to IDs issued by German ID Issuer only.
      tags:
        - economic operator IDs
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/EoId'
      responses:
        200:
          description: Query accepted. The response holds the ID status indicator.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdStatusQueryResponse'
        400: # returned in case the ID parameter is missing, malformed or
             # the ID was not issued by the German ID Issuer
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
    put:
      summary: Submit an order to correct information regarding the EO's identifier.
        This correction can concern information about the company itself or about
        a retailer on whose behalf the EO acts.
      tags:
        - economic operator IDs
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/EoId'
      requestBody:
        description: The complete master record data acc. to TPD Implementation
          act, Annex II including the modifications
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EoIdCorrectionOrderParameter'
      responses:
        200:
          description: Order accepted, entity modified. The ID of the modified entity
            is enclosed in the body of the response.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EoId'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
    delete:
      summary: Submit an order to deactivate an EO-ID. The deactivation can
        concern the company itself or a retailer on whose behalf the EO acts.
        All assets will be deactivated, too, linked with the affected EO.
      tags:
        - economic operator IDs
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/EoId'
          description: The ID of the EO to be deactivated
        - name: eoCode
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/ConfirmationCode'
          description: The EO's confirmation code to be deactivated
        - name: reg3rd
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/ChoiceSelector'
          description: This paramter is set to true, if this order is made on behalf
            of a retail operator
      responses:
        200:
          description: Order accepted, entity deactivated. Also depending entities
            have been deactivated, e.g. all machines will be deactivated along with an
            deactivation order on the facility the machines are deployed in.
            The identifiers of the deactivated entities are returned in the response body.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - $ref: '#/components/schemas/EoId'
                    - $ref: '#/components/schemas/Fid'
                    - $ref: '#/components/schemas/Mid'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
  /facility:
    post:
      summary: Submit an order for a facility id. This operation serves both
        cases, registration of own assets and 3rd party registration.
        Multiple facilities can be processed by one order.
      tags:
        - facility IDs
      requestBody:
          description: A not empty array of ID orders. Each id order item must
            hold the information specified in TPD Implementation act, Annex II
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FacilityIdOrderParameter'
      responses:
        200:
          description: Order accepted. The created identifiers are enclosed
            in the body of the response.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FidOrderResult'
        207:
          description: The operation succeeded partially. The error result provides details.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiItemErrorFM'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
  /facility/{identifier}:
    get:
      summary: Query the status of one F-ID. A boolean value is returned,
        where 'true' means F-ID is confirmed to be registered with status
        active. 'false' is returned in ANY other case, e.g. F-ID is unknown
        or F-ID is deactivated.
        This query can be applied to IDs issued by German ID Issuer only.
      tags:
        - facility IDs
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Fid'
      responses:
        200:
          description: Query accepted. The response holds the ID status indicator.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IdStatusQueryResponse'
        400: # returned in case the ID parameter is missing, malformed or
             # the ID was not issued by the German ID Issuer
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
    put:
      summary: Submit an order to correct information regarding a facility identifier.
        This correction can concern a facility of the company itself or about
        a retailer's facility on whose behalf the EO acts.
      tags:
        - facility IDs
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Fid'
          description: The ID of the facility its information shall be corrected
      requestBody:
        description: The complete master record data acc. to TPD Implementation
          act, Annex II including the modifications
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FacilityIdCorrectionOrderParameter'
      responses:
        200:
          description: Order accepted, entity modified. The ID of the modified entity
            is enclosed in the body of the response.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fid'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
    delete:
      summary: Submit an order to deactivate a facility-ID. The deactivation can
        concern a facility of the company itself or a retailer's facility on
        whose behalf the EO acts. If applicable, all machines will be deactivated,
        too, linked with the affected facility.
      tags:
        - facility IDs
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Fid'
          description: The ID of the facility to be deactivated
        - name: eoCode
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/ConfirmationCode'
          description: The EO's confirmation code the facility belongs to
        - name: reg3rd
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/ChoiceSelector'
          description: This paramter is set to true, if this order is made on behalf
            of a retail operator
      responses:
        200:
          description: Order accepted, entity deactivated. Also depending entities
            have been deactivated, e.g. all machines will be deactivated along with an
            deactivation order on the facility the machines are deployed in.
            The identifiers of the deactivated entities are returned in the response body.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - $ref: '#/components/schemas/Fid'
                    - $ref: '#/components/schemas/Mid'
                example: ['QCBDR<1!000000000025000021', 'QCBDR>1!000000000025000003' ]
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
  /machine:
    post:
      summary: Submit an order for a machine id. Multiple machines can be
        processed by one order.
      tags:
        - machine IDs
      requestBody:
          description: A not empty array of ID orders. Each id order item must
            hold the information specified in TPD Implementation act, Annex II
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MachineIdOrderParameter'
      responses:
        200:
          description: Order accepted. The created identifiers are enclosed
            in the body of the response.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MidOrderResult'
        207:
          description: The operation succeeded partially. The error result provides details.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultiItemErrorFM'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
  /machine/{identifier}:
    put:
      summary: Submit an order to correct properties of a machine.
      tags:
        - machine IDs
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Mid'
          description: The machine's ID to correct its information
      requestBody:
        description: The complete master record data acc. to TPD Implementation
          act, Annex II including the modifications
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MachineIdCorrectionOrderParameter'
      responses:
        200:
          description: Order accepted, entity modified. The ID of the modified entity
            is enclosed in the body of the response.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mid'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
    delete:
      summary: Submit an order to deactivate a machine-ID.
      tags:
        - machine IDs
      parameters:
        - name: identifier
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/Mid'
          description: The ID of the machine to be deactivated
        - name: eoCode
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/ConfirmationCode'
          description: The EO's confirmation code
        - name: fid
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/Fid'
          description: The ID of the facility the machine to be deactivated is
            assigned to
      responses:
        200:
          description: Order accepted, entity/entites deactivated.
            The identifier of the deactivated entity/entities is/are returned in the response body.
          headers:
            X-Api-Version:
              description: The implemented API version
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Mid'
                example: ['QCBDR>1!000000000025000002', 'QCBDR>1!000000000025000003' ]
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/MissingAuthorization'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        503:
          $ref: '#/components/responses/ServiceTempNotAvailable'
components:
  schemas:
#
# general types used in operations on code orders
#
    OrderPosition:
      type: integer
      example: 1
    OrderId:
      type: string
      minLength: 11
      maxLength: 11
      description: An order ID in the format YYNNNNNNNNN
      format: '^\d{11}$'
      example: "18000093616"
    OrderStatus:
      type: string
      enum:
        - stored
        - in-processing
        - ready-for-delivery
        - delivered
        - closed
        - canceled
        - pending-at-secondary
        - rejected-by-secondary
        - failed
        - inCancellationPeriod
        - suspended
      example:
        in-processing
    OrderSummary:
      type: string
      description: >-
        A summary on the order. Summary content and item order are
        unspecified and my be subject to changes in future releases.
      example: "2018/09/13, 20.000 upUIs, product x"
    OrderInfoObject:
      type: object
      properties:
        orderId:
          $ref: '#/components/schemas/OrderId'
        orderStatus:
          $ref: '#/components/schemas/OrderStatus'
        orderSummary:
          $ref: '#/components/schemas/OrderSummary'
      required:
      - orderId
      - orderStatus
      - orderSummary
    OpenOrderList:
      type: array
      items:
        $ref: '#/components/schemas/OrderInfoObject'
      nullable: true
    UiType:
      type: string
      enum:
        - upUI
        - aUI
    UpUi:
      type: string
      minLength: 35
      maxLength: 35
      example: 'QCBDRa20wBnq5V300003172440841dTQM90'
    AUi:
      type: string
      minLength: 39
      maxLength: 39
      example: 'CQBDRG1jEwk74JR0wBnq5xqK7w303kPV38aH0S+'
    DentsuRecallCode:
      type: string
      minLength: 36
      maxLength: 36
      format: UUID version 5
      example: '873345b2-882f-4064-91f0-90669b46c30a'
    UpUiList:
      type: object
      properties:
        orderId:
          $ref: '#/components/schemas/OrderId'
        idType:
          $ref: '#/components/schemas/UiType'
        amount:
          $ref: '#/components/schemas/Quantity'
        recallCodeList:
          type: array
          items:
            $ref: '#/components/schemas/DentsuRecallCode'
          minItems: 1
        uiList:
          type: array
          items:
            $ref: '#/components/schemas/UpUi'
          minItems: 1
          maxItems: 1000000
      required:
        - orderId
        - idType
        - amount
        - recallCodeList
        - uiList
      example:
        orderId: 32789
        idType: 'upUI'
        amount: 2
        recallCodeList: [873345b2-882f-4064-91f0-90669b46c30a]
        uiList: [QCBDRa20wBnq5V300003172440841dTQM90, QCBDRa2fT3wp08200003172440841dTQM90]
    AUiList:
      type: object
      properties:
        orderId:
          $ref: '#/components/schemas/OrderId'
        idType:
          $ref: '#/components/schemas/UiType'
        amount:
          $ref: '#/components/schemas/Quantity'
        recallCodeList:
          type: array
          items:
            $ref: '#/components/schemas/DentsuRecallCode'
          minItems: 1
        uiList:
          type: array
          items:
            $ref: '#/components/schemas/AUi'
          minItems: 1
          maxItems: 1000000
      required:
        - orderId
        - idType
        - amount
        - recallCodeList
        - uiList
    UiList:
      oneOf:
        - $ref: '#/components/schemas/UpUiList'
        - $ref: '#/components/schemas/AUiList'
      example:
        orderId: 32789
        idType: 'upUI'
        amount: 2
        recallCodeList: [873345b2-882f-4064-91f0-90669b46c30a]
        uiList: [QCBDRa20wBnq5V300003172440841dTQM90, QCBDRa2fT3wp08200003172440841dTQM90]
    CustomerOrderId:
      description: An optional order ID defined by an EO when creating an
        upUI order. This property is not evaluated by the ID Issuer but only
        stored with the invoicing record. When conveyed to SAP, the
        CustomerOrderId is printed along with the invoicing information.
      type: string
      minLength: 0
      maxLength: 23
      nullable: false
      example: '19abc#1'
#
# basic types used in operations on identifiers stored in the registry
#
    DescriptionType:
      type: string
      minLength: 1
      maxLength: 50
    MachineDescriptionType:
      type: string
      minLength: 1
      maxLength: 20
    EoId:
      description: EO-ID issued by German ID Issuer
      type: string
      example: 'QCBDR+1DE020054'
      minLength: 15
      maxLength: 15
    Fid:
      description: F-ID issued by German ID Issuer
      type: string
      minLength: 21
      maxLength: 21
      example: 'QCBDR<1DE020054000048'
    Mid:
      description: M-ID issued by German ID Issuer
      type: string
      minLength: 21
      maxLength: 21
      example: 'QCBDR>1DE020054000012'
    ArbitraryEoId:
      description: EO-ID issued by an arbitrary ID Issuer
      type: string
      example: '666fL4q332069t3'
      minLength: 1
      maxLength: 50
    ArbitraryFid:
      description: F-ID issued by an arbitraryID Issuer
      type: string
      minLength: 1
      maxLength: 50
      example: '666dhd40rh00048'
    ArbitraryMid:
      description: M-ID issued by an arbitrary ID Issuer
      type: string
      minLength: 1
      maxLength: 50
      example: '666g2h00540rI00012'
    ConfirmationCode:
      description: Confirmation code acc. to TPD - Annex II
      type: string
      minLength: 6
      maxLength: 6
      format: '^[0-9A-KMNP-Z]{6}$'
      example: 'DZU51X'
    ChoiceSelector:
      type: boolean
      description: false means "0-No", true means "1-Yes" acc. to TPD-Annex II
    EoName:
      type: string
      minLength: 1
      maxLength: 100
      example: 'A company manufacturing everyting (ACME)'
    Street:
      type: string
      minLength: 1
      maxLength: 40
      example: 'Mainstreet'
    HouseNumber:
      type: string
      minLength: 1
      maxLength: 20
      example: '1a'
    ZipCode:
      type: string
      minLength: 1
      maxLength: 10
      example: '14195'
    City:
      type: string
      minLength: 1
      maxLength: 40
      example: 'The greatest city on earth'
    Address:
      properties:
        street:
          $ref: '#/components/schemas/Street'
        houseNumber:
          $ref: '#/components/schemas/HouseNumber'
        zipCode:
          $ref: '#/components/schemas/ZipCode'
        city:
          $ref: '#/components/schemas/City'
      required:
        - street
        - houseNumber
        - city
    IsoCountry:
      description: Country name coded with ISO-3166-1:2013
      type: string
      minLength: 2
      maxLength: 2
      example: 'DE'
    Email:
      description: acc. to RFC5322
      type: string
      minLength: 5
      maxLength: 80
      format: email
      example: 'here@acme.eu'
    EmailOption:
      description: This type is used in UI orders to control the use of notification emails
      properties:
        notification:
          description: if true, an email notification is sent
          type: boolean
        eMailAddress:
          $ref: '#/components/schemas/Email'
      required:
        - notification
      example:
        notification: true
        eMailAddress: 'some.other@email.de'
    VatId:
      description: see https://en.wikipedia.org/wiki/VAT_identification_number
      type: string
      minLength: 8
      maxLength: 14
      example: 'DE999999999'
    Tin:
      description: acc. To https://ec.europa.eu/taxation_customs/tin/
      type: string
      minLength: 8
      maxLength: 16
      example: '99999999999'
    Steuernummer:
      description: The German Steuernummer acc. to 'Standardschema der Länder'
      type: string
      minLength: 12
      maxLength: 13
      pattern: '^(\d{2,3}\/\d{3}\/\d{5})|(\d{3}\/\d{4}\/\d{4})$'
      example: '123/123/12345'
    Seed:
      description: acc. To http://ec.europa.eu/taxation_customs/dds2/seed/help/seedhedn.jsp?Lang=en
      type: string
      minLength: 13
      maxLength: 13
      format: '^[A-Za-z]{2}[A-Za-z0-9]{11}$'
      example: 'DEabcdef12345'
    FacilityType:
      type: string
      enum:
        - ManufacturingSiteWithWarehouse
        - StandaloneWarehouse
        - RetailOutlet
        - Other
    FacilityTypeOther:
      $ref: '#/components/schemas/DescriptionType'
    MachineProducer:
      $ref: '#/components/schemas/MachineDescriptionType'
    MachineModel:
      $ref: '#/components/schemas/MachineDescriptionType'
    MachineSerialNumber:
      $ref: '#/components/schemas/MachineDescriptionType'
    MachineCapacity:
      type: integer
      format: int32
      example: 1130
    MachineNote:
      $ref: '#/components/schemas/MachineDescriptionType'
    TobaccoProductType:
      type: string
      enum:
        - Cigarette
        - Cigar
        - Cigarillo
        - RollYourOwnTobacco
        - PipeTobacco
        - WaterpipeTobacco
        - OralTobacco
        - NasalTobacco
        - ChewingTobacco
        - NovelTobaccoProduct
        - Other
    TobaccoProductTypeOther:
      $ref: '#/components/schemas/DescriptionType'
    CombinedNomenclatureCode:
      type: string
      minLength: 4
      maxLength: 10
      format: '^[\d]{4}(\s[\d]{2}(\s[\d]{2})?)?$'
    ProductBrand:
      $ref: '#/components/schemas/DescriptionType'
    Gtin:
      description: If the gtin property is populated in an upUI order
        the value is used as product description within the upUI
      type: string
      minLength: 14
      maxLength: 14
      example: "00221400023554"
    ProductAvgGrossWeight:
      type: number
      format: float
    EuCegTobaccoProductId:
      type: string
      minLength: 14
      maxLength: 14
      format: '^\d{5}-\d{2}-\d{5}$'
      description: EU-CEG TP-ID „Übermittler-ID–Jahr–Produktnummer“ (NNNNN–NN–NNNNN)
    EuCegTobaccoProductNumber:
      type: string
      minLength: 1
      maxLength: 30
    Quantity:
      type: integer
      minimum: 1
      maximum: 1000000
      example: 50000
    WebHook:
      type: string
      minLength: 1
      maxLength: 250
      format: uri
      example: 'https://notifications.acme.eu/upui/'
    OrderProcessingPriority:
      type: string
      enum:
        - TpdStandardProcessing
        - ImmediateProcessingNoRecallPossible
      default:
        TpdStandardProcessing
      description: Controls how the order shall be processed by the ID Issuer.
        If omitted, TpdStandardProcessing is assumed.
    RecallCode:
      type: string
      minLength: 6
      maxLength: 6
      example: "fR5K49"
      description: This code is used to recall upUI or aUI orders.
    RecallReasons:
      type: string
      enum:
        - ErroneousInformation
        - Other
    RecallReasonOther:
      $ref: '#/components/schemas/DescriptionType'
    DeliveryMethod:
      type: string
      enum:
        - Electronically
        - Physically
    InvoicingLanguageKey:
      description: Denotes the desired language used in the invoice
      type: string
      enum:
        - d # German
        - e # English
    BuendeOrderId:
      description: In case of an upUI order with deliveryMethod physically,
        this property holds the order ID of the Buende order, upUIs shall be
        ordered for
      type: string
      minLength: 1
      maxLength: 35
      example: '2019-12345'
    BuendeOrderPosition:
      description: In case of an upUI order with deliveryMethod physically,
        this property holds the order position of the Buende order, upUIs
        shall be ordered for
      type: integer
      example: 1
#
# Types used in identifier orders
#
#
# 3rd party EO-ID order
    3rdPartyEoIdOrderParameter:
      type: array
      items:
        type: object
        properties:
          position:
            $ref: '#/components/schemas/OrderPosition'
          details:
            $ref: '#/components/schemas/3rdPartyEoIdOrderDetails'
        required:
          - position
          - details
      minItems: 1
#
    3rdPartyEoIdOrderDetails:
      type: object
      properties:
        eoName1:
          $ref: '#/components/schemas/EoName'
        eoName2:
          $ref: '#/components/schemas/EoName'
        eoAddress:
          $ref: '#/components/schemas/Address'
        eoCountryReg:
          $ref: '#/components/schemas/IsoCountry'
        eoEmail: # retail operator's email address
          $ref: '#/components/schemas/Email'
        vatR:
          $ref: '#/components/schemas/ChoiceSelector'
        vatN:
          $ref: '#/components/schemas/VatId'
        taxN:
          $ref: '#/components/schemas/Tin'
        steuernummer:
          $ref: '#/components/schemas/Steuernummer'
        eoExciseNumber1:
          $ref: '#/components/schemas/ChoiceSelector'
        eoExciseNumber2:
          $ref: '#/components/schemas/Seed'
        otherEoIdR:
          $ref: '#/components/schemas/ChoiceSelector'
        otherEoIdN:
          type: array
          items:
            $ref: '#/components/schemas/ArbitraryEoId'
      required:
        - eoName1
        - eoAddress
        - eoCountryReg
        - vatR
        - eoExciseNumber1
        - otherEoIdR
      example:
        eoName1: "The friendly corner shop"
        eoAddress: {
          street: "Mainstreet",
          houseNumber: "1a",
          zipCode: "1000",
          city: "The greatest city on earth"
        }
        eoCountryReg: "DE"
        eoEmail: "here@cornershop.eu"
        vatR: true
        vatN: "DE999999999"
        eoExciseNumber1: false
        otherEoIdR: false
#
    EoIdCorrectionOrderParameter:
      type: object
      properties:
        eoCode:
          $ref: '#/components/schemas/ConfirmationCode'
        eoName1:
          $ref: '#/components/schemas/EoName'
        eoName2:
          $ref: '#/components/schemas/EoName'
        eoAddress:
          $ref: '#/components/schemas/Address'
        eoCountryReg:
          $ref: '#/components/schemas/IsoCountry'
        eoEmail:
          $ref: '#/components/schemas/Email'
        vatR:
          $ref: '#/components/schemas/ChoiceSelector'
        vatN:
          $ref: '#/components/schemas/VatId'
        taxN:
          $ref: '#/components/schemas/Tin'
        steuernummer:
          $ref: '#/components/schemas/Steuernummer'
        eoExciseNumber1:
          $ref: '#/components/schemas/ChoiceSelector'
        eoExciseNumber2:
          $ref: '#/components/schemas/Seed'
        otherEoIdR:
          $ref: '#/components/schemas/ChoiceSelector'
        otherEoIdN:
          type: array
          items:
            $ref: '#/components/schemas/ArbitraryEoId'
        reg3rd:
          $ref: '#/components/schemas/ChoiceSelector'
        invoicingCompanyName:
          $ref: '#/components/schemas/EoName'
        invoicingAddress:
          $ref: '#/components/schemas/Address'
        invoicingCountry:
          $ref: '#/components/schemas/IsoCountry'
        invoicingEmail:
          $ref: '#/components/schemas/Email'
        invoicingLanguage:
          $ref: '#/components/schemas/InvoicingLanguageKey'
      required:
        - eoCode
        - eoName1
        - eoAddress
        - eoCountryReg
        - vatR
        - eoExciseNumber1
        - otherEoIdR
        - reg3rd
      example:
        eoCode: "DZU51X"
        eoName1: "A company manufacturing everything"
        eoName2: "ACME"
        eoAddress: {
          street: "Mainstreet",
          houseNumber: "1a",
          zipCode: "1000",
          city: "The greatest city on earth"
        }
        eoCountryReg: "DE"
        eoEmail: "here@acme.eu"
        vatR: true
        vatN: "DE999999999"
        eoExciseNumber1: true
        eoExciseNumber2: "DEabcdef12345"
        otherEoIdR: true
        otherEoIdN: ["anAdditionalId"]
        reg3rd: false
        invoicingAddress: "invoicing@acme.eu"
#
# Facility-ID order
    FacilityIdOrderParameter:
      type: array
      items:
        type: object
        properties:
          position:
            $ref: '#/components/schemas/OrderPosition'
          details:
            $ref: '#/components/schemas/FacilityIdOrderDetails'
        required:
          - position
          - details
      minItems: 1
#
    FacilityIdOrderDetails:
      type: object
      properties:
        # eoId: in case of 3rd party registration the eoId of the retail operator,
        # omitted else as invoking eoId is taken from token
        eoId:
          $ref: '#/components/schemas/EoId'
        eoCode:
          $ref: '#/components/schemas/ConfirmationCode'
        fAddress:
          $ref: '#/components/schemas/Address'
        fCountry:
          $ref: '#/components/schemas/IsoCountry'
        fType:
          $ref: '#/components/schemas/FacilityType'
        fTypeOther:
          $ref: '#/components/schemas/FacilityTypeOther'
        fStatus:
          $ref: '#/components/schemas/ChoiceSelector'
        fExciseNumber1:
          $ref: '#/components/schemas/ChoiceSelector'
        fExciseNumber2:
          $ref: '#/components/schemas/Seed'
        otherFidR:
          $ref: '#/components/schemas/ChoiceSelector'
        otherFidN:
          type: array
          items:
            $ref: '#/components/schemas/ArbitraryFid'
        reg3rd:
          $ref: '#/components/schemas/ChoiceSelector'
      required:
        - eoCode
        - fAddress
        - fCountry
        - fType
        - fStatus
        - fExciseNumber1
        - otherFidR
        - reg3rd
      example:
        eoId: 'QCBDR+1DE020054'
        eoCode: "DZU51X"
        fAddress: {
          street: "Mainstreet",
          houseNumber: "1a",
          zipCode: "1000",
          city: "The greatest city on earth"
        }
        fCountry: "DE"
        fType: "RetailOutlet"
        fStatus: true
        fExciseNumber1: true
        fExciseNumber2: "DEabcdef12345"
        otherFidR: true
        otherFidN: ["someOtherId"]
        reg3rd: true
#
    FacilityIdCorrectionOrderParameter:
      type: object
      properties:
        eoId:
          $ref: '#/components/schemas/EoId'
        eoCode:
          $ref: '#/components/schemas/ConfirmationCode'
        fAddress:
          $ref: '#/components/schemas/Address'
        fCountry:
          $ref: '#/components/schemas/IsoCountry'
        fType:
          $ref: '#/components/schemas/FacilityType'
        fTypeOther:
          $ref: '#/components/schemas/FacilityTypeOther'
        fStatus:
          $ref: '#/components/schemas/ChoiceSelector'
        fExciseNumber1:
          $ref: '#/components/schemas/ChoiceSelector'
        fExciseNumber2:
          $ref: '#/components/schemas/Seed'
        otherFidR:
          $ref: '#/components/schemas/ChoiceSelector'
        otherFidN:
          type: array
          items:
            $ref: '#/components/schemas/ArbitraryFid'
        reg3rd:
          $ref: '#/components/schemas/ChoiceSelector'
      required:
        - eoCode
        - fAddress
        - fCountry
        - fType
        - fStatus
        - fExciseNumber1
        - otherFidR
        - reg3rd
      example:
        eoId: 'QCBDR+1DE020054'
        eoCode: "DZU51X"
        fAddress: {
          street: "Mainstreet",
          houseNumber: "1a",
          zipCode: "1000",
          city: "The greatest city on earth"
        }
        fCountry: "DE"
        fType: "ManufacturingSiteWithWarehouse"
        fStatus: true
        fExciseNumber1: true
        fExciseNumber2: "DEabcdef12345"
        otherFidR: true
        otherFidN: ["someOtherId", "yetAnotherId"]
        reg3rd: false
#
# Machine-ID Order
    MachineIdOrderParameter:
      type: array
      items:
        type: object
        properties:
          position:
            $ref: '#/components/schemas/OrderPosition'
          details:
            $ref: '#/components/schemas/MachineIdOrderDetails'
        required:
          - position
          - details
      minItems: 1
#
    MachineIdOrderDetails:
      type: object
      properties:
        eoCode:
          $ref: '#/components/schemas/ConfirmationCode'
        fId:
          $ref: '#/components/schemas/Fid'
        mProducer:
          $ref: '#/components/schemas/MachineProducer'
        mModel:
          $ref: '#/components/schemas/MachineModel'
        mNumber:
          $ref: '#/components/schemas/MachineSerialNumber'
        mCapacity:
          $ref: '#/components/schemas/MachineCapacity'
        mNote:
            $ref: '#/components/schemas/MachineNote'
      required:
        - eoCode
        - fId
        - mProducer
        - mModel
        - mNumber
        - mCapacity
#
    MachineIdCorrectionOrderParameter:
      type: object
      properties:
        eoCode:
          $ref: '#/components/schemas/ConfirmationCode'
        fId:
          $ref: '#/components/schemas/Fid'
        mProducer:
          $ref: '#/components/schemas/MachineProducer'
        mModel:
          $ref: '#/components/schemas/MachineModel'
        mNumber:
          $ref: '#/components/schemas/MachineSerialNumber'
        mCapacity:
          $ref: '#/components/schemas/MachineCapacity'
        mNote:
            $ref: '#/components/schemas/MachineNote'
      required:
        - eoCode
        - fId
        - mProducer
        - mModel
        - mNumber
        - mCapacity
#
# ID order result types
#
    EoIdOrderResult:
      type: object
      properties:
        idList:
          type: array
          items:
            type: object
            properties:
              position:
                $ref: '#/components/schemas/OrderPosition'
              eoId:
                $ref: '#/components/schemas/EoId'
              confirmationCode:
                $ref: '#/components/schemas/ConfirmationCode'
            required:
              - position
              - eoId
              - confirmationCode
      required:
        - idList
#
    FidOrderResult:
      type: object
      properties:
        idList:
          type: array
          items:
            type: object
            properties:
              position:
                $ref: '#/components/schemas/OrderPosition'
              fid:
                $ref: '#/components/schemas/Fid'
            required:
              - position
              - fid
      required:
        - idList
#
    MidOrderResult:
      type: object
      properties:
        idList:
          type: array
          items:
            type: object
            properties:
              position:
                $ref: '#/components/schemas/OrderPosition'
              mid:
                $ref: '#/components/schemas/Mid'
            required:
              - position
              - mid
      required:
        - idList
#
# UI order types
#
    UpUiOrderParameter:
      type: object
      properties:
        fId:
          $ref: '#/components/schemas/ArbitraryFid'
        processType:
          $ref: '#/components/schemas/ChoiceSelector'
        mId:
          $ref: '#/components/schemas/ArbitraryMid'
        pType:
          $ref: '#/components/schemas/TobaccoProductType'
        pOtherType:
          $ref: '#/components/schemas/TobaccoProductTypeOther'
        pCn:
          $ref: '#/components/schemas/CombinedNomenclatureCode'
        pBrand:
          $ref: '#/components/schemas/ProductBrand'
        pWeight:
          $ref: '#/components/schemas/ProductAvgGrossWeight'
        tpId:
          $ref: '#/components/schemas/EuCegTobaccoProductId'
        tpPn:
          $ref: '#/components/schemas/EuCegTobaccoProductNumber'
        intendedMarket:
          $ref: '#/components/schemas/IsoCountry'
        intendedRoute1:
          $ref: '#/components/schemas/ChoiceSelector'
        intendedRoute2:
          $ref: '#/components/schemas/IsoCountry'
        import:
          $ref: '#/components/schemas/ChoiceSelector'
        reqQuantity:
          $ref: '#/components/schemas/Quantity'
        orderProcessing:
          $ref: '#/components/schemas/OrderProcessingPriority'
        deliveryMethod:
          $ref: '#/components/schemas/DeliveryMethod'
        webHookBase:
          $ref: '#/components/schemas/WebHook'
        gtin:
          $ref: '#/components/schemas/Gtin'
        buendeOrderId:
          $ref: '#/components/schemas/BuendeOrderId'
        buendeOrderPosition:
          $ref: '#/components/schemas/BuendeOrderPosition'
        customerOrderId:
          $ref: '#/components/schemas/CustomerOrderId'
        eMailOption:
          $ref: '#/components/schemas/EmailOption'
      required:
        - fid
        - pType
        - pBrand
        - pWeight
        - intendedMarket
        - intendedRoute1
        - import
        - reqQuantity
        - deliveryMethod
      example:
        fId: 'QCBDR<1DE020054000048'
        processType: true
        mId: 'QCBDR>1DE020054000012'
        pType: "Cigarette"
        pCn: "12345678"
        pBrand: "Greatest Cigarette on Earth"
        pWeight: 50.2
        tpId: "12345-18-12345"
        tpPn: "1234567890"
        intendedMarket: "IT"
        intendedRoute1: true
        intendedRoute2: "AT"
        import: false
        reqQuantity: 50000
        orderProcessing: "ImmediateProcessingNoRecallPossible"
        deliveryMethod: 'Electronically'
        webHookBase: "https://notifications.acme.eu/upui/"
        gtin: "0022140002355"
        customerOrderId: '2019-abc-224'
        eMailOption: {
          notification: false
        }
#
    AuiOrderParameter:
      type: object
      properties:
        fId:
          $ref: '#/components/schemas/ArbitraryFid'
        reqQuantity:
          $ref: '#/components/schemas/Quantity'
        orderProcessing:
          $ref: '#/components/schemas/OrderProcessingPriority'
        webHookBase:
          $ref: '#/components/schemas/WebHook'
        eMailOption:
          $ref: '#/components/schemas/EmailOption'
      required:
        - fId
        - reqQuantity
      example:
        fId: 'QCBDR<1DE020054000048'
        reqQuantity: 5000
        eMailOption: {
          notification: true,
          eMailAddress: 'some.other@email.de'
        }
#
# UI order result types
#
    UiOrderResponse:
      description: This type is used in a response to a upUI order
      properties:
        orderId:
          $ref: '#/components/schemas/OrderId'
        recallCode:
          $ref: '#/components/schemas/RecallCode'
      required:
        - orderId
        - recallCode
#
# ID status query response
#
    IdStatusQueryResponse:
      description: This type is returned in response to an ID status query
      properties:
        idActive:
          type: boolean
      required:
        - idActive
#
# Error types
#
    MultiItemErrorEo:
      type: object
      properties:
        idList:
          type: array
          items:
            type: object
            properties:
              position:
                type: integer
              result:
                type: string
                enum:
                  - '201'
                  - '400'
                  - '409'
              id:
                # property id is populated only, if result is 201
                $ref: '#/components/schemas/EoId'
              confirmationCode:
                # property confirmationCode is populated only, if result is 201
                $ref: '#/components/schemas/ConfirmationCode'
              message:
                # property message is populated only, if result is unequal 201
                type: string
            required:
              - position
              - result
      example:
        idList:
        - position: 1
          result: '201'
          id: 'QCBDR+1DE020054'
          confirmationCode: '6fSE23'
        - position: 2
          result: '400'
          message: 'invalid VAT ID'
        - position: 3
          result: '201'
          id: 'QCBDR+1DE020055'
          confirmationCode: 'HkyS3T'
#
    MultiItemErrorFM:
      type: object
      properties:
        idList:
          type: array
          items:
            type: object
            properties:
              position:
                type: integer
              result:
                type: string
                enum:
                  - '201'
                  - '400'
                  - '409'
              id:
                # property id is populated only, if result is 201
                oneOf:
                - $ref: '#/components/schemas/Fid'
                - $ref: '#/components/schemas/Mid'
              message:
                # property message is populated only, if result is unequal 201
                type: string
            required:
              - position
              - result
      example:
        idList:
        - position: 1
          result: '201'
          id: 'QCBDR<1DE020054000048'
        - position: 2
          result: '400'
          message: 'invalid facility type'
        - position: 3
          result: '201'
          id: 'QCBDR<1DE020054000049'
#
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              fieldName:
                type: string
              message:
                type: string
            required:
              - fieldName
              - message
          minItems: 1
#
# common responses
#
  responses:
    ServiceTempNotAvailable:
      description: service temporary unavailable
      headers:
        Retry-After:
          description: Retry-After header field acc. to RFC7231, value denoted in seconds
          schema:
            type: integer
        X-Api-Version:
          description: The implemented API version
          schema:
            type: string
    MissingAuthorization:
      description: missing authorization
      headers:
        X-Api-Version:
          description: The implemented API version
          schema:
              type: string
    UnsupportedMediaType:
      description: unsupported media type
      headers:
        X-Api-Version:
          description: The implemented API version
          schema:
            type: string
    OrderNotFound:
      description: order not found
      headers:
        X-Api-Version:
          description: The implemented API version
          schema:
            type: string
    BadRequest:
      description: Bad request, e.g. parameter error
      headers:
        X-Api-Version:
          description: The implemented API version
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    UnavailableForLegalReasons:
      description: order not accecpted because VAT/TIN of EO was not validated
        yet and EO is still pending in order-ban period
      headers:
        X-Api-Version:
          description: The implemented API version
          schema:
            type: string
