REST Image API Migrationsleitfaden

Emburse Enterprise wird die veralteten SOAP-basierten Expense and Invoice Image APIs einstellen. Dieser Leitfaden für den Übergang hilft Kunden bei der Migration zur neuen REST-basierten Image API. Er erläutert Änderungen bei der Authentifizierung, listet die aktualisierten Endpunkte auf und liefert funktionierende Beispiele zum Abrufen von PDF- und Bilddateien über die moderne REST-Schnittstelle.

Ausführliche Informationen zur Sicherheit der REST-API finden Sie in den häufig gestellten Fragen zur Sicherheit bei der Migration zur REST Image API.

Voraussetzungen

Bevor Sie zur REST Image API wechseln, stellen Sie sicher, dass die folgenden Einrichtungsschritte vom Supportteam von Emburse und Ihrem Unternehmen durchgeführt wurden.

1. Erforderliche Einrichtung durch Emburse

  • REST API-Zugriff aktivieren: Emburse muss den REST-Endpunkt für Ihr Unternehmen aktivieren.
  • API-Schlüsselverwaltung aktivieren: In den Zugriffsberechtigungen muss Emburse die Berechtigung zur Verwendung des Bildschirms „API-Schlüsselverwaltung“ erteilen.

2. API-Schlüssel generieren

Wenn Ihr Unternehmen bereits REST-APIs für andere Datenintegrationen verwendet, können Sie diesen Schritt überspringen und Ihre vorhandenen API-Schlüssel sowohl für die Produktions- (PROD) als auch für die Benutzerakzeptanztest(UAT)-Umgebungen verwenden.

Wenn Ihr Unternehmen noch keine REST-APIs verwendet, kann ein Administrator die unten aufgeführten Maßnahmen durchführen, um API-Schlüssel zu generieren.

1. Wählen Sie im Menü Admin-Einstellungen die Option Sicherheit > API-Schlüsselverwaltung.

2. Klicken Sie auf API-Schlüssel generieren. Der generierte API-Schlüssel wird automatisch in die Zwischenablage kopiert. Sobald Sie auf Kopiert geklickt haben, wird das Fenster geschlossen und der Schlüssel ist nicht mehr verfügbar.

Weitere Informationen finden Sie im Verwaltungsbildschirm der API-Schlüsselverwaltung.

3. Nur Invoice API: Eine Person für das Sicherheitsnetz der Rechnungsweiterleitung (Invoice Routing Safety Net) bestimmen

Kunden, die zur Invoice REST API wechseln, sollten überprüfen, ob ihnen eine Person für das Sicherheitsnetz der Rechnungsweiterleitung zugewiesen wurde. 

Klicken Sie im Menü Admin-Einstellungen auf Konfiguration > Kundeneinstellungen > Genehmigungsweiterleitung.

CPA - FindMeFixMe.png

Wenn unter „Person für das Sicherheitsnetz der Rechnungsweiterleitung“ niemand zugewiesen ist, klicken Sie auf Bearbeiten und wählen Sie über das Dropdown-Menü den entsprechenden Benutzer aus. Klicken Sie anschließend auf Speichern.

Die wichtigsten Unterschiede auf einen Blick

Die folgende Tabelle verwendet die Invoice API als Beispiel für die Unterschiede zwischen der alten Image API und der neuen REST-API.

Funktion Veraltete Invoice Image API Neue REST Invoice Image API
Authentifizierung Benutzer-ID und Passwort (Formularfelder: un, pw) API-Schlüssel + Kundencode + Ketten-ID (HTTP-Header)
Kommunikationsstil Mehrteiliges Formular POST RESTful GET mit Abfrageparametern
Basis-URL https://pt.ca1.chromeriver.com/receipts/doit https://service.chromeriver.com/v1/invoice-api
Image/PDF Retrieval method=getInvoiceImages GET /invoices/images/pdf
Art des Inhalts multipart/form-data application/json
Sicherheit Cookie-basierte Sitzung + Formular-Anmeldedaten Header-basierte, zustandslose API-Authentifizierung

Best Practice

Wir empfehlen dringend die Migration weg von allen SOAP-basierten APIs, da sich die Plattform-Roadmap von Emburse in Zukunft auf REST-basierte APIs konzentriert.

Authentifizierung in der neuen REST API

Erforderliche Kopfzeilen

Ersetzen Sie die folgenden Platzhalter durch die Anmeldedaten, die Emburse Enterprise Ihrem Unternehmen zur Verfügung gestellt hat.

x-api-key: [Ihr-API-Schlüssel]

customerCode: [Ihr-Kundencode]

chain-ID: [Ihre-Ketten-ID]

Content-Type: application/json

Beispiel für Ausgaben: Abrufen von Quittungen

Altes SOAP-Beispiel für Ausgaben

curl --location 'https://api.ca1.chromeriver.com/receipts/doit' \

--form 'un="APIDemo"' \

--form 'pw="xxxxx"' \

--form 'method="getReceipts"' \

--form 'invoiceID="050018911471"'

Neues REST-API-Beispiel für Ausgaben

curl --location 'https://service.chromeriver.com/expense-image-api/getReceipts?reportID=050018911471' \

--header 'x-api-key: 1a234b56-7c89-1234-5678-d9e1fghijk23' \

--header 'customerCode: 0XX0' \

--header 'chain-id: APIDemo' \

--header 'Content-Type: application/json'

Optionen für Parameter zur Ausgabenabfrage

Parameter Beschreibung
voucherInvoice Rechnungsnummer des Gutscheins.
Report-ID Die Report-ID ist eine zwölfstellige Nummer, die von Emburse Enterprise erzeugt wird und mit 0100 beginnt. Geben Sie die Nummer ohne Bindestriche ein!
getMileageDetails Wenn wahr, enthält die PDF-Datei Angaben zur Kilometerleistung, einschließlich Karte und Entfernung, falls die Ausgabe mit Maps erstellt wurde.
getImage Wenn wahr, enthält die PDF-Datei die dem Report beigefügten Bilder der Quittungen.
getPDFReport Wenn wahr, wird die ursprüngliche PDF-Datei zuerst abgerufen, falls verfügbar.
getPDFReportWithNotes Wenn wahr, enthält die ursprüngliche PDF-Datei Anmerkungen zur Genehmigung.
imageFirst Wenn wahr, werden Bilder vor allen PDF-Dateien abgerufen.

Beispiel einer Rechnung: Bilder abrufen (PDFs)

Altes SOAP-Beispiel für eine Rechnung

curl --location 'https://api.ca1.chromeriver.com/receipts/doit' \

--form 'un="APIDemo"' \

--form 'pw="xxxxx"' \

--form 'method="getInvoiceImages"' \

--form 'invoiceID="050018911471"'

Neues REST-API-Beispiel für eine Rechnung

curl --location 'https://service.chromeriver.com/v1/invoice-api/invoices/images/pdf?imageFirst=true&invoiceId=050018911471&getPDFReport=true&getImage=true' \

--header 'x-api-key: 1a234b56-7c89-1234-5678-d9e1fghijk23' \

--header 'customerCode: 0XX0' \

--header 'chain-id: APIDemo' \

--header 'Content-Type: application/json'

Optionen für Abfrageparameter für Rechnungsbilder

Parameter Beschreibung
invoiceID Die abzurufende Rechnungs-ID
getPDFReport Wenn wahr, enthält die Datei einen PDF-Report der Rechnung
getImage Wenn wahr, enthält die Datei angehängte Bilder
imageFirst Wenn wahr, wird das Bild vor dem Report zurückgegeben

Alte Methoden auf REST-Endpunkte abbilden

Veraltete SOAP-Methode REST API-Endpunkt
getInvoiceImages GET /v1/invoice-api/invoices/images/pdf
getInvoices /v1/invoice-api/invoices
getLineItemReceipts /expense-image-api/getLineItemReceipts
getLineItemReceiptsWithMileageDetails /expense-image-api/getLineItemReceiptsWithMileageDetails
getLineItemVoucherInvoices /expense-image-api/getLineItemVoucherInvoices
getReceipts /expense-image-api/getReceipts
getReceiptsForXML /expense-image-api/getReceiptsForXML
getReceiptsWithCoverPage /expense-image-api/getReceiptsWithCoverPage
getVoucherInvoices /expense-image-api/getVoucherInvoices
getVoucherInvoicesForXML /expense-image-api/getVoucherInvoicesForXML

Test und Validierung

So testen Sie die REST API:

  • Verwenden Sie Tools wie Postman, curl oder Insomnia.
  • Geben Sie alle erforderlichen Header an, insbesondere x-api-key und customerCode.
  • Überprüfen Sie den Zugriff auf Ausgaben oder Rechnungen anhand bekannter Werte von Report-ID oder Rechnungs-ID.

Bei korrekter Authentifizierung gibt die API Folgendes zurück:

  • PDF-Stream des Ausgaben- oder Rechnungs-Reports
  • Zugehörige Bilder (falls verfügbar)

REST Image API Migration – Häufig gestellte Fragen zur Sicherheit

Warum stellt Emburse die SOAP-basierte Expense Image API ein?

Die SOAP API basiert auf veralteter Infrastruktur, wie etwa:

  • Server, auf denen ein Betriebssystem ausgeführt wird, das das Ende der Lebensdauer überschritten hat
  • Eine Codebasis, die an die inzwischen veraltete Flash-Benutzeroberfläche gebunden ist
  • Ein Protokoll, das nicht mehr mit der REST-First-Strategie von Emburse übereinstimmt

Diese Einschränkungen bergen erhöhte Sicherheits- und Compliance-Risiken und erfordern den Übergang zu einer moderneren und sichereren REST-basierten Lösung.

Ist REST API so sicher wie SOAP?

Ja, REST APIs sind genauso sicher wie SOAP APIs.

Wie werden Daten während der Übertragung mit REST geschützt?

Alle REST-APIs verwenden HTTPS mit TLS 1.2+ für eine sichere Kommunikation und verschlüsseln Daten während der Übertragung, um Abfangen oder Manipulationen zu verhindern.

Wie funktioniert die Authentifizierung in der REST API?

Die REST API verwendet API-Schlüssel zur Authentifizierung.

Wo werden Kundendaten gespeichert und wie werden sie geschützt?

Alle Kundendaten werden in verschlüsselten Datenbanken (AES-256) gespeichert. Wir unterhalten georedundante Backups, automatisierte Notfallwiederherstellung und Echtzeitüberwachung. Der Zugriff auf Daten wird eingeschränkt, protokolliert und regelmäßig geprüft.

Entspricht die REST API den Branchenvorschriften?

Ja. Unsere Compliance entspricht den wichtigsten Compliance-Rahmenwerken, darunter:

  • DSGVO (Datenschutz-Grundverordnung)
  • SOC 2 Typ II
  • PCI-DSS (ggf. für Zahlungsdaten)

Darüber hinaus werden regelmäßig Sicherheitsaudits und Penetrationstests durch Dritte durchgeführt.

Wie schützen Sie sich vor gängigen Schwachstellen?

  • Sichere API-Praktiken
  • TLS-Verschlüsselung
  • Authentifizierung und Autorisierung
  • Protokollierung und Überwachung
  • SQL-Injektion
  • Cross-Site Scripting (XSS)

Wie schützt Emburse meine Daten während der Migration?

Die Daten werden weiterhin durch die gleichen Kontrollen der Enterprise-Klasse geschützt, die bereits vorhanden sind:

  • Der gesamte REST API-Datenverkehr ist gesichert.
  • Keine Änderung der bestehenden Protokolle zur Datenspeicherung oder zum Datenschutz.
  • Bei der Migration werden Kundendaten nicht automatisch offengelegt oder übertragen. Integrationen müssen manuell aktualisiert und validiert werden.

An wen kann ich mich bei Sicherheitsfragen oder Reports wenden?

Bitte wenden Sie sich an Ihren Emburse Enterprise Customer Success Manager.

Weitere Informationen finden Sie in den Dokumenten zu Sicherheit und Compliance im Emburse Trust Center. 

Referenz-Dokumentation

Ausführliche Informationen zu Endpunkten, Eingabeparametern und Antwortstrukturen finden Sie auf den offiziellen Swagger-Seiten:

War dieser Beitrag hilfreich?