API publique

L’API publique Eveos permet aux intégrations de consulter et gérer les données autorisées par le rôle de votre clé API. Elle est adaptée aux CRM, outils no-code, automatisations Zapier et assistants IA.

Démarrer

1. Créez une clé API avec le rôle et les projets nécessaires.
2. Ouvrez la référence interactive.
3. Dans le bloc Authentication, collez la clé dans le champ Value de X-Api-Key, puis lancez une requête d’essai avec Test Request.

Attention

Ne collez jamais une clé API dans une URL, un tableur partagé ou une conversation. La référence interactive conserve l’autorisation uniquement dans votre navigateur.

Ressources disponibles

L’API couvre notamment les projets, sessions, participants, exposants, programme, intervenants, lieux, catégories, produits, codes promotionnels, taxonomies, champs personnalisés, modules personnalisés, check-ins, checkpoints, widgets, médias, checklists exposants et analytics non financières.

Toutes les opérations sont limitées par le rôle et le périmètre de projets de la clé. Une réponse 403 indique que la clé ne possède pas la permission requise.

Bonnes pratiques pour les intégrations

1. Authentifier chaque appel

Envoyez la clé API dans l’en-tête X-Api-Key. La clé détermine l’organisateur, les projets accessibles et les permissions de votre intégration. N’envoyez jamais organizerId pour tenter de choisir un autre organisateur.

GET /api/v1/public/projects HTTP/1.1
Host: backend.eveos.com
X-Api-Key: evk_live_votre_cle

2. Créer sans doublon avec Idempotency-Key

Chaque requête POST exige un en-tête Idempotency-Key: générez une valeur aléatoire unique pour une seule tentative de création, puis conservez-la si vous devez relancer cette même opération après un timeout ou une erreur réseau.

POST /api/v1/public/sessions/ses_123/participants HTTP/1.1
Host: backend.eveos.com
X-Api-Key: evk_live_votre_cle
Idempotency-Key: 9d3c98bb-6afc-4bb0-a7cf-75c8d75b7dc1
Content-Type: application/json

{ "person": { "firstName": "Ana", "lastName": "Martin", "email": "ana@example.com" } }

Pendant 24 heures, une nouvelle requête utilisant la même clé API et le même Idempotency-Key ne crée rien de plus: Eveos renvoie la réponse mémorisée de la première requête, accompagnée de Idempotency-Replayed: true. Utilisez donc une nouvelle valeur pour toute nouvelle création, même sur une autre ressource. Un header absent, vide ou supérieur à 200 caractères retourne 400.

3. Parcourir une liste complète

Les collections renvoient un tableau items et, s’il reste des résultats, un nextCursor. Passez cette valeur opaque telle quelle dans cursor pour obtenir la page suivante. Ne tentez pas de la décoder ni de construire vous-même un offset.

GET /api/v1/public/sessions/ses_123/participants?limit=100 HTTP/1.1
X-Api-Key: evk_live_votre_cle

{
  "items": [{ "id": "par_123" }],
  "nextCursor": "NjM4..."
}

GET /api/v1/public/sessions/ses_123/participants?limit=100&cursor=NjM4... HTTP/1.1
X-Api-Key: evk_live_votre_cle

L’absence de nextCursor signifie que la liste est terminée. limit est optionnel, vaut 25 par défaut et ne peut pas dépasser 100.

4. Traiter les erreurs de manière fiable

Les erreurs fonctionnelles utilisent le format standard RFC 7807 application/problem+json. Testez le code HTTP, puis lisez title pour la catégorie machine et detail pour un message exploitable.

{
  "status": 403,
  "title": "forbidden",
  "detail": "La clé API ne dispose pas de la permission requise."
}

Les cas les plus fréquents sont 400 (requête invalide), 401 (clé absente ou invalide), 403 (clé valide mais permission ou projet non autorisé), 404 (ressource introuvable dans votre périmètre) et 429 (limite de débit). Pour un 429 ou une erreur réseau, relancez progressivement; pour un POST, gardez le même Idempotency-Key.

5. Rester compatible avec les évolutions

L’URL /api/v1/public reste stable pour les évolutions compatibles. Eveos peut ajouter des champs ou de nouvelles ressources sans changer de version. Votre client doit lire les champs dont il a besoin et ignorer les champs inconnus; ne rendez pas la désérialisation stricte sur les propriétés non utilisées.

Zapier et agents IA

Zapier peut appeler les endpoints HTTP avec le header X-Api-Key et recevoir les événements configurés dans les webhooks. Un GPT personnalisé peut importer directement le document OpenAPI:

https://backend.eveos.com/openapi/public-v1.json

Pour un agent autonome, limitez la clé au rôle et aux projets strictement nécessaires. Conservez une validation humaine pour les suppressions et les modifications de configuration à fort impact.