Aperçu
Le parcours, de bout en bout :
- Le courtier clique sur la fiche d'un projet (ou d'un prospect : Scorimmo n'a pas besoin de savoir lequel). Votre logiciel appelle
POST /criteria-linksavec votre identifiant pour cet élément (external_ref). Scorimmo y rattache un jeu de critères et renvoie un lien. - L'acheteur ouvre le lien — sans compte ni mot de passe, le jeton est dans l'URL. Il répond au questionnaire, ou décrit sa recherche avec ses mots : texte, PDF ou message vocal. Il envoie.
- Les critères sont générés et vous parviennent par webhook (
criteria_set.updated). Vous les affichez ; le courtier les modifie avec les routes/criteria-sets. - Une recherche dans votre logiciel envoie le jeu de critères et les fiches (jusqu'à 100) à
POST /analyses/batch. Les scores et leur détail reviennent dans la réponse, au fil de l'eau, ou par webhook fiche par fiche.
- Toutes les routes sont sous
/v1/partner. L'adresse de l'API vous est communiquée avec votre jeton. - Requêtes et réponses en JSON (
Content-Type: application/json), UTF-8. - Les montants et surfaces sont exprimés dans la devise et l'unité du marché de votre contrat (ex. :
CADet pi² au Québec,EURet m² en France). - Les messages d'erreur (
detail) sont rédigés en français.
| Méthode | Route | Usage |
|---|---|---|
| GET | /account | contrat, marché, consommation du mois |
| GET | /criteria-schema | champs, mesures et types de lieux utilisables |
| PUT | /webhook | votre point de réception (secret renvoyé une fois) |
| GET | /webhook | le webhook configuré |
| DELETE | /webhook | le retirer |
| POST | /webhook/test | envoyer un ping signé, voir le résultat |
| GET | /webhook/deliveries | envois récents (?status=failed) |
| GET | /webhook/deliveries/{id} | un envoi, avec son contenu |
| POST | /webhook/deliveries/{id}/retry | renvoyer |
| POST | /criteria-links | un lien pour l'acheteur (crée le jeu au besoin) |
| GET | /criteria-links/{link_id} | où en est ce lien |
| GET | /criteria-sets?external_ref=… | vos jeux, avec leurs critères |
| GET | /criteria-sets/{id} | un jeu |
| PUT | /criteria-sets/{id}/criteria | remplacer toute la liste |
| POST | /criteria-sets/{id}/criteria | ajouter un critère |
| PATCH | /criteria-sets/{id}/criteria/{critere} | modifier un critère |
| DELETE | /criteria-sets/{id}/criteria/{critere} | retirer un critère |
| DELETE | /criteria-sets/{id} | supprimer un jeu (libère une place) |
| POST | /analyses/batch | analyser 1 à 100 fiches |
| GET | /analyses/batches/{batch_id} | relire le résultat d'une recherche |
| GET | /criteria-sets/{id}/listings?listing_ref=… | dernier score enregistré de chaque fiche |
| GET | /criteria-sets/{id}/listings/{fiche} | dernier score d'une fiche, avec le détail |
Authentification
Chaque requête porte le jeton de votre société dans l'en-tête :
Authorization: Bearer smk_live_…- Le jeton vous est remis une seule fois, à sa création. Scorimmo n'en conserve qu'une empreinte et ne peut pas vous le renvoyer.
- Traitez-le comme un mot de passe : coffre de secrets, appels depuis vos serveurs uniquement, jamais dans du code exécuté par le navigateur.
- Plusieurs jetons peuvent coexister (production, recette), chacun révocable séparément. Un jeton révoqué est refusé dès la requête suivante (
401). - Le lien envoyé à l'acheteur, lui, ne porte aucun jeton d'API : seulement un jeton propre à ce lien, qui ne donne accès qu'au formulaire de ce jeu de critères.
Contrat et limites
Votre contrat fixe un marché, un périmètre géographique et des quotas. Vous pouvez les lire à tout moment, avec votre consommation du mois :
GET /v1/partner/account
{
"company": "Votre société",
"market": {
"id": "quebec", "currency": "CAD", "currency_symbol": "$",
"area_unit": "sqft", "area_label": "pi²", "locale": "fr-CA", …
},
"perimeter_zones": "montreal:45.40,-73.98,45.71,-73.47",
"requests_per_minute": 60,
"max_photos": 12,
"batch_max_listings": 100,
"webhook_configured": true,
"usage": {
"period": "2026-10",
"analyses_used": 312, "analyses_limit": 1000, "analyses_remaining": 688,
"criteria_sets": 17, "criteria_sets_limit": 50
}
}| Limite | Effet quand elle est atteinte |
|---|---|
| Analyses par mois (mois civil UTC) | 429 sur POST /analyses/batch jusqu'au 1er du mois suivant |
| Nombre de jeux de critères | 409 sur POST /criteria-links pour un nouvel external_ref ; supprimez un jeu pour libérer une place |
| Requêtes par minute | 429 avec Retry-After: 60 |
| Périmètre géographique | une fiche située hors zone est refusée (403 dans rejected) — non décomptée |
| Photos par fiche | les suivantes sont ignorées, avec un avertissement dans le résultat |
perimeter_zones liste les zones couvertes, chacune sous la forme nom:lat_sud,lon_ouest,lat_nord,lon_est, séparées par ;.
Webhook
Scorimmo vous pousse les critères générés et, si vous le demandez, les résultats de vos recherches. Déclarez une adresse HTTPS (port 443, adresse publique) :
PUT /v1/partner/webhook
{ "url": "https://crm.example.com/hooks/scorimmo" }
→ 200
{
"url": "https://crm.example.com/hooks/scorimmo",
"secret": "whsec_4kQ…", // renvoyé une seule fois (et à chaque rotation)
"secret_hint": "whsec_4kQ9…",
"events": ["criteria_set.updated", "criteria_set.generation_failed",
"analysis.completed", "analysis.failed", "batch.completed"]
}Le secret sert à signer chaque envoi. Il n'est renvoyé qu'à sa création et quand vous demandez "rotate_secret": true ; changer d'URL le conserve.
Ce que vous recevez
POST https://crm.example.com/hooks/scorimmo
Content-Type: application/json; charset=utf-8
Scorimmo-Event: criteria_set.updated
Scorimmo-Delivery: 0b6f2c1e-… // identique à chaque nouvel essai : dédoublonnez dessus
Scorimmo-Timestamp: 1792681445
Scorimmo-Signature: v1=5f1d0c…
{ "id": "0b6f2c1e-…", "type": "criteria_set.updated",
"created_at": "2026-10-22T15:04:05Z", "data": { … } }| Événement | Quand |
|---|---|
criteria_set.updated | l'acheteur a envoyé ; ses critères sont dans le jeu |
criteria_set.generation_failed | rien d'exploitable n'a pu être tiré de l'envoi ; l'acheteur peut compléter et renvoyer |
analysis.completed | une fiche d'une recherche, notée, avec son détail |
analysis.failed | une fiche n'a pas pu être notée (non décomptée) |
batch.completed | une recherche livrée par webhook est terminée |
ping | envoyé par POST /webhook/test |
Vérifier la signature
Scorimmo-Signature vaut v1= suivi du HMAC-SHA256, en hexadécimal, de {Scorimmo-Timestamp}.{corps brut} avec votre secret. Calculez-le sur les octets reçus, avant toute analyse du JSON, comparez en temps constant, et refusez un horodatage de plus de 5 minutes.
import crypto from "node:crypto";
// rawBody : les octets reçus, AVANT tout JSON.parse
function isFromScorimmo(rawBody, headers, secret) {
const timestamp = headers["scorimmo-timestamp"];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; // rejeu
const expected = "v1=" + crypto.createHmac("sha256", secret)
.update(`${timestamp}.`).update(rawBody).digest("hex");
const received = headers["scorimmo-signature"] ?? "";
return expected.length === received.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}Livraison et nouveaux essais
- Toute réponse
2xxvaut accusé de réception. Répondez vite (moins de 10 s) et traitez ensuite : un délai dépassé compte comme un échec. - Sinon (autre code, délai, connexion refusée), nouvel essai après 10 s, 1 min, 5 min, 30 min et 2 h. Après le 6e essai, l'envoi passe en
failedet reste consultable. Les redirections ne sont pas suivies. Scorimmo-Deliveryest identique à chaque essai : un même envoi peut arriver deux fois, dédoublonnez sur cet identifiant.- L'ordre n'est pas garanti : chaque événement porte ce qu'il concerne (
criteria_id,external_ref,batch_id).
GET /v1/partner/webhook/deliveries?status=failed
[
{ "delivery_id": "0b6f2c1e-…", "event": "analysis.completed", "status": "failed",
"attempts": 6, "last_status_code": 503, "last_error": "HTTP 503",
"created_at": "2026-10-22T15:04:05", "delivered_at": null, "next_attempt_at": null }
]
POST /v1/partner/webhook/deliveries/0b6f2c1e-…/retry → 202Lien de critères
Quand le courtier clique sur votre bouton, demandez un lien pour l'élément concerné. Le premier appel pour un external_ref crée son jeu de critères ; les suivants le réutilisent et renvoient chacun un nouveau lien.
POST /v1/partner/criteria-links
{
"external_ref": "projet-4812", // votre identifiant : un projet, un prospect…
"name": "Projet condo Plateau", // facultatif, jamais montré à l'acheteur
"expiry_days": 30 // 1 à 180
}
→ 201
{
"link_id": "7b1e…",
"criteria_id": "sc-3f9a0c21b7e44d12",
"external_ref": "projet-4812",
"status": "pending",
"url": "https://scorimmo.ca/q/kY3…", // renvoyée une seule fois
"expires_at": "2026-11-21T15:04:05",
"source": null, "error": null
}- Affichez
urlau courtier : il l'ouvre lui-même ou l'envoie à l'acheteur. Elle n'est renvoyée qu'une fois — pour la réafficher plus tard, demandez un nouveau lien. - Les liens déjà envoyés restent valables jusqu'à leur expiration. Le dernier envoi reçu, par n'importe lequel d'entre eux, l'emporte.
- La page ne révèle ni le courtier, ni le nom du jeu, ni votre identifiant.
Ce que voit l'acheteur
Deux façons de répondre, au choix, chacune enregistrée au fil de la saisie :
- Le questionnaire du marché de votre contrat : budget, surface, pièces, étage, proximités, trajets — dans la langue du jeu de questions.
- Ses propres mots : un texte libre, un PDF (une analyse des besoins, par exemple) ou un message vocal enregistré sur la page ou envoyé en fichier (m4a, mp3, wav, webm…, 14 Mo au maximum). Un fichier est d'abord converti en texte, que l'acheteur relit et corrige avant d'envoyer.
À l'envoi, le lien passe en processing le temps de générer les critères (quelques secondes), puis en applied — ou failed, avec la raison dans error. L'acheteur peut compléter et renvoyer tant que le lien est valable : chaque envoi régénère les critères.
GET /v1/partner/criteria-links/7b1e…
{ "link_id": "7b1e…", "criteria_id": "sc-3f9a0c21b7e44d12", "external_ref": "projet-4812",
"status": "applied", // pending → processing → applied | failed
"source": "audio", // questionnaire | text | pdf | audio
"submitted_at": "2026-10-22T15:03:51", "applied_at": "2026-10-22T15:04:05",
"url": null, "error": null, … }GET /criteria-links/{id} sert à rattraper un envoi manqué.Critères reçus et modifiés
Les critères générés remplacent ceux du jeu, puis vous sont envoyés avec ce que l'acheteur a dit, pour que le courtier voie l'un à côté de l'autre :
{
"id": "0b6f2c1e-…",
"type": "criteria_set.updated",
"created_at": "2026-10-22T15:04:05Z",
"data": {
"criteria_set": {
"criteria_id": "sc-3f9a0c21b7e44d12",
"external_ref": "projet-4812",
"name": "Projet condo Plateau",
"exclusions": [
{ "id": "prix_max", "label": "Prix > 650 000 $", "is_exclusion": true, "points": 0,
"evaluations": [{ "method": "reso_field", "params": { "field": "list_price", "op": "gt", "value": 650000 } }] }
],
"scored_criteria": [
{ "id": "metro_10", "label": "Métro à moins de 10 min à pied", "points": 10, … },
…
],
"total_points_possible": 35,
"updated_at": "2026-10-22T15:04:05"
},
"link_id": "7b1e…",
"source": "questionnaire", // questionnaire | text | pdf | audio
"submitted_at": "2026-10-22T15:03:51",
"answers": [ // questionnaire : ce que l'acheteur a répondu
{ "key": "budget", "question": "Quel prix vous conviendrait ?", "answer": "excellent 550 000 $, acceptable 600 000 $, limite 650 000 $" }
],
"brief": null, // texte, PDF ou audio : le texte dont les critères sont tirés
"unmapped": ["près d'une bonne école"], // demandé, mais aucun critère ne peut le vérifier
"rejected": []
}
}| Champ | Contenu |
|---|---|
criteria_set | le jeu complet, tel qu'il est maintenant (même forme que GET /criteria-sets/{id}) |
source | questionnaire, text, pdf ou audio |
answers | questionnaire : chaque question et la réponse, en clair |
brief | texte, PDF ou audio : le texte dont les critères ont été tirés (corrigé par l'acheteur) |
unmapped | ce que l'acheteur a demandé et qu'aucun critère ne sait vérifier — à montrer au courtier |
rejected | critères proposés puis écartés parce qu'inévaluables, avec la raison |
{
"type": "criteria_set.generation_failed",
"data": { "criteria_id": "sc-3f9a0c21b7e44d12", "external_ref": "projet-4812",
"link_id": "7b1e…", "source": "text",
"error": "La description est trop courte pour en tirer des critères." }
}Modifier les critères
Le courtier ajuste le jeu dans votre écran ; enregistrez avec les routes ci-dessous. Ces modifications ne déclenchent pas de webhook (elles viennent de vous). Le plus simple : renvoyer la liste complète.
PUT /v1/partner/criteria-sets/sc-3f9a0c21b7e44d12/criteria
{
"criteria": [
{ "id": "prix_max", "label": "Prix > 650 000 $", "is_exclusion": true,
"evaluations": [{ "method": "reso_field",
"params": { "field": "list_price", "op": "gt", "value": 650000 } }] },
{ "id": "surface_900", "label": "Plus de 900 pi²", "points": 5,
"evaluations": [{ "method": "reso_field",
"params": { "field": "living_area", "op": "gt", "value": 900 } }] },
{ "id": "metro_10", "label": "Métro à moins de 10 min à pied", "points": 10,
"evaluations": [{ "method": "signal",
"params": { "signal": "metro_walk_minutes", "op": "lte", "value": 10, "radius_m": 3000 } }] },
{ "id": "travail_30", "label": "Moins de 30 min du bureau en transport", "points": 8,
"evaluations": [{ "method": "signal",
"params": { "signal": "commute_minutes", "destination": "1000 rue De La Gauchetière O, Montréal",
"mode": "transit", "op": "lte", "value": 30 } }] },
{ "id": "cuisine_renovee", "label": "Cuisine rénovée", "points": 10,
"evaluations": [{ "method": "llm", "params": { "inputs": ["description", "photos"] } }] }
]
}| Méthode | Route | Usage |
|---|---|---|
| GET | /criteria-sets?external_ref=… | le jeu rattaché à votre identifiant |
| GET | /criteria-sets/{id} | un jeu, avec tous ses critères |
| PUT | /criteria-sets/{id}/criteria | remplacer toute la liste |
| POST | /criteria-sets/{id}/criteria | ajouter un critère |
| PATCH | /criteria-sets/{id}/criteria/{critere} | modifier un critère |
| DELETE | /criteria-sets/{id}/criteria/{critere} | retirer un critère |
| DELETE | /criteria-sets/{id} | l'élément n'existe plus chez vous : libère une place |
| GET | /criteria-schema | champs, mesures et types de lieux, pour construire l'éditeur |
Anatomie d'un critère
| Champ | Rôle |
|---|---|
id | identifiant stable, a-z 0-9 _, 2 à 64 caractères, unique dans le jeu |
label | libellé affiché, jusqu'à 300 caractères |
is_exclusion | true = rédhibitoire : s'il est vrai, la fiche est éliminée. Le libellé décrit donc le problème (« Prix > 650 000 $ », « Rez-de-chaussée »), jamais le souhait. |
points | poids d'un critère noté : de 1 (petit plus) à 10 (priorité de l'acheteur), jamais plus. Toujours 0 pour une exclusion. |
definition | précision optionnelle, lue par l'IA |
category | regroupement optionnel pour votre affichage |
evaluations | une ou plusieurs façons d'y répondre ; la première qui donne une réponse est retenue |
Trois méthodes d'évaluation
Le moteur exécute les méthodes de la moins coûteuse à la plus coûteuse et s'arrête dès qu'une exclusion est confirmée.
reso_field— comparaison exacte sur un champ de la fiche. Paramètresfield,op(gt,gte,lt,lte,eq) etvalue.signal— une mesure sur l'emplacement. Paramètressignal,op,value, et ceux propres à la mesure (rayon, type de lieu, adresse de destination…).llm— jugé par l'IA. Paramètreinputs:["description"](par défaut),["photos"]ou les deux.
Champs de la fiche (reso_field)
| Champ | Contenu |
|---|---|
list_price | prix affiché |
living_area | surface habitable, dans l'unité du marché |
rooms_total | nombre de pièces |
bedrooms_total | chambres |
bathrooms_total_integer | salles de bain |
year_built | année de construction |
entry_level | étage (0 = rez-de-chaussée) |
lot_size_area | surface du terrain |
association_fee | frais de copropriété, ramenés au mois |
tax_annual_amount | taxes foncières annuelles |
monthly_taxes_and_fees | taxes et frais de copropriété, par mois |
energy_class_rank | classe énergétique (DPE) : A = 1 … G = 7 |
ghg_class_rank | classe climat (GES) : A = 1 … G = 7 |
Mesures sur l'emplacement (signal)
| Mesure | Ce qu'elle renvoie |
|---|---|
metro_walk_minutes | minutes à pied jusqu'à la station de métro la plus proche |
grocery_walk_minutes | minutes à pied jusqu'à l'épicerie la plus proche |
place_walk_minutes | minutes à pied jusqu'au lieu le plus proche d'un type donné (école, parc, pharmacie…) |
place_count | nombre de lieux d'un type donné dans un rayon |
commercial_density_count | densité de commerces et restaurants autour du bien |
commute_minutes | durée du trajet vers une adresse (destination), en voiture, transport, vélo ou à pied (mode) |
osm_nearest_distance_m | distance en mètres à l'élément OpenStreetMap le plus proche (littoral, plage, parc, gare…) |
osm_count | nombre d'éléments OpenStreetMap dans un rayon |
air_quality_index | indice de qualité de l'air |
pollen_index | indice pollinique |
roof_sunshine_hours | heures d'ensoleillement annuelles du toit |
roof_solar_potential_kwh | potentiel solaire du toit |
elevation_m | altitude |
GET /v1/partner/criteria-schema. C'est la référence à utiliser pour construire un éditeur de critères.Recherche de fiches
Quand le courtier lance une recherche pour l'élément, envoyez son jeu de critères (le criteria_id, ou votre external_ref) et les fiches trouvées, jusqu'à 100. Elles sont analysées en parallèle et partagent ce qui peut l'être (même immeuble, même rue).
POST /v1/partner/analyses/batch
{
"criteria_id": "sc-3f9a0c21b7e44d12", // ou "external_ref": "projet-4812"
"properties": [ { "ListingKey": "A-1042", … }, … ], // 1 à 100 fiches
"format": "auto", // auto | reso | mlsconnect
"delivery": "response" // ou "webhook"
}Format des fiches
"format": "reso"— une fiche aux noms de champs RESO Data Dictionary (ListingKey,ListPrice,LivingArea,BedroomsTotal,Latitude,Longitude,PublicRemarks,Media…).- Votre format natif — si votre flux n'est pas au format RESO, nous mettons en place un adaptateur qui lit vos fiches telles que votre système les produit.
"format": "auto"(par défaut) reconnaît le format tout seul.
{
"ListingKey": "A-1042",
"ListPrice": 549000,
"LivingArea": 842,
"BedroomsTotal": 2,
"BathroomsTotalInteger": 1,
"EntryLevel": 3,
"Latitude": 45.5343, "Longitude": -73.5812,
"PublicRemarks": "Condo lumineux au 3e étage, cuisine refaite en 2024…",
"Media": [ { "MediaURL": "https://…/1.jpg" }, { "MediaURL": "https://…/2.jpg" } ]
}Les coordonnées sont nécessaires pour vérifier le périmètre et pour toutes les mesures d'emplacement. Les photos sont lues dans l'ordre, jusqu'à la limite de votre contrat.
Trois façons de recevoir les résultats
| Requête | Ce qui revient |
|---|---|
delivery: "response" (défaut) | tout le résultat à la fin, dans la réponse |
idem + Accept: application/x-ndjson | une ligne par fiche dès qu'elle est prête, puis le résultat complet |
delivery: "webhook" | 202 immédiatement ; chaque fiche arrive en analysis.completed, puis batch.completed |
Le résultat d'une fiche
Le même objet partout — réponse, flux, webhook : le score, une phrase prête à afficher, et dans result le détail de chaque critère.
{
"index": 3,
"listing_ref": "A-1042",
"analysis_id": "5d0c…",
"excluded": false,
"exclusion_reasons": [],
"score": 86, "score_min": 86, "score_max": 86,
"summary": "4 critères remplis sur 5 : Métro à moins de 10 min à pied, Cuisine rénovée, Moins de 30 min du bureau en transport et 1 autre. Manque : Plus de 900 pi².",
"cached": false, "billed": true,
"warnings": [],
"result": {
"score": 86,
"disqualified": false,
"disqualifying_reasons": [],
"total_points_earned": 30, "total_points_possible": 35,
"points_unevaluated": 0,
"breakdown": [
{ "id": "surface_900", "label": "Plus de 900 pi²", "is_exclusion": false,
"points_possible": 5, "points_earned": 0, "passed": false,
"methods": ["reso_field"], "resolved_by": "reso_field", "note": "living_area=842 (gt 900)" },
{ "id": "metro_10", "label": "Métro à moins de 10 min à pied", "is_exclusion": false,
"points_possible": 10, "points_earned": 10, "passed": true,
"methods": ["signal"], "resolved_by": "signal", "note": "station la plus proche à 6 min à pied" },
{ "id": "cuisine_renovee", "label": "Cuisine rénovée", "is_exclusion": false,
"points_possible": 10, "points_earned": 10, "passed": true,
"methods": ["llm"], "resolved_by": "llm", "inputs_used": ["description", "photos"],
"note": "« cuisine refaite en 2024 », comptoirs de quartz visibles en photo 2" },
…
],
"unevaluated_criteria": [],
"skipped_criteria": [],
"explanation": "…",
"llm_explanation": "…"
}
}| Champ | Signification |
|---|---|
score | 0 à 100 : points obtenus ÷ points des critères notés effectivement évalués. 0 si la fiche est éliminée. |
excluded | une exclusion est vraie ; les libellés sont dans exclusion_reasons |
score_min | / score_max : le score si les critères non vérifiables échouaient / réussissaient. score est toujours entre les deux ; égaux quand tout a été vérifié. |
summary | une phrase : ce qui écarte la fiche, ou les critères remplis les plus importants et ce qui manque |
result.breakdown[] | chaque critère : passed (true / false, ou null si la donnée manque), points, resolved_by (la méthode qui a répondu) et note (la valeur ou l'élément sur lequel repose le verdict) |
result.unevaluated_criteria | critères dont l'information n'existe pas ; ils sortent du calcul |
result.skipped_criteria | critères non calculés parce que la fiche était déjà éliminée |
result.llm_explanation | l'explication rédigée par l'IA, quand elle a participé |
warnings | points d'attention sur la fiche (position approximative, location plutôt que vente, photos ignorées…) |
cached | résultat réutilisé, non décompté (voir plus bas) |
Dans la réponse
→ 200
{
"batch_id": "9f2c…",
"criteria_id": "sc-3f9a0c21b7e44d12",
"external_ref": "projet-4812",
"delivery": "response",
"total": 42,
"complete": true,
"excluded": [ { "listing_ref": "A-0977", "exclusion_reasons": ["Prix > 650 000 $"], "result": { … }, … } ],
"ranking": [ { "listing_ref": "A-1042", "score": 86, "summary": "…", "result": { … }, … }, … ],
"rejected": [ { "index": 7, "listing_ref": null, "status": 422, "detail": "Propriété illisible : …" } ],
"failed": [ { "index": 12, "listing_ref": "A-1101", "status": 502, "detail": "…" } ],
"usage": { "analyses_used": 351, "analyses_limit": 1000, … }
}| Champ | Signification |
|---|---|
ranking | les fiches retenues, de la meilleure à la moins bonne (score, puis score_max) |
excluded | les fiches écartées par une exclusion |
rejected | refusées sans frais : illisible (422), hors périmètre (403), en double dans la requête (409) |
failed | analyse échouée de notre côté (502) : non décomptée, à renvoyer |
complete | false si la recherche a été interrompue avant la fin |
Au fil de l'eau
Avec Accept: application/x-ndjson, un objet JSON par ligne. Les lignes listing arrivent dans l'ordre où les analyses se terminent ; index est la position de la fiche dans properties.
POST /v1/partner/analyses/batch
Accept: application/x-ndjson
{"type":"batch","batch_id":"9f2c…","criteria_id":"sc-3f9a…","external_ref":"projet-4812","total":42,"accepted":41,"to_analyse":38,"rejected":[{"index":7,"listing_ref":null,"status":422,"detail":"…"}]}
{"type":"listing","index":3,"listing_ref":"A-1042","score":86,"summary":"…","result":{ … }, …}
{"type":"listing","index":0,"listing_ref":"A-0977","excluded":true,"exclusion_reasons":["Prix > 650 000 $"],"score":0, …}
{"type":"listing_error","index":12,"listing_ref":"A-1101","status":502,"detail":"…"}
…
{"type":"result","result":{ …le corps de la réponse non diffusée… }}const res = await fetch(`${API}/v1/partner/analyses/batch`, {
method: "POST",
headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": "application/json",
Accept: "application/x-ndjson" },
body: JSON.stringify({ criteria_id, properties }),
});
if (!res.ok) throw new Error((await res.json()).detail); // 404, 422, 429… : pas de flux
const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
for (;;) {
const { value, done } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
let nl;
while ((nl = buffer.indexOf("\n")) >= 0) {
const event = JSON.parse(buffer.slice(0, nl));
buffer = buffer.slice(nl + 1);
if (event.type === "listing") showListing(event); // score + détail, dès qu'il est prêt
if (event.type === "listing_error") showFailed(event);
if (event.type === "result") return event.result; // classement final
if (event.type === "error") throw new Error(event.detail);
}
}404, 422, 429…) restent des réponses HTTP ordinaires, sans flux. Fermer la connexion en cours de route abandonne les analyses restantes, non décomptées ; celles qui sont terminées restent enregistrées.Par webhook
POST /v1/partner/analyses/batch
{ "criteria_id": "sc-3f9a0c21b7e44d12", "properties": [ … ], "delivery": "webhook" }
→ 202
{
"batch_id": "9f2c…", "criteria_id": "sc-3f9a0c21b7e44d12", "external_ref": "projet-4812",
"delivery": "webhook",
"total": 42, "accepted": 41, "to_analyse": 38, "cached": 3,
"rejected": [ { "index": 7, "status": 422, "detail": "…" } ],
"usage": { … }
}{
"type": "analysis.completed",
"data": {
"batch_id": "9f2c…", "criteria_id": "sc-3f9a0c21b7e44d12", "external_ref": "projet-4812",
"listing": { "index": 3, "listing_ref": "A-1042", "score": 86, "summary": "…",
"result": { "breakdown": [ … ], … }, … }
}
}
{ "type": "analysis.failed",
"data": { "batch_id": "9f2c…", …, "index": 12, "listing_ref": "A-1101", "status": 502, "detail": "…" } }
{ "type": "batch.completed",
"data": { "batch_id": "9f2c…", "complete": true, "total": 42,
"ranking": [ { "listing_ref": "A-1042", "score": 86, "result": null, … }, … ],
"excluded": [ … ], "rejected": [ … ], "failed": [ … ], "usage": { … } } }- Chaque fiche arrive avec son détail complet.
batch.completedrécapitule le classement sans répéter les détails (result: null). - Une recherche interrompue par un redémarrage de notre côté se termine par
batch.completedaveccomplete: false: renvoyez les fiches que vous n'avez pas reçues — celles déjà analysées sont rejouées gratuitement. GET /analyses/batches/{batch_id}relit à tout moment le résultat d'une recherche, détail compris.
Scores déjà calculés
Chaque analyse est conservée. Quand le courtier ouvre une fiche, ou qu'une liste affiche des fiches déjà notées pour ce jeu, lisez le dernier score enregistré plutôt que de relancer une analyse — c'est gratuit. stale: true signale que les critères ont changé depuis : le score n'est plus à jour, relancez une recherche pour le rafraîchir.
GET /v1/partner/criteria-sets/sc-3f9a0c21b7e44d12/listings/A-1042
→ 200
{
"listing_ref": "A-1042", "analysis_id": "5d0c…",
"score": 86, "score_min": 86, "score_max": 86, "excluded": false,
"summary": "…",
"created_at": "2026-10-22T15:12:40",
"batch_id": "9f2c…",
"stale": false, // true : les critères ont changé depuis cette analyse
"result": { "breakdown": [ … ], … }
}
GET /v1/partner/criteria-sets/sc-3f9a0c21b7e44d12/listings?listing_ref=A-1042&listing_ref=A-0977
→ 200
[ { "listing_ref": "A-1042", "score": 86, "summary": "…", "stale": false, "result": null, … },
{ "listing_ref": "A-0977", "score": 0, "excluded": true, "stale": false, "result": null, … } ]| Méthode | Route | Usage |
|---|---|---|
| GET | /criteria-sets/{id}/listings/{fiche} | dernier score d'une fiche, avec le détail de chaque critère (404 si jamais analysée) |
| GET | /criteria-sets/{id}/listings?listing_ref=… | dernier score de chaque fiche nommée (ou de toutes, les plus récentes d'abord) ; details=true pour inclure le détail |
Votre géocodage (facultatif)
Si votre système connaît déjà la position exacte du bien ou ses lieux proches, joignez-les à la fiche sous scorimmo_geo : Scorimmo s'en sert au lieu de les rechercher.
{
"ListingKey": "A-1042", "ListPrice": 549000, …,
"scorimmo_geo": {
"latitude": 45.53431, "longitude": -73.58124,
"precision": "rooftop", // "rooftop" | "street" | "approximate"
"places": [
{ "type": "subway_station", "name": "Laurier", "walk_minutes": 6 },
{ "type": "supermarket", "name": "IGA", "latitude": 45.5351, "longitude": -73.5838 },
{ "type": "park", "name": "Parc Laurier", "distance_m": 420 }
]
}
}- Les coordonnées remplacent celles de la fiche (sauf
precision: "approximate"). - Chaque lieu de
placesa untypedu vocabulaireplace_typeset au moins un de :walk_minutes(pris tel quel),distance_m(à vol d'oiseau, le temps de marche en est estimé) ou ses coordonnées. - Un
scorimmo_geomal formé est ignoré, avec un avertissement.
Ce qui est décompté
- Une analyse décomptée = une fiche analysée dans une recherche.
- Ré-analyse gratuite pendant 24 h : la même fiche, avec les mêmes données, analysée avec le même jeu de critères dans les 24 h est rejouée (
cached: true,billed: false). Les champs purement administratifs (dates de mise à jour…) n'y changent rien ; une modification du prix, de la surface, de la description, des photos ou des critères déclenche une nouvelle analyse. - Tout ou rien : si le quota restant ne couvre pas toutes les fiches à analyser d'une recherche, rien n'est lancé (
429). - Jamais décompté : une fiche hors périmètre, illisible ou en double, une analyse qui échoue de notre côté, les liens de critères, la génération des critères et la lecture des fichiers de l'acheteur, la lecture des scores enregistrés.
Erreurs
Toutes les erreurs ont la forme {"detail": "message"}.
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{ "detail": "Trop de requêtes : 60 par minute au maximum." }| Code | Signification |
|---|---|
401 | jeton absent, invalide ou révoqué |
403 | compte désactivé |
404 | jeu, critère, lien, envoi ou recherche introuvable (ou appartenant à une autre société) |
409 | limite de jeux atteinte, identifiant de critère déjà utilisé, ou aucun webhook configuré |
422 | données invalides : critère inévaluable, URL de webhook refusée, plus de 100 fiches, criteria_id et external_ref ensemble |
429 | quota mensuel insuffisant, ou trop de requêtes par minute (voir Retry-After) |
Exemple complet
API=https://… # adresse communiquée avec votre jeton
TOKEN=smk_live_…
H=(-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json")
# 0. une fois : votre webhook (gardez le secret renvoyé)
curl -s -X PUT $API/v1/partner/webhook "${H[@]}" \
-d '{"url":"https://crm.example.com/hooks/scorimmo"}' | jq -r .secret
# 1. le courtier clique : un lien pour le projet 4812
curl -s -X POST $API/v1/partner/criteria-links "${H[@]}" \
-d '{"external_ref":"projet-4812","name":"Projet condo Plateau"}' | jq -r .url
# 2. l'acheteur remplit le lien → criteria_set.updated arrive sur votre webhook
# 3. une recherche : les fiches, classées, avec le détail
curl -s -X POST $API/v1/partner/analyses/batch "${H[@]}" \
-d "{\"external_ref\":\"projet-4812\",\"properties\":$(cat fiches.json)}" \
| jq '.ranking[] | {listing_ref, score, summary}'