REST Image API Migrationsleitfaden

Emburse Enterprise wird die veralteten SOAP-basierten APIs für Ausgaben und Rechnungsbilder 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 enthält 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-Umgebungen (UAT) verwenden.

Wenn Ihr Unternehmen noch keine REST-APIs verwendet, kann ein Administrator die folgenden Maßnahmen ergreifen, 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 Rechnungs-API: Eine Person für das Sicherheitsnetz der Rechnungsweiterleitung bestimmen

Kunden, die zur Invoice REST API wechseln, sollten überprüfen, ob ihnen eine Person für das Invoice Routing Safety Net 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 Rechnungs-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
Abrufen von Bildern/PDFs method=getInvoiceImages GET /Rechnungen/Bilder/PDFs
Art des Inhalts Mehrteilige/Formulardaten Anwendung/JSON
Sicherheit Cookie-basierte Sitzung + Formular-Anmeldedaten Header-basierte, zustandslose API-Authentifizierung

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

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 Bericht beigefügten Bilder der Quittungen.
getPDFReport Wenn wahr, wird die ursprüngliche PDF-Datei zuerst abgerufen, falls verfügbar.
getPDFReportWithNotes Wenn wahr, enthält das Original-PDF Anmerkungen zur Genehmigung.
imageFirst Wenn wahr, werden Bilder vor allen PDFs 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-Bericht der Rechnung
getImage Wenn wahr, enthält die Datei angehängte Bilder
imageFirst Wenn wahr, wird das Bild vor dem Bericht zurückgegeben

Legacy-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 Berichts-ID oder Rechnungs-ID.

Bei korrekter Authentifizierung gibt die API Folgendes zurück:

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

Referenz-Dokumentation

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

War dieser Beitrag hilfreich?