LXP API

Die REST-Schnittstelle bietet fast unbegrenzte Möglichkeiten über eigene Softwaresysteme, Webanwendungen oder sonstige Programme (z. B. Warenwirtschafts-, ERP- oder CRM-Systeme) die eigenen Prozesse vollumfänglich zu automatisieren und PDF-Briefe an LXP zu übermitteln.

Dokumentation   API-Key erstellen

Briefe übertragen mit unserer REST-Schnittstelle (API)

Die LXP API ist unsere eigene REST-Schnittstelle (Programmierschnittstelle = Application Programmierung Interface - API) und die ideale Lösung für das Outsourcen Ihres Postausgangs. Diese Schnittstelle zur Anwendungsprogrammierung kann direkt von der in Ihrem Unternehmen vorhandenen Software zur Anbindung an das LetterXpress-System genutzt werden. Versand von Sendungen (Rechnungen, Mahnungen, Serienbriefe, Mailings, Tagespost und vieles mehr) mit bis zu 50 MB sind möglich. REST-Schnittstellen (APIs) dienen dem Austausch und der Weiterverarbeitung von Daten zwischen verschiedenen Programmen oder Anbietern. Sind Ihre Prozesse weitestgehend automatisiert, so bietet sich die Anbindung an die Schnittstelle ideal an. Der Initialaufwand der API-Anbindung ist unkompliziert und schnell zu realisieren. Um Ihrer IT die Nutzung unserer API so einfach wie möglich zu machen, bieten wir darüber hinaus eine umfassende Dokumentation an:

Dokumentation zur REST-Schnittstelle (API)

Einleitung

Mit Hilfe unserer API können Softwaresysteme, Webanwendungen oder sonstige Programme direkt, professionell und vollautomatisiert an LetterXpress angebunden werden.

Unsere REST-Schnittstelle (API) erwartet die Request-Daten in JSON (JavaScript Object Notation). Das heißt, die Anfrage an unseren Server muss im Header den Content-Type: application/json mit übertragen. Die Authentifizierung erfolgt neben dem Benutzernamen mit einem persönlichen API-Key, welcher im Kundenbereich unter Mein Konto > LXP API generiert werden kann.

Somit können PDF-Briefsendungen, die z. B. in der eigenen Anwendung erstellt werden, direkt über einen einfachen Request an LetterXpress übermittelt werden.

API-Key erstellen
Versionierung
Version Datum Beschreibung
1.0 15.03.2018 Release der ersten Version der LetterXpress API v1

PHP-Integration

Um möglichst einen schnellen und einfachen Einstieg zu ermöglichen, stellen wir ein Beispiel für die Integration in PHP bereit (PHP-Klasse mit Beispiel wie die Klasse genutzt werden kann). Damit der Request erfolgen kann ist es wichtig, dass innerhalb der php.ini die PHP-Extension cURL aktiviert ist.

PHP-Beispiel herunterladen (letterxpress-api-1.0.zip)

Request-URLs

Die Requests können über folgende URLs erfolgen:

HTTP Method URL & Kurzbeschreibung
GET / POST https://api.letterxpress.de/v1/getBalance
Guthaben Abfrage
GET / POST https://api.letterxpress.de/v1/getPrice
Peis Abfrage
GET / POST https://api.letterxpress.de/v1/getJobs/queue
Alle Jobs in Warteschlange
GET / POST https://api.letterxpress.de/v1/getJobs/sent
Alle Postausgelieferten Jobs
GET / POST https://api.letterxpress.de/v1/getJobs/deleted
Alle gelöschten Jobs der letzten 60 Tage
GET / POST https://api.letterxpress.de/v1/getJobs/queue/(int)days
Alle Jobs in Warteschlange der letzten x Tage
GET / POST https://api.letterxpress.de/v1/getJobs/sent/(int)days
Alle Postausgelieferten Jobs der letzten x Tage
GET / POST https://api.letterxpress.de/v1/getJobs/deleted/(int)days
Alle gelöschten Jobs der letzten x Tage
GET / POST https://api.letterxpress.de/v1/getJobs/hold
Alle Jobs die mangels Guthaben gesperrt sind
GET / POST https://api.letterxpress.de/v1/getJobs/timer
Alle Jobs mit Versanddatum in der Zukunft
GET / POST https://api.letterxpress.de/v1/getJob/(int)id
Ein bestimmter Job anhand der id
POST https://api.letterxpress.de/v1/setJob
Legt einen neuen Job an und überträgt das PDF-Dokument
PUT https://api.letterxpress.de/v1/updateJob/(int)id
Bearbeitet einen bestimmten Job anhand der id
DELETE https://api.letterxpress.de/v1/deleteJob/(int)id
Löscht einen bestimmten Job anhand der id, solange dieser nicht versand ist
GET / POST https://api.letterxpress.de/v1/listInvoices
Listet vorhandene Rechnungseinträge auf
GET / POST https://api.letterxpress.de/v1/getInvoice
Holt die letzte verfügbare Rechnung - PDF encode stream
GET / POST https://api.letterxpress.de/v1/getInvoice/(int)id
Holt eine bestimmte Rechnung anhand der id - PDF encode stream

JSON (Request)

Jeder Request benötigt das auth-Object mit den Elementen "username" sowie "apikey" zur Authentifizierung.


  "auth": {
    "username": "(string)",
    "apikey": "(string)"
  }
                             

Um ein PDF-Dokument zu übertragen muss das letter-Object mit übermittelt werden, welches weitere Elemente benötigt. Beim einem Update kann auf die Elemente "base64_file" sowie "base64_checksum" verzichtet werden, da das Dokument nachträglich nicht mehr geändert werden kann.


  "letter": {
    "base64_file":      "(string)", // Optional bei einem Update-Request
    "base64_checksum":  "(string)", // Optional bei einem Update-Request
    "address":          "(string)", // Optional
    "dispatchdate":     "(string)", // Optional
    "specification": {
      "color":"(int)",
      "mode":"(string)",
      "ship":"(string)",
      "c4":"(string)" // Optional für C4 Versandtasche unter 9 Blatt
    }
  }

Bei einer Preisabfrage sieht das letter-Object nahezu identisch aus, unter "specification" ist jedoch ein zusätzliches Element "page" erforderlich.


  "letter": {
    "specification": {
      "page":"(int)", // Erforderlich bei einer Preisanfrage
      "color":"(int)",
      "mode":"(string)",
      "ship":"(string)",
      "c4":"(string)" // Optional für C4 Versandtasche unter 9 Blatt
    }
  }

JSON (Response)

Der Response enthält zusätzlich noch weitere Informationen, z. B. die Auftragsnummer, sowie die Kosten des Auftrags (brutto). Im notice-Object werden ggf. weitere Hinweise zurückgegeben, der Auftrag wurde in dem Fall aber trotzdem erfolgreich übermittelt. Weitere Informationen befinden sich weiter unten.


  "notice": {
    "balance":"empty"
  },

  "letter": {
    "price":0.90,
    "job_id":"99999",
    "status":"hold",
    "specification": {
      "page":1,
      "color":"4",
      "mode":"simplex",
      "ship":"national"
    }
  },

  "status":200,
  "message":"OK"

Status im notice-Object
Element Value Beschreibung
balance empty Das aktuelle Guthaben reicht nicht aus, um den Auftrag zu verarbeiten. Der Auftrag wurde trotzdem übermittelt und wird verarbeitet sobald das Guthaben aufgeladen wurde.
timer not set Das aktuelle Guthaben reicht nicht aus, um den Auftrag zu verarbeiten. Der Auftrag wurde trotzdem übermittelt und wird verarbeitet sobald das Guthaben aufgeladen wurde. Jedoch konnte bei dieser Sendung das "dispatchdate" nicht berücksichtigt werden.
Status im letter-Object
Status Beschreibung
queue Auftrag wartet auf Produktion bzw. in der Warteschlange für den Versand (die Produktion erfolgt werktags von Mo. - Fr. um 16.00 Uhr, außer an gesetzlichen Feiertagen)
hold Auftrag wurde angehalten, da zum Zeitpunkt der Übermittlung das Guthaben nicht ausreichend gedeckt war. Sobald das Guthaben aufgeladen wird wechselt der Status automatisch zu "queue".
timer Auftrag wird an einem definierten Datum produziert. Das jeweilige Datum für diesen Auftrag wurde über die API oder im Kundenbereich unter Tracking definiert.
sent Auftrag wurde verarbeitet, produziert und anschließend der Deutschen Post übergeben.
deleted Auftrag wurde gelöscht.
Status im Response
Status Beschreibung
200 OK
400 Anfrage fehlerhaft
401 Anmeldung fehlgeschlagen
403 Verboten
404 Keine passenden Daten gefunden
405 Ungültiger Aufruf
500 Serverfehler - Anfrage fehlgeschlagen

Elemente & Datentypen

Element Datentyp Wert(e)
auth object username, apikey
username string beliebig
apikey string beliebig
letter object base64_file, base64_checksum, address, dispatchdate, specification
base64_file string PDF base64-encode
base64_checksum string MD5 aus base64_file
address string beliebig, read (es wird versucht innerhalb des Fensterbereichs die Adresse automatisch auszulesen)
dispatchdate string dd.mm.yyyy
specification object page, color, mode, ship
page int 0-9
color int 1, 4
mode string simplex, duplex
ship string national, international
c4 string y, n
(Versand optional in C4 Versandtasche, automatisch ab 9 Blatt)
notice object balance, timer
balance string empty
timer string not set

Hinweise

Die übermittelte Adresse (address) innerhalb des letter-Objects wird nicht verwendet, um die Briefsendung an genau diese Adresse zuzustellen. Die dort übermittelte Adresse ist z. B. nützlich, um später im Tracking im Kundenbereich nach der Sendung zu suchen. Es wäre also auch möglich statt der Adresse andere Werte zu übermitteln, die später die Suche einer Sendung im Tracking erleichtern würde. Entscheidend für die Zustellung ist letztendlich einzig und allein die Adresse, die sich innerhalb der PDF im Fensterbereich befindet.

Aktuell können nur Einzelsendungen per API an uns übertragen werden (keine Serienbriefe als einzelner Request), diese dürfen die maximale Dateigröße von 50 MB nicht überschreiten.