> ## Documentation Index
> Fetch the complete documentation index at: https://doc.fluximmo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Foire aux questions

> Réponses aux 15 questions les plus fréquentes — onboarding, propriétés vs adverts, webhooks, rate limits, billing.

Cette page regroupe les questions revenant le plus souvent en intégration. Pour un sujet précis, suivez le lien vers la page dédiée.

## Onboarding

<AccordionGroup>
  <Accordion title="Comment obtenir une clé API test ?">
    Créez un compte sur [my.fluximmo.io](https://my.fluximmo.io). Une clé test est générée automatiquement, valable **1 semaine**, sans carte bancaire. Voir [Authentification](/authentification).
  </Accordion>

  <Accordion title="Quelle est la limite de la clé test ?">
    Quotas réduits (\~5 req/s, valable 7 jours) mais accès **complet** aux modules Search, Refetch, Analytics, IA et Géocodage. Seule restriction : la **création d'alertes webhook** se fait sur demande (par mail à [contact@fluximmo.com](mailto:contact@fluximmo.com)). Suffisante pour coder et valider une intégration de bout en bout.
  </Accordion>

  <Accordion title="Comment passer en production ?">
    Activation depuis votre espace client [my.fluximmo.io](https://my.fluximmo.io) — onglet **API**. Pas d'engagement initial, pas de paiement avant validation de votre intégration. Pour un besoin custom (volume élevé, endpoints non publics, devis sur-mesure), écrivez à [contact@fluximmo.com](mailto:contact@fluximmo.com).
  </Accordion>

  <Accordion title="Y a-t-il une période d'engagement ?">
    Aucun engagement initial. Le pricing se fait au volume, et les conditions custom sont fixées au cas par cas selon votre besoin.
  </Accordion>
</AccordionGroup>

## Property vs Advert

<AccordionGroup>
  <Accordion title="Quand utiliser /properties vs /adverts ?">
    * **`/properties`** : un objet par bien physique unique (dédupliqué). Idéal pour de la BDD, du matching, des analytics.
    * **`/adverts`** : un objet par annonce publiée (un même bien peut générer plusieurs adverts). Idéal pour suivre la diffusion, les changements de prix, les portails.

    Voir la [matrice de décision](/concepts/property-vs-advert).
  </Accordion>

  <Accordion title="Comment savoir quel endpoint utiliser ?">
    Posez-vous la question : *« j'ai besoin du bien ou de l'annonce ? »*. Si la réponse contient "diffusion", "portail", "prix qui change", "republication" → adverts. Sinon → properties.
  </Accordion>

  <Accordion title="Pourquoi le webhook properties n'envoie que des IDs ?">
    Les webhooks Properties livrent uniquement le `flxId` pour optimiser le débit. Vous appelez ensuite `GET /v2/protected/properties/{flxId}` (ou `POST /v2/protected/properties/_many` pour le bulk) pour récupérer la donnée fraîche. Voir [Webhooks](/concepts/webhooks).
  </Accordion>
</AccordionGroup>

## Webhooks & alertes

<AccordionGroup>
  <Accordion title="Comment éviter de perdre des webhooks ?">
    * Acquitter en **moins d'1 seconde** avec un code 2xx (200-205).
    * Mettre la logique métier en file d'attente côté worker (NE PAS traiter dans le handler HTTP).
    * Implémenter une logique **UPSERT par flxId** pour absorber les retries.

    Voir [Livraison des webhooks](/ressources/webhooks-livraison) et le playbook [Architecture haut volume](/playbooks/webhook-volume-architecture).
  </Accordion>

  <Accordion title="Pourquoi je reçois plusieurs fois le même webhook ?">
    La politique de retry peut livrer le même payload deux fois (ex : ack > 1s côté client, ou réponse 5xx transitoire). C'est attendu : votre logique de persistance doit être **idempotente** (UPSERT par `flxId`).
  </Accordion>

  <Accordion title="Que se passe-t-il si je delete + recrée mon alerte ?">
    Le cycle de vie redémarre à zéro : vous re-recevrez les matches initiaux. Pour modifier les critères sans re-livraison, **mettez à jour l'alerte existante** plutôt que de la recréer. Voir [Cycle de vie d'une alerte](/concepts/match-types-cycle-alerte).
  </Accordion>
</AccordionGroup>

## Filtres & géographie

<AccordionGroup>
  <Accordion title="Pourquoi le filtre `city` ne fonctionne pas ?">
    Le filtre `location[].city` est **ignoré** par le moteur. Utilisez `postalCode`, `inseeCode` ou `department`. Voir [Recherche géographique](/concepts/recherche-geographique).
  </Accordion>

  <Accordion title="Comment chercher dans plusieurs zones ?">
    Le tableau `location[]` accepte plusieurs entrées combinées en OR. Mélangez codes postaux, INSEE, départements et bbox/distance dans une même requête.
  </Accordion>

  <Accordion title="Quel mode geo choisir entre bbox et distance ?">
    * **`geoBoundingBox`** : pour des zones administratives ou rectangulaires (carte, secteur agence). Cohérence des bornes (`topLeft` au-dessus et à gauche de `bottomRight`) validée runtime côté serveur.
    * **`geoDistance`** : pour un rayon autour d'un point (recherche client, point de vente). `distanceKm` strictement positif (validé runtime côté serveur).
  </Accordion>
</AccordionGroup>

## Billing & support

<AccordionGroup>
  <Accordion title="Comment voir ma consommation ?">
    Endpoint dédié : [`GET /v2/protected/admin/consumption`](/api-v2-reference/consumption/get-your-credit-consumption) (paramètres requis : `from_date`, `to_date`). Le dashboard my.fluximmo.io affiche aussi un récapitulatif.
  </Accordion>

  <Accordion title="Quels endpoints ne sont pas exposés publiquement ?">
    Certains endpoints de niche (Market analytics avancé, Properties analytics avancé, Agences, etc.) ne figurent pas dans la documentation publique par défaut. Ils peuvent être ajoutés à votre clé sur demande, ou faire l'objet d'un sur-mesure (devis). Détails dans la [matrice des capabilities](/api-reference/capabilities-sur-demande).
  </Accordion>

  <Accordion title="Comment contacter le support ?">
    [contact@fluximmo.com](mailto:contact@fluximmo.com) — incluez votre `clientId`, l'endpoint concerné, un exemple de requête et la réponse reçue.
  </Accordion>
</AccordionGroup>

<Card title="Clé test gratuite — 1 semaine" icon="key" href="https://my.fluximmo.io">
  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.
</Card>