REST API
Inhaltsverzeichnis
Über unsere API
liftbase verfügt über eine leistungsstarke und einfache REST API, welche verwendet werden kann, um liftbase mit weiteren Systemen zu integrieren. Hier finden Sie alle notwendigen Informationen, die Sie zum Entwickeln benötigen.
Alle Endpunkte unserer API erfordern Authentifizierung. Das bedeutet, dass nur mit einem gültigen liftbase-Zugang Daten abgefragt werden können. Dazu wird ein Authentifizierungstoken benötigt. Im Folgenden finden Sie eine Übersicht über die benötigten Tokens.
Übersicht der API-Endpunkte
In unserer API kommen zwei wesentliche API-Endpunkte vor. Bei jeder Abfrage ist genau auf die API-URL zu achten, da die API-Aufrufe sonst fehlschlagen.
API-Endpunkt | Kennzeichnung in Dokumentation | Beschreibung |
https://app.liftbase.de/api/** |
@/api |
API-Endpunkt für Authentifizierung und PDF-Erzeugung (Core-Backend). |
https://app.liftbase.de/api/rest/** |
@/api/rest |
Daten-API-Endpunkt für alle Datenabfragen (Data-Backend). |
Übersicht der API-Tokens
Token Name | Token Art | Token Gültigkeit | Beschreibung |
API Token | JWT-Refresh-Token | Unbeschränkt, wie ausgewählt | Permanent gültiges Token, welches genutzt wird, um Access-Token anzufordern, welches für die eigentliche Datenabfrage benötigt wird. |
Access Token | JWT-Access-Token | 15 Minuten | Kurzlebiges Token, welches direkt für Datenabfragen genutzt werden kann. |
API-Token erhalten
Wählen Sie anschließend aus, wie lange das Token gültig sein soll. Bei den meisten API-Integrationen sollte hier ein langer Zeitraum ausgewählt werden. Wir empfehlen allerdings, das Token regelmäßig zu tauschen, um die Sicherheit der Integration zu erhöhen.
Kopieren Sie das Token nun in die Konfiguration Ihres Drittanbieter-Tools. Bitte beachten Sie, dass das Token nur ein einziges Mal angezeigt wird. Sie können jederzeit ein neues Token erzeugen.
API-Token sperren
Um ein API-Token zu sperren, muss der komplette liftbase-User gesperrt werden. Weitere Informationen dazu finden Sie hier.
Access Token erhalten
Um Daten über die API anzufragen, ist ein Access Token notwendig. Ein API-Token kann einfach gegen ein Access Token getauscht werden. Der Vorteil dieser 2-Token-Lösung liegt darin, dass das API-Token gesperrt werden kann. Somit können keine neuen Access Token mehr erzeugt werden.
Mit der folgenden Abfrage lässt sich ein Access Token erhalten:
# REQUEST @/api
POST https://app.liftbase.de/api/auth/access-token
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTMyOTk3NDAsIm5iZiI6MTY1MzI5OTc0MC[...] <<-- API-Token
# RESPONSE
{
"jwt": "eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTMyOTk4MTksIm5iZiI[...]" <<-- Access Token
}
Mit diesem Access Token lassen sich nun alle weiteren API-Endpunkte nutzen. Bitte beachten Sie, dass das Access Token spätestens alle 15 Minuten erneuert werden muss, da es ansonsten abläuft.
Wird ein abgelaufenes Access Token verwendet, erhalten Sie einen Fehler HTTP 400 Bad Request:
{
"path": "$",
"error": "Could not verify JWT: JWSError JWSInvalidSignature",
"code": "invalid-jwt"
}
Daten über die API abfragen
Mit dem Access Token lassen sich jetzt Daten über die API abfragen. Im Folgenden finden Sie die wichtigsten Endpunkte mit Beispielen.
Bestellungen zu Lieferunternehmen
Um für die Buchhaltung bzw. Rechnungsprüfung alle Bestellanforderungen aufzulisten, bei denen die Freigabe abgeschlossen ist – z. B. um eine Rechnung zuzuordnen – kann die folgende Abfrage genutzt werden:
# REQUEST @/api/rest
GET https://app.liftbase.de/api/rest/supplier/66622/procurements/completed
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTMyOTk3NDAsIm5iZiI6MTY1MzI5OTc0MC[...]
# RESPONSE
{
"procurement": [
{
"bcase_id": 741,
"order_number_formatted": "LB000081",
"name": "Neues Headset für Tobias",
"created_at": "2022-05-18T00:00:00+00:00",
"lb_user": {
"name": "Daniel Huhn",
"email": "daniel.huhn@liftbase.de"
},
"status": "ordered",
"client": {
"id": 12,
"name": "make.digital GmbH"
},
"lines": [
{
"id": 2780,
"name": "Logitech G733 LIGHTSPEED kabelloses Gaming-Headset mit Kopfbügel, LIGHTSYNC RGB, Blue VO!CE Mikrofontechnologie, PRO G Lautsprechern, Ultraleicht, 29-Stunden Akkulaufzeit, 20m Reichweite - Schwarz",
"price_brutto": 97.0921,
"price_netto": 81.59,
"tax": 19.0,
"quantity": 1
},
]
}
]
}
Dabei wird die Externe ID aus der Administration als Kreditorennummer in der URL übergeben (in diesem Beispiel 66622):
Rechnung zu Bestellanforderung zuordnen
Externe Rechnung anmelden
Zunächst muss die externe Rechnung bei liftbase angelegt werden:
Parameter | Bezeichnung | Erklärung |
external_invoice.invoice_date |
Rechnungsdatum | Das Rechnungsdatum des Rechnungsbelegs. |
external_invoice.invoice_number |
Rechnungsnummer | Die Rechnungsnummer des Rechnungsbelegs. |
external_invoice.link |
Beleglink-URL | Eine URL, die Anwender/innen öffnen können, um die Rechnung im System anzuschauen. |
# REQUEST @/api/rest
POST https://app.liftbase.de/api/rest/external-invoice
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTMyOTk3NDAsIm5iZiI6MTY1MzI5OTc0MC[...]
Content-Type: application/json
{
"external_invoice": {
"invoice_date": "2022-05-23T11:05:42+0000",
"invoice_number": "R10003",
"link": "https://example.com/app/invoices/R10003"
}
}
# RESPONSE
{
"result": {
"id": 31
}
}
Externe Rechnung mit Bestellanforderung verknüpfen
Nachdem die Rechnung angelegt wurde, kann sie wie folgt mit der Bestellanforderung verknüpft werden:
Parameter | Bezeichnung | Erklärung |
external_invoice_id |
ID der externen Rechnungsnummer | Die ID der vorherigen Abfrage. |
invoiced_date |
Datum des Rechnungseingangs | Zeitstempel, wann die Rechnung bei Ihnen eingegangen ist (NICHT das Rechnungsdatum). |
order_number |
Bestellnummer | Die eindeutige Bestellnummer. |
external_supplier_id |
Lieferunternehmen-ID | Die eindeutige externe ID des Lieferunternehmens. |
# REQUEST @/api/rest
POST https://app.liftbase.de/api/rest/procurement/mark-as-invoiced
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTMyOTk3NDAsIm5iZiI6MTY1MzI5OTc0MC[...]
Content-Type: application/json
{
"external_invoice_id": 31,
"invoiced_date": "2022-05-23T11:05:42+0000",
"order_number": "LB000081",
"external_supplier_id": "66622"
}
# RESPONSE
{
"update_procurement_line": {
"returning": [
{
"id": 2780
},
{
"id": 2781
}
]
}
}
Bestell-PDFs zur Langzeitarchivierung
Zu exportierende Bestellanforderungen auflisten
Um Bestellanforderungen nach der Übermittlung an das Lieferunternehmen ins Langzeitarchiv zu überführen, kann folgender Endpunkt genutzt werden. Es werden alle Bestellanforderungen aufgelistet, die noch nicht als „Exportiert“ bzw. „Archiviert“ gekennzeichnet wurden:
# REQUEST @/api/rest
GET https://app.liftbase.de/api/rest/procurement/with-lines/ready-for-export
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTMyOTk3NDAsIm5iZiI6MTY1MzI5OTc0MC[...]
# RESPONSE
{
"procurement": [
{
"id": 741,
"order_number_formatted": "LB000081",
"client": {
"number": 12,
"name": "make.digital GmbH",
"currency": "EUR"
},
"lb_user": {
"name": "Daniel Huhn",
"email": "daniel.huhn@liftbase.de"
},
"lines": [
{
"id": 2780,
"name": "Logitech G733 LIGHTSPEED kabelloses Gaming-Headset mit Kopfbügel, LIGHTSYNC RGB, Blue VO!CE Mikrofontechnologie, PRO G Lautsprechern, Ultraleicht, 29-Stunden Akkulaufzeit, 20m Reichweite - Schwarz",
"price_brutto": 97.0921,
"price_netto": 81.59,
"tax": 19.0,
"quantity": 1,
"supplier": {
"id": 10,
"external_id": "",
"name": "Lager PLUS"
}
}
]
}
]
}
Bestell-PDF erzeugen bzw. abfragen
Da eine Bestellanforderung Zeilen von verschiedenen Lieferunternehmen enthalten kann, jedoch eine Bestell-PDF pro Lieferunternehmen erzeugt wird, ist es notwendig, die Bestellanforderungen und Bestellzeilen nach Lieferunternehmen zu gruppieren.
Anschließen kann mit der Bestell-ID + Lieferunternehmen-ID das PDF für die Langzeitarchivierung abgefragt werden:
# REQUEST @/api
GET https://app.liftbase.de/api/procurement/pdf/with-attachments?procurementId=741&supplierId=10
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTMyOTk3NDAsIm5iZiI6MTY1MzI5OTc0MC[...]
# RESPONSE
HTTP/1.1 200 OK
Content-Type: application/octet-stream
[[PDF-Datei]]
Bestellung als exportiert kennzeichnen
Nach dem das PDF sicher gespeichert wurde, kann es über die folgende Abfrage als „Exportiert“ gekennzeichnet werden, sodass es in zukünftigen Abfragen nicht mehr auftaucht. So wird sichergestellt, dass jedes PDF immer mindestens einmal archiviert wurde:
# REQUEST @/api/rest
POST https://app.liftbase.de/api/rest/procurement/mark-as-exported?order_number=LB000014&external_supplier_id=5
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJpYXQiOjE2NTMyOTk3NDAsIm5iZiI6MTY1MzI5OTc0MC[...]
# RESPONSE
{
"update_procurement_line": {
"affected_rows": 1
}
}
Als nächstes erfahren Sie, wie der Ablauf einer Bestellanforderung aussieht.