Imports
Faites entrer votre inventaire depuis le système qui le détient déjà. Un import ponctuel règle une migration ; une source d'import garde un CRM et Skautik au pas indéfiniment.
/v1/api/importsimports:writeDémarrer un import
Envoyez un fichier, ou indiquez-nous où il se trouve, et lancez le traitement.
Accepte un envoi multipart ou une URL que nous récupérons. La validation passe en premier et le fichier entier est rejeté s'il ne peut pas être analysé ; les fiches individuelles en échec sont signalées sans arrêter les autres, sauf si vous demandez le tout-ou-rien.
Paramètres de requête
| Nom | Type | Description |
|---|---|---|
formatobligatoire | enum | Format du fichier envoyé. blm | csv | json | kyero | openimmo exemple : csv |
mode | enum | Le mode incrémental met à jour ce que contient le fichier et laisse le reste tranquille. Une synchronisation complète retire en plus tout ce qui en est absent, et c'est pourquoi ce n'est pas le mode par défaut. incremental | full_sync par défaut : incrementalexemple : incremental |
source_id | string | Source d'import à laquelle appartient ce transfert, lorsqu'il provient d'un connecteur permanent et non d'un envoi ponctuel. exemple : src_immoscout |
dry_run | boolean | Analyse et signale ce qui changerait sans rien écrire. À faire une fois avec un nouveau mappage. exemple : true |
filename | string | Nom d'origine du fichier, consigné sur l'exécution pour qu'un échec puisse être remonté jusqu'au fichier qui l'a causé. exemple : transfer-2026-08-12.zip |
confirm_shrink | boolean | Autoriser une synchronisation complète qui retirerait une grande part du portefeuille de la source. Sans cela, une livraison comportant beaucoup moins d'enregistrements que la source n'en détient voit ses retraits suspendus et l'exécution signalée comme partielle, en supposant que l'export était tronqué. Activez-le lorsque la réduction est réelle. exemple : true |
Champs du corps
| Nom | Type | Description |
|---|---|---|
file | binary | Le contenu. Mutuellement exclusif avec url. exemple : listings.csv |
En-têtes
| Nom | Type | Description |
|---|---|---|
Idempotency-Key | string | Empêche qu'un envoi réessayé soit traité deux fois. exemple : a7f3c9e2-4b1d-4e8a-9c2f-1d3b5a7c9e01 |
Corps de la requête
curl -sS -X POST "https://api.skautik.com/v1/api/imports" \
-H "Authorization: Bearer $SKAUTIK_API_KEY" \
-H "Idempotency-Key: 9c1f-…" \
-F "format=openimmo" \
-F "mode=incremental" \
-F "file=@transfer-2026-08-12.zip"Réponse
{
"data": {
"id": "imp_5a91c0",
"status": "validating",
"format": "openimmo",
"mode": "incremental",
"dry_run": false,
"created_at": "2026-08-12T10:04:00Z"
}
}Réponses notables
- 202
- Accepté pour traitement. Interrogez l'état ou attendez import.completed.
- 415
- Le contenu n'est pas au format déclaré.
- 422
- Le fichier a été analysé mais aucune de ses fiches n'était exploitable.
https://api.skautik.com/v1/api/imports
POST /v1/api/imports?format=csv&mode=incremental&source_id=src_immoscout&dry_run=true HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"file": "listings.csv"
}/v1/api/imports/{import_id}imports:writeRécupérer un import
Avancement, décomptes et récapitulatif de ce qui a changé.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
import_idobligatoire | string | Identifiant de l'import. exemple : imp_3d9b7e2145 |
Réponse
{
"data": {
"id": "imp_5a91c0",
"status": "completed",
"format": "openimmo",
"mode": "incremental",
"counts": {
"read": 214,
"created": 12,
"updated": 196,
"withdrawn": 3,
"unchanged": 0,
"failed": 3
},
"started_at": "2026-08-12T10:04:02Z",
"finished_at": "2026-08-12T10:05:41Z"
}
}https://api.skautik.com/v1/api/imports/{import_id}
GET /v1/api/imports/imp_3d9b7e2145 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/imports/{import_id}/recordsimports:writeLister les fiches d'un import
Résultat fiche par fiche, y compris la raison des échecs.
Filtrez sur failed pour obtenir la liste de travail d'une correction. Chaque entrée nomme l'identifiant source et la ligne ou l'élément d'où elle venait, pour qu'un problème se trouve dans votre export plutôt que se devine.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
import_idobligatoire | string | Identifiant de l'import. exemple : imp_3d9b7e2145 |
Réponse
{
"data": [
{
"external_id": "AG-4471-0812",
"property_id": "prop_8f2a41c9d0",
"outcome": "updated",
"changed": ["price", "status"]
},
{
"external_id": "AG-4471-0904",
"property_id": null,
"outcome": "failed",
"location": "immobilie[17]",
"errors": [
{ "field": "preise.kaufpreis", "code": "missing",
"detail": "A sale listing needs a price." }
]
}
],
"meta": { "has_more": false, "limit": 50 }
}https://api.skautik.com/v1/api/imports/{import_id}/records
GET /v1/api/imports/imp_3d9b7e2145/records HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/imports/formatsimports:writeLister les formats et colonnes acceptés
Ce qu'un import peut porter : les formats qui fonctionnent aujourd'hui, toutes les colonnes CSV et les limites.
Servi depuis les tables que lit l'analyseur, il ne peut donc pas être en retard sur ce qui est réellement accepté. À appeler une fois en construisant l'intégration plutôt que de recopier la liste des colonnes depuis cette page.
Réponse
{
"data": {
"formats": ["blm", "csv", "json", "kyero", "openimmo"],
"csv_columns": [
"address_city", "address_country", "address_district", "address_number",
"address_postal_code", "address_province", "address_street",
"attic_sqm", "balcony_count", "balcony_terrace_sqm", "bathrooms",
"bedrooms", "cellar_sqm", "commission_amount", "commission_note",
"commission_payer", "commission_percent", "condition",
"construction_phase", "construction_type", "currency", "deposit",
"description", "description_fittings", "description_location",
"description_other", "energy_certificate_issued_at",
"energy_certificate_type", "energy_certificate_valid_until",
"energy_co2_emissions", "energy_consumption_kwh", "energy_demand_kwh",
"energy_includes_hot_water", "energy_label", "energy_primary_carrier",
"external_id", "floor", "flooring", "floors_in_building", "garden_sqm",
"half_bathrooms", "has_air_conditioning", "has_alarm_system",
"has_balcony", "has_cellar", "has_fireplace", "has_fitted_kitchen",
"has_garden", "has_guest_toilet", "has_lift", "has_pool", "has_sauna",
"has_solar_panels", "has_terrace", "heating_costs", "heating_type",
"is_barrier_free", "is_furnished", "is_leasehold",
"is_monument_protected", "kitchen_type", "latitude", "living_area_sqm",
"location_precision", "longitude", "office_area_sqm", "other_area_sqm",
"parking_included", "parking_space_count", "parking_type",
"plot_area_sqm", "price", "price_on_request", "price_period",
"property_subtype", "publish_address", "retail_area_sqm",
"service_charges", "status", "storage_area_sqm", "terrace_count",
"title", "total_area_sqm", "total_rent", "total_rooms",
"transaction_type", "type", "usable_area_sqm", "window_glazing",
"year_built", "year_renovated"
],
"limits": {
"max_records": 10000,
"max_bytes": 33554432,
"max_archive_records": 25000,
"max_archive_bytes": 536870912,
"required_field": "external_id"
},
"modes": ["incremental", "full_sync"]
}
}https://api.skautik.com/v1/api/imports/formats
GET /v1/api/imports/formats HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/importsimports:writeLister les imports
Historique des imports de votre organisation.
https://api.skautik.com/v1/api/imports
GET /v1/api/imports HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/import-sourcesimports:writeLister les sources d'import
Tous les connecteurs permanents configurés par votre organisation.
Les identifiants ne sont jamais renvoyés. Une source de type récupération porte souvent dans son URL les identifiants de votre propre serveur : l'URL revient donc avec le mot de passe supprimé.
Réponse
{
"data": [
{
"id": "src_1d77a0",
"name": "Head office CRM",
"format": "csv",
"delivery": {
"type": "fetch_url",
"url": "https://partner:***@feeds.example.com/stock.csv"
},
"schedule": "0 */4 * * *",
"deletion_policy": "explicit_only",
"active": true,
"last_delivery_at": "2026-08-13T12:00:04Z",
"next_expected_at": "2026-08-13T16:00:00Z",
"created_at": "2026-08-12T10:04:00Z"
}
]
}https://api.skautik.com/v1/api/import-sources
GET /v1/api/import-sources HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/import-sourcesimports:writeCréer une source d'import
Un connecteur permanent qui importe selon un calendrier.
Configurez-le une fois et cessez d'y penser. Une source contient le format, le mode de livraison, le mappage des champs et la politique de suppression, et chaque exécution produit un import que vous pouvez inspecter.
Champs du corps
| Nom | Type | Description |
|---|---|---|
nameobligatoire | string | Votre propre libellé pour le connecteur. exemple : Nightly listing sync |
formatobligatoire | enum | Format livré par cette source. Seuls csv et json sont analysés aujourd'hui ; les autres sont nommés dans le schéma et refusés ici, plutôt qu'acceptés dans un connecteur qui échouerait à chaque exécution. csv | json exemple : csv |
deliveryobligatoire | object | Comment les données arrivent. fetch_url tire depuis une URL que vous nous donnez, selon un calendrier ; api_push signifie que vous nous envoyez chaque livraison. Les dépôts SFTP sont nommés dans le schéma et ne fonctionnent pas encore : en demander un est refusé plutôt que suivi d'identifiants pour un hôte qui ne les accepterait jamais. exemple : {"url": "https://example.com/hooks/skautik", "compression": "gzip"} |
schedule | string | Fréquence de récupération, pour les sources tirées. Expression cron en UTC. Ignorée pour les dépôts et les envois, qui s'exécutent à l'arrivée. exemple : 15 3 * * * |
mapping | object | Mappage des champs, pour les formats qui en ont besoin. À omettre pour OpenImmo et RESO, déjà normalisés. exemple : {"Objektnummer": "external_id", "Kaufpreis": "price", "Wohnflaeche": "living_area"} |
deletion_policy | enum | explicit_only n'honore que les marqueurs de suppression. absence_withdraws retire en plus tout ce qui manque dans une livraison complète, et ne devrait servir que lorsque le format constitue un état complet du stock. explicit_only | absence_withdraws par défaut : explicit_onlyexemple : explicit_only |
Corps de la requête
{
"name": "Head office CRM",
"format": "csv",
"delivery": {
"type": "fetch_url",
"url": "https://feeds.example.com/stock.csv"
},
"schedule": "0 */4 * * *",
"deletion_policy": "explicit_only"
}Réponse
{
"data": {
"id": "src_1d77a0",
"name": "Head office CRM",
"format": "csv",
"delivery": {
"type": "fetch_url",
"url": "https://feeds.example.com/stock.csv"
},
"schedule": "0 */4 * * *",
"deletion_policy": "explicit_only",
"active": true,
"next_expected_at": "2026-08-12T12:00:00Z",
"created_at": "2026-08-12T10:04:00Z"
}
}https://api.skautik.com/v1/api/import-sources
POST /v1/api/import-sources HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"name": "Head office CRM",
"format": "csv",
"delivery": {
"type": "fetch_url",
"url": "https://feeds.example.com/stock.csv"
},
"schedule": "0 */4 * * *",
"deletion_policy": "explicit_only"
}/v1/api/import-sources/{source_id}imports:writeRécupérer une source d'import
Configuration et santé des exécutions récentes.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
source_idobligatoire | string | Identifiant de la source. exemple : src_immoscout |
https://api.skautik.com/v1/api/import-sources/{source_id}
GET /v1/api/import-sources/src_immoscout HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/import-sources/{source_id}imports:writeMettre à jour une source d'import
Modifiez le mappage, le calendrier ou la politique de suppression.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
source_idobligatoire | string | Identifiant de la source. exemple : src_immoscout |
Corps de la requête
{
"schedule": "15 3 * * *",
"active": true,
"mapping": {
"Objektnummer": "external_id",
"Kaufpreis": "price"
}
}https://api.skautik.com/v1/api/import-sources/{source_id}
PATCH /v1/api/import-sources/src_immoscout HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"schedule": "15 3 * * *",
"active": true,
"mapping": {
"Objektnummer": "external_id",
"Kaufpreis": "price"
}
}/v1/api/import-sources/{source_id}imports:writeSupprimer une source d'import
Cessez d'importer depuis ce connecteur.
Supprimer une source arrête les exécutions futures. Cela ne retire pas les biens qu'elle a créés, qui restent rattachés à votre organisation jusqu'à ce que vous les retiriez vous-même.
Paramètres de chemin
| Nom | Type | Description |
|---|---|---|
source_idobligatoire | string | Identifiant de la source. exemple : src_immoscout |
https://api.skautik.com/v1/api/import-sources/{source_id}
DELETE /v1/api/import-sources/src_immoscout HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…