Connecter votre site

La Website API permet à une agence de garder son propre site internet et d'utiliser Hussteer comme source de ses biens et réceptacle de ses prospects. Trois capacités : lire les biens publiables, envoyer un prospect, être prévenu quand une annonce change.

1. Créer une intégration

Dans Hussteer : Réglages → Website API → « Créer une intégration ». Seul un administrateur de l'agence peut le faire. Donnez un nom (celui du site), l'adresse du site, et — si vous voulez des webhooks — l'URL de réception.

2. Client ID et Client Secret

À la création, Hussteer affiche un Client ID et un Client Secret. Le Client ID identifie l'intégration et peut être conservé en clair. Le Client Secret, lui, ne s'affiche QU'UNE FOIS : Hussteer n'en garde qu'une empreinte et ne peut pas vous le redonner. Si vous le perdez, régénérez-le — l'ancien cesse alors immédiatement de fonctionner.

3. Obtenir un jeton d'accès

Échangez vos identifiants contre un jeton valable une heure. C'est le flux OAuth 2.0 « client_credentials » (RFC 6749 §4.4) — et lui seul : il n'existe ni code d'autorisation, ni jeton de rafraîchissement, ni connexion d'un utilisateur tiers.

{
  "grant_type": "client_credentials",
  "client_id": "hus_client_example",
  "client_secret": "hus_secret_example"
}

curl -X POST 'https://hussteer.com/api/v1/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "hus_client_example",
    "client_secret": "hus_secret_example"
  }'

{
  "access_token": "hus_at_example",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "properties:read leads:write"
}

Réutilisez le même jeton pendant sa durée de vie : en redemander un à chaque visiteur épuiserait votre quota. Quand il expire, l'API rend 401 — redemandez-en un et rejouez l'appel.

Portées

• properties:read — lire les biens publiables de votre agence.
• leads:write — déposer un prospect.
• webhooks:manage — réservé : la V1 gère les webhooks depuis l'écran Hussteer.
• Le paramètre `scope` ne peut que RESTREINDRE : demander une portée non accordée ne l'accorde pas.

Erreurs

Toutes les erreurs ont la même forme. Branchez votre logique sur `error.code` — il est stable ; le message, lui, peut être réécrit.

{ "error": { "code": "invalid_token", "message": "Jeton absent, expiré ou révoqué." } }

• 400 invalid_request — requête mal formée, ou curseur illisible.
• 401 invalid_client — identifiants refusés. La réponse est identique que le client soit inconnu, le secret faux ou l'intégration révoquée.
• 401 invalid_token — jeton absent, expiré ou révoqué.
• 403 insufficient_scope — l'intégration n'a pas ce droit.
• 404 not_found — inexistant, d'une autre agence, ou non publiable : indistinctement.
• 413 payload_too_large — corps de requête au-delà de 16 Ko.
• 422 unprocessable — données refusées ; `error.fields` dit quel champ.
• 429 rate_limited — trop de requêtes ; voir `Retry-After`.
• 503 unavailable — indisponibilité temporaire ; réessayez.

Limite d'appels

Par intégration et par minute : 300 lectures, 30 écritures, 30 demandes de jeton. Ces bornes protègent le service d'un emballement — elles ne sont pas un quota commercial. Chaque réponse porte X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; une 429 porte en plus Retry-After.

Sécurité

• Le jeton détermine l'agence : aucun paramètre de requête ne peut la désigner, et un jeton ne voit jamais les données d'une autre agence.
• Révoquer une intégration coupe l'accès au prochain appel, sans attendre l'expiration du jeton.
• Régénérer le secret invalide immédiatement l'ancien et tous les jetons qu'il avait produits.
• HTTPS uniquement, en entrée comme en sortie.