Verbinden Sie Ihren Shop mit unserer API.

Senden Sie Angebots-Batches für einen freigegebenen Anbieter. Asynchrone Batches, der empfohlene Weg, werden sofort angenommen und für Sie verarbeitet; synchrone Batches liefern abgeschlossene Schreibergebnisse.

Zugriffstoken verwaltenAPI-Dokumentation öffnen(öffnet in neuem Tab)
Typischer AblaufZwei Modi
  1. 01Bis zu 100 Einträge sendenPOST · PATCH · PUT · DELETE
  2. 02
    AsynchronEmpfohlenZur Verarbeitung angenommenHTTP 202
    SynchronSchreibvorgänge abgeschlossenHTTP 200
  3. 03
    AsynchronKein Nachfragen nötig; den Rest übernehmen wirkeine Nachverfolgung nötig
    SynchronNur fehlgeschlagene Einträge wiederholen[] = alle geschrieben

I — So funktionieren Batches

Zwei Wege, einen Batch zu senden.

Beide Modi nehmen dieselben Angebots-Batches für denselben Anbieter an: bis zu 100 Einträge, POST zum Erstellen, PATCH zum Aktualisieren, PUT für Upserts und DELETE zum Zurücknehmen. Sie unterscheiden sich darin, was die Antwort bestätigt; asynchron ist der empfohlene Standard.

AsynchronEmpfohlenHTTP 202
Batch senden und weitermachen: Angenommene Einträge werden für Sie verarbeitet, ohne Abfragen oder Bestätigen.
SynchronHTTP 200
Wählen Sie diesen Modus, wenn Ihr System das Schreibergebnis jedes Eintrags braucht, bevor es weiterarbeitet.

AsynchronEmpfohlen

HTTP 202 · Angenommen

Jetzt angenommen, für Sie verarbeitet.

Endpunkt · POST · PATCH · PUT · DELETE/v1/listing-sources/{listingSourceId}/product-listings/async
Die Antwort
HTTP 202 liefert einen Annahmebericht: submissionId, acceptedCount und einen Fehler für jeden Eintrag, dessen Annahme nicht bestätigt wurde.
Wenn Einträge fehlschlagen
Angenommene Einträge werden weiterverarbeitet. Ob ein Angebot existiert, Auktionen und die Anbieterberechtigung werden bei der Verarbeitung geprüft, nicht in der Antwort. Wird nichts angenommen, liefern 400, 413, 500 oder 503 denselben Bericht.
Wiederholen
Senden Sie nach einer verlorenen oder unsicheren Antwort den unveränderten Batch mit demselben Idempotency-Key erneut. Korrigieren Sie ungültige Einträge in einem neuen Batch mit neuem Schlüssel.
Danach
Kein Nachfragen nötig: Ist ein Eintrag angenommen, liegt er bei uns und wird für Sie verarbeitet. Wenn Sie trotzdem nachsehen möchten, lesen Sie Angebote per GET zurück; delegierte Tokens brauchen dafür zusätzlich product-listings:read.

Synchron

HTTP 200 · Abgeschlossen

Abgeschlossene Schreibvorgänge, direkt in der Antwort.

Endpunkt · POST · PATCH · PUT · DELETE/v1/listing-sources/{listingSourceId}/product-listings
Die Antwort
HTTP 200 nennt nur fehlgeschlagene Einträge; [] bedeutet, dass jeder Eintrag abgeschlossen ist, auch bei einem leeren Batch.
Wenn Einträge fehlschlagen
Jeder Eintrag hat eine eigene Transaktion, abgeschlossene Schreibvorgänge bleiben also gespeichert. Schlagen alle Einträge fehl, kommt stattdessen eine Problemantwort.
Wiederholen
Korrigieren Sie nur die fehlgeschlagenen Einträge und senden Sie sie erneut.
Danach
Die Sichtbarkeit in der Suche folgt separat; ein abgeschlossener Schreibvorgang ist noch nicht in der Suche sichtbar.

II — Einrichtung

Vom Zugriffstoken zum ersten Angebots-Batch.

Ein praktischer Ablauf, um ein eigenes Shopsystem mit Aura Historia zu verbinden, in beiden Modi.

  1. Schritt 1

    Freigegebenen Anbieter auswählen

    Wählen Sie für diese Integration einen Anbieter aus, auf den Sie derzeit Zugriff haben. Der Zugriff bestätigt weder Eigentum noch die Berechtigung, Anbieterdetails zu bearbeiten.

    Worauf Sie achten solltenVerwenden Sie die kanonische Anbieter-ID für die Integration; beide Modi verwenden dieselbe.

  2. Schritt 2

    Benutzer-Zugriffstoken erstellen

    Erstellen Sie ein Benutzer-Zugriffstoken mit product-listings:write für ein Konto mit aktueller Freigabe für den Zielanbieter. Dasselbe Token funktioniert in beiden Modi.

    Worauf Sie achten solltenKopieren Sie das Token sofort, da es nur einmal angezeigt wird. Speichern Sie es sicher und senden Sie es bei jedem API-Request als Bearer-Token.

    Name
    Produktsynchronisation per eigener API
    Berechtigung
    product-listings:write
    Anbieter
    Nicht ausgewählt
  3. Schritt 3

    Ersten Produkt-Request vorbereiten und senden

    Asynchron ist ausgewählt; wechseln Sie zu synchron, wenn Sie Schreibergebnisse in der Antwort brauchen. Die URL verwendet die ausgewählte listingSourceId des Anbieters. Ersetzen Sie YOUR_USER_ACCESS_TOKEN auf Ihrem Server, bei asynchron zusätzlich YOUR_BATCH_KEY, und senden Sie den Beispiel-Batch per POST.

    Worauf Sie achten solltenAsynchron: Prüfen Sie HTTP 202, acceptedCount und failures; angenommene Einträge werden danach für Sie verarbeitet. Synchron: Prüfen Sie HTTP 200 und das Fehlerarray.

    cURL · POST
    curl --request POST \
  --url 'https://api.aura-historia.com/v1/listing-sources/YOUR_LISTING_SOURCE_ID/product-listings/async' \
  --header 'Authorization: Bearer YOUR_USER_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: YOUR_BATCH_KEY' \
  --data '[
  {
    "sourceListingId": "demo-violin-001",
    "title": {
      "text": "Baroque Violin",
      "language": "en"
    },
    "description": {
      "text": "A baroque violin with a carved scroll.",
      "language": "en"
    },
    "price": {
      "type": "MONETARY",
      "currency": "EUR",
      "amount": 420000
    },
    "availability": null,
    "url": "https://example-shop.com/products/demo-violin-001",
    "images": [
      "https://example-shop.com/images/demo-violin.jpg"
    ]
  }
]'

    Liefert 202 · angenommen, für Sie verarbeitet

  4. Schritt 4

    Ergebnis für Ihren Modus lesen

    Asynchron: acceptedCount plus failures ergibt die gesendeten Einträge, jeder Fehler steht an seinem ursprünglichen Index; angenommene Einträge brauchen keine Nachverfolgung. Synchron: [] bedeutet, dass jeder Eintrag abgeschlossen ist; bei Teilerfolg werden nur fehlgeschlagene Einträge genannt; ein vollständig fehlgeschlagener Batch liefert eine Problemantwort.

    Worauf Sie achten solltenBewahren Sie Antworten sicher auf. Senden Sie einen unsicheren asynchronen Batch unverändert mit demselben Schlüssel erneut; wiederholen Sie synchron nur korrigierbare Fehler.

    Relevante Endpunkte
    async/v1/listing-sources/{listingSourceId}/product-listings/async
    sync/v1/listing-sources/{listingSourceId}/product-listings

    Asynchron · zur Verarbeitung angenommen

    Alle angenommen
    202 · Bericht
    Teilweise angenommen
    202 · Fehler
    Keiner angenommen
    4xx · 5xx · Bericht

    Synchron · abgeschlossene Schreibvorgänge

    Alle geschrieben
    200 · []
    Teilweise
    200 · Fehler
    Alle fehlgeschlagen
    problem+json

III — Referenz

Partner-Produkt-API-Referenz.

Die Regeln der einzelnen Methoden in beiden Modi, dann die eingebettete OpenAPI-Referenz für die asynchronen und synchronen Batch-Endpunkte.

  • ASYNC

    Annahmeergebnisse

    POST, PATCH, PUT und DELETE auf /product-listings/async nehmen dieselben Einträge an, maxItems 100. HTTP 202 bedeutet, dass mindestens ein Eintrag bestätigt angenommen wurde oder der Batch leer war; angenommene Einträge werden danach für Sie verarbeitet, ohne dass Sie nachfragen müssen. Der Bericht lautet { submissionId, acceptedCount, failures }: acceptedCount plus failures ergibt die gesendeten Einträge, und jeder Fehler enthält index, error, retryable sowie, wenn sie gefahrlos zurückgegeben werden kann, die sourceListingId. Wird nichts angenommen: 503 bei unbestätigten, wiederholbaren oder blockierten Sendungen; sonst 500 bei internen Fehlern; 413, wenn nur die Größe scheitert; sonst 400. Ob ein Angebot existiert, Auktionen und die Anbieterberechtigung werden bei der Verarbeitung geprüft.

  • ASYNC

    Idempotenz und Wiederholungen

    Senden Sie genau einen Idempotency-Key-Header: 1–128 sichtbare ASCII-Zeichen, ohne Komma. Ohne Header wird ein Schlüssel erzeugt und im Bericht zurückgegeben; geht diese Antwort verloren, lässt sich der Schlüssel nicht wiederherstellen. Senden Sie nach einer verlorenen oder unsicheren Antwort genau denselben Batch unverändert, in derselben Reihenfolge und mit demselben Schlüssel erneut, abgelehnte Einträge eingeschlossen. retryable kennzeichnet Fehler, bei denen dieses erneute Senden angebracht ist (ENQUEUE_UNCONFIRMED ist möglicherweise schon eingereiht); Validierungs- und Größenfehler sind nicht wiederholbar. Korrigieren Sie ungültige Einträge in einer neuen Anfrage mit neuem Schlüssel und lassen Sie angenommene und unsichere Einträge weg. submissionId dient nur der Zuordnung. Um Angebote selbst einzusehen, verwenden Sie GET auf /product-listings; delegierte Tokens brauchen dafür zusätzlich product-listings:read.

  • SYNC

    Ergebnisse abgeschlossener Schreibvorgänge

    POST, PATCH, PUT und DELETE auf /product-listings: maxItems 100; [] liefert HTTP 200 mit []. Jeder Eintrag läuft in einer eigenen Transaktion. Bei Teilerfolg liefert HTTP 200 nur Fehler als { listingSourceId, sourceListingId, error }. Scheitern alle Einträge eines nicht leeren Batches, wird der erste Fehler als application/problem+json zurückgegeben. Wiederholen Sie keine erfolgreichen Einträge.

  • POST

    Erstellungsfelder und Preise

    POST erfordert sourceListingId, url und images; geben Sie lokalisierte title und description an, wenn vorhanden (der aktuelle Vertrag erlaubt Weglassen oder null). Verkäufer- und Adressfelder werden nicht unterstützt. availability darf null sein. Der Angebotspreis ist { type: MONETARY, currency: EUR, amount: 420000 } in kleinsten Währungseinheiten oder { type: ON_REQUEST }; null erfasst keinen Preis.

  • PATCH

    Beibehalten oder löschen

    Weggelassene Felder behalten bestehende Werte bei. null löscht title, description, availability, price und jede Preisschätzung. url: null, images: null und auction: null sind ungültig (400 BAD_BODY_VALUE). images: [] löscht Bilder. Der gesamte Batch-Vertrag wird vor Beginn der Einzeltransaktionen geprüft.

  • PUT

    Upsert-Semantik

    Bei bestehenden Angeboten: title, description, availability oder Preise weglassen zum Beibehalten, null zum Löschen, Wert zum Setzen. images weglassen zum Beibehalten, [] zum Löschen, Array zum Ersetzen; null ist ungültig. url weglassen oder null behält die URL bei; ein Wert ersetzt sie. Neue Angebote erfordern sourceListingId, url und images; fehlende/null title, description, availability und Preise erfassen keinen Wert.

  • AUCTION

    Auktionszuordnung und Loszeiten

    auction weglassen behält den Kontext bei; auction: null ist ungültig. auctionId muss eine bestehende Auktion desselben Anbieters bezeichnen: weglassen behält die Zuordnung bei, null löscht sie, eine ID setzt sie. Für lotNumber, cataloguePosition und jedes Zeitfeld (biddingOpens, scheduledCloses, reportedClosedAt) gilt: weglassen zum Beibehalten, null zum Löschen, Wert zum Setzen. Zeiten sind RFC3339-Zeitpunkte.

  • DELETE

    Batch-Rücknahme und Wiederherstellung

    DELETE nimmt auf beiden Pfaden ein Array aus { sourceListingId } an. Es nimmt Angebote zurück, was umkehrbar ist, und bewahrt ihren Verlauf; PUT stellt ein zurückgenommenes Angebot wieder her, bevor aktuelle Angaben angewendet werden. Lesen Sie das Ergebnis je nach Modus: den Annahmebericht bei asynchron, fehlgeschlagene Einträge bei synchron.

OpenAPI · Partner-ProdukteVollständige Doku(öffnet in neuem Tab)

Partner-Produkt-API-Referenz