Documentation de l’API

Codes d’erreur

Toutes les erreurs ont la même forme, et un code stable. Testez le code, pas le message.

L’indicateur d’aides

Trois états, calculés à partir de l’âge et de la situation fiscale. Ce n’est pas une décision d’éligibilité : seule l’Anah décide.

Recevoir les leads dans votre CRM

Vous n’êtes pas obligé d’interroger l’API : la plateforme peut pousser chaque lead acheté vers l’adresse de votre choix, dès l’achat. C’est ce qu’attendent Zapier, Make, n8n ou un script maison, et à travers eux n’importe quel CRM.

1. Dans votre espace, page API et CRM, enregistrez une adresse HTTPS.
2. Cliquez « Envoyer un test » : un lead fictif arrive, au même format que les vrais.
3. À chaque achat, un POST JSON part vers cette adresse. Trois tentatives en cas d’échec, puis le résultat est visible sur la même page.

POST https://votre-crm.exemple/senior24
Content-Type: application/json
X-Senior24-Evenement: achat
X-Senior24-Signature: t=1788790000,v1=…

{
  "evenement": "achat",
  "envoyeLe": "2026-09-07T12:00:00.000Z",
  "partenaireId": "…",
  "leads": [
    {
      "id": "…", "venteId": "…", "acheteLe": "2026-09-07T12:00:00.000Z",
      "metier": "monte_escalier", "departement": "69", "codePostal": "69003",
      "delai": "urgent", "age": "oui", "imposable": "non",
      "indicateur": "probable", "niveauAide": "taux_plein",
      "donneesMetier": { "typeEscalier": "tournant", "niveaux": "1" },
      "qualification": { "occupation": "proprietaire", "aide": "depose", "moment": "matin" },
      "prixCredits": 90,
      "nom": "…", "telephone": "…", "email": "…",
      "autresCoordonnees": []
    }
  ]
}

Répondez avec un code 2xx. Tout autre code est compté comme un échec ; un 4xx n’est pas réessayé.

Événement « complement »

Un demandeur refait parfois sa demande avec un autre numéro ou une autre adresse, par exemple pour corriger une faute de frappe. La plateforme reconnaît la même personne, ne crée pas de second lead, et garde les nouvelles coordonnées avec le lead d’origine. Si vous aviez déjà acheté ce lead, vous recevez le même envoi avec "evenement": "complement" et le lead complet : autresCoordonnees liste alors chaque jeu reçu après coup (nom, telephone, email, codePostal, recuLe), du plus ancien au plus récent. Le champ est aussi présent dans /api/v1/leads/achetes et dans la réponse d’achat.

Vérifier la signature

La signature est t=<secondes>,v1=<hex>, où v1 est le HMAC-SHA256 de la chaîne t + "." + corps avec votre secret, affiché sur la page API et CRM. Refusez un envoi dont t a plus de cinq minutes.

// Node.js
const [t, v1] = signature.split(',').map((p) => p.split('=')[1]);
const attendu = crypto.createHmac('sha256', SECRET).update(t + '.' + corpsBrut).digest('hex');
const valide = attendu === v1 && Math.abs(Date.now() / 1000 - Number(t)) < 300;

L’ordre d’arrivée décide

Chaque lead n’est vendu qu’une fois, et tout le monde voit le catalogue en même temps. Le premier qui achète l’emporte. Interrogez souvent, achetez sans attendre.

Conseils

• Interrogez souvent, achetez tout de suite. Toutes les cinq minutes suffit. Ce qui compte, c’est de ne pas attendre entre la lecture et l’achat.
• Ne rejouez pas un achat après un délai réseau. Interrogez d’abord /api/v1/leads/achetes : si le lead y est, l’achat a abouti.
• Stockez l’identifiant du lead. Il ne change jamais.
• Traitez la situation fiscale comme une donnée personnelle. Elle vous est transmise pour qualifier le dossier de financement, rien d’autre.