📖 API Radar

API REST JSON, asynchrone pour les traitements longs, documentée en OpenAPI. Tout ce que fait l'interface est faisable par API.

1. Authentification

Crée une clé API (Bearer) dans /keys.

curl -H "Authorization: Bearer rk_12_xxxxxxxx" https://radar.artisan-digital.eu/api/v1/me

2. Parcours type

# Créer et lancer une prospection (scan → sites → audit) — HTTP 201, renvoie search + job
curl -X POST https://radar.artisan-digital.eu/api/v1/searches \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"address":"Place Bellecour, Lyon","radius_m":800,"category":"resto","deep":true,"external_ref":"crm:42"}'

# Suivre le job (progress 0-100, status queued|running|done|failed)
curl -H "Authorization: Bearer $KEY" https://radar.artisan-digital.eu/api/v1/jobs/123

# Récupérer les prospects (JSON, ou format=csv / format=geojson), cibles prioritaires seulement
curl -H "Authorization: Bearer $KEY" "https://radar.artisan-digital.eu/api/v1/searches/7/prospects?target=1&sort=opportunity"

# Mettre à jour le suivi d'un prospect depuis votre CRM
curl -X PATCH https://radar.artisan-digital.eu/api/v1/prospects/4242 -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"status":"contacted","notes":"RDV mardi 10h"}'

3. Webhooks

À la fin d'un job, Radar POSTe l'événement sur l'URL de ta clé (ou de ton compte). Vérifie la signature avant de traiter.

POST https://votre-logiciel/hook
X-Radar-Event: job.done
X-Radar-Signature: t=1761420000,v1=<hex HMAC-SHA256(secret, t + "." + body)>

{"event":"job.done","job":{"id":123,"type":"pipeline","status":"done","search_id":7,"result":{...}},"sent_at":"…"}

4. Intégrations

• n8n / Make / Zapier : nœud HTTP Request avec l'en-tête Bearer ; déclencheur Webhook pour recevoir job.done.
• Google Sheets / Excel : GET …/prospects?format=csv (import « depuis le web »), ou l'export CSV du tableau.
• SIG / QGIS / uMap : GET …/prospects?format=geojson.
• CRM : external_ref pour rattacher une prospection à votre fiche client, PATCH /prospects/{id} pour synchroniser les statuts.
• Intégration en iframe : https://radar.artisan-digital.eu/embed?external_ref=… (sans chrome). SSO possible via jeton signé (voir /sso, secret partagé fourni par Artisan Digital).

5. Limites & bonnes pratiques

Par compte : 240 lectures/min, 300 écritures/h, 60 jobs/h, 60 géocodages/min. Les scans sont mis en cache 24 h par zone, les audits 30 j par domaine : relancer coûte peu. Les données proviennent de sources publiques (OSM, SIRENE) — vérifie un site « deviné » avant de l'utiliser.

6. OpenAPI

openapi.yaml — importable dans Postman, Insomnia, n8n, ou tout générateur de client.