Ablauf eines Jobs

Job anlegen, Status abfragen, Ergebnis herunterladen: die API Schritt für Schritt.

Jede Abfrage an die API läuft als Job: Sie legen den Job an, unser Bot arbeitet die Anfragen ab, und Sie holen das Ergebnis, sobald es fertig ist. Ihr System muss also nicht auf die Quelle warten.

Adresse und API-Key

Alle Aufrufe gehen an https://pod.preishoheit.de/v2. Ihren API-Key senden Sie bei jedem Aufruf mit, entweder im Header X-API-KEY (empfohlen) oder als Parameter api_key. Den Key finden Sie im Kundenportal unter Konto.

1. Job anlegen

POST /jobs mit diesen Feldern (Format application/x-www-form-urlencoded):

Feld	Pflicht	Bedeutung
`platform`	ja	Quelle, z. B. `amazon`
`country`	ja	Land, z. B. `de`
`category`	ja	`offers`, `product` oder `search`
`data`	ja	Liste Ihrer Anfragen als JSON
`max_pages`	nein	Anzahl der Ergebnisseiten, Standard 1

Welche Werte je Quelle möglich sind, steht unter Quellen und Länder.

Jede Anfrage in data besteht aus dem Kennungstyp type und dem Wert value. Zusätzlich können Sie eigene Felder mitgeben, zum Beispiel Ihre Artikelnummer. Sie kommen im Ergebnis unverändert zurück, so ordnen Sie die Daten leicht Ihren Produkten zu:

[
  { "type": "gtin", "value": "4006381333931", "sku": "A-1001" },
  { "type": "gtin", "value": "4006381333948", "sku": "A-1002" }
]

Die möglichen Kennungstypen erklärt Kennungen. Wir empfehlen höchstens 10.000 Anfragen je Job, die Obergrenze liegt bei 40.000.

Die Antwort enthält die job_id des neuen Jobs:

{
  "response": {
    "header": {
      "status": "success",
      "job_id": "POD2-XX-XXXXXXXXXXXXXXXX",
      "msg": "Request has been saved, for detailed status see GET /v2/jobs/{job_id}"
    }
  }
}

2. Status abfragen

GET /jobs/{job_id} liefert den Stand des Jobs:

Status	Bedeutung
`new`	angelegt, noch nicht gestartet
`working`	wird bearbeitet
`done`	fertig, das Ergebnis kann abgeholt werden
`closed`	geschlossen

Dazu kommen Zähler: count_total (Anfragen im Job), count_work (in Bearbeitung) und count_done (erledigt). Fragen Sie den Status in Abständen ab, zum Beispiel einmal pro Minute.

Eine Liste Ihrer Jobs erhalten Sie mit GET /jobs, gefiltert nach Status mit GET /jobs/status/{status} (all, new, working, done, closed) und nach Datum mit den Parametern since und until (Format yyyy-mm-dd).

3. Ergebnis herunterladen

Sobald der Status done ist, holen Sie das Ergebnis mit GET /jobs/{job_id}/download als JSON ab. Den Aufbau beschreibt Antwortformat. Unter GET /jobs/{job_id}/download/raw gibt es zusätzlich alle Rohdaten, die wir zu Ihren Anfragen gefunden haben.

4. Job schließen

Mit GET /jobs/{job_id}/close schließen Sie einen Job. Er verschwindet dann aus Ihrer Jobliste und wird zum Löschen vorgemerkt. Laden Sie das Ergebnis vorher herunter.