Briefe übertragen mit unserer 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.

Versionierung

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:

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

Status im letter-Object

Status im Response

Elemente & Datentypen

Hinweise