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

Versionierung

Version Datum Beschreibung Download als PDF
2.0 14.10.2022 Release der LXP API Version 2.0 LXP API Dokumentation
Deutsch / English
Download


Technische Details

Content-Type: application/json
Authentifizierung erfolgt mit Benutzernamen und API-Key
Maximale Dateigröße darf 50 MB je PDF / Request nicht überschreiten


Authentifizierung

Die Authentifizierung erfolgt durch einen JSON-Request mit Benutzernamen und API-Key, dieser kann im Kundenbereich unter Mein Konto > Zugangsdaten > LXP API generiert werden.

Request

"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
} 

Response bei fehlerhafter Authentifizierung

{
    "message": "Unauthorized."
}

Beispiel

curl -X GET "https://api.letterxpress.de/v2/balance" \
-H "Content-Type: application/json" \
-d '{
    "auth": {
        "username": "(string)",
        "apikey": "(string",
        "mode": "(string)"
    }
}'


Letter-Objekt

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
}

Die minimale Konfiguration eines Letter-Objekt sieht so aus:

"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
    }
}


Endpoints

Request
{
    "auth": {
      "username": "(string)",
      "apikey": "(string)",
      "mode": "(string)"
    }
}
Response
{
    "status": 200,
    "message": "OK",
    "data": {
        "balance": 54.89,
        "currency": "EUR"
    }
}

Bei einer Preisabfrage ist unter "specification" ein zusätzliches Element "pages" (Seitenzahl) erforderlich.

Request
"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"
}
Response
{
    "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).

Request
{
    "auth": {
        "username": "(string)",
        "apikey": "(string)",
        "mode": "(string)"
    }
}
Response
{
    "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"
                    }
                ]
            },
            ...
        ],
        "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
        }
    }
}
Request
"letter": {
    "base64_file": "(string)",
    "base64_file_checksum": "(string)",
    "specification": {
        "color": "(string)",
        "mode": "(string)",
        "shipping": "(string)"
    }
}
Response
{
    "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"
            }
        ]
    }
}
Request
{
    "auth": {
        "username": "(string)",
        "apikey": "(string)",
        "mode": "(string)"
    }
}
Response
{
    "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"
            }
        ]
    }
}

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.

Request
{
    "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
        }
    }
}
Response
{
    "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"
            }
        ]
    }
}
Request
{
    "auth": {
        "username": "(string)",
        "apikey": "(string)",
        "mode": "(string)"
    }
}
Response
{
    "status": 200,
    "message": "Print job deleted successfully"
}

Es werden alle Transaktionen des Kunden (Aufladungen, Gutscheine, Aufträge etc.) zurückgeliefert.

Request
{
    "auth": {
        "username": "(string)",
        "apikey": "(string)",
        "mode": "(string)"
    }
}
Response
{
    "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.

Request
{
    "auth": {
        "username": "(string)",
        "apikey": "(string)",
        "mode": "(string)"
    }
}
Response
{
    "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.

Request
{
    "auth": {
        "username": "(string)",
        "apikey": "(string)",
        "mode": "(string)"
    }
}
Response
{
    "status": 200,
    "message": "OK",
    "data": {
        "id": 25402,
        "amount": 0.67,
        "vat": 0.13,
        "invoice_date": "2020-05-31",
        "base64_data": "xxxxxxxx"
    }
}


Statusmeldungen

Status Beschreibung
200 OK
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
500 Internal Server Error