Documentation API — v1

L'API Web-Client Radar

API REST autonome. Tout ce que fait l'interface passe par ces endpoints — tu peux intégrer le radar à ton CRM, tes scripts ou tes automatisations (n8n, Make…). Base URL en développement local : http://localhost:4000.

Authentification

Toutes les routes protégées attendent un header Authorization: Bearer <token>. Deux types de tokens :

Préfixe	Type	Obtention	Portée
`wcr_sess_…`	Session web (30 jours)	login / register	tout, y compris gestion du compte
`wcr_live_…`	Clé API	dashboard → « Créer une clé API »	recherche, scoring, solde — pas la gestion du compte

La clé API n'est affichée qu'une seule fois à sa création : seul son hachage SHA-256 est conservé. Perdue = à révoquer puis recréer.

Jetons

1 jeton = 1 sous-cercle balayé (jusqu'à 60 établissements analysés). Une recherche avec sub_circles: 16 coûte 16 jetons, débités avant exécution et remboursés automatiquement si la recherche échoue. Le scoring seul (/v1/score) est gratuit.

Endpoints

POST /v1/auth/register

Crée un compte et retourne une session. 25 jetons offerts.

curl -X POST http://localhost:4000/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"toi@exemple.fr","password":"8 caractères minimum"}'

# → {"token":"wcr_sess_…","expires_at":"…","balance":25}

POST /v1/auth/login

Mêmes paramètres, mêmes retours. POST /v1/auth/logout pour révoquer la session.

GET /v1/me

Email, date de création, solde de jetons. Fonctionne en session ou clé API.

POST /v1/search

Le cœur du service : balaye la zone, filtre les commerces déjà équipés d'un site, retourne les leads déjà notés et triés.

Champ	Type	Détail
`query`	string, requis	ville, quartier ou adresse (géocodée par Google)
`radius`	int, requis	rayon principal en mètres (100 – 50 000)
`sub_circles`	int, requis	nombre de sous-cercles (1 – 100) = coût en jetons
`tags`	string[]	types Google Places (défaut : `["restaurant"]`)
`weights`	object	poids du score : `popularity`, `financial`, `growth`, `marketing`
`stream`	bool	`true` (défaut) : flux NDJSON · `false` : JSON unique

curl -N http://localhost:4000/v1/search \
  -H "Authorization: Bearer wcr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"query":"Nantes centre","radius":5000,"sub_circles":16,
       "tags":["restaurant","cafe"],"weights":{"growth":40}}'

# flux NDJSON, une ligne JSON par événement :
{"type":"log","level":"info","message":"Géocodage de « Nantes centre »…"}
{"type":"log","level":"progress","message":"Balayage 4/16 — 87 lieux uniques","current":4,"total":16}
{"type":"done","count":23,"tokens_spent":16,"balance":384,"data":[…]}

Chaque élément de data est un lieu Google Places (New) enrichi de score (0–100) et score_breakdown (valeur, poids et contribution de chaque composante).

Erreurs : 402 solde insuffisant · 403 service fermé au public (voir plus bas) · 429 limite de débit (5 recherches/min) · en cas d'échec en cours de balayage, l'événement {"type":"error","refunded":…} confirme le remboursement.

POST /v1/score

Note et trie une liste de lieux Google Places (New) que tu possèdes déjà. Gratuit, limité à 5 000 lieux et 30 requêtes/min.

curl -X POST http://localhost:4000/v1/score \
  -H "Authorization: Bearer wcr_live_…" \
  -H "Content-Type: application/json" \
  -d '{"places":[…], "weights":{"popularity":50,"marketing":10}}'

GET /v1/pricing · GET /v1/config

Publics : packs et prix, poids par défaut du score, limites de l'API.

GET /v1/account/usage · GET/POST/DELETE /v1/account/keys · POST /v1/billing/checkout

Gestion du compte — session web uniquement (une clé API volée ne peut ni créer d'autres clés, ni dépenser d'argent).

Fermeture au public

Le service peut être temporairement fermé au public. L'achat de jetons et les routes de l'outil (/v1/search, /v1/score, /v1/account/state, /v1/reverse-geocode) répondent alors 403 avec {"code":"service_disabled"}. Pour le savoir à l'avance : GET /v1/pricing renvoie "purchases_enabled": false, et GET /v1/me indique dans service_access si ton compte a accès à l'outil. Ton solde de jetons est conservé.

Limites de débit

Groupe	Limite
auth (register/login)	10 requêtes / min / IP
search	5 requêtes / min / compte
score	30 requêtes / min / compte

Au-delà : 429 avec header Retry-After.

Bonnes pratiques

Stocke ta clé API côté serveur, jamais dans du code front exposé.
Pour couvrir une ville : rayon 5 000 m et 16 sous-cercles est un bon départ.
Le flux NDJSON te donne la progression en direct — idéal pour une UI ; passe stream:false pour un script simple.
Réutilise /v1/score pour re-trier les mêmes résultats avec d'autres poids : c'est gratuit.