API et webhooks

Pour les développeurs sur le plan Pro, Cleartix propose une API REST et des webhooks afin de relier la billetterie à vos propres systèmes.

Clés API

Créez des clés API sous Settings pour utiliser l'API REST de Cleartix. Avec une clé, vous pouvez lire vos données depuis votre code ou vos outils — vos événements, commandes, participants et statistiques de vente par événement (billets vendus, enregistrements et recettes, ventilés par type de billet, sans données des participants) — pour alimenter des tableaux de bord, synchroniser un CRM ou bâtir un rapport sur mesure. Chaque clé reçoit ses propres scopes, pour donner à une intégration exactement l'accès dont elle a besoin — par exemple uniquement les chiffres de vente agrégés.

Webhooks

Plutôt que d'interroger l'API, enregistrez des webhooks pour que Cleartix notifie votre point de terminaison quand un événement se produit, par exemple :

• Un billet vendu
• Un participant enregistré
• Une commande remboursée

Lorsque l'événement survient, Cleartix envoie une requête à votre URL. Les livraisons sont signées, ce qui vous permet de vérifier qu'elles viennent bien de Cleartix, et elles sont réessayées si votre point de terminaison est momentanément indisponible — une brève panne ne perd donc aucun événement.

Charges utiles des webhooks

Chaque webhook est une requête HTTP POST dont le corps JSON utilise toujours la même enveloppe — seuls event et data changent :

{
  "id": "evt_3f9a2b7c1d4e5f60",
  "event": "ticket.sold",
  "created_at": "2026-06-12T14:05:00.000Z",
  "organization_id": "org_abc123",
  "data": {}
}

Deux en-têtes accompagnent chaque requête :

• X-ClearTix-Signature — sha256= suivi du HMAC-SHA256 du corps brut de la requête, avec le secret de signature de votre point de terminaison. Vérifiez-le avant de faire confiance à une charge utile.
• X-ClearTix-Event — le type d'événement, p. ex. ticket.sold.

L'objet data dépend de l'événement. Chaque événement ci-dessous montre un exemple de data et son schéma JSON.

ticket.sold — billet acheté et payé

{ "orderId": "ord_9f8e7d6c", "ticketCount": 2, "totalAmount": "50.00" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ticket.sold · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["orderId", "ticketCount", "totalAmount"],
  "properties": {
    "orderId": { "type": "string" },
    "ticketCount": { "type": "integer", "minimum": 0 },
    "totalAmount": { "type": "string", "description": "Decimal total as a string, e.g. \"50.00\" (\"0\" for free orders)" }
  }
}

ticket.checked_in — participant enregistré à l'événement

{ "ticketId": "tkt_1a2b3c4d", "eventId": "ev_5e6f7a8b", "checkedInAt": "2026-06-12T14:05:00.000Z" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ticket.checked_in · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["ticketId", "eventId", "checkedInAt"],
  "properties": {
    "ticketId": { "type": "string" },
    "eventId": { "type": "string" },
    "checkedInAt": { "type": "string", "format": "date-time" }
  }
}

ticket.refunded — billet remboursé

{ "orderId": "ord_9f8e7d6c", "refundRef": "re_4d3c2b1a", "refundAmount": 2500 }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "ticket.refunded · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["orderId", "refundRef", "refundAmount"],
  "properties": {
    "orderId": { "type": "string" },
    "refundRef": { "type": "string", "description": "Provider refund reference" },
    "refundAmount": { "type": "integer", "description": "Refunded amount in cents" }
  }
}

order.created — commande confirmée (y compris gratuite)

{ "orderId": "ord_9f8e7d6c", "status": "paid" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "order.created · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["orderId", "status"],
  "properties": {
    "orderId": { "type": "string" },
    "status": { "type": "string", "enum": ["paid"] }
  }
}

event.published — événement publié et en ligne

{ "eventId": "ev_5e6f7a8b", "eventName": "Summer Yoga Retreat", "startAt": "2026-07-01T09:00:00.000Z" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "event.published · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["eventId", "eventName", "startAt"],
  "properties": {
    "eventId": { "type": "string" },
    "eventName": { "type": "string" },
    "startAt": { "type": "string", "format": "date-time" }
  }
}

Widgets via l'API

Tout ce que vous pouvez faire avec les widgets d'événements dans le tableau de bord est aussi disponible via l'API. Une intégration de site web — par exemple un plugin WordPress — peut ainsi créer et placer des widgets sans que personne ne copie des extraits à la main. Les clés ont besoin du scope widgets:read pour lister les widgets et widgets:write pour les créer, modifier ou supprimer.

Le corps d'un widget reprend les mêmes champs que le formulaire du tableau de bord :

{
  "name": "Page d'accueil",
  "view": "list",
  "selectionMode": "templates",
  "eventTemplateIds": ["tpl_abc123"],
  "dateFrom": "2026-10-01T00:00:00.000Z",
  "theme": { "primaryColor": "#4f46e5", "borderRadius": "md" },
  "defaultLocale": "fr"
}

selectionMode vaut all_upcoming, templates (avec eventTemplateIds), manual (avec eventIds) ou location (avec locationIds) ; view vaut list ou calendar. Chaque widget renvoyé par l'API contient un bloc embed avec l'URL du script de chargement, l'URL de l'iframe, un snippet prêt à coller et les attributs data-* lus par le script — collez l'extrait ou construisez votre propre <script>/<iframe> à partir de ces valeurs. Comme l'extrait ne référence que l'ID du widget, les modifications ultérieures via l'API ou le tableau de bord apparaissent immédiatement sur le site.

Spécification OpenAPI

L'API complète est décrite dans un document OpenAPI 3.1 lisible par machine à l'adresse https://cleartix.io/api/v1/openapi.json. Importez-le dans Postman ou Swagger UI pour explorer les endpoints, ou fournissez-le à un générateur de client pour votre langage. Chaque opération indique le scope requis et la forme exacte de la requête et de la réponse.

Gardez les clés en sécurité

Une clé API agit au nom de votre organisation : traitez-la comme un mot de passe.

1. Ne la mettez jamais dans un gestionnaire de versions et ne la partagez pas publiquement.
2. Utilisez si possible une clé distincte par intégration.
3. Renouvelez une clé immédiatement en cas de fuite, et supprimez celles que vous n'utilisez plus.