Importazione massiva

L'importazione serve a far entrare un portafoglio in Skautik e a tenercelo. Un annuncio singolo è un POST verso properties; quattrocento, aggiornati ogni notte, sono questo.

Un trasferimento

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"

La risposta è una passata che puoi interrogare:

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

GET /v1/api/imports/{import_id} riporta l'avanzamento e, alla fine, i conteggi:

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

GET /v1/api/imports/{import_id}/records è il resoconto riga per riga, compreso ogni rifiuto con il motivo. È il primo posto in cui guardare quando i conteggi non sono quelli che ti aspettavi.

Le due modalità

incremental aggiorna ciò che il file contiene e lascia stare tutto il resto. È la modalità predefinita e la scelta giusta per un feed parziale: un file con le variazioni della settimana, o gli annunci di una sola filiale.

full_sync tratta il file come la verità completa per quella fonte. Tutto ciò che questa fonte ha pubblicato in precedenza e che manca dal file viene ritirato.

La modalità predefinita è incremental per un motivo: una modalità che rimuove cose non dovrebbe capitarti per omissione. Un caricamento troncato in modalità sincronizzazione completa ritira un intero portafoglio.

Fai sempre una prova a vuoto con una mappatura nuova

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"

Una prova a vuoto analizza tutto, convalida tutto e riporta esattamente i conteggi e gli esiti per scheda che produrrebbe una passata reale, senza scrivere nulla. Su una sincronizzazione completa ti dirà quanti immobili verrebbero ritirati, ed è la cifra che vale la pena guardare prima di scoprirlo nell'altro modo.

L'identità, e perché conta external_id

Ogni formato di importazione ha un campo che identifica una scheda nel tuo sistema, e Skautik ci si indicizza. Invia due volte lo stesso external_id e la seconda passata aggiorna la prima scheda; inviane uno nuovo ogni volta e pubblicherai lo stesso immobile ripetutamente.

Quel campo è tutta la storia della riconciliazione. Viene restituito su ogni immobile, quindi non ti serve mai una tabella che mappi i nostri identificatori sui tuoi.

Se la tua esportazione non ha un identificatore stabile per scheda, sistemalo prima di importare. Qualsiasi altra cosa, incluso l'abbinamento per indirizzo, finirà per fondere due appartamenti dello stesso edificio o per dividere un appartamento in due schede.

Fonti permanenti

Un caricamento occasionale va bene per una migrazione. Per un feed, crea una fonte una volta e lasciala girare:

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 vale fetch quando preleviamo da un URL a intervalli programmati, oppure una consegna quando sei tu a inviarci i dati.
• schedule è cron, in UTC. Ogni notte a un'ora tranquilla batte ogni ora: un feed interrogato più spesso di quanto cambi è soltanto carico.
• mapping traduce i nomi delle tue colonne nei nostri, così non devi rinominare nulla dalla tua parte.
• deletion_policy decide cosa significa una scheda assente per questa fonte.

last_delivery_at e next_expected_at sulla fonte sono ciò su cui impostare un allarme. Un feed che si ferma in silenzio è il guasto che vale la pena intercettare, e assomiglia esattamente a un feed senza variazioni a meno che tu non sorvegli quei due campi.

Schede che appartengono a una fonte

Un immobile arrivato tramite un'importazione appartiene a quell'importazione. Il suo source lo dichiara, e gli endpoint di scrittura rifiutano di modificarlo con 409 managed_by_import.

È voluto. Se sia il feed sia l'API potessero modificare una scheda, la passata successiva del feed annullerebbe in silenzio la modifica, e nessuno saprebbe quale sistema faccia fede. Modificala nel sistema che alimenta l'importazione.

Formati

Formati di importazione copre ciascuno di quelli che Skautik legge, come identifica una scheda e come vi funziona il ritiro. Nella maggior parte dei casi ne produci già uno per un portale immobiliare, e puoi inviarlo così com'è.

Se il tuo sistema esporta qualcosa che non è in elenco, mandaci un campione invece di scrivere un convertitore. I formati di scambio immobiliare sono un insieme piccolo e ben noto.

Una lista di controllo per una prima importazione

• Fai una prova a vuoto, e leggi gli esiti per scheda invece dei soli conteggi.
• Verifica che external_id sia stabile e univoco nella tua fonte.
• Comincia con incremental; passa a full_sync solo quando il file è davvero completo.
• Invia una Idempotency-Key, così un timeout non diventa una seconda importazione.
• Sorveglia next_expected_at non appena diventa una fonte permanente.