Die API mit Postman erkunden

Der beste Weg, die SIGN DE API V2 zu erkunden, ist die Verwendung einer Anwendung namens Postman. Eine Alternative ist das Linux/Unix-Befehlszeilentool curl.

Dieser Leitfaden verwendet Postman, um Beispiele für alle Vorgänge bereitzustellen, die zum Einrichten einer TSS mit den zugehörigen Clients und Transaktionen erforderlich sind. Sie können die Details jeder Anfrage und Antwort überprüfen und verschiedene Szenarien einfach testen.

Was ist Postman?

Postman ist eine kostenlose Softwareanwendung, die es einfach macht, APIs zu erkunden.

Eine Postman-Sammlung und eine Postman-Umgebung stellen ein Testsystem bereit, das alle notwendigen Konfigurationen für eine bestimmte API enthält. Laden Sie diese beiden Dateien in Postman, und Sie sind bereit, zu erkunden und zu testen.

📘Testumgebung

Es wird empfohlen (aber nicht zwingend erforderlich), diesen Leitfaden in Verbindung mit dem fiskaly HUB zu verwenden.

Beachten Sie, dass dies eine Test-Umgebung zum Testen und Evaluieren ist. Ihre Persistenz ist nicht garantiert. Alle Daten aus der Testumgebung werden periodisch ohne vorherige Ankündigung gelöscht.

📘Bestehende V1-Kunden

Dies ist eine Demo für die Test-Umgebung, für die Sie neue temporäre Konten erstellen müssen, die nur zum Testen und Evaluieren verwendet werden.

Wenn Sie ein Kunde mit einem V1-Konto sind, sind Ihre Organisationen und API-Schlüssel für V2 weiterhin gültig. Sie müssen in der Produktion nichts ändern!

---

Einrichtung

1. Postman herunterladen

   Laden Sie die kostenlose Version von Postman von postman.com/downloads herunter.

   Es ist für alle drei gängigen Plattformen verfügbar: Linux, macOS und Windows. Alternativ gibt es auch eine Web-Version von Postman.

2. Einen API-Schlüssel erstellen

   Bevor Sie mit Postman beginnen, müssen Sie einen API-Schlüssel und ein Geheimnis über den fiskaly HUB erstellen.

   

3. Ihre personalisierte Umgebung herunterladen

   Gehen Sie zur API V2 Quick Start-Seite und geben Sie Ihren API-Schlüssel und Ihr Geheimnis ein, um Ihre personalisierte Postman-Umgebung zu erhalten.

   

---

Die API V2-Umgebung importieren

Um SIGN DE API V2 mit Postman zu erkunden, müssen Sie zuerst seine Konfigurationsdateien importieren.

1. Postman-Importdialog öffnen

   Starten Sie Postman und wählen Sie im Importdialog Dateien hochladen aus.

   

2. Sammlung und Umgebungsdateien auswählen

   Wählen Sie die Sammlung und die Umgebungsdateien aus, die Sie zuvor heruntergeladen haben.

   

3. Ihren Arbeitsbereich überprüfen

   Sie sollten jetzt 1 Sammlung und 1 Umgebung im Postman-Arbeitsbereich sehen können.

   

4. Umgebung auswählen

   Wählen Sie die SIGN DE API V2-Umgebung aus dem Umgebungs-Dropdown aus.

   

💡Tip

Um sicherzustellen, dass Sie die aktuellste Version der Produktions-API verwenden, laden Sie die neuesten Sammlungs- und Umgebungsdateien von der API V2 Quick Start-Seite herunter.

---

Die Demo ausführen

Die Postman API V2-Sammlung enthält umfassende Beispiele für jede Anfrage, die beim Einrichten einer TSS-Umgebung beteiligt ist, von der ersten Authentifizierung bis hin zu Datenexporten.

Sie können diese Anfragen mit Postmans Collection Runner ausführen.

1. Collection Runner öffnen

   Wählen Sie Sammlungen, dann Standardszenario, und klicken Sie dann auf die Schaltfläche Ausführen.

   

2. Sammlung ausführen

   Postman listet die auszuführenden Anfragen auf. Klicken Sie auf die Schaltfläche SIGN DE API V2 ausführen.

   

3. Ergebnisse überprüfen

   Sie sollten für jede Anfrage einen 200-Statuscode vom Server sehen, was anzeigt, dass die Anfrage erfolgreich war.

   

   Andere mögliche Antworten sind 400 (Problem mit der Anfrage) oder 500 (Problem mit dem Server).

Die Demo zeigt die Reihenfolge der Anfragen für:

• Erste Admin-Authentifizierung
• Erstellen und Verwalten einer TSS
• Erstellen und Verwalten von Clients
• Transaktionen
• Exportieren von Daten aus der TSS

Die folgenden Abschnitte untersuchen diese Anfragen detaillierter.

---

Variablen verstehen

Postman speichert wichtige API-Werte in Variablen. Variablen können in verschiedenen Anfragen wiederverwendet werden. Wenn Sie den Wert einer Variablen ändern, wird der neue Wert in allen diesen Anfragen verwendet.

Wenn Sie die SIGN DE API V2-Umgebung zum ersten Mal importieren, enthält sie nur drei Variablen:

Variable	Beschreibung
baseUrl	Die API-Basis-URL
api_key	Ihr API-Schlüssel
api_secret	Ihr API-Geheimnis

Sie können sehen, wie eine Variable in einer Authentifizierungsanfrage verwendet wird. Postman ersetzt die Variable {{baseUrl}} durch den in der SIGN DE API V2-Umgebung gespeicherten Wert:

https://kassensichv-middleware.fiskaly.com/api/v2

Eine Authentifizierungsanfrage wird also tatsächlich an folgende Adresse gepostet:

https://kassensichv-middleware.fiskaly.com/api/v2/auth

---

Anfragen stellen

Stellen wir eine Authentifizierungsanfrage. Es ist eine POST-Anfrage, die an {{baseUrl}}/auth gesendet wird.

Der Anfragekörper verwendet Umgebungsvariablen:

{
  "api_key": "{{api_key}}",
  "api_secret": "{{api_secret}}"
}

Postman erhält die folgende Antwort vom Server (grünes 200 OK zeigt Erfolg an):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "access_token_claims": {
    "env": "TEST",
    "organization_id": "0bd118a1-eed7-4065-9e6b-710ab3aaf445"
  },
  "access_token_expires_in": 600,
  "access_token_expires_at": 1626678863,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token_expires_in": 600,
  "refresh_token_expires_at": 1626678863
}

Wir erhalten ein Zugriffstoken und ein Aktualisierungstoken. Postman speichert die neuen Werte in Variablen, die dann in nachfolgenden Anfragen verwendet werden.

📘Note

Das Zugriffstoken läuft in der Testumgebung nach 600 Sekunden ab, wonach die Authentifizierungsanfrage erneut ausgeführt werden muss. In der Produktion sind es etwa 24 Stunden.

Sie können auf ähnliche Weise Header und Body sehen und die Antwort des Servers für alle anderen Anfragen in dieser Sammlung überprüfen.

---

Code-Generierung

Postman kann den relevanten Code zum Stellen von Anfragen in einer Vielzahl von Programmiersprachen generieren.

In diesem Beispiel generieren wir die entsprechende Authentifizierungsanfrage für curl.

1. Authentifizierungsanfrage ausführen

   Führen Sie die Authentifizierungsanfrage aus der Sammlung erneut aus.

   

2. Code-Snippet-Seitenleiste öffnen

   Klicken Sie auf das Code-Symbol in der rechten Seitenleiste.

   

3. Ihre Sprache auswählen

   Die Code-Snippet-Seitenleiste öffnet sich. curl sollte standardmäßig ausgewählt sein; falls nicht, verwenden Sie das Dropdown-Menü, um es auszuwählen.

   

4. Generierten Code kopieren und verwenden

   Sie können nun die curl-Befehle sehen, die dieser Postman-Anfrage entsprechen. Führen Sie sie in einem Terminal aus, um sich zu authentifizieren.

   

💡Tip

Die Code-Generierung ist wertvoll für Bash-Skripte, in denen Sie die Werte der Token in Variablen speichern können. Postman erledigt dies jedoch automatisch, was es zu einem praktischen Tool zum Untersuchen von APIs macht.

---

Querverweise mit dem HUB

TSS- und Client-Verwaltungsanfragen, die von Postman aus gemacht werden, können im fiskaly HUB angezeigt werden.

Unmittelbar nach dem Erstellen einer neuen Organisation zeigt der HUB an, dass keine Clients, TSS, Transaktionen oder Exporte vorhanden sind.

Nachdem Sie eine Authentifizierungsanfrage gefolgt von einer TSS-Erstellungsanfrage aus der Postman-Sammlung gesendet haben, aktualisieren Sie die HUB-Ansicht, und Sie sehen die neue TSS aufgelistet.

Weitere Postman-Vorgänge zur Verwaltung von TSS und Clients werden ebenfalls im HUB widergespiegelt. Der fiskaly HUB bietet einen einfacheren Überblick über Ihre Organisation und kann TSS und Clients direkt verwalten.

💡Tip

Verwenden Sie den HUB zusammen mit Postman, um zu überprüfen, ob Ihre API-Anfragen den erwarteten Effekt auf die Ressourcen Ihrer Organisation haben.

---

Verwandte Seiten

Leitfaden für Neukunden

Vollständige API-Einrichtungsanleitung

HUB-Handbuch

Organisationen, TSS und Clients verwalten

Fehlerbehebung

Best Practices für Timeouts und Fehlerwiederherstellung