API Partenaire

Périmètre

Cette API couvre un besoin précis : amener vos participants dans une session qui existe déjà. Elle ne pilote pas la plateforme.

Sessions éligibles

Une session accepte les inscriptions par API lorsqu'elle est gratuite, qu'elle demande une inscription, qu'elle n'est ni terminée ni annulée, et qu'il reste des places. Une session payante est refusée : son accès suppose un achat en pièces (PCS) que l'utilisateur effectue lui-même — une clé API ne peut pas s'y substituer.

Comment ça marche

1. 1L'organisateur crée la session dans StreameexIl vous communique son identifiant. Cette étape ne passe pas par l'API.
2. 2Votre application appelle l'API avec l'email du participantUn seul appel suffit : le compte est créé s'il n'existe pas, puis inscrit à la session.
3. 3Le participant reçoit ses identifiants par emailMot de passe provisoire, à changer à sa première connexion sur app.streameex.com.
4. 4Il rejoint la session le jour JDepuis le web ou l'application mobile Streameex AIO, avec ces identifiants.

Votre clé

Streameex vous remet une clé de la forme strx_live_1NXUvMKVU4hORQR3rpzvbSTjzYae0Q5Y2u51xBLVXLw. Elle s'envoie dans l'en-tête X-API-Key à chaque appel.

Vérifiez votre configuration avec l'appel de diagnostic — il ne modifie rien et confirme que la clé est reconnue :

curl https://api.streameex.com/api/partner/ping \
  -H "X-API-Key: $STREAMEEX_API_KEY"

Réponse

{
  "ok": true,
  "name": "App Événements Kinshasa",
  "keyPrefix": "strx_live_1NXUvMKV",
  "scopes": ["users:create", "rooms:read", "rooms:register"]
}

Scopes

Chaque clé porte la liste des actions qui lui sont permises. Un appel hors scope renvoie 403.

Si votre clé est restreinte à certaines adresses IP, seuls les appels venant de ces adresses sont acceptés. L'adresse retenue est celle que Streameex constate réellement : un en-tête X-Forwarded-For envoyé par vos soins n'a aucun effet. Communiquez-nous l'adresse de sortie publique de votre serveur, et prévenez-nous si elle change.

Inscrire un participant

C'est l'appel principal de l'intégration. Un seul appel : il crée le compte Streameex si le participant n'en a pas encore, puis l'inscrit à la session.

curl -X POST \
  https://api.streameex.com/api/partner/rooms/BY2ez8dMiDAbvQiAsPXG/registrations \
  -H "X-API-Key: $STREAMEEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jean.kabila@example.com",
    "displayName": "Jean Kabila",
    "phone": "+243812345678",
    "externalId": "crm-4471",
    "customFields": { "entreprise": "Silikin Village", "fonction": "CTO" }
  }'

Réponse — 200

{
  "userId": "kQ7dP2mXbN4vR8sL1wZa",
  "email": "jean.kabila@example.com",
  "displayName": "Jean Kabila",
  "created": true,
  "registrationId": "9fH3kLm2nQpR5tV8wXyZ",
  "registrationStatus": "approved",
  "registered": true
}

Champs de la requête

Champs de la réponse

Ce que voit le participant

Un compte nouvellement créé reçoit par email ses identifiants et un mot de passe provisoire, qu'il devra changer à sa première connexion sur app.streameex.com. Si le participant a déjà un compte Streameex, rien ne lui est envoyé et aucune de ses données n'est modifiée : il est simplement inscrit à la session.

L'API ne renvoie jamais de mot de passe ni de jeton de connexion. Une clé partenaire ne peut pas ouvrir de session au nom d'un utilisateur — c'est une limite de conception, pas une option.

Inscription en lot

Jusqu'à 100 participants par appel. Chaque ligne est traitée indépendamment : une erreur sur l'une n'annule pas les autres.

curl -X POST \
  https://api.streameex.com/api/partner/rooms/BY2ez8dMiDAbvQiAsPXG/registrations/bulk \
  -H "X-API-Key: $STREAMEEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [
      { "email": "alice@example.com", "displayName": "Alice Mbala" },
      { "email": "bruno@example.com", "displayName": "Bruno Ilunga" }
    ]
  }'

Réponse — 200

{
  "total": 2,
  "succeeded": 1,
  "failed": 1,
  "results": [
    {
      "email": "alice@example.com",
      "ok": true,
      "userId": "...",
      "registrationId": "...",
      "created": true,
      "registered": true,
      "registrationStatus": "approved"
    },
    {
      "email": "bruno@example.com",
      "ok": false,
      "error": "Le nombre maximum de participants est atteint."
    }
  ]
}

Réessayez uniquement les lignes ok: false. Le champ error est rédigé pour être affiché à votre équipe : il explique la cause métier (session pleine, email invalide…). En cas d'incident technique de notre côté, il porte un message générique et l'incident est tracé chez nous.

Appelez la consultation de session avant un gros envoi : seatsRemaining vous évite une série d'échecs.

Consulter une session

Lecture seule. Utile pour valider un identifiant, afficher une date, ou vérifier les places restantes avant d'inscrire.

{
  "id": "BY2ez8dMiDAbvQiAsPXG",
  "title": "Webinaire Innovation 2026",
  "status": "scheduled",
  "scheduledAt": "2026-07-22T14:00:00.000Z",
  "registrationRequired": true,
  "pricingModel": "FREE",
  "manualApproval": false,
  "maxParticipants": 100,
  "registrationCount": 12,
  "seatsRemaining": 88,
  "acceptsPartnerRegistrations": true
}

acceptsPartnerRegistrations résume à lui seul l'éligibilité : s'il vaut false, toute inscription sur cette session sera refusée, et les autres champs vous disent pourquoi (session payante, complète, terminée…).

Créer un compte seul

Si votre flux crée les comptes en amont des inscriptions, l'appel POST /partner/users (scope users:create) accepte les mêmes champs d'identité, sans customFields, et renvoie userId, email, displayName et created.

Rejouer un appel

L'API est idempotente sur le couple (email, session). Concrètement :

• Email déjà connu de Streameex → le compte existant est réutilisé, aucune donnée écrasée (created: false).
• Participant déjà inscrit → l'inscription existante est renvoyée en 200 (registered: false).

Rejouer une requête après un délai d'attente réseau est donc sans danger : vous ne créerez ni doublon de compte, ni doublon d'inscription, et le participant ne recevra pas un second email. Vous n'avez pas besoin de tenir un registre des appels déjà passés.

Erreurs

Toutes les réponses d'erreur sont en JSON et le champ message est explicite. Il est rédigé en français, à destination de votre équipe technique.

Exemple de corps d'erreur

{
  "statusCode": 400,
  "message": "Cette room est payante — l'API partenaire ne gère que les rooms gratuites.",
  "error": "Bad Request"
}

Quotas

Le quota est compté par clé, pas par adresse IP. Un dépassement renvoie 429 avec les en-têtes Retry-After et X-RateLimit-*.

Pour une liste importante, préférez l'appel en lot : 10 appels par minute à 100 participants couvrent 1 000 inscriptions par minute.

Sécurité

Votre clé vaut un mot de passe serveur : elle permet de créer des comptes en votre nom.

Les appels sont journalisés de notre côté : date, adresse IP, action et clé utilisée. Nous pouvons vous fournir cet historique sur demande.

Mise en service

Le parcours d'intégration, dans l'ordre :

• Stocker la clé reçue dans votre gestionnaire de secrets
• Valider la configuration avec GET /partner/ping
• Récupérer l'identifiant de session auprès de l'organisateur
• Vérifier la session avec GET /partner/rooms/{roomId}
• Inscrire un premier participant de test avec une adresse que vous contrôlez
• Confirmer la réception de l'email d'identifiants et la connexion
• Brancher votre flux réel, à l'unité ou en lot
• Traiter les codes 400 et 429 dans votre gestion d'erreurs