Public API für Entwickler

API-Schlüssel haben das Format mp_live_... (Produktion) bzw. mp_test_... (Test). Sie werden serverseitig nur als HMAC-Hash gespeichert und einmalig bei Erstellung angezeigt.

Beim Erstellen wählen Sie, welche Berechtigungen (Scopes) der Schlüssel erhält:

Ein optionales Ablaufdatum können Sie beim Erstellen des Schlüssels selbst festlegen. Die Verwaltung von Schlüsseln (anlegen, rotieren, widerrufen) erfolgt ausschließlich über Ihre eingeloggte Sitzung unter Einstellungen → API, nicht über die Public API selbst – ein kompromittierter Schlüssel kann also nie einen anderen Schlüssel anlegen oder widerrufen.

Ein „Listing” entspricht genau dem, was die Verkäufer-Oberfläche ein „Angebot” nennt – dieselbe Datenbank, dieselbe Geschäftslogik.

Neue Angebote durchlaufen denselben zweistufigen Prozess wie in der Oberfläche: nach submit geht ein Angebot in die bestehende Moderationswarteschlange, bevor es sichtbar wird – ein direktes Veröffentlichen an der Prüfung vorbei ist über die API nicht möglich.

Änderungen per PATCH erfordern einen If-Match-Header mit der aktuellen Version (aus dem ETag einer vorherigen Antwort) – so verhindern wir, dass zwei gleichzeitige Änderungen sich gegenseitig überschreiben.

Ein optionaler Idempotency-Key-Header auf POST-Anfragen sorgt dafür, dass ein wiederholter Request (z. B. nach einem Netzwerkfehler) niemals doppelt anlegt. Für die Synchronisation mit Ihrem CRM können Sie externalId/externalSource mitgeben, oder direkt PUT /listings/upsert verwenden (legt an oder aktualisiert, je nachdem ob der Eintrag schon existiert).

Listen werden per Cursor paginiert, nicht per Seitenzahl:

GET /listings?status=active&limit=50&cursor=eyJjcmVhdGVkQXQiOi...

Bevor Sie ein Angebot anlegen, können Sie abfragen, welche Felder eine Kategorie erwartet – nützlich, um in Ihrem eigenen System automatisch das passende Formular zu erzeugen.

GET /categories
GET /categories/{id}
GET /categories/{id}/attributes

Die meisten Kategorien haben kein zusätzliches Attribut-Schema – dort genügen Titel und (vor dem Einreichen) mindestens ein Foto, wie gewohnt. Nur einzelne Kategorien (z. B. Bremsbeläge) verlangen zusätzliche, strukturierte Angaben; diese werden beim Anlegen unter newProduct.attributes mitgeschickt und können später über PATCH /listings/:id/attributes nachgetragen werden.

POST /listings/:id/photos
Content-Type: multipart/form-data

Erlaubte Formate: JPEG, PNG, WebP. Maximal 8 MB pro Datei, 24 Fotos pro Angebot.

Der tatsächliche Dateiinhalt wird geprüft, nicht nur die angegebene Content-Type – ein falsch deklariertes Format wird abgelehnt.

Über Webhooks erfahren Sie in Echtzeit von Änderungen an Ihren Angeboten sowie von neuen Bestellungen und Verkäufen (listing.created, listing.published, order.created, offer.sold u. a.) – ohne dass Sie selbst regelmäßig abfragen müssen.

Webhook-Endpunkte richten Sie ausschließlich über Ihre eingeloggte Sitzung ein, nicht über einen API-Schlüssel:

Einstellungen → Webhooks

Jede Zustellung ist per HMAC-SHA256 signiert (X-Marketplace-Signature). Prüfen Sie die Signatur über die exakten, unveränderten Rohdaten des Requests:

const signedPayload = `${timestamp}.${rawBody}`;
const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
// mit dem hex-Teil von X-Marketplace-Signature (Format "v1=<hex>") vergleichen

Jede Fehlerantwort hat dieselbe Struktur:

{
  "error": {
    "code": "SKU_ALREADY_EXISTS",
    "message": "...",
    "details": [ { "field": "inventory.sku", "message": "..." } ],
    "requestId": "a73c6fbb-ed58-45d7-896d-1a9f3df27e56"
  }
}

requestId finden Sie auch im X-Request-Id-Response-Header jeder Antwort – geben Sie ihn bei Rückfragen an unseren Support an.

Begrenzt pro API-Schlüssel und Anfrageart, konfigurierbar serverseitig – Richtwerte:

Bei Überschreitung antwortet die API mit 429 und dem Header Retry-After-publicApiKey.