Aller au contenu
API & webhooks

Développeurs

API et webhooks

Lisez les données de votre organisation depuis vos propres outils (CRM, comptabilité, tableau de bord) et recevez chaque nouvelle inscription, paiement ou présence en temps réel. L'API est en lecture seule et réservée aux organisations en formule Pro ou Sur mesure.

Créer une clé d'API →

Authentification

Créez une clé dans Organisation → Intégrations. Elle n'est affichée qu'une seule fois : rangez-la côté serveur, jamais dans une application mobile ou une page web. Chaque clé porte des droits (un par type de données) ; une route hors de ses droits répond 403.

Envoyez la clé dans l'en-tête Authorization :

curl https://api.teriya-events.com/api/v1/events/ \
  -H "Authorization: Bearer tk_live_ab12cd34_…"

Droits disponibles

events:read
Événements de l'organisation
registrations:read
Inscrits
payments:read
Paiements
checkins:read
Présences
stands:read
Réservations de stands

Limites

Par clé : 60 requêtes par minute et 10 000 par jour. Au-delà, la réponse est 429 Too Many Requests avec un en-tête Retry-After (en secondes) : attendez ce délai avant de réessayer.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{"detail": "…", "retry_after": 23}

Pagination

Les listes sont paginées par curseur, 100 éléments par page, du plus ancien au plus récent. Suivez l'URL next telle quelle jusqu'à ce qu'elle vaille null ; ne construisez pas le paramètre cursor vous-même.

let url = "https://api.teriya-events.com/api/v1/events/123/registrations/?updated_since=2026-10-01T00:00:00Z";
while (url) {
  const r = await fetch(url, { headers: { Authorization: `Bearer ${process.env.TERIYA_API_KEY}` } });
  if (r.status === 429) {
    await new Promise((ok) => setTimeout(ok, Number(r.headers.get("Retry-After") ?? 60) * 1000));
    continue;
  }
  const page = await r.json();
  for (const inscrit of page.results) traiter(inscrit);
  url = page.next; // null sur la dernière page
}

Formats

  • Dates et heures en ISO 8601 avec fuseau (2026-11-14T09:00:00+00:00).
  • Montants en chaînes décimales ("25000.00"), jamais en nombres flottants ; la devise est dans currency.
  • Un champ sans valeur vaut null.
  • Un événement d'une autre organisation répond 404.

Routes

GET/api/v1/events/

Les événements de l'organisation.

Droit requis : events:read

Paramètres

updated_since
Date ISO 8601 : seulement les éléments modifiés depuis (synchronisation incrémentale).
cursor
Fourni par l'URL next ; à ne pas construire.

Exemple de réponse

{
  "next": "https://…/api/v1/events/?cursor=cD0xMjM%3D",
  "previous": null,
  "results": [
    {
      "id": 123,
      "title": "Assises du numérique 2026",
      "type": "CONFERENCE",
      "status": "PUBLISHED",
      "start_date": "2026-11-14T09:00:00+00:00",
      "end_date": "2026-11-15T18:00:00+00:00",
      "location": "Ouagadougou",
      "currency": "XOF",
      "slug": "assises-numerique-2026",
      "updated_at": "2026-10-02T16:41:07.512000+00:00"
    }
  ]
}

GET/api/v1/events/{id}/registrations/

Les inscrits d'un événement : champs système, catégorie, statut, réponses au formulaire (answers, par clé de champ), numéro de dossier.

Droit requis : registrations:read

Paramètres

updated_since
Date ISO 8601 : seulement les éléments modifiés depuis (synchronisation incrémentale).
status
PENDING, CONFIRMED, CANCELLED, PRE_REGISTERED, VALIDATED, WAITLISTED, DECLINED ou EXPIRED.
cursor
Fourni par l'URL next ; à ne pas construire.

Exemple de réponse

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 5012,
      "event_id": 123,
      "dossier_number": "ASS2026NUM-00042",
      "full_name": "Aminata Ouédraogo",
      "phone": "+22670000000",
      "email": "aminata@example.com",
      "status": "CONFIRMED",
      "status_label": "Confirmé",
      "category": "Professionnel",
      "quantity": 1,
      "answers": { "entreprise": "Faso Data", "fonction": "Directrice" },
      "created_at": "2026-10-01T08:12:44+00:00",
      "updated_at": "2026-10-01T08:15:02+00:00"
    }
  ]
}

GET/api/v1/events/{id}/payments/

Les paiements d'un événement : montant brut, frais de service, frais d'opérateur, commission, net, statut (PENDING, COMPLETED, FAILED, REFUNDED).

Droit requis : payments:read

Paramètres

updated_since
Date ISO 8601 : seulement les éléments modifiés depuis (synchronisation incrémentale).
cursor
Fourni par l'URL next ; à ne pas construire.

Exemple de réponse

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 8840,
      "event_id": 123,
      "registration_id": 5012,
      "type": "EVENT_REGISTRATION",
      "status": "COMPLETED",
      "gateway": "YENGAPAY",
      "currency": "XOF",
      "amount_gross": "25000.00",
      "service_fee": "500.00",
      "operator_fee": "375.00",
      "commission": "1250.00",
      "amount_net": "23375.00",
      "refunded_at": null,
      "created_at": "2026-10-01T08:13:10+00:00",
      "updated_at": "2026-10-01T08:15:02+00:00"
    }
  ]
}

GET/api/v1/events/{id}/checkins/

Les présences d'un événement : zone et heure de passage ; duplicate signale un second scan du même billet.

Droit requis : checkins:read

Paramètres

cursor
Fourni par l'URL next ; à ne pas construire.

Exemple de réponse

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 301,
      "event_id": 123,
      "registration_id": 5012,
      "scanned_at": "2026-11-14T08:47:31+00:00",
      "zone": "Entrée générale",
      "duplicate": false
    }
  ]
}

GET/api/v1/events/{id}/stands/

Les réservations de stands d'un événement.

Droit requis : stands:read

Paramètres

updated_since
Date ISO 8601 : seulement les éléments modifiés depuis (synchronisation incrémentale).
cursor
Fourni par l'URL next ; à ne pas construire.

Exemple de réponse

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 77,
      "event_id": 123,
      "reservation_number": "STD-0007",
      "structure_name": "Faso Data SARL",
      "buyer_name": "Issa Kaboré",
      "buyer_phone": "+22671000000",
      "buyer_email": "issa@example.com",
      "status": "CONFIRMED",
      "stand_type": "Stand 9 m²",
      "amount_total": "150000.00",
      "created_at": "2026-09-20T10:02:00+00:00",
      "updated_at": "2026-09-22T14:30:00+00:00"
    }
  ]
}

Erreurs

401
Clé absente, invalide, révoquée ou expirée.
403
La clé n'a pas le droit demandé, ou l'organisation n'a plus la formule Pro.
404
Événement inconnu ou d'une autre organisation.
400
Paramètre invalide (updated_since non ISO 8601…).
429
Limite atteinte : attendre Retry-After secondes.

Webhooks

Ajoutez une adresse https publique dans Organisation → Intégrations et cochez les événements voulus. Les adresses privées ou locales sont refusées. Le secret de signature (whsec_…) n'est affiché qu'une fois, à la création. « Envoyer un test » expédie un événement ping signé.

Événements

registration.confirmed
Une inscription est confirmée.
registration.cancelled
Une inscription est annulée.
payment.completed
Un paiement est reçu.
payment.refunded
Un paiement est remboursé.
checkin.created
Une présence est enregistrée (hors doublons).
stand.confirmed
Une réservation de stand est confirmée.

En-têtes

X-Teriya-Signature
t=<horodatage Unix>,v1=<HMAC-SHA256(secret, t + "." + corps)>, en hexadécimal.
X-Teriya-Event
Le type d'événement (ou ping pour un test).
X-Teriya-Delivery
L'identifiant de l'envoi, identique d'un réessai à l'autre.

Exemple d'envoi

Le corps est un objet { type, id, created, data } ; data a exactement la forme de l'objet renvoyé par la route correspondante.

POST /teriya/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Teriya-Webhooks/1
X-Teriya-Event: payment.completed
X-Teriya-Delivery: 98231
X-Teriya-Signature: t=1760180000,v1=5f2b0c…e91a

{"type":"payment.completed","id":"payment.completed:8840","created":"2026-10-01T08:15:03+00:00","data":{"id":8840,"event_id":123,"registration_id":5012,"type":"EVENT_REGISTRATION","status":"COMPLETED","gateway":"YENGAPAY","currency":"XOF","amount_gross":"25000.00","service_fee":"500.00","operator_fee":"375.00","commission":"1250.00","amount_net":"23375.00","refunded_at":null,"created_at":"2026-10-01T08:13:10+00:00","updated_at":"2026-10-01T08:15:02+00:00"}}

Vérifier la signature

Calculez HMAC-SHA256 avec votre secret sur la chaîne `${t}.${corps brut}` (t est l'horodatage de l'en-tête, en secondes), comparez le résultat hexadécimal à v1 en temps constant, et refusez un horodatage écarté de plus de 5 minutes de votre horloge (protection contre le rejeu). Vérifiez sur le corps brut reçu, avant tout décodage JSON.

Node.js

import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.TERIYA_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_S = 300; // 5 minutes

function verifier(entete, corpsBrut, secret) {
  // entete = "t=1760180000,v1=5f2b…"
  const parts = Object.fromEntries(
    entete.split(",").map((p) => {
      const i = p.indexOf("=");
      return [p.slice(0, i), p.slice(i + 1)];
    })
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_S) return false;

  // HMAC-SHA256(secret, `${t}.${corpsBrut}`) — sur le corps BRUT, octet pour octet
  const attendu = crypto
    .createHmac("sha256", secret)
    .update(`${t}.`)
    .update(corpsBrut)
    .digest("hex");

  const a = Buffer.from(attendu, "utf8");
  const b = Buffer.from(parts.v1, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

// express.raw : surtout pas express.json(), qui re-sérialiserait le corps
app.post("/teriya/webhook", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifier(req.get("X-Teriya-Signature") ?? "", req.body, SECRET)) {
    return res.sendStatus(400);
  }
  const evenement = JSON.parse(req.body.toString("utf8"));
  // evenement.id est stable d'un réessai à l'autre : dédoublonnez dessus.
  console.log(evenement.type, evenement.data);
  res.sendStatus(200); // répondre en moins de 10 s
});

app.listen(3000);

Python

import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

SECRET = os.environ["TERIYA_WEBHOOK_SECRET"].encode()  # whsec_…
TOLERANCE_S = 300  # 5 minutes


def verifier(entete: str, corps_brut: bytes) -> bool:
    # entete = "t=1760180000,v1=5f2b…"
    try:
        parts = dict(p.split("=", 1) for p in entete.split(","))
        t = int(parts["t"])
        recu = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > TOLERANCE_S:
        return False
    # HMAC-SHA256(secret, f"{t}.{corps_brut}") — sur le corps BRUT
    attendu = hmac.new(SECRET, f"{t}.".encode() + corps_brut, hashlib.sha256).hexdigest()
    return hmac.compare_digest(attendu, recu)  # comparaison à temps constant


app = Flask(__name__)


@app.post("/teriya/webhook")
def webhook():
    corps = request.get_data()  # octets bruts, avant tout décodage JSON
    if not verifier(request.headers.get("X-Teriya-Signature", ""), corps):
        abort(400)
    evenement = json.loads(corps)
    # evenement["id"] est stable d'un réessai à l'autre : dédoublonnez dessus.
    print(evenement["type"], evenement["data"])
    return "", 200  # répondre en moins de 10 s

Réessais et désactivation

  • Un envoi réussit quand votre serveur répond 2xx en moins de 10 secondes. Les redirections ne sont pas suivies.
  • Sinon il est réessayé 1 min, 5 min, 30 min, 2 h puis 12 h plus tard ; après ces cinq réessais, il est marqué en échec.
  • Une adresse qui échoue sans interruption depuis 3 jours est désactivée, et l'organisation prévenue par e-mail. Réactivez-la depuis l'onglet Intégrations une fois corrigée.
  • Un même événement peut arriver plus d'une fois (réessai, « Renvoyer ») : dédoublonnez sur le champ id du corps.
  • L'ordre d'arrivée n'est pas garanti : fiez-vous à updated_at.

Schéma OpenAPI

Le schéma OpenAPI généré décrit toutes les routes et leurs champs : https://api.teriya-events.com/api/v1/schema/