openapi: 3.2.0
info:
  title: Kuehne Nagel Upload API
  x-api-guideline-version: 1.11.7
  x-refined-note:
  - x-api-id differs across the merged source definitions and was not carried
  - x-api-version differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Upload across 2 of this provider''s published API definitions: kuehne-nagel-shipment-document-management-v2-openapi.json, kuehne-nagel-shipment-document-management-v3-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://gateway.api.kuehne-nagel.com/transport/execution/documentation/shipment/v2
- url: https://gateway.api.kuehne-nagel.com/transport/execution/documentation/shipment/v3
tags:
- name: Upload
  description: Operations to upload shipment documents.
paths:
  /shipments/{uniqueShipmentReference}/documents:
    post:
      tags:
      - Upload
      description: 'Add a document to a specific shipment.


        Before the document is actually added to the shipment the uploaded content must pass a

        security scan and conversion to [PDF/A](https://en.wikipedia.org/wiki/PDF/A). This is done asynchronously

        and usually only takes a couple of seconds. For the future it is planned to immediately scan and convert the document.

        '
      operationId: addDocument
      parameters:
      - $ref: '#/components/parameters/uniqueShipmentReferenceParameter'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AddDocumentRequest'
        required: true
      responses:
        '201':
          description: 'Request to add a document to the shipment was created.


            The status of the request can be retrieved using the returned link.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddDocumentResponse'
        default:
          $ref: '#/components/responses/default'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: 10KPerMin
    servers:
    - url: https://gateway.api.kuehne-nagel.com/transport/execution/documentation/shipment/v2
  /shipments/{uniqueShipmentReference}/documents/{documentId}:
    get:
      tags:
      - Upload
      description: Retrieve meta data of a specific shipment document.
      operationId: retrieveDocumentDetails
      parameters:
      - $ref: '#/components/parameters/uniqueShipmentReferenceParameter'
      - $ref: '#/components/parameters/documentIdParameter'
      responses:
        '200':
          description: Meta data of the document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveDocumentDetailsResponse'
        default:
          $ref: '#/components/responses/default'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: 10KPerMin
    servers:
    - url: https://gateway.api.kuehne-nagel.com/transport/execution/documentation/shipment/v2
  /shipments/{uniqueShipmentReference}/uploadable-document-types:
    get:
      tags:
      - Upload
      description: Retrieve the document types that can be used to add a document to the specific shipment.
      operationId: retrieveUploadableDocumentTypes
      parameters:
      - $ref: '#/components/parameters/uniqueShipmentReferenceParameter'
      responses:
        '200':
          description: Set of document types that can be used to add a document to the specific shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveUploadableDocumentTypesResponse'
        default:
          $ref: '#/components/responses/default'
      security:
      - default: []
      x-auth-type: Application & Application User
      x-throttling-tier: 10KPerMin
    servers:
    - url: https://gateway.api.kuehne-nagel.com/transport/execution/documentation/shipment/v2
components:
  schemas:
    DocumentTypeName:
      maxLength: 255
      type: string
      description: Name of a document type according to the Kuehne+Nagel specific classification.
      example: Commercial Invoice
    DocumentId:
      maxLength: 255
      minLength: 1
      type: string
      description: Unique identifier of a shipment document.
      example: Q1234S56
    RetrieveDocumentDetailsResponse:
      required:
      - documentId
      - documentType
      - status
      type: object
      properties:
        documentId:
          $ref: '#/components/schemas/DocumentId'
        documentType:
          $ref: '#/components/schemas/DocumentType'
        status:
          $ref: '#/components/schemas/DocumentStatus'
      description: Response containing the detailed metadata of a specific shipment document.
    DocumentType:
      required:
      - code
      - name
      type: object
      properties:
        code:
          $ref: '#/components/schemas/DocumentTypeCode'
        name:
          $ref: '#/components/schemas/DocumentTypeName'
      description: Kuehne+Nagel specific classification of shipment documents.
      example:
        code: '380'
        name: Commercial Invoice
    Problem:
      required:
      - detail
      - title
      type: object
      properties:
        detail:
          maxLength: 256
          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
        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
        title:
          maxLength: 128
          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
        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
      description: A problem details object as defined by RFC 7807, used to carry error information in HTTP API responses.
    RetrieveUploadableDocumentTypesResponse:
      required:
      - uploadableDocumentTypes
      type: object
      properties:
        uploadableDocumentTypes:
          maxItems: 512
          uniqueItems: true
          type: array
          description: List of document types available for uploading to the shipment.
          example:
          - code: '380'
            name: Commercial Invoice
          - code: '271'
            name: Packing List
          items:
            $ref: '#/components/schemas/DocumentType'
      description: Response containing the document types that can be uploaded for a specific shipment.
    AddDocumentResponse:
      required:
      - documentId
      - self
      type: object
      properties:
        documentId:
          $ref: '#/components/schemas/DocumentId'
        self:
          type: string
          description: URI to retrieve the meta data of the uploaded shipment document.
          format: uri
          example: https://.../shipments/N4242/documents/Q1234S56
      description: Response returned after a document upload request has been created.
    AddDocumentRequest:
      required:
      - documentContent
      - documentTypeCode
      type: object
      properties:
        documentContent:
          type: string
          description: "Content of the document (preferably a PDF) that should be added to the shipment.\n\nMust have\n* a size of max. 10 MB\n* a supported file extension\n  * pdf\n  * docx/doc\n  * xlsx/xls\n  * png\n  * jpeg/jpg\n  * tiff/tif\n  * rtf\n  * bmp\n* in case of a PDF: no read protection\n"
          format: binary
        documentTypeCode:
          $ref: '#/components/schemas/DocumentTypeCode'
      description: Request body for adding a document to a shipment.
    DocumentStatus:
      maxLength: 128
      type: string
      description: 'Extensible enum:

        * `OK`

        * `PROCESSING_UPLOAD`

        * `PROCESSING_UPLOAD_FAILED`

        '
      example: OK
      x-extensible-enum:
      - OK
      - PROCESSING_UPLOAD
      - PROCESSING_UPLOAD_FAILED
    DocumentTypeCode:
      maxLength: 3
      minLength: 3
      type: string
      description: 'Code of a document type according to the Kuehne+Nagel specific classification.


        The document types allowed for uploading a document can be retrieved via the operation `/shipments/{uniqueShipmentReference}/uploadable-document-types`.


        Often uploaded document types:

        * 380 (Commercial Invoice)

        * 271 (Packing List)

        * 944 (Customs Documents)

        * 833 (Export Declaration)

        '
      example: '380'
    AddDocumentRequest_2:
      required:
      - documentContent
      - documentTypeCode
      type: object
      properties:
        documentContent:
          type: string
          description: "Content of the document (preferably a PDF) that should be added to the shipment.\n\nMust have \n* a size of max. 10 MB\n* a supported file extension \n  * pdf\n  * docx/doc\n  * xlsx/xls\n  * png\n  * jpeg/jpg\n  * tiff/tif\n  * rtf\n  * bmp\n* in case of a PDF: no read protection\n"
          format: binary
        documentTypeCode:
          $ref: '#/components/schemas/DocumentTypeCode'
      description: Request body for adding a document to a shipment.
  parameters:
    documentIdParameter:
      name: documentId
      in: path
      description: Unique identifier of a document
      required: true
      style: simple
      explode: false
      schema:
        $ref: '#/components/schemas/DocumentId'
    uniqueShipmentReferenceParameter:
      name: uniqueShipmentReference
      in: path
      description: "By default this is the shipment __tracking number__ e.g. `N4242`.\n\nIn case a tracking number is not available a limited set of alternative references can be used.\nPlease use the track and trace API to first search for shipment details (e.g. by a customer specific reference)\nif none of the supported references are available .\n\nSupported references:\n* __tracking number__\n  * `{trackingNumber}` or `tracking-number:{trackingNumber}`\n  * e.g. `N4242` or `tracking-number:N4242`\n* __booking number__\n  * `booking-number:{bookingNumber}`\n  * e.g. `booking-number:B1`\n* __shipment id__\n  * `shipment-id:{shipmentId}`\n  * e.g. `shipment-id:S1`\n"
      required: true
      style: simple
      explode: false
      schema:
        maxLength: 255
        pattern: ^(tracking-number:|booking-number:|shipment-id:)?[A-Za-z0-9]+$
        type: string
        example: N4242
    uniqueShipmentReferenceParameter_2:
      name: uniqueShipmentReference
      in: path
      description: "By default this is the shipment __tracking number__ e.g. `N4242`. \n\nIn case a tracking number is not available a limited set of alternative references can be used.\nPlease use the track and trace API to first search for shipment details (e.g. by a customer specific reference)\nif none of the supported references are available .\n    \nSupported references:\n* __tracking number__\n  * `{trackingNumber}` or `tracking-number:{trackingNumber}`\n  * e.g. `N4242` or `tracking-number:N4242`\n* __booking number__\n  * `booking-number:{bookingNumber}`\n  * e.g. `booking-number:B1`\n* __shipment id__\n  * `shipment-id:{shipmentId}` \n  * e.g. `shipment-id:S1`\n"
      required: true
      style: simple
      explode: false
      schema:
        maxLength: 255
        pattern: ^(tracking-number:|booking-number:|shipment-id:)?[A-Za-z0-9]+$
        type: string
        example: N4242
  responses:
    default:
      description: An error occurred - please see the HTTP status code and the problem object for more information.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    default:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://gateway.api.kuehne-nagel.com/authorize
          scopes: {}
    api_key:
      type: apiKey
      name: apikey
      in: header
x-refined-from:
- kuehne-nagel-shipment-document-management-v2-openapi.json
- kuehne-nagel-shipment-document-management-v3-openapi.json
x-wso2-api-key-header: ApiKey