Développeurs

Envoyez un sondage depuis vos propres systèmes, en un seul appel

Une API REST avec des clés que vous contrôlez, des sondages déclenchés par des événements et des webhooks signés pour chaque réponse complète, chaque paiement et chaque alerte.

Ouvrir la référence de l’API Demander un environnement de test

Clés API

Créez vos clés dans la console, menu Paramètres, page Développeurs. La clé complète ne s’affiche qu’une fois ; vous pouvez la révoquer à tout moment. Les clés sont limitées à votre compte.

Déclencheurs

Invitez un client à un sondage au moment même où quelque chose se produit : une transaction, une livraison, la fin d’un appel au service client.

Webhooks

Recevez sur votre endpoint les réponses complètes, les paiements réussis et les alertes de baromètre, signés et renvoyés en cas d’échec.

Déclencheurs

Des sondages déclenchés par des événements

Faites un POST sur /api/v1/triggers avec votre clé API. La personne est invitée tout de suite sur le canal du sondage.

Consentement intégré. Si la personne ne fait pas encore partie du panel, envoyez le consentement que vous avez recueilli (consent.source) ; sinon l’appel est refusé.
Pas de lassitude. Un seul déclencheur par numéro de téléphone et par sondage sur 24 heures.
Réessais sans risque. Un même external_ref n’invite jamais deux fois.
Débit limité par clé, avec un en-tête Retry-After si vous allez trop vite.

# Inviter un client juste après une transaction
curl -X POST https://api.smartsurvafrica.com/api/v1/triggers \
  -H "X-Api-Key: ss_xxxxxxxxxx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "survey_id": "3f6c...",
    "phone": "+233244777123",
    "external_ref": "txn-48213",
    "attributes": {"branch": "Osu", "product": "mobile-app"},
    "consent": {"source": "app-terms-v3"}
  }'

# 201 Created
{"trigger_id": "...", "invitation_id": "...", "status": "invited",
 "channel": "whatsapp", "external_ref": "txn-48213", "duplicate": false}

Webhooks

Les réponses livrées dans vos systèmes

Ajoutez un endpoint dans la console et choisissez les événements. Chaque envoi est un POST JSON signé avec le secret de votre webhook.

Événements webhook
Événement	Quand
`response.completed`	Un répondant a terminé un sondage (réponses par clé de question, identifiant du reçu, votre `external_ref`)
`payout.succeeded`	Une incitation a été payée
`alert`	Une alerte de baromètre ou une alerte de règle d’arrêt s’est déclenchée

En-tête X-SmartSurv-Signature: sha256=<hex> : un HMAC-SHA256 du corps brut
Toute réponse 2xx vaut succès ; dans tous les autres cas, l’envoi est retenté à intervalles croissants pendant environ deux heures
Un journal des envois dans la console montre chaque tentative
Aucun numéro de téléphone ni aucun nom dans les contenus envoyés

# Vérifier un envoi (Python)
import hmac, hashlib

def verified(secret: str, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

// Vérifier un envoi (Node.js)
const crypto = require('crypto');

function verified(secret, rawBody, header) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

# Corps d’un envoi response.completed
{"id": "...", "event": "response.completed", "created_at": "...",
 "data": {"survey_id": "...", "survey_title": "NPS après transaction",
          "receipt_id": "R-7KQ2M9", "external_ref": "txn-48213",
          "answers": {"nps": "9", "nps__probe": "Appli rapide"}}}

Référence

L’API complète

Sondages, résultats, répondants, paiements, rapports et plus encore : tout ce que fait la console se trouve dans l’API. La référence interactive liste chaque endpoint avec le format des requêtes et des réponses.

URL de base

https://api.smartsurvafrica.com/api/v1

Authentification

Les déclencheurs utilisent l’en-tête X-Api-Key. Les endpoints de la console utilisent un jeton bearer obtenu à la connexion.

Erreurs

Du JSON avec un message detail. Les listes renvoient {"items", "total"}.

Ouvrir la référence de l’API