Skip to main content
Retrieve a property by url

À quoi ça sert

GET /v2/protected/properties/url?url=… prend l’URL d’une annonce portail et retourne la property qui l’agrège. Une property est un bien physique dédupliqué qui regroupe N adverts, les annonces publiées sur des portails différents (voir Property vs Advert) : vous partez donc d’un lien leboncoin, seloger ou autre, et vous récupérez le bien complet côté Fluximmo. Si l’annonce est déjà indexée et déjà rattachée à une property, celle-ci part immédiatement. Sinon — annonce inconnue, ou connue mais pas encore rattachée — elle est collectée à la demande et la requête attend que la chaîne annonce → property soit complète.
Cette route peut bloquer jusqu’à ~45 secondes avant de répondre, le temps de la collecte. Réglez le timeout de votre client HTTP au-dessus de cette valeur — un timeout à 10 ou 30 s vous fera manquer des réponses valides. Ne parallélisez pas des dizaines d’appels : voir Limites et rate limits.

Facturation

1 crédit, uniquement quand un document est renvoyé (200). Les réponses 202 et 422 ne sont pas facturées : une URL qui n’aboutit pas ne vous coûte rien.
Aucune déduplication côté serveur. Deux appels concurrents sur la même url déclenchent deux collectes, et deux crédits si les deux répondent 200. Dédupliquez vos appels sur une même url avant de les émettre.

Cas d’usage

  • Enrichir un lien collé par un utilisateur — votre utilisateur colle une URL d’annonce, vous affichez le bien normalisé, géolocalisé et dédupliqué.
  • Rattacher votre base à Fluximmo — retrouver le flx_id de biens que vous suivez déjà par leur URL portail.
  • Amorcer un suivi — récupérer la property puis surveiller ses évolutions via une alerte ou un webhook.
Le contrat exact est documenté plus bas par le bloc OpenAPI (GET /v2/protected/properties/url).

Les trois issues possibles

1

200 — la property est disponible

Le corps contient la property complète, enveloppée : {"data": { … }}. 1 crédit décompté.
2

202 — collecte faite, indexation en cours

L’annonce a été collectée mais la chaîne annonce → property n’est pas encore complète. Réessayez la même url après retry_after_s secondes. Cette valeur est dans le corps : il n’y a pas d’en-tête HTTP Retry-After.
3

422 — rejetée par l'ingestion

L’annonce a été collectée mais refusée (données incohérentes ou manquantes, hors périmètre). Elle ne deviendra jamais disponible : ne réessayez pas, retirez l’url de votre file.
Deux réponses portent le code 422 sur cette route, et elles n’ont rien à voir. Le 422 de validation est une vraie erreur, non enveloppée : {"error":{"message":"Url query parameter must be a valid http(s) url","code":10002}} — même message que le paramètre soit absent, vide ou mal formé ; branchez tout de même sur le code 10002, pas sur le libellé. Le 422 de rejet d’ingestion est une réponse métier, enveloppée dans data et porteuse d’un status. Fiez-vous à la clé racine : error contre data.

Exemples

1 — Résoudre une URL leboncoin

En 200, le corps est la property elle-même sous data. Notez le --max-time 60 / timeout=60 : c’est le point à ne pas rater.

2 — Distinguer un 202 d’un 422 d’ingestion

Réponse 202 — à réessayer dans 120 s
Réponse 422 — définitif, ne pas réessayer
Un client correct branche sur status : pending → replanifier le même appel après retry_after_s, rejected_by_ingestion → abandonner définitivement cette url. website_ref sert à corréler un retry, mais peut valoir null : ne le prenez pas comme clé obligatoire.

Erreurs spécifiques

  • 404 — portail non couvert, url invalide, ou url ne désignant pas une annonce unique (page de recherche, url tronquée). Enveloppe d’erreur classique.
La liste complète des codes est sur Codes d’erreur.

Liens utiles

Clé test gratuite — 1 semaine

Créez un compte sur my.fluximmo.io pour récupérer une clé API test gratuite (1 semaine, accès limité). Aucun paiement requis.

Authorizations

x-api-key
string
header
required

Query Parameters

url
string
required

Url of an advert to get the associated property

Response

data
object