Import en masse

L'import sert à faire entrer un portefeuille dans Skautik et à l'y maintenir. Une annonce, c'est un POST vers properties ; quatre cents, rafraîchies chaque nuit, c'est ceci.

Un transfert

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 réponse est une exécution que vous pouvez interroger :

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

GET /v1/api/imports/{import_id} indique l'avancement et, à la fin, les décomptes :

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

GET /v1/api/imports/{import_id}/records est le compte rendu ligne par ligne, incluant chaque rejet avec sa raison. C'est le premier endroit où regarder quand les décomptes ne sont pas ceux attendus.

Les deux modes

incremental met à jour ce que contient le fichier et laisse tout le reste tranquille. C'est le mode par défaut, et le bon choix pour un flux partiel : un fichier des changements de la semaine, ou les annonces d'une seule agence.

full_sync traite le fichier comme la vérité complète pour cette source. Tout ce que cette source a publié auparavant et qui est absent du fichier est retiré.

Le défaut est incremental pour une raison : un mode qui supprime des choses ne doit pas s'obtenir par omission. Un envoi tronqué en mode synchronisation complète retire un portefeuille entier.

Faites toujours un essai à blanc avec un nouveau mappage

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"

Un essai à blanc analyse tout, valide tout et signale exactement les décomptes et les résultats par fiche qu'une exécution réelle produirait, sans rien écrire. Sur une synchronisation complète, il vous dira combien de biens seraient retirés, et c'est le chiffre à regarder avant de l'apprendre autrement.

L'identité, et pourquoi external_id compte

Chaque format d'import possède un champ qui identifie une fiche dans votre système, et Skautik s'y indexe. Envoyez deux fois le même external_id et la seconde exécution met à jour la première fiche ; envoyez-en un nouveau à chaque fois et vous publiez le même bien en boucle.

Ce champ constitue toute l'histoire du rapprochement. Il est renvoyé sur chaque bien : vous n'avez donc jamais besoin d'une table de correspondance entre nos identifiants et les vôtres.

Si votre export n'a pas d'identifiant stable par fiche, corrigez cela avant d'importer. Tout le reste, y compris le rapprochement par adresse, finira par fusionner deux appartements d'un même immeuble ou par scinder un appartement en deux fiches.

Sources permanentes

Un envoi ponctuel convient à une migration. Pour un flux, créez une source une fois et laissez-la tourner :

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 vaut fetch quand nous tirons depuis une URL selon un calendrier, ou un dépôt quand c'est vous qui poussez vers nous.
• schedule est du cron, en UTC. Chaque nuit à une heure calme vaut mieux qu'à l'heure : un flux interrogé plus souvent qu'il ne change n'est que de la charge.
• mapping traduit vos noms de colonnes vers les nôtres, pour que vous n'ayez rien à renommer de votre côté.
• deletion_policy décide de ce que signifie une fiche absente pour cette source.

last_delivery_at et next_expected_at sur la source sont ce sur quoi alerter. Un flux qui s'arrête en silence est la panne à attraper, et elle ressemble exactement à un flux sans changement, sauf si vous surveillez ces deux champs.

Fiches détenues par une source

Un bien arrivé par un import appartient à cet import. Son source le dit, et les endpoints d'écriture refusent de le modifier avec 409 managed_by_import.

C'est délibéré. Si le flux et l'API pouvaient tous deux modifier une fiche, la prochaine exécution du flux défaisait silencieusement la modification, et personne ne saurait quel système fait autorité. Modifiez-la dans le système qui alimente l'import.

Formats

Formats d'import couvre chacun de ceux que Skautik lit, comment il identifie une fiche, et comment le retrait y fonctionne. Dans la plupart des cas vous produisez déjà l'un d'eux pour un portail, et vous pouvez l'envoyer tel quel.

Si votre système exporte quelque chose qui n'est pas dans la liste, envoyez un échantillon plutôt que d'écrire un convertisseur. Les formats d'échange immobilier forment un ensemble restreint et bien connu.

Une liste de contrôle pour un premier import

• Faites un essai à blanc, et lisez les résultats par fiche plutôt que les seuls décomptes.
• Vérifiez que external_id est stable et unique dans votre source.
• Commencez en incremental ; passez à full_sync seulement quand le fichier est réellement complet.
• Envoyez une Idempotency-Key, pour qu'un délai dépassé ne devienne pas un second import.
• Surveillez next_expected_at dès qu'il s'agit d'une source permanente.