openapi: '3.0.0'
info:
  version: 1.0.1
  title: Paket DE Retoure API
  description: >
      Hinweis:
      Dies ist die Spezifikation der DPDHL Paket DE Retoure API. Dieser Webservice ermöglicht es Geschäftskunden, Retourenetiketten bei Bedarf zu erstellen.

servers:
  - description: Sandbox Environment (Customer Testing)
    url: https://api-sandbox.dhl.com/parcel/de/shipping/returns/v1
  - description: Production Environment
    url: https://api-eu.dhl.com/parcel/de/shipping/returns/v1

paths:
  /orders:
    post:
      operationId: createReturnOrder
      tags:
        - Orders
      summary: Create a return label.
      description: Creates a return label by given information.
      parameters:
        - in: query
          name: labelType
          required: false
          description: Controls which documents are returned.
          schema:
            $ref: '#/components/schemas/LabelType'
      requestBody:
        description: >-
          The request body contains the details of the return label that should be created. E.g. sender, references
          and shipment details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnOrder'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReturnOrderConfirmation'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Error'
                minItems: 1
                maxItems: 1000
  /locations:
    get:
      operationId: getLocations
      tags:
        - Locations
      summary: Get available return locations
      description: The response should be a list of Receiver, each containing the following information
      parameters:
        - in: query
          name: countryCode
          required: false
          description: The ISO3 code of the location
          schema:
            $ref: '#/components/schemas/Country'
        - in: query
          name: postalCode
          required: false
          description: The postal code code of the location
          schema:
            $ref: '#/components/schemas/PostalCode'
        - in: query
          name: receiverId
          required: false
          description: The receiver id of the location
          schema:
            $ref: '#/components/schemas/ReceiverId'
        - in: query
          name: billingNumber
          required: false
          schema:
            $ref: '#/components/schemas/BillingNumber'
        - in: query
          name: maxResult
          required: false
          description: The result should be containable.
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Receiver'
                minItems: 0
                maxItems: 5000
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
components:
  schemas:
    ReturnOrder:
      type: object
      properties:
        receiverId:
          $ref: '#/components/schemas/ReceiverId'
        customerReference:
          type: string
          minLength: 0
          maxLength: 50
        shipmentReference:
          type: string
          minLength: 0
          maxLength: 50
        shipper:
          $ref: '#/components/schemas/ContactAddress'
        itemWeight:
          $ref: '#/components/schemas/Weight'
        itemValue:
          $ref: '#/components/schemas/Value'
        customsDetails:
          $ref: '#/components/schemas/CustomsDetails'
      required:
        - ContactAddress
        - receiverId
    Receiver:
      type: object
      properties:
        receiverId:
          $ref: '#/components/schemas/ReceiverId'
        shipperCountry:
          $ref: '#/components/schemas/Country'
        ekp:
          type: string
          pattern: '\d{10}'
        billingNumber:
          $ref: '#/components/schemas/BillingNumber'
        companyName:
          type: string
          maxLength: 50
        numberRange:
          type: string
          maxLength: 35
          description: TODO
        receiverAddress:
          $ref: '#/components/schemas/ContactAddress'
        companyAddress:
          $ref: '#/components/schemas/ContactAddress'
        contactEmail:
          $ref: '#/components/schemas/Email'
        additionalEmailNote:
          type: string
          maxLength: 250
          description: TODO
        salesTaxIdentificationNumber:
          type: string
          maxLength: 30
          description: TODO
        court:
          type: string
          maxLength: 30
          description: TODO
        companyManagement:
          type: string
          maxLength: 50
      required:
        - receiverId
        - shipperCountry
        - ekp
        - billingNumber
        - companyName
        - numberRange
        - receiverAddress
        - companyAddress
    ContactAddress:
      type: object
      properties:
        name1:
          maxLength: 50
          minLength: 1
          type: string
          description: "Name1. Line 1 of name information"
        name2:
          maxLength: 50
          minLength: 0
          type: string
          description: "An optional, additional line of name information"
        name3:
          maxLength: 50
          minLength: 0
          type: string
          description: "An optional, additional line of name information"
        addressStreet:
          type: string
          description: "This is just the street name."
          maxLength: 50
          minLength: 1
        addressHouse:
          type: string
          description: "This is just the house number."
          maxLength: 10
          minLength: 1
        additionalAddressInformation1:
          maxLength: 60
          minLength: 1
          type: string
          description: Line 2 of the street address. Most of the time this is not needed and not printed to most labels.
          example: "3rd Floor"
        additionalAddressInformation2:
          maxLength: 60
          minLength: 1
          type: string
          description: Line 3 of the street address. Rarely needed and not printed to most labels.
          example: "Apartment 12"
        city:
          type: string
          maxLength: 40
          minLength: 1
          example: Berlin
        country:
          $ref: '#/components/schemas/Country'
        email:
          $ref: '#/components/schemas/Email'
        phone:
          description: contact phone number
          maxLength: 20
          minLength: 1
          type: string
          example: "+49 123456789"
        postalCode:
          $ref: '#/components/schemas/PostalCode'
        state:
          type: string
          maxLength: 20
          example: NRW
      required:
        - name1
        - address1
        - postalCode
        - city

    CustomsDetails:
      type: object
      description: A customs declaration (CN23) is a customs document that is only needed for returns from outside the EEC (e.g  Switzerland).
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Commodity'
          minItems: 1
          maxItems: 20
          description: The customs items to be declared.
      required:
        - positions
    Commodity:
      type: object
      description: Represents a declared item in customs declaration.
      properties:
        itemDescription:
          type: string
          maxLength: 50
          description: Description of the declared item.
        packagedQuantity:
          type: integer
          description: Amount of the declared item(s).
        itemWeight:
          $ref: '#/components/schemas/Weight'
        itemValue:
          $ref: '#/components/schemas/Value'
      required:
        - itemDescription
        - packagedQuantity
        - itemWeight
        - itemValue

    ReturnOrderConfirmation:
      type: object
      description: Confirmation number.
      properties:
        sstatus:
          $ref: '#/components/schemas/JSONStatus'
        shipmentNo:
          $ref: '#/components/schemas/shipmentNo'
        internationalShipmentNo:
          $ref: '#/components/schemas/shipmentNo'
        label:
          $ref: '#/components/schemas/Document'
        qrLabel:
          $ref: '#/components/schemas/Document'
        routingCode:
          type: string
          description: Routing code of the returnlabel.
      required:
        - shipmentNo
        - label
        - routingCode
        - sstatus

    Document:
      description: "Encoded document. All types of labels and documents. "
      type: object
      additionalProperties: false
      properties:
        b64:
          description: The encoded byte stream
          type: string
          format: byte
          example: "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABmgvaeTAAAA="

    JSONStatus:
      description: "Standard elements for json status from (https://tools.ietf.org/html/rfc7807) "
      type: object
      additionalProperties: false
      required:
        - title
        - status
      properties:
        title:
          type: string
          example: "Unauthorized"
        status:
          type: integer
          minimum: 200
          maximum: 999
          example: 401
        type:
          description: "A URI reference [RFC3986] that identifies the problem type and is human-readable."
          type: string
          format: uri
          example: "https://api.dhl.com/parcel/de/shipping/e0001.html"
        detail:
          description: "A human-readable explanation specific to this occurrence of the problem"
          type: string
          maxLength: 80
          example: "The credentials you provided are invalid."
        instance:
          description: "A URI reference that identifies the specific occurrence of the problem."
          type: string
          format: uri
          example: "https://api.dhl.com/parcel/de/shipping/e0001.html"
    ReceiverId:
      type: string
      maxLength: 30
      example: 'DE'
      description: the receiver id of the return shipment
    BillingNumber:
      type: string
      pattern: '\d{10}\d{2}\w{2}'
    PostalCode:
      description: postal code, relaxed UPU version
      maxLength: 10
      minLength: 3
      pattern: "^[0-9A-Za-z]+([ -]?[0-9A-Za-z]+)*$"
      type: string
      example: 12345
    Country:
      type: string
      enum:
      - bel
      - bgr
      - dnk
      - deu
      - est
      - fin
      - fra
      - grc
      - gbr
      - irl
      - ita
      - hrv
      - lva
      - ltu
      - lux
      - mlt
      - nld
      - aut
      - pol
      - prt
      - rou
      - swe
      - che
      - svk
      - svn
      - esp
      - cze
      - hun
      - cyp
    Weight:
      required:
        - uom
        - value
      type: object
      properties:
        uom:
          type: string
          description: Unit of measurement. Metric unit for weight.
          example: g
          enum:
            - g
            - kg
        value:
          description: Weight of item or shipment. Both uom and value are required.
          type: number
          minimum: 0.001
          maximum: 31500
          example: 500.0
          multipleOf: 0.001
    Email:
      description: contact email address
      format: email
      maxLength: 80
      minLength: 3
      type: string
      example: "max@mustermann.de"
    Value:
      description: Currency and numeric value.
      type: object
      additionalProperties: false
      properties:
        currency:
          description: "iso 4217 3 digit currency code accepted. Recommended to use EUR where possible"
          type: string
          enum: [ EUR, USD, CZK, GBP, CHF, SGD ]
          default: "EUR"
        value:
          description: "Numeric value"
          type: number
          minimum: 0
          maximum: 100000
          multipleOf: 0.01
    shipmentNo:
      type: string
      maxLength: 50
    LabelType:
      type: string
      enum:
        - SHIPMENT_LABEL
        - QR_LABEL
        - BOTH
      default: BOTH
      description: Controls which documents are returned.
    Error:
      $ref: '#/components/schemas/JSONStatus'
  responses:
    '400':
      description: >
        Bad Request - The request could not be understood by the server due to
        malformed syntax.
    '401':
      description: >
        Unauthorized - The client could not be authenticated since the request
        lacks the required HTTP headers or the credentials are just wrong.
    '403':
      description: >
        Forbidden - The client has successfully been authenticated but could not
        be authorized for the particular request.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: Active business customer credentials (username and password).
    ApiKey:
      type: apiKey
      description: API key to authorize requests. API key can be obtained at [DHL's development
        portal](https://developer.dhl.com).
      name: dhl-api-key
      in: header
security:
    - ApiKey: []
    - BasicAuth: []
