{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/dhl/json-schema/dhl-letter-status-schema.json",
  "title": "LetterStatus",
  "description": "Letter-Status - Liefert den aktuellen Status einer Sendung",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/dhl-deutsche-post-hybrid-mail-shipments-e-post-post-parcel-germany-openapi.json#/components/schemas/LetterStatus",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "letterID",
    "fileName",
    "statusID"
  ],
  "properties": {
    "letterID": {
      "type": "integer",
      "description": "Eindeutige Sendungs-ID(z.B. '43556780')",
      "format": "int64"
    },
    "fileName": {
      "type": "string",
      "description": "Eindeutiger Dateiname der eingelieferten Sendung, welcher von der Quell-Software mitgeliefert wurde. ",
      "maxLength": 200,
      "minLength": 1
    },
    "statusID": {
      "type": "integer",
      "description": "Ident zum aktuellen Verarbeitungsstatus der Sendung:\n            \n            1 - Annahme der Sendung\n                Die Sendung wurde erfolreich übermittelt und es wurden keine Schema und Inhalts-Verletzungen im JSON festgestellt.\n                Status-Platzierung: Bei erfolgreichem Upload der Sendung\n            \n            2 - Verarbeitung der Sendung  \n                 Die PDF wurde auf EPost-Konformität geprüft und ist für den Versand an das Druckzentrum freigegeben. \n                 Hinweis: Trotz bestmöglicher Prüfungen können technische Fehler in dem jeweiligen PDF Dokument zu \n                 einem Abbruch im Druckzentrum führen. Hierdurch wird nach dem Status 3 zeitnah der Status 99 \n                 zusammen mit den Fehlerinformationen signalisiert.\n                 Status-Platzierung: Einige Minuten nach Annahme der Sendung\n            \n            3 - Einlieferung in Druckzentrum\n                Die Sendung wurde an das Druckzentrum zur Produktion übertragen.\n                Hinweis: Sollten technische Fehler in dem jeweiligen PDF Dokument zu einem Abbruch im Druckzentrum führen, \n                wird dies zeitnah über den Status 99 zusammen mit den Fehlerinformationen signalisiert und der Status 4 wird nicht erreicht.\n                Status-Platzierung: Innerhalb der nächsten Stunden nach Verarbeitung der Sendung\n            \n            4 - Verarbeitung in Druckzentrum \n                Die Sendung wurde als \"versendet\" vom Druckzentrum an die API zurückgemeldet.\n                Status-Platzierung: 1-2 Werktage nach Einlieferung in das Druckzentrum\n            \n            \n            99 - Verarbeitungsfehler: Siehe errorList\n            ",
      "format": "int32"
    },
    "statusDetails": {
      "type": [
        "string",
        "null"
      ],
      "description": "Details zum aktuellen Verarbeitungsstatus der Sendung (z.B. Einlieferung in Druckzentrum)"
    },
    "createdDate": {
      "type": "string",
      "description": "Zeitpunkt der Sendungsannahme",
      "format": "date-time"
    },
    "processedDate": {
      "type": [
        "string",
        "null"
      ],
      "description": "Verarbeitungs-Zeitpunkt in docuguide",
      "format": "date-time"
    },
    "printUploadDate": {
      "type": [
        "string",
        "null"
      ],
      "description": "Einlieferungs-Zeitpunkt in das Druckzentrum",
      "format": "date-time"
    },
    "printFeedbackDate": {
      "type": [
        "string",
        "null"
      ],
      "description": "Verarbeitungs-Rückmeldung des Druckzentrums",
      "format": "date-time"
    },
    "testFlag": {
      "type": "boolean",
      "description": "Test-Kennzeichen - bei true wird die Sendung nur zur Prüfung verarbeitet. Es erfolgt kein Briefversand"
    },
    "testEMail": {
      "type": [
        "string",
        "null"
      ],
      "description": "Test-Emailadresse - An diese Email-Adresse wird bei aktiviertem Test-Flag die Test-Sendung als Anhang verschickt "
    },
    "testShowRestrictedArea": {
      "type": "boolean",
      "description": "Test-Sperrflächenmodus - Über dieses Flag wird das per email zurückgesendete pdf-Dokument mit einer Schablone überlagert, damit Sperrflächenverletzungen schneller erkannt werden."
    },
    "registeredLetter": {
      "type": [
        "string",
        "null"
      ],
      "description": "Nationales Einschreiben-Kennzeichen - Mögliche Optionen: 'Einwurf Einschreiben', 'Einschreiben', 'Einschreiben eigenhändig', 'Einschreiben Rückschein', 'Einschreiben eigenhändig Rückschein'"
    },
    "registeredLetterID": {
      "type": [
        "string",
        "null"
      ],
      "description": "Einschreibennummer, wenn die Sendung als Einschreiben deklariert wurde. Diese Nummer wird nach der Übertragung in das Druckzentrum (Status 3) plaziert."
    },
    "batchID": {
      "type": "integer",
      "description": "Kennung einer Stapelverarbeitung (z.b. 15342)",
      "format": "int32"
    },
    "coverLetter": {
      "type": "boolean",
      "description": "true -> Deckblatt vorhanden"
    },
    "noOfPages": {
      "type": "integer",
      "description": "Seitenanzahl der Sendung",
      "format": "int32"
    },
    "subVendorID": {
      "type": [
        "string",
        "null"
      ],
      "description": "Partnerverwaltete Kunden-Kennung, sofern vorhanden"
    },
    "custom1": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von Sendungsinformationen (z.B. RE345232)"
    },
    "custom2": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von Sendungsinformationen"
    },
    "custom3": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von Sendungsinformationen"
    },
    "custom4": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von Sendungsinformationen"
    },
    "custom5": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von Sendungsinformationen"
    },
    "zipCode": {
      "type": [
        "string",
        "null"
      ],
      "description": "Empfänger Postleitzahl"
    },
    "city": {
      "type": [
        "string",
        "null"
      ],
      "description": "Empfänger Stadt"
    },
    "country": {
      "type": [
        "string",
        "null"
      ],
      "description": "Empfänger Land (Kann bei Inlandsendungen leer sein)"
    },
    "isColor": {
      "type": "boolean",
      "description": "Option Farbe oder S/W"
    },
    "isDuplex": {
      "type": "boolean",
      "description": "Option für doppelseitigen Druck"
    },
    "registeredLetterStatus": {
      "type": [
        "string",
        "null"
      ],
      "description": "Aktuellste Statusmeldung zur angegebenen Einschreibennummer."
    },
    "registeredLetterStatusDate": {
      "type": [
        "string",
        "null"
      ],
      "description": "Tag der aktuellsten Statusmeldung zur angegebenen Einschreibennummer.",
      "format": "date-time"
    },
    "vendorSystemInformation": {
      "type": [
        "string",
        "null"
      ],
      "description": "Benutzerdefiniertes Feld zur Mitgabe von systemspezifischen Kennungen und Informationen betreffend der vom Versender verwendeten Partner Software",
      "maxLength": 150,
      "minLength": 0
    },
    "costCenter": {
      "type": [
        "string",
        "null"
      ],
      "description": "Kostenstelle mit einer möglichen Kombination der Zeichen 0-9, a-z, A-Z(keine Umlaute oder andere Sonderzeichen), auf welcher die Kosten bei der Abrechnung gruppiert werden",
      "maxLength": 8,
      "minLength": 0
    },
    "frankierID": {
      "type": [
        "string",
        "null"
      ],
      "description": "Eindeutige FrankierID des Schreibens.Dieses Datum wird nach der erfolgreichen Verarbeitung im Druckzentrum (Status 4) plaziert, i.d.R.wenn das Schreiben im Zielgebiet eingetroffen ist.\n            \n            Hinweis: Erst mit dem 12.04.2023 stehen diese Produktivdaten bereit, vorher werden lediglich Beispiel- bzw. Leerwerte bereitgestellt. \n            "
    },
    "destinationAreaStatus": {
      "type": [
        "string",
        "null"
      ],
      "description": "Aktuelle Statusmeldung des Schreibenseingangs im Zielgebiet.\n            \n            Hinweis: Erst mit dem 12.04.2023 stehen diese Produktivdaten bereit, vorher werden lediglich Beispiel- bzw. Leerwerte bereitgestellt. \n            "
    },
    "destinationAreaStatusDate": {
      "type": [
        "string",
        "null"
      ],
      "description": "Tag der aktuellsten Statusmeldung zum Zielgebiet.\n            \n            Hinweis: Erst mit dem 12.04.2023 stehen diese Produktivdaten bereit, vorher werden lediglich Beispiel- bzw. Leerwerte bereitgestellt. \n            ",
      "format": "date-time"
    },
    "errorList": {
      "type": [
        "array",
        "null"
      ],
      "description": "Liste von Error Objekten - Liefert Details zur Fehlern, Warnungen und Informationen",
      "items": {
        "$ref": "#/$defs/Error"
      }
    },
    "plugInFeedbackList": {
      "type": [
        "array",
        "null"
      ],
      "description": "Liste von PlugInFeedback Objekten - Liefert spezifische Informationen zu angewandten PlugIns",
      "items": {
        "$ref": "#/$defs/PlugInFeedback"
      }
    }
  },
  "$defs": {
    "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"
        }
      }
    },
    "PlugInFeedback": {
      "type": "object",
      "description": "PlugInFeedback-Objekt zur Rückmeldung von funktionsspezifischen Informationen über den LetterStatus",
      "additionalProperties": false,
      "required": [
        "plugInName"
      ],
      "properties": {
        "plugInName": {
          "type": "string",
          "description": "Namenskennung des PlugIn",
          "maxLength": 200,
          "minLength": 0
        },
        "plugInFeedbackModel": {
          "description": "Mit Daten angereichertes PlugIn-Model im JSON Format",
          "nullable": true
        }
      }
    }
  }
}