Introduction

L'API REST de Suivi Prospects te permet de lire et d'écrire les prospects de ton compte depuis n'importe quel serveur. Elle est réservée aux comptes Pro : si l'abonnement expire, l'API répond 403 pro_required.

• Format : JSON (UTF-8), Content-Type: application/json pour les requêtes avec corps.
• Version : v1 (incluse dans l'URL). Les ajouts de champs ne casseront pas la v1.
• Accès limité à ton compte : une clé ne voit jamais les données d'un autre utilisateur.

URL de base

Copier

Authentification

Chaque requête envoie la paire de clés dans deux en-têtes HTTP :

CopierX-Public-Key: pk_xxxxxxxxxxxxxxxxxxxxxxxx
X-Secret-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

La clé secrète n'est jamais stockée en clair chez nous (seule son empreinte SHA-256 l'est). Stocke-la dans une variable d'environnement de ton serveur, jamais dans le code source ni côté navigateur.

Permissions (scopes)

Une clé sans la permission requise reçoit 403 insufficient_scope.

Test rapide

Copiercurl "/me" \
  -H "X-Public-Key: $SP_PUBLIC_KEY" \
  -H "X-Secret-Key: $SP_SECRET_KEY"

L'objet Prospect

Les champs inconnus sont ignorés. Envoyer null ou "" vide un champ.

Copier{
  "id": "3f1c9a52-8d1e-4c36-9b0a-6d1c2e7f4a10",
  "external_id": "crm-48213",
  "prenom": "Camille",
  "nom": "Durand",
  "pseudo": "@camille.d",
  "ville": "Lyon",
  "age": 34,
  "situation_pro": "Infirmière",
  "statut": "Chaud",
  "premier_msg": "2026-10-12",
  "dernier_echange": "2026-10-13",
  "prochaine_relance": "2026-10-16",
  "freins": "Manque de temps",
  "notes": "Vient de la campagne Instagram d'octobre",
  "custom": { "campagne": "oct-2026", "source": "instagram" },
  "created_at": "2026-10-13T09:12:44.120Z",
  "updated_at": "2026-10-13T09:12:44.120Z"
}

Lister les prospects GET /prospects

Paramètres de requête (tous optionnels) :

Copiercurl "/prospects?statut=Chaud&limit=20" \
  -H "X-Public-Key: $SP_PUBLIC_KEY" -H "X-Secret-Key: $SP_SECRET_KEY"

Copier{
  "data": [ { …prospect… }, … ],
  "pagination": { "total": 128, "limit": 20, "offset": 0, "has_more": true }
}

Lire un prospect GET /prospects/{id}

Par identifiant Suivi Prospects. Pour utiliser ton propre identifiant : GET /prospects?external_id=crm-48213 (renvoie une liste de 0 ou 1 élément).

Copiercurl "/prospects/3f1c9a52-8d1e-4c36-9b0a-6d1c2e7f4a10" \
  -H "X-Public-Key: $SP_PUBLIC_KEY" -H "X-Secret-Key: $SP_SECRET_KEY"

Réponse : { "data": { …prospect… } } — 404 not_found si absent.

Ajouter / mettre à jour POST /prospects

Accepte un objet, un tableau ou { "prospects": [ … ] } (100 maximum par requête). Si un prospect fournit un external_id déjà connu, il est mis à jour (seuls les champs envoyés changent ; custom est fusionné) au lieu d'être dupliqué. Tu peux donc rejouer un envoi sans risque.

Copiercurl -X POST "/prospects" \
  -H "X-Public-Key: $SP_PUBLIC_KEY" -H "X-Secret-Key: $SP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "crm-48213",
    "prenom": "Camille",
    "nom": "Durand",
    "ville": "Lyon",
    "statut": "Chaud",
    "premier_msg": "2026-10-12",
    "prochaine_relance": "2026-10-16",
    "custom": { "campagne": "oct-2026" }
  }'

Réponse unitaire : 201 (créé) ou 200 (mis à jour) avec { "data": {…}, "status": "created" | "updated" }.

Réponse en lot :

Copier{
  "data": [ {…}, {…} ],
  "results": [ { "index": 0, "status": "created", "id": "…" }, { "index": 1, "status": "updated", "id": "…" } ],
  "summary": { "created": 1, "updated": 1 }
}

Un lot est validé en entier avant écriture : une erreur de validation (422) rejette tout le lot et indique l'indice fautif (prospects[3] : …).

Modifier PATCH /prospects/{id}

Modification partielle : seuls les champs envoyés changent. Dans custom, les clés sont fusionnées ; une clé à null est supprimée. Alternative sans connaître l'id : PATCH /prospects?external_id=crm-48213.

Copiercurl -X PATCH "/prospects?external_id=crm-48213" \
  -H "X-Public-Key: $SP_PUBLIC_KEY" -H "X-Secret-Key: $SP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "statut": "Client", "dernier_echange": "2026-10-14" }'

Retirer DELETE /prospects/{id}

Nécessite le scope delete. Suppression définitive. Aussi possible par DELETE /prospects?external_id=…. Réponse : { "deleted": true, "id": "…" }.

Suppression en lot POST /prospects/delete

Copiercurl -X POST "/prospects/delete" \
  -H "X-Public-Key: $SP_PUBLIC_KEY" -H "X-Secret-Key: $SP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_ids": ["crm-48213", "crm-48214"] }'

Corps : ids (UUID) ou external_ids, 100 maximum. Réponse : { "deleted": 2, "ids": ["…", "…"] }. Les identifiants inconnus sont simplement ignorés.

Configuration et statistiques

GET /config

Tes statuts et champs personnalisés — pour que ton application utilise exactement les mêmes valeurs.

Copier{ "data": {
    "statuses": [ { "value": "Chaud", "color": "#E94B3C", "bg": "#FBE3DF" }, … ],
    "custom_fields": [ { "key": "campagne", "label": "Campagne", "type": "text" } ]
} }

GET /stats

Copier{ "data": { "total": 128, "by_status": { "Chaud": 12, "Froid": 40, "": 3 } } }

GET /me

Vérifie qu'une paire de clés fonctionne et renvoie ses permissions.

Erreurs et limites

Toute erreur a la forme { "error": { "code": "…", "message": "…" } }.

Limite : 120 requêtes par minute et par clé (en-têtes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). Pour importer beaucoup de prospects, utilise les lots de 100.

Exemples d'intégration

Node.js / TypeScript (côté serveur)

Copierconst BASE = '';
const headers = {
  'X-Public-Key': process.env.SP_PUBLIC_KEY,
  'X-Secret-Key': process.env.SP_SECRET_KEY,
  'Content-Type': 'application/json',
};

async function sp(method, path, body) {
  const res = await fetch(BASE + path, { method, headers, body: body ? JSON.stringify(body) : undefined });
  const json = await res.json();
  if (res.status === 429) { // trop de requêtes : on attend puis on réessaie
    await new Promise(r => setTimeout(r, (+res.headers.get('Retry-After') || 5) * 1000));
    return sp(method, path, body);
  }
  if (!res.ok) throw new Error(`${json.error.code}: ${json.error.message}`);
  return json;
}

// Ajouter / mettre à jour un lead de campagne (idempotent grâce à external_id)
await sp('POST', '/prospects', {
  external_id: 'crm-48213', prenom: 'Camille', nom: 'Durand',
  statut: 'Chaud', custom: { campagne: 'oct-2026' },
});

// Passer le prospect en « Client »
await sp('PATCH', '/prospects?external_id=crm-48213', { statut: 'Client' });

// Le retirer de la liste
await sp('DELETE', '/prospects?external_id=crm-48213');

// Relire les prospects modifiés depuis hier
const { data } = await sp('GET', '/prospects?updated_since=2026-10-12T00:00:00Z&limit=200');

PHP

Copier$ch = curl_init('/prospects');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'X-Public-Key: ' . getenv('SP_PUBLIC_KEY'),
    'X-Secret-Key: ' . getenv('SP_SECRET_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'external_id' => 'crm-48213', 'prenom' => 'Camille', 'statut' => 'Chaud',
  ]),
]);
$res = json_decode(curl_exec($ch), true);

Python

Copierimport os, requests

H = {"X-Public-Key": os.environ["SP_PUBLIC_KEY"], "X-Secret-Key": os.environ["SP_SECRET_KEY"]}
r = requests.post("/prospects", headers=H,
                  json={"external_id": "crm-48213", "prenom": "Camille", "statut": "Chaud"})
r.raise_for_status()
print(r.json()["data"]["id"])

Bonnes pratiques de sécurité

• Garde la clé secrète côté serveur uniquement (variable d'environnement). Si elle fuite : révoque-la ici, crée-en une nouvelle.
• Une clé par application / environnement, avec le minimum de permissions (lecture seule si tu ne fais que consulter).
• Utilise une expiration pour les clés temporaires.
• Utilise toujours external_id pour tes envois automatiques : un rejeu ne crée pas de doublons.
• Les données importées via l'API apparaissent immédiatement dans l'application desktop (rafraîchis la liste) et dans ton compte cloud.