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 erstellenDie 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:
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 > Zugangsdaten > 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| Version | Datum | Download als PDF | |
|---|---|---|---|
| 2.0 | 15.04.2024 | LXP API Dokumentation Deutsch / English |
Download |
Content-Type: application/json
Authentifizierung erfolgt mit Benutzernamen und API-Key
Maximale Dateigröße darf 50 MB je PDF / Request nicht überschreiten
Die Authentifizierung erfolgt durch einen JSON-Request mit Benutzernamen und API-Key, dieser kann im Kundenbereich unter Mein Konto > Zugangsdaten > LXP API generiert werden.
Das “auth”-Objekt muss bei jedem Request mit übertragen werden.
Um die API im Testmodus zu testen muss der Wert “test” im Feld “mode” gesetzt werden (“mode”: “test”).
Im Testmodus übertragene Aufträge gehen nicht in Verarbeitung, sondern werden in der Postbox abgelegt. Dort können Aufträge nachträglich geprüft, gelöscht oder auch versendet werden. Aufträge, die in der Postbox liegen gelassen werden, werden nach 7 Tagen automatisch gelöscht.
Bei einem produktiven Einsatz muss der Wert “live” im Feld “mode” gesetzt sein (“mode”: “live”). Im Livemodus erfolgt die Übertragung der Sendungen direkt und nicht über die Postbox.
"auth": {
"username": "(string)",
"apikey": "(string)",
// If the access mode is set to "test", the transmitted letters are
// not processed but are stored in the "Postbox"
"mode": "(string)" // test, live
} {
"message": "Unauthorized."
}curl -X GET "https://api.letterxpress.de/v2/balance" \
-H "Content-Type: application/json" \
-d '{
"auth": {
"username": "(string)",
"apikey": "(string",
"mode": "(string)"
}
}'Das Letter-Objekt bildet den Grund-Baustein für die Übermittlung von Briefen über die API Schnittstelle. Viele der Felder sind dabei optional und müssen nicht ausgefüllt und mitgeschickt werden.
"letter": {
"base64_file": "(string)",
"base64_file_checksum": "(string)", // md5 from base64 string
"specification": {
"color": "(string)", // 1 - black/white, 4 - color
"mode": "(string)", // simplex, duplex
"shipping": "(string)", // national, international, auto
"c4": (number) // 0, 1 - optional, for C4 envelope under 9 sheets
},
// optional
// A file name can also be transferred with the request.
// When retrieving jobs via the API, the file name is also returned.
"filename_original": "(string)", // i.e. Rechnung-123456.pdf
// optional
// Important! Registered mail can only be sent nationally.
// r1 - Einschreiben Einwurf
// r2 - Einschreiben
// r3 - Einschreiben eigenhändig
"registered": "(string)", // r1, r2, r3
// optional
// Important! Dispatch day must be in the future.
"dispatch_date": "(string)", // yyyy-mm-dd Format
// optional
// If the separator type is "string", then a keyword is expected as
// the separator value, which is used to separate the individual letters.
// If the separator type is "number", then a number is expected as the
// separator value. The serial letter is then broken down into individual
// letters after this number of pages.
"serial_letter": {
"pages_separator_type": "(string)", // string, number
"pages_separator_value": "(string)|(number)" // keyword or number of pages
},
// optional
// Multiple attachments can be added to a letter. The order of the
// attachments in the letter depends on the order of the attachments
// in the request.
// The attachments must be created as a PDF in A4 portrait format
// (29.7 x 21.0 cm) and converted to a base64 string.
"base64_attachments": ["(string)", "(string)", ...],
// optional
// The letter background must be created as a PDF in A4 portrait format
// (29.7 x 21.0 cm) and consist of one page. With a serial letter, the
// background is inserted on each individual letter after the selection made.
"backgrounds": {
"base64_background_first_page": "(string)",
"base64_background_other_pages": "(string)"
},
// optional
// The terms and conditions must be created as a PDF in A4 portrait
// format (29.7 x 21.0 cm) and consist of one page. They can either be
// inserted behind the 1st page or behind all pages of a letter.
// Printing is automatically double-sided (duplex). If the terms and conditions
// are only inserted behind the first page, blank pages will be inserted
// behind all subsequent pages. With a serial letter, the terms and
// conditions are added to each individual letter according to the rules
// that have been set.
"terms_and_conditions": {
"base64_terms": "(string)", // PDF format
"terms_on_all_pages": (number) // 0, 1
},
// optional
// The bank transfer form is always attached as the last sheet of a letter.
"bank_form": {
// Payment details are printed on the last sheet.
// This sheet must be blank except for the payment details.
"bank_form_included": (number), // 0, 1
// This information is ignored if "bank_form_included" is set to 1
"payee": "(string)", // max. 27 characters
"iban": "(string)", // max. 34 characters
"bic": "(string)", // max. 11 characters
"amount": "(string)", // max. 12 characters
"purpose_of_payment": "(string)", // max. 27 characters
"purpose_of_payment2": "(string)" // max. 27 characters
},
// optional
// This field can contain any information. The data is stored in the
// database for a certain period of time and can be called up again
// via API or in the customer area.
"notice": "(string)" // max. 255 characters
}"letter": {
"base64_file": "(string)", // file encoded in base64 format
"base64_file_checksum": "(string)", // checksum from base64 encoded string
"specification": {
"color": "(string)", // 1 - black/white, 4 - color
"mode": "(string)", // simplex, duplex
"shipping": "(string)" // national, international, auto
}
}{
"auth": {
"username": "(string)",
"apikey": "(string)",
"mode": "(string)"
}
}{
"status": 200,
"message": "OK",
"data": {
"balance": 54.89,
"currency": "EUR"
}
}Bei einer Preisabfrage ist unter "specification" ein zusätzliches Element "pages" (Seitenzahl) erforderlich.
"letter": {
"specification": {
"pages": (int), // number of pages
"color": "(string)",
"mode": "(string)",
// When asking for a price, we can only use the "national"
// and "international" values for shipping
"shipping": "(string)", // national, international
"c4": "0" // optional
},
// optional
// If the price request is made for registered letter, only "national"
// shipping can be used. Registered mail cannot be sent internationally.
"registered": "r1"
}{
"status": 200,
"message": "OK",
"data": {
"price": 4.99,
"letter": {
"specification": {
"pages": 1,
"color": "4",
"mode": "simplex",
"shipping": "national",
"c4": 0
},
"registered": "r1"
}
}
}Die Reihenfolge der Aufträge richtet sich nach dem Auftrags-Datum (von neu zu alt).
Diesem Endpunkt können bestimmte Parameter mit übergeben werden:
“filter”: queue, hold, done, canceled, draft
| Wert | Beschreibung |
|---|---|
| queue | Aufträge in der Warteschlange |
| hold | angehaltene Aufträge |
| done | verarbeitete Aufträge |
| canceled | stornierte Aufträge |
| draft | Aufträge in der Postbox |
Beispiel
GET: /v2/printjobs?filter=hold
{
"auth": {
"username": "(string)",
"apikey": "(string)",
"mode": "(string)"
}
}{
"status": 200,
"message": "OK",
"data": {
"printjobs": [
{
"id": 6035138,
"shipping": "national",
"mode": "simplex",
"color": "1",
"c4": 0,
"registered": null,
"bank_form": 0,
"notice": null,
"status": "done",
"dispatch_date": null,
"filename_original": null,
"created_at": "2022-07-26 09:38:00",
"updated_at": "2022-07-26 10:00:04",
"items": [
{
"address": "Jim Knopf, Bahnhofstr. 1, 21337 Lüneburg",
"pages": 1,
"amount": 0.67,
"vat": 0.13,
"status": "sent",
"tracking_code": "RC123456789DE" // optional
}
]
},
...
],
"pagination": {
"total": 7,
"count": 7,
"current_page": 1,
"last_page": 1,
"per_page": 15,
"first_page_url": "https://api.letterxpress.de/v2/printjobs?page=1",
"last_page_url": "https://api.letterxpress.de/v2/printjobs?page=1",
"prev_page_url": null,
"next_page_url": null
}
}
}"letter": {
"base64_file": "(string)",
"base64_file_checksum": "(string)",
"specification": {
"color": "(string)",
"mode": "(string)",
"shipping": "(string)"
}
}{
"status": 200,
"message": "OK",
"data": {
"id": 6035143,
"shipping": "national",
"mode": "simplex",
"color": "1",
"c4": 0,
"registered": null,
"bank_form": 0,
"notice": null,
"status": "queue",
"dispatch_date": null,
"filename_original": null,
"created_at": "2022-08-01 13:38:07",
"updated_at": "2022-08-01 13:38:07",
"items": [
{
"address": "Jim Knopf, Bahnhofstr. 1, 21337 Lüneburg",
"pages": 1,
"amount": 0.68,
"vat": 0.13,
"status": "queue"
}
]
}
}{
"auth": {
"username": "(string)",
"apikey": "(string)",
"mode": "(string)"
}
}{
"status": 200,
"message": "OK",
"data": {
"id": 6035138,
"shipping": "national",
"mode": "simplex",
"color": "1",
"c4": 0,
"registered": null,
"bank_form": 0,
"notice": null,
"status": "done",
"dispatch_date": null,
"filename_original": null,
"created_at": "2022-07-26 09:38:00",
"updated_at": "2022-07-26 10:00:04",
"items": [
{
"address": "Jim Knopf, Bahnhofstr. 1, 21337 Lüneburg",
"pages": 1,
"amount": 0.67,
"vat": 0.13,
"status": "sent",
"tracking_code": "RC123456789DE" // optional
}
]
}
}Das PDF Dokument (Datei) kann durch ein Update nicht mehr nachträglich verändert werden. Nur bestimmte Spezifikationen bzw. Versandoptionen können noch angepasst werden.
{
"auth": {
"username": "(string)",
"apikey": "(string)",
"mode": "(string)"
},
"letter": {
"dispatch_date": "2022-09-01", // optional
"registered": "r1", // optional
"notice": "KdNr. xxxxx", // optional
"specification": {
"color": "4",
"mode": "simplex",
"shipping": "national",
"c4": 1 // optional
}
}
}{
"status": 200,
"message": "OK",
"data": {
"id": 6035145,
"shipping": "national",
"mode": "simplex",
"color": "4",
"c4": 0,
"registered": "r1",
"bank_form": 0,
"notice": "KdNr. xxxxx",
"status": "queue",
"dispatch_date": "2022-09-01",
"filename_original": null,
"created_at": "2022-08-01 13:42:12",
"updated_at": "2022-08-01 13:52:04",
"items": [
{
"address": "Jim Knopf, Bahnhofstr. 1, 21337 Lüneburg",
"pages": 1,
"amount": 1.51,
"vat": 0.29,
"status": "queue"
}
]
}
}{
"auth": {
"username": "(string)",
"apikey": "(string)",
"mode": "(string)"
}
}{
"status": 200,
"message": "Print job deleted successfully"
}Es werden alle Transaktionen des Kunden (Aufladungen, Gutscheine, Aufträge etc.) zurückgeliefert.
Diesem Endpunkt können bestimmte Parameter mit übergeben werden:
“filter”: payins, payouts, printjobs
| Wert | Beschreibung |
|---|---|
| payins | Einzahlungen / Gutscheine / Kickbacks … |
| payouts | Auszahlungen |
| printjobs | Aufträge |
Beispiel
GET: /v2/transactions?filter=printjobs
{
"auth": {
"username": "(string)",
"apikey": "(string)",
"mode": "(string)"
}
}{
"status": 200,
"message": "OK",
"data": {
"transactions": [
{
"amount": -1.04,
"currency": "EUR",
"description": "Farbe, Doppelseitig, National, 2 Seiten",
"created_at": "2022-09-21 15:32:45"
},
{
"amount": -1.04,
"currency": "EUR",
"description": "Farbe, Doppelseitig, National, 2 Seiten",
"created_at": "2022-09-21 15:10:49"
},
{
"amount": 1000,
"currency": "EUR",
"description": "Zum Testen",
"created_at": "2022-09-21 13:37:04"
},
{
"amount": -0.81,
"currency": "EUR",
"description": "Schwarzweiß, Einseitig, National, 1 Seite",
"created_at": "2022-09-21 11:45:28"
},
{
"amount": -0.81,
"currency": "EUR",
"description": "Schwarzweiß, Einseitig, National, 1 Seite",
"created_at": "2022-09-21 11:45:28"
},
...
],
"pagination": {
"total": 62,
"count": 15,
"current_page": 1,
"last_page": 5,
"per_page": 15,
"first_page_url": "https://api.letterxpress.de/v2/transactions?page=1",
"last_page_url": "https://api.letterxpress.de/v2/transactions?page=5",
"prev_page_url": null,
"next_page_url": "https://api.letterxpress.de/v2/transactions?page=2"
}
}
}Auflistung aller Rechnungen mit Rechnungsbetrag, Steueranteil sowie Rechnungsdatum.
{
"auth": {
"username": "(string)",
"apikey": "(string)",
"mode": "(string)"
}
}{
"status": 200,
"message": "OK",
"data": {
"invoices": [
{
"id": 25402,
"amount": 0.67,
"vat": 0.13,
"invoice_date": "2020-05-31"
},
{
"id": 26472,
"amount": 0.67,
"vat": 0.13,
"invoice_date": "2020-06-30"
},
{
"id": 35254,
"amount": 0,
"vat": 0,
"invoice_date": "2021-01-31"
},
{
"id": 49365,
"amount": 0.67,
"vat": 0.13,
"invoice_date": "2021-10-31"
},
{
"id": 59934,
"amount": 0,
"vat": 0,
"invoice_date": "2022-04-30"
}
],
"pagination": {
"total": 5,
"count": 5,
"current_page": 1,
"last_page": 1,
"per_page": 15,
"first_page_url": "https://api.letterxpress.de/v2/invoices?page=1",
"last_page_url": "https://api.letterxpress.de/v2/invoices?page=1",
"prev_page_url": null,
"next_page_url": null
}
}
}Hiermit kann eine einzelne Rechnung samt der PDF-Daten (im base64-Format) abgerufen werden.
{
"auth": {
"username": "(string)",
"apikey": "(string)",
"mode": "(string)"
}
}{
"status": 200,
"message": "OK",
"data": {
"id": 25402,
"amount": 0.67,
"vat": 0.13,
"invoice_date": "2020-05-31",
"base64_data": "xxxxxxxx"
}
}| Status | Beschreibung |
|---|---|
| 200 | OK |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 405 | Method Not Allowed |
| 500 | Internal Server Error |