Massenimport

Der Import ist dafür da, ein Portfolio nach Skautik zu bringen und dort zu halten. Ein einzelnes Angebot ist ein POST auf properties; vierhundert, nächtlich aktualisiert, sind das hier.

Eine Übertragung

curl -sS -X POST "https://api.skautik.com/v1/api/imports?format=csv&mode=incremental" \
  -H "Authorization: Bearer $SKAUTIK_API_KEY" \
  -H "Idempotency-Key: 6f1c2a7e-4d90-4a1b-9f33-0c2f5b8e77aa" \
  -F "file=@listings.csv"

Die Antwort ist ein Lauf, den Sie abfragen können:

{
  "data": {
    "id": "imp_3d9b7e2145",
    "format": "csv",
    "mode": "incremental",
    "status": "queued",
    "dry_run": false
  }
}

GET /v1/api/imports/{import_id} meldet den Fortschritt und am Ende die Zählungen:

{
  "counts": { "read": 412, "created": 37, "updated": 361, "withdrawn": 9 }
}

GET /v1/api/imports/{import_id}/records ist die zeilenweise Aufstellung, einschließlich jeder Ablehnung mit Grund. Das ist die erste Anlaufstelle, wenn die Zählungen nicht dem entsprechen, was Sie erwartet haben.

Die zwei Modi

incremental aktualisiert, was die Datei enthält, und lässt alles andere in Ruhe. Das ist die Voreinstellung und die richtige Wahl für einen Teil-Feed: eine Datei mit den Änderungen dieser Woche oder mit den Angeboten einer Niederlassung.

full_sync behandelt die Datei als vollständige Wahrheit für diese Quelle. Alles, was diese Quelle zuvor veröffentlicht hat und was in der Datei fehlt, wird zurückgezogen.

Die Voreinstellung ist aus einem Grund incremental: Ein Modus, der Dinge entfernt, sollte nichts sein, was man durch Weglassen bekommt. Ein abgebrochener Upload im Modus full_sync zieht ein Portfolio zurück.

Eine neue Zuordnung immer erst als Probelauf

curl -sS -X POST "https://api.skautik.com/v1/api/imports?format=csv&mode=full_sync&dry_run=true" \
  -H "Authorization: Bearer $SKAUTIK_API_KEY" \
  -F "file=@listings.csv"

Ein Probelauf liest alles, prüft alles und meldet genau die Zählungen und Ergebnisse je Datensatz, die ein echter Lauf erzeugen würde, ohne etwas zu schreiben. Bei einem full_sync sagt er Ihnen, wie viele Objekte zurückgezogen würden, und das ist die Zahl, die man ansehen sollte, bevor man es auf die andere Weise erfährt.

Identität, und warum external_id zählt

Jedes Importformat hat ein Feld, das einen Datensatz in Ihrem System ausweist, und Skautik schlüsselt darauf. Senden Sie dieselbe external_id zweimal, und der zweite Lauf aktualisiert den ersten Datensatz; senden Sie jedes Mal eine neue, und Sie veröffentlichen dasselbe Objekt immer wieder.

Dieses Feld ist die gesamte Abgleichsgeschichte. Es wird an jedem Objekt zurückgespiegelt, Sie brauchen also nie eine Tabelle, die unsere Kennungen Ihren zuordnet.

Wenn Ihr Export keine stabile Kennung je Datensatz hat, beheben Sie das vor dem Import. Alles andere, auch der Abgleich über die Adresse, führt irgendwann dazu, dass zwei Wohnungen in einem Haus verschmelzen oder eine Wohnung zu zwei Datensätzen wird.

Dauerhafte Quellen

Ein einmaliger Upload ist für eine Migration in Ordnung. Für einen Feed legen Sie eine Quelle einmal an und lassen sie laufen:

curl -sS -X POST "https://api.skautik.com/v1/api/import-sources" \
  -H "Authorization: Bearer $SKAUTIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly listing sync",
    "format": "csv",
    "delivery": { "type": "fetch", "url": "https://partner.example.com/exports/latest.csv" },
    "schedule": "15 3 * * *",
    "deletion_policy": "withdraw",
    "mapping": { "Objektnummer": "external_id", "Kaufpreis": "price" }
  }'

• delivery.type ist fetch, wenn wir nach Plan von einer URL holen, oder eine Ablage, wenn Sie zu uns senden.
• schedule ist Cron, in UTC. Nächtlich zu einer ruhigen Stunde schlägt stündlich: Ein Feed, der öfter abgefragt wird, als er sich ändert, ist bloß Last.
• mapping übersetzt Ihre Spaltennamen in unsere, Sie müssen bei sich also nichts umbenennen.
• deletion_policy entscheidet, was ein fehlender Datensatz für diese Quelle bedeutet.

last_delivery_at und next_expected_at an der Quelle sind das, worauf man alarmieren sollte. Ein Feed, der stillschweigend aufhört, ist der Fehler, den es zu erwischen gilt, und er sieht genau aus wie ein Feed ohne Änderungen, wenn man diese beiden Felder nicht beobachtet.

Datensätze, die einer Quelle gehören

Ein Objekt, das über einen Import kam, gehört diesem Import. Sein source sagt das, und die Schreib-Endpunkte verweigern eine Änderung mit 409 managed_by_import.

Das ist Absicht. Könnten sowohl der Feed als auch die API einen Datensatz bearbeiten, würde der nächste Lauf des Feeds die Bearbeitung stillschweigend zurücknehmen, und niemand wüsste, welches System maßgeblich ist. Ändern Sie es im System, das den Import speist.

Formate

Importformate behandelt jedes Format, das Skautik liest, wie es einen Datensatz ausweist und wie darin das Entfernen funktioniert. Meist erzeugen Sie bereits eines davon für ein Immobilienportal und können es unverändert senden.

Wenn Ihr System etwas exportiert, das nicht auf der Liste steht, schicken Sie ein Muster, statt einen Konverter zu schreiben. Austauschformate für Immobilien sind eine kleine, gut bekannte Menge.

Eine Prüfliste für den ersten Import

• Probelauf, und lesen Sie die Ergebnisse je Datensatz statt nur die Zählungen.
• Bestätigen Sie, dass external_id in Ihrer Quelle stabil und eindeutig ist.
• Beginnen Sie mit incremental; wechseln Sie erst zu full_sync, wenn die Datei wirklich vollständig ist.
• Senden Sie einen Idempotency-Key, damit aus einem Timeout kein zweiter Import wird.
• Beobachten Sie next_expected_at, sobald es eine dauerhafte Quelle ist.