DHL Login API

openapi: 3.2.0
info:
  title: Dhl Login API
  version: v2.3.3
  description: 'Operations tagged Login across 2 of this provider''s published API definitions: dhl-deutsche-post-hybrid-mail-shipments-e-post-post-parcel-germany-openapi.json, dhl-deutsche-post-hybrid-mail-shipments-e-post-post-parcel-germany-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.epost.docuguide.com
tags:
- name: Login
  description: Anfordern eines JWT (JSON Web Token) für Zugriff auf den Letter-Controller.
paths:
  /api/Login:
    post:
      tags:
      - Login
      summary: Anfrage eines JSON Web Token
      description: 'Anfrage eines gültigen JWT (JSON Web Token) für den Zugriff auf die weiteren Controller der E-POSTBUSINESS API.


        Beispiel-Anfrage:


        POST

        {

        "vendorID": "12345",

        "ekp": "1234567890",

        "secret": "77831f6f-d39b-4d5b-a5ae-b4006f894179",

        "password": "56789"

        }'
      operationId: Login_Post
      requestBody:
        x-name: login
        description: Login-Objekt mit allen erforderlichen Zugangsdaten
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Login'
        required: true
        x-position: 1
      responses:
        '200':
          description: Die Login-Parameter wurden akzeptiert und es wurde eine gültige Tokeninformation per JSON zurückgegeben
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Die Login-Parameter sind ungültig. Gibt ein Error-Objekt zurück
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Allgemeiner Fehler. Gibt ein Error-Objekt zurück
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Zu häufige Abfragen innerhalb einer bestimmten Zeit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - JWT: []
    servers:
    - url: https://api.epost.docuguide.com
  /api/Login/smsRequest:
    post:
      tags:
      - Login
      summary: Anfrage des SMS-Codes
      description: 'Anfrage eines zeitlich begrenzten SMS-Code zur Verifizierung einer Passwortvergabe/änderung bzw. zur Aktivierung.


        Beispiel-Anfrage:


        POST

        {

        "vendorID": "12345",

        "ekp": "56789"

        }'
      operationId: Login_Post2
      requestBody:
        x-name: smsCodeRequest
        description: Objekt mit Software/Benutzer-Kennung
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SmsCodeRequest'
        required: true
        x-position: 1
      responses:
        '202':
          description: Die Software/Benutzer-Kennung war gültig. Es wird ein Code an die hinterlegte Mobilnummer per SMS versendet, der 10 Minuten gültig ist.
          content:
            application/json:
              schema:
                type: string
        '401':
          description: Die Software/Benutzer-Kennung war ungültig
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Allgemeiner Fehler. Gibt ein Error-Objekt zurück
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Zu häufige Abfragen innerhalb einer bestimmten Zeit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - JWT: []
    servers:
    - url: https://api.epost.docuguide.com
  /api/Login/setPassword:
    post:
      tags:
      - Login
      summary: Setzen des Passworts
      description: 'Speichert ein benutzerdefiniertes Passwort in der E-POSTBUSINESS API. Liefert bei Erfolg einen Sicherheitsschlüssel der E-POSTBUSINESS API (secret) zurück, welcher für die Login-Methode erforderlich ist und aktiviert die E-POSTBUSINESS API.


        Beispiel-Anfrage:


        POST

        {

        "vendorID": "123",

        "ekp": "1234567890",

        "newPassword": "qawsedrftg123",

        "smsCode": "9182"

        }'
      operationId: Login_Post3
      requestBody:
        x-name: setPassword
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetPassword'
        required: true
        x-position: 1
      responses:
        '200':
          description: Das Passwort wurde hinterlegt und kann für API-Anfragen genutzt werden. Liefert einen Sicherheitsschlüssel der EPost (secret) zurück, welcher für die Login-Methode erforderlich ist.
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Ungültige Anfragedaten. Gibt ein Error-Objekt zurück
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - JWT: []
    servers:
    - url: https://api.epost.docuguide.com
  /api/Login/HealthCheck:
    get:
      tags:
      - Login
      summary: Status-Prüfung der API
      description: Abfrage des Verfügbarkeitsstatus der E-POSTBUSINESS API und Bereitstelllung von Wartungsfenstern, sowie möglicher Störungen.
      operationId: Login_GetHealthCheck
      responses:
        '200':
          description: 'Erfolgreiche Anfrage des API-Status. Es wird ein Error-Object zurückgeliefert, welches den Status anhand einer Information (I501 - API-Status: OK), Warnung (W501 - API-Status: Wartungsankündigung) oder eines Fehlers (E501 - API-Status: Inaktiv) zurückmeldet.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Allgemeiner Fehler. Gibt ein Error-Objekt zurück
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Zu häufige Abfragen innerhalb einer bestimmten Zeit. Die Mindestdauer zwischen den Abfragen darf 5 Sekunden nicht unterschreiten.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - JWT: []
    servers:
    - url: https://api.epost.docuguide.com
components:
  schemas:
    SetPassword:
      type: object
      description: Informations-Objekt zur Festlegung eines neuen Passworts
      additionalProperties: false
      required:
      - vendorID
      - ekp
      - newPassword
      - smsCode
      properties:
        vendorID:
          type: string
          description: DPAG-Kennung des Software-Herstellers
          minLength: 1
        ekp:
          type: string
          description: DPAG-Kennung des Software-Kunden
          maxLength: 10
          minLength: 10
        newPassword:
          type: string
          description: 'Benutzerdefiniertes Password des Software-Kunden. '
          maxLength: 100
          minLength: 5
        smsCode:
          type: string
          description: SMS Code, welcher durch einen SMSCodeRequest zugesendet wurde
          maxLength: 6
          minLength: 6
    Error:
      type: object
      description: "Error-Objekt - Liefert Fehlercodes und Details bei entsprechenden Rückmeldungen über die API.\n\nAufstellung der Fehler-Codes pro Typ:\n\n\nError: Fehler aufgetreten, Handlungsbedarf, Verarbeitungsabbruch \n  \n  E001 - Ungültige Zugangsdaten - Bitte überprüfen Sie Ihre Anmeldedaten\n  \n  E002 - Ungültige Zugangsdaten - VendorSubID ungültig\n  \n  E003 - Zu viele SMS Anfragen - Es wurden innerhalb kurzer Zeit zu viele SMS-Codes angefordert. Die Anfrage über diese Kennung ist für 15 min blockiert.\n \n  E004 - Diese EKP wurde von der Deutsche Post AG gesperrt\n\n  E101 - Ungültiges Token - Abgelaufen\n  \n  E201 - Ungültige Statusabfrage - Es wurde keine Sendung über dieses Suchkriterium gefunden\n  \n  E203 - Adress-Metadaten: Abweichungen festgestellt {Platzhalter für Fehlerdetails}\n  \n  E301 - Kein PDF-Format erkannt\n  \n  E302 - Erkannte Verletzung des DVF Sperrbereich\n  \n  E303 - Maximale Dateigröße von 20 MB überschritten\n  \n  E304 - Maximale Seitenanzahl von 94 Seiten überschritten\n  \n  E305 - Ungültiger Ländercode: {Platzhalter für Fehlerdetails}\n  \n  E306 - Ungültiges Format der Empfängeradresse erkannt: {Platzhalter für Fehlerdetails}\n  \n  E307 - 1. Seite im Querformat eingeliefert - Dateiname: {Platzhalter für Fehlerdetails}\n  \n  E308 - Kein DinA4 Format - Dateiname: {Platzhalter für Fehlerdetails}\n  \n  E309 - Dublette bei eingelieferten Dateinamen erkannt - {Platzhalter für Fehlerdetails}\n  \n  E311 - Unzulässige Kombination: Einschreiben und Ausland\n  \n  E312 - Unzulässige Kombination: Dublex + Einschreiben\n  \n  E313 - Verletzung des Letter-Schemas: {Platzhalter für Fehlerdetails}\n  \n  E314 - Maximale Deckblatt-Dateigröße von 1 MB überschritten\n  \n  E315 - Fehler in Sendungsverarbeitung: {Platzhalter für Fehlerdetails}\n  \n  E316 - Fehler bei Sendungsupload: {Platzhalter für Fehlerdetails}\n  \n  E317 - Unzulässiges Einschreiben-Format in Feld RegisteredLetter: {Platzhalter für Fehlerdetails}  \n  \n  E318 - Ablehnung in Druckzentrum: {Platzhalter für Fehlerdetails}  \n  \n  E319 - EKP ist nicht für das Druckzentrum freigegeben. Ein Live-Versand ist aktuell noch nicht möglich.\n\n  E320 - Die maximal zulässige Menge an Testsendungen pro Tag wurde erreicht. Es sind heute keine weiteren Testsendungen möglich\n    \n  E321 - (Überholt) Es wurden nicht alle notwendigen Rückschein-Adressfelder für Einschreiben per Rückschein angegeben\n\n  E322 - Zu hohe Abfragefrequenz von Letter-Status Anfragen. Die Mindestdauer zwischen 2 Statusabfragen liegt bei 5 Sekunden. \n\n  E323 - Kein Inhalt im Empfängerbereich der PDF erkannt (Weiße Fläche) \n\n  E399 - Allgemeiner Fehler: {Platzhalter für Fehlerdetails} \n  \n  E501 - API-Status: Inaktiv {Platzhalter für Fehlerdetails}\n            \n  E601 - PlugIn Fehler: {Platzhalter für Fehlerdetails} \n  \n  E900 - Unspezifizierter Fehler: {Platzhalter für Fehlerdetails} \n\nWarnungen: Fehler aufgetreten, möglicher Handlungsbedarf, kein Verarbeitungsabbruch\n \n  W101 - PDF/A Konvertierungswarnungen: {Platzhalter für Details}\n  \n  W201 - Überschreitung Adressbereich: {Platzhalter für Details}\n  \n  W202 - Überschreitung Sperrfläche Links: Dieser Bereich wird im Druckzentrum geweißt \n  \n  W203 - Adress-Metadaten: Abweichungen festgestellt {Platzhalter für Fehlerdetails}\n  \n  W220 - Die angegeben Daten zum Rückschein von Einschreiben werden mit dem 01.10.2022 nur noch automatisch aus dem Sichtfenster des Briefes ermittelt. Dies gilt insbesondere für die Rücksendeadresse aus der im Sichtfenster ermittelbaren Absenderzeile. Mögliche explizite Angaben werden ab diesem Zeitpunkt nicht mehr verwendet.\n  \n  W301 - Senderadresse nicht vorhanden\n   \n  W501 - API-Status: Wartungsankündigung {Platzhalter für Details}\n\n  W601 - PlugIn Warnung: {Platzhalter für Details} \n\n\nInfos: Reine Information, kein Handlungsbedarf\n  \n  I101 - Zusatzoption: PDF -> PDFA Konvertierung\n  \n  I501 - API-Status: OK\n  \n  I601 - PlugIn Info: {Platzhalter für Details} \n  \n  I701 - Track And Trace Statusmeldung: {Platzhalter für Details}  \n  \n  I751 - Statusmeldung zum Zielgebiet: {Platzhalter für Details}\n  \n  "
      additionalProperties: false
      required:
      - level
      - code
      - description
      properties:
        level:
          type: string
          description: 'Art der Meldung: ''Info'',''Warning'',''Error'''
          minLength: 1
        code:
          type: string
          description: 'Eindeutige Kennung der Meldung (z.B. E101). '
          minLength: 1
        description:
          type: string
          description: Beschreibung der Meldung (z.B. 'Ungültige Sendungsnummer')
          minLength: 1
        date:
          type:
          - string
          - 'null'
          description: Zeitpunkt der Meldung
          format: date-time
    Login:
      type: object
      description: Login-Objekt zur Anmeldung und ermitteln des JWT
      additionalProperties: false
      required:
      - vendorID
      - ekp
      - secret
      - password
      properties:
        vendorID:
          type: string
          description: DPAG-Kennung des Software-Herstellers
          minLength: 1
        ekp:
          type: string
          description: DPAG-Kennung des Software-Kunden
          maxLength: 10
          minLength: 10
        secret:
          type: string
          description: 'Sicherheitsschlüssel der EPost, welcher bei der Passwort-Festlegung (Route: SetPassword) zurückgemeldet wurde'
          maxLength: 100
          minLength: 0
        password:
          type: string
          description: Benutzerdefiniertes Passwort des Software-Kunden
          maxLength: 100
          minLength: 5
        vendorSubID:
          type:
          - string
          - 'null'
          description: (optional) Partnerverwaltete Kunden-Kennung
          maxLength: 100
          minLength: 0
        tokenDuration:
          type: integer
          description: (optional) Lebendauer des Tokens in Minuten. Maximum und Standardwert ist 1440 (24 Std)
          format: int32
    LoginResponse:
      type: object
      description: 'Rückgabe eines Token nach Login '
      additionalProperties: false
      required:
      - token
      properties:
        token:
          type: string
          description: Token-Schlüssel
          minLength: 1
    SmsCodeRequest:
      type: object
      description: Anforderungsobjekt zur Anfrage eines SMS-Code, der 10 Minuten gültig ist. Dieser ist notwendig, um eine Erstellung/Änderung des benutzerdefinierten Passwort zu verifizieren
      additionalProperties: false
      required:
      - vendorID
      - ekp
      properties:
        vendorID:
          type: string
          description: DPAG-Kennung des Software-Herstellers
          minLength: 1
        ekp:
          type: string
          description: DPAG-Kennung des Software-Kunden.
          maxLength: 10
          minLength: 10
  securitySchemes:
    JWT:
      type: apiKey
      description: "Bitte JWT eingeben, welcher durch die Login-Methode zurückgeliefert wurde: \n\n                    Bearer {JWT}.\n\n                    "
      name: Authorization
      in: header
x-refined-from:
- dhl-deutsche-post-hybrid-mail-shipments-e-post-post-parcel-germany-openapi.json
- dhl-deutsche-post-hybrid-mail-shipments-e-post-post-parcel-germany-openapi.json