swagger: '2.0'
info:
  title: Returnlabel Service for Business Customers of DP-DHL Group
  description: >


    # Introduction

    ## Overview

      This is the specification of the DP-DHL Group Parcel Return Web Services for business customers. This web service allows business customers to create returnlabels on demand.

    ## Pre-conditions

      In order to access this service, a registration for the DP-DHL Group Customer Integration Gateway ("CIG") is required. Partners can register [here](https://entwickler.dhl.de/web/ep/anmeldung).

      Apart from CIG credentials, a partner system has to identify itself and needs be authorized for this particular service. This requires another pair of credentials. Both credentials must be passed as request headers. (See "Web service authentication".)

      The service can only be reached through HTTPS. HTTP requests are ignored (by CIG).

      The web service is a REST interface that can be accessed by a number of libraries and tools for different programming languages and environments.


    ## Error handling

    All error responses (4xx and 5xx) have the `Content-Type` header set to
    `application/problem+json` or `application/problem+xml`, if the requests
    `Content-Type` were `application/json` or `application/xml`. 


    The response content must also contain the HTTP return code as well as the
    reason for the error. For example


    ```

    {"code":"INVALID_PRODUCT_SELECTION","detail":"Invalid product/service
    combination."}

    ```

    Note that the error code given here is a business-level error code, not the
    HTTP error code.


    The most common HTTP codes to expect from this service are:

    >400: Bad Request. A client error that can denote a syntax or semantic
    error. Error details can be found in the return `Error` object. Do not
    repeat the request without changing it.


    >401: Authentication failed. The caller provided the wrong credentials. Do
    not repeat the request without changing it.


    >403: Authorization failed. The caller has provided the correct credentials,
    but hasn't got sufficient privileges to access a given resource.

    ## Web Service Authentication

    The caller needs two sets of credentials:

    The Gateway (CIG) authenticates users using [Basic HTTP
    Authentication](https://tools.ietf.org/html/rfc7617), passed as a
    `Authorization` request header


    ```

    'Authorization: Basic <base-64 coded cigUser:cigPassword>'

    ```

    The authentication of the partner system is given by the
    `DPDHL-User-Authentication-Token` header. The value uses the same syntax as
    that of the `Authentication`.

    ```

    'DPDHL-User-Authentication-Token: <base-64 coded partnerId:partnerPassword>'

    ```

  version: 0.0.1
basePath: /services/sandbox/rest/returns
consumes:
  - application/json
  - application/xml
produces:
  - application/json
  - application/xml
paths:
  /:
    post:
      tags:
        - Returns
      summary: Request for returnlabels.
      description: Contains all details needed to create a returnlabel.
      parameters:
        - in: body
          name: returnOrder
          description: >-
            The object contains the details of the sender, the returnshipment
            and references.
          schema:
            $ref: '#/definitions/ReturnOrder'
      responses:
        '201':
          description: Created
          schema:
            $ref: '#/definitions/ReturnOrderConfirmation'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
definitions:
  ReturnOrder:
    type: object
    properties:
      receiverId:
        type: string
        minLength: 0
        maxLength: 30
        example: 'DE'
      customerReference:
        type: string
        minLength: 0
        maxLength: 30
      shipmentReference:
        type: string
        minLength: 0
        maxLength: 30
      senderAddress:
        $ref: '#/definitions/SimpleAddress'
      email:
        type: string
        minLength: 0
        maxLength: 70
        format: email
      telephoneNumber:
        type: string
        minLength: 0
        maxLength: 35
        format: string
      weightInGrams:
        type: integer
        minimum: 0
      value:
        type: number
        minimum: 0
      customsDocument:
        $ref: '#/definitions/CustomsDocument'
      returnDocumentType:
        type: string
        enum:
          - SHIPMENT_LABEL
          - QR_LABEL
          - BOTH
        description: >-
          The type of document(s) to return in the response':' The SHIPMENT_LABEL only, the QR_LABEL or BOTH.
    required:
      - senderAddress
      - receiverId
  SimpleAddress:
    type: object
    properties:
      name1:
        type: string
        minLength: 0
        maxLength: 35
      name2:
        type: string
        minLength: 0
        maxLength: 35
      name3:
        type: string
        minLength: 0
        maxLength: 35
      streetName:
        type: string
        minLength: 0
        maxLength: 35
      houseNumber:
        type: string
        minLength: 0
        maxLength: 5
      postCode:
        type: string
        minLength: 0
        maxLength: 10
        example: '12345'
      city:
        type: string
        minLength: 0
        maxLength: 35
      country:
        $ref: '#/definitions/Country'
    required:
      - name1
      - streetName
      - houseNumber
      - postCode
      - city
  Country:
    type: object
    properties:
      countryISOCode:
        type: string
        minLength: 3
        maxLength: 3
      country:
        type: string
        minLength: 0
        maxLength: 30
      state:
        type: string
        minLength: 0
        maxLength: 30
    required:
      - countryISOCode
  CustomsDocument:
    type: object
    description: >-
      A customs form ("CN23") is only needed for returns from outside the EEC
      (e.g. Switzerland).
    properties:
      currency:
        type: string
        enum:
          - EUR
          - GBP
          - CHF
        description: Currency the returned goods were payed in.
      originalShipmentNumber:
        type: string
        minLength: 0
        maxLength: 35
        description: Original shipment number.
      originalOperator:
        type: string
        minLength: 0
        maxLength: 40
        description: Company that delivered the original parcel.
      acommpanyingDocument:
        type: string
        minLength: 0
        maxLength: 35
        description: Additional documents.
      originalInvoiceNumber:
        type: string
        minLength: 0
        maxLength: 35
        description: Invoice number of the returned goods.
      originalInvoiceDate:
        type: string
        minLength: 0
        maxLength: 35
        description: Date of the invoice number.
      comment:
        type: string
        minLength: 0
        maxLength: 150
        description: Comment.
      positions:
        type: array
        items:
          $ref: '#/definitions/CustomsDocumentPosition'
        minItems: 1
        maxItems: 5
        description: The customs items to be declared.
    required:
      - currency
      - positions
      
  CustomsDocumentPosition:
    type: object
    description: Represents the returned items.
    properties:
      positionDescription:
        type: string
        minLength: 0
        maxLength: 50
        description: Description of the returend item.
      count:
        type: integer
        minimum: 0
        description: Amount of items declared per position.
      weightInGrams:
        type: integer
        minimum: 0
        description: Weight of the returend item.
      values:
        type: number
        minimum: 0
        description: Value of returned item.
      originCountry:
        type: string
        minLength: 3
        maxLength: 3
        description: Country the returned item was produced.
      articleReference:
        type: string
        minLength: 0
        maxLength: 40
        description: Reference of the returned item.
      tarifNumber:
        type: string
        minLength: 0
        maxLength: 8
        description: Customs tariff number.
    required:
      - positionDescription
      - count
      - weightInGrams
      - values
  ReturnOrderConfirmation:
    type: object
    description: Confirmation number.
    properties:
      shipmentNumber:
        type: string
        minLength: 12
        maximum: 39
        description: The shipment number.
      labelData:
        type: string
        minLength: 0
        description: Base64 encoded returnlabel string (pdf file).
      qrLabelData:
        type: string
        minLength: 0
        description: Base64 encoded returnlabel (QR Code).
      routingCode:
        type: string
        description: Routing code of the returnlabel.
    required:
      - shipmentNumber
  Error:
    type: object
    description: Error information.
    properties:
      code:
        type: integer
        description: The business-level error code.
      detail:
        type: string
        description: >-
          Reason the error occurred. This string is provided for
          user-friendliness and may change in future. (Note':' This is a
          business cause, not the HTTP error.)
    required:
      - code
      - detail
    example:
      code: 456
      detail: 'Invalid date format, should be yyyy-mm-dd'
parameters:
  billingNumber:
    name: billingNumber
    in: path
    description: The billing number of the return shipment.
    required: true
    type: string
responses:
  '400':
    description: >
      Bad Request - The request could not be understood by the server due to
      malformed syntax or semantic errors.
    schema:
      $ref: '#/definitions/Error'
  '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.
securityDefinitions:
  appAuth:
    type: basic
    description: >-
      Colon-separated and base64-encoded *application ID* and *application
      token*. These credentials can be obtained at [DPDHL's development
      portal](https://entwickler.dhl.de).
  userAuth:
    description: >
      Colon-separated and base64-encoded username and password of the partner
      system. The header field is proprietary to DPDHL. The header value follows
      the schema of HTTP Basic Authentication.
    type: apiKey
    name: DPDHL-User-Authentication-Token
    in: header
security:
  - appAuth: []
  - userAuth: []
