Import per REST-API (JSON)

Überblick

Über die Import-API können Partner Produkt- und Veranstaltungsdaten im JSON-Format automatisiert an Semigator übermitteln. Die Schnittstelle ermöglicht so eine direkte Synchronisierung aus Ihrem eigenen System – ohne manuelle Pflege im Partner-Dashboard.

Die API steht in zwei Varianten zur Verfügung: einer Testumgebung (Preprod) und der Produktivumgebung (Prod). Beide Varianten sind in der Swagger-Dokumentation beschrieben.

Varianten der API

1. Testumgebung (Preprod)

Interessierten Partnern stellen wir auf Anfrage einen eigenen Zugang und API-Key für die Preprod-Umgebung bereit, damit Sie unabhängig vom Live-System entwickeln und testen können.

Swagger-Dokumentation:
https://partner.preprod.semigator.de/api/documentation

Server:
https://partner.preprod.semigator.de/api/

Diese Umgebung dient ausschließlich zu Testzwecken. Sie ist von der Live-Plattform getrennt, sodass Sie gefahrlos Importprozesse ausprobieren können.

2. Produktivumgebung (Prod)

Swagger-Dokumentation:
https://partner.semigator.de/api/documentation

Server:
https://partner.semigator.de/api/

Diese Umgebung ist mit dem Live-System verknüpft. Der benötigte API-Key steht in Ihrem Partner-Account bereit, sobald sich Ihr Account auf der neuen Plattform befindet:
→ Firmeneinstellungen › Integrationen

Import-Workflow im Überblick

Der Importprozess ist asynchron aufgebaut, um auch große Datenmengen effizient zu verarbeiten.

  • Übermittlung der Daten per POST-Request an den Import-Endpunkt.
  • Validierung der Datenstruktur und Authentizität durch unser System.
  • Rückmeldung einer Import-ID bei erfolgreicher Annahme des Payloads.
  • Verarbeitung der Daten im Hintergrund.
  • Abfrage des aktuellen Status über die Import-ID.

Datenübertragung

Verwenden Sie den Endpunkt POST /imports, um Produkte und Termine im JSON-Format zu übertragen.
Hinweise:

  • Alle Felder und Validierungsregeln finden Sie in der Swagger-Dokumentation.
  • HTML im product_description-Feld darf nur die in der Dokumentation erlaubten Tags (p, ul, li, strong, etc.) enthalten.

Nach erfolgreichem Upload erhalten Sie eine Import-ID, mit der Sie den Fortschritt abfragen können (GET /imports/{import_id}/status).

Erweiterte Steuerungselemente des Imports

Für eine präzisere Kontrolle des Importvorgangs stehen Ihnen zusätzliche Parameter zur Verfügung.

  • Die Funktion delete_old_products ermöglicht eine automatische Bereinigung Ihres Portfolios. Wenn dieser Wert auf true gesetzt wird, entfernt das System nach dem Import alle Produkte oder Termine, die nicht im aktuellen Payload enthalten waren.
  • Über das Feld webhook_url können Sie eine eigene URL definieren. Unser System sendet nach Abschluss der Verarbeitung automatisch eine Statusmeldung an diese Adresse, sodass eine manuelle Abfrage des Import-Status entfällt.

Best Practices

  • Nutzen Sie zuerst die Preprod-Umgebung, bevor Sie produktiv importieren.
  • Verwenden Sie eindeutige IDs (partner_product_id, partner_event_id) für jedes Produkt und Event.
  • Nutzen Sie für die initiale Einrichtung die bereitgestellten JSON-Templates, um die korrekte Strukturierung Ihrer Daten sicherzustellen.
  • Prüfen Sie Importstatus regelmäßig, um mögliche Fehler früh zu erkennen.
  • Halten Sie Ihre Daten stets aktuell mit delete_old_products
  • Verwenden Sie webhook_url um über Fehler informiert zu werden
  • Nutzen Sie die CRUD-Operatoren für noch präzisere Produktverwaltung

Weitere Informationen

  • API Felddokumentation
  • Ressourcenverwaltung per CRUD-Operationen

Bei Interesse an einem eigenen Testzugang (Preprod) oder falls wir Sie bei Ihrer API-Implementierung unterstützen können, wenden Sie sich bitte an das Partner Management.