REST-Schnittstelle (API)

Einleitung

Mit Hilfe unserer API können ab sofort 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). Die Authentifizierung erfolgt neben dem Benutzernamen mit einem persönlichen API-Key, welcher im Kundenbereich unter Konto > Benutzerdaten ändern > Optionen 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.

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/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/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

Sandbox

Bitte für die Entwicklungsphase unsere Sandbox benutzen, die unter https://sandbox.letterxpress.de/ erreichbar ist. Die Sandbox ist komplett isoliert, so dass alle übermittelten Aufträge nicht produziert werden. Mit dem Gutschein SANDBOX100 können Sie das Guthaben des Sandbox-Benutzers aufladen (100,00 €, bis zu fünf Einlösungen pro Benutzer möglich).

Sandbox-URL
  https://sandbox.letterxpress.de/v1/

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.74,
    "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 14.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 15 MB nicht überschreiten.

 

Jetzt kostenlos anmelden

Melden Sie sich jetzt kostenlos bei LetterXpress an und testen uns als Geschäftskunde mit einem Startguthaben* von 5,00 €.

Anmelden