liftbase - API

REST API

Ü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

Der erste Schritt, um Daten über die API abzufragen, ist, im Administrationsbereich unter „

Personen“ einen liftbase-User anzulegen und für diesen User einen API-Token anzulegen. Alle API-Abfragen und -Aktionen laufen im Kontext dieses Users. Wird eine Schreib-Aktion ausgeführt, wird der entsprechende User als Autor angezeigt. Vergeben Sie daher einen aussagekräftigen Namen für den API-User (bei einer DMS-Integration könnte man den User z. B. „DMS-System“ nennen). Und klicken Sie anschließend auf „API-Token erzeugen“:

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.