API et webhooks

Pour les développeurs, Cleartix propose une API REST (Studio et Pro) et des webhooks (Pro) afin de relier la billetterie à vos propres systèmes. Vous préférez parler à vos événements plutôt que coder ? Connectez un assistant IA via MCP — disponible sur tous les plans.

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 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. L'API permet aussi de créer et gérer vos événements, modèles d'événement, types de billets, dates, codes d'accès, options (add-ons), pools de capacité, portes, e-mails d'événement et lieux : un formulaire sur votre propre site, un outil de planification interne ou un assistant IA peut ainsi configurer des événements sans que personne ne passe par le tableau de bord.

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 :

Vous pouvez modifier les scopes d'une clé à tout moment depuis la même page (Modifier les scopes) ; le changement s'applique immédiatement à toutes les intégrations qui l'utilisent, sans émettre une nouvelle clé.

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
• Un produit à stock faible

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é

Envoyé lorsque des billets sont émis sur une commande payée : un paiement en ligne, une commande gratuite ou POS, des billets invités, un échange de pass, ou un virement, un paiement POS ou une facture que vous avez comptabilisé comme payé. totalAmount vaut "0" pour les commandes à 0 €.

{ "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

Envoyé à chaque check-in : via l'app de scan (y compris les scans synchronisés plus tard après une coupure de connexion), un check-in manuel dans le tableau de bord, et les check-ins via l'API ou un assistant IA.

{ "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é

Envoyé pour chaque remboursement effectué dans Cleartix — un remboursement individuel depuis le tableau de bord, l'API ou un assistant IA, et chaque commande remboursée automatiquement lorsque vous annulez un événement.

{ "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)

Envoyé lorsqu'une commande devient payée, avec ticket.sold (un achat de pass n'envoie que order.created). Une facture réglée est aussi signalée avec status: "paid".

{ "orderId": "ord_9f8e7d6c", "kind": "tickets", "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" },
    "kind": { "type": "string", "enum": ["tickets", "pass", "shop"] },
    "status": { "type": "string", "enum": ["paid"] }
  }
}

order.shipped — commande boutique expédiée

Envoyé lorsque vous marquez une commande comme expédiée (tableau de bord, API ou assistant IA), avec le transporteur et le code de suivi s'il a été saisi.

{ "orderId": "ord_9f8e7d6c", "carrier": "bpost", "trackingCode": "323212345678901234", "shippedAt": "2026-06-12T14:05:00.000Z" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "order.shipped · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["orderId", "carrier", "trackingCode", "shippedAt"],
  "properties": {
    "orderId": { "type": "string" },
    "carrier": { "type": "string", "enum": ["bpost", "postnl", "dhl", "dpd", "gls", "ups", "other"] },
    "trackingCode": { "type": ["string", "null"] },
    "shippedAt": { "type": "string", "format": "date-time" }
  }
}

order.refunded — produits ou livraison remboursés

Envoyé lors d'un remboursement de lignes de produits ou de la ligne de livraison (commandes boutique et extras expédiés), avec chaque ligne remboursée. Les remboursements de billets continuent d'envoyer ticket.refunded.

{ "orderId": "ord_9f8e7d6c", "refundRef": "re_1a2b3c", "amountCents": 3095, "lines": [{ "orderAddOnId": "oao_1", "productId": "prod_1", "shipping": false, "quantity": 1, "amountCents": 2500, "restocked": true }, { "orderAddOnId": null, "productId": null, "shipping": true, "quantity": 1, "amountCents": 595, "restocked": false }] }

product.stock_low — un produit est presque épuisé

Envoyé une seule fois quand une commande fait passer le stock disponible d'un produit physique à 5 unités ou moins (il repart seulement après que le stock est remonté au-dessus du seuil puis redescendu). Utilisez-le pour recommander du merchandising ou prévenir votre équipe.

{ "productId": "prod_1", "stock": 200, "stockAvailable": 4, "threshold": 5 }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "product.stock_low · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["productId", "stock", "stockAvailable", "threshold"],
  "properties": {
    "productId": { "type": "string" },
    "stock": { "type": "integer", "description": "Stock total configuré sur le produit" },
    "stockAvailable": { "type": "integer", "description": "Unités encore disponibles après cette commande" },
    "threshold": { "type": "integer", "const": 5 }
  }
}

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" }
  }
}

consent.opted_in — l'acheteur a accepté le marketing

Envoyé lorsqu'un acheteur coche l'option marketing lors du paiement (événements et pass).

{ "buyerEmail": "buyer@example.com", "consentPurpose": "Event checkout for event ev_5e6f7a8b", "consentedAt": "2026-06-15T09:00:00.000Z", "eventId": "ev_5e6f7a8b" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "consent.opted_in · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["buyerEmail", "consentPurpose", "consentedAt"],
  "properties": {
    "buyerEmail": { "type": "string", "format": "email" },
    "consentPurpose": { "type": "string" },
    "consentedAt": { "type": "string", "format": "date-time" },
    "eventId": { "type": "string", "description": "Present for event checkout; omitted for pass purchases" }
  }
}

consent.withdrawn — l'acheteur a retiré son consentement marketing

Envoyé lorsqu'une personne se désabonne via le lien d'un e-mail, et lorsqu'un consentement actif disparaît suite à une demande d'effacement RGPD — pour que votre outil d'e-mailing cesse aussi de lui écrire.

{ "buyerEmail": "buyer@example.com", "withdrawnAt": "2026-06-15T09:00:00.000Z" }

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "consent.withdrawn · data",
  "type": "object",
  "additionalProperties": false,
  "required": ["buyerEmail", "withdrawnAt"],
  "properties": {
    "buyerEmail": { "type": "string", "format": "email" },
    "withdrawnAt": { "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.

Un widget boutique définit "type": "shop" et liste les catégories affichées dans productCategoryIds (vide = toute la boutique, avec le filtre par catégorie) ; les champs d'événements comme selectionMode ne s'y appliquent pas. Les widgets sans type sont des widgets d'événements ("type": "events"). Voir Widgets boutique.

Gérer des événements via l'API

Chaque requête transmet votre clé comme jeton bearer, les corps JSON utilisent les mêmes champs que les formulaires du tableau de bord, et les réponses sont enveloppées dans { "data": … } (les erreurs dans { "error", "message" }). Les exemples ci-dessous font passer un événement du brouillon à la publication en trois appels.

1. Créer un brouillon d'événement avec un type de billet (events:write) :

curl -X POST https://cleartix.io/api/v1/events \
  -H "Authorization: Bearer ctk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": { "fr": "Soirée quiz" },
    "description": {},
    "locales": ["fr"],
    "startAt": "2026-11-14T18:30:00.000Z",
    "endAt": "2026-11-14T22:00:00.000Z",
    "timezone": "Europe/Brussels",
    "ticketTypes": [
      { "name": { "fr": "Équipe (max. 4 personnes)" }, "basePrice": 20, "capacity": 40 }
    ]
  }'

La réponse contient l'id du nouvel événement et status: "draft". Les types de billets peuvent aussi être ajoutés ou modifiés plus tard via POST /api/v1/events/{id}/ticket-types et PATCH …/ticket-types/{ttId} ; GET /api/v1/events/{id}/readiness indique ce qui manque encore avant la mise en ligne.

2. Le publier (events:write) :

curl -X POST https://cleartix.io/api/v1/events/ev_5e6f7a8b/publish \
  -H "Authorization: Bearer ctk_live_…"

3. Définir l'e-mail de rappel de cet événement (emails:write) :

curl -X PUT https://cleartix.io/api/v1/events/ev_5e6f7a8b/emails/event_reminder \
  -H "Authorization: Bearer ctk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": { "fr": "À demain pour la soirée quiz !" },
    "body": { "fr": "Ouverture des portes à 19h00. Apportez le nom de votre équipe et vos neurones." },
    "isActive": true
  }'

GET /api/v1/events/{id}/emails montre l'e-mail effectif par type (votre version ou celle par défaut de l'organisation), POST …/emails/{type}/preview le rend avec des variables d'exemple, et DELETE …/emails/{type} retire à nouveau votre version.

Mise en page du billet. GET/PUT /api/v1/ticket-layout lit et remplace le contenu par défaut de votre organisation pour le tiers inférieur des billets PDF (sponsors, publicité) ; GET/PUT /api/v1/events/{id}/ticket-layout lit et définit le mode d'un événement (inherit, custom ou hidden) et son propre content. Le contenu est du JSON Tiptap par langue, comme pour les e-mails. La lecture demande events:read, la modification events:write. Voir Sponsors et publicité sur vos billets.

Les modèles fonctionnent de la même façon sous /api/v1/templates : créez-en un avec POST, planifiez jusqu'à 50 dates d'un coup avec POST /api/v1/templates/{id}/schedule (envoyez dryRun: true pour prévisualiser les dates et le contrôle du plafond mensuel sans rien créer), ou appliquez-le à un événement existant avec POST /api/v1/templates/{id}/apply. Un PATCH sur un modèle (ou un événement) est une mise à jour partielle : seuls les champs envoyés changent — tout le reste, y compris ses types de billets et ses e-mails, reste tel quel. Les réponses d'événement renvoient le plafond de places configuré dans capacity et les places encore libres dans availableCapacity ; l'ancien champ eventCapacity est obsolète (toujours accepté en entrée, et encore renvoyé comme alias pour l'instant).

Commandes, billets et check-in. GET /api/v1/orders liste les commandes de toute votre organisation (filtrez avec eventId, status, paymentMethod, email, le texte libre q ou une période from/to), POST /api/v1/orders/{id}/refund rembourse une commande entière ou certains billets, et POST /api/v1/orders/{id}/cancel annule une commande encore en attente de paiement (les deux avec orders:write). Pour rapprocher vos extraits de compte, envoyez les paiements entrants (montant, communication, nom du payeur) à POST /api/v1/orders/reconcile (orders:read) : vous obtenez, par ligne, la commande qui attend ce virement ou ce paiement de facture, sans que rien ne soit comptabilisé. POST /api/v1/orders/mark-paid comptabilise ensuite jusqu'à 50 commandes comme payées et POST /api/v1/orders/{id}/mark-paid une seule (orders:write) ; transmettez expectedAmount et une commande dont le total diffère est refusée avec 409 AMOUNT_MISMATCH. GET /api/v1/orders/{id} contient aussi la communication (wireTransferReference) et le numéro de facture (invoiceNumber). GET /api/v1/tickets recherche des billets sur tous les événements par e-mail, nom, identifiant de billet ou de commande, et POST /api/v1/tickets/{id}/resend régénère les billets et renvoie la confirmation à l'acheteur (tickets:write). POST /api/v1/events/{id}/guest-tickets émet des billets invités gratuits — une commande à 0 € pour la presse, les sponsors ou les bénévoles, qui consomme de la capacité comme une vente et envoie les billets par e-mail (orders:write) ; PATCH /api/v1/tickets/{id} remplace les données de participant d'un billet et POST /api/v1/tickets/{id}/transfer transmet un billet à quelqu'un d'autre, avec un nouveau code QR et un e-mail pour l'accepter (les deux avec tickets:write). Pour l'entrée, GET /api/v1/tickets/{id} renvoie le statut de check-in et l'historique des scans d'un billet, POST /api/v1/tickets/{id}/check-in enregistre son arrivée et POST /api/v1/tickets/{id}/undo-check-in l'annule (checkin:write). POST /api/v1/events/{id}/unpublish retire de la vente un événement publié qui n'a pas encore de commandes. Les remboursements sont enregistrés au nom de la personne qui les a demandés : /refund ne fonctionne donc que pour un assistant IA connecté via OAuth — une simple clé API reçoit 409 CONFLICT et vous remboursez alors depuis le tableau de bord.

Liste d'attente, équipe, confidentialité, audit et facturation. GET /api/v1/events/{id}/waitlist liste la liste d'attente d'un événement et DELETE /api/v1/events/{id}/waitlist/{entryId} en retire une inscription (waitlist:write). GET/PATCH/DELETE /api/v1/team/members[/{id}] listent les membres de l'équipe, changent leur rôle et les retirent, GET/POST /api/v1/team/invites et DELETE /api/v1/team/invites/{id} (plus POST …/{id}/resend) gèrent les invitations en attente, et POST/DELETE /api/v1/events/{id}/gates/{gateId}/scanners[/{membershipId}] affectent des scanners à une porte ou les en retirent (le tout avec team:write). POST /api/v1/privacy/export renvoie tout ce que vous détenez sur une adresse e-mail et POST /api/v1/privacy/anonymize l'efface de manière irréversible (privacy:write). GET /api/v1/audit-log lit le journal d'audit (audit:read), et GET /api/v1/billing et GET /api/v1/billing/invoices renvoient votre plan, la consommation mensuelle d'événements et les factures de la plateforme (billing:read).

Les lieux se trouvent sous /api/v1/locations, les kits de démarrage (quiz, repas de soutien, série d'ateliers, …) sous GET /api/v1/starter-kits, et POST /api/v1/uploads/presign vous donne une URL d'envoi pour l'image d'un événement ou d'un modèle (la réponse contient aussi une publicUrl permanente). Si vous préférez ne pas envoyer les octets vous-même, POST /api/v1/uploads/import avec { "url": "https://…/photo.jpg" } (ou base64) laisse Cleartix télécharger et stocker l'image pour vous. Pour placer une image dans la description de l'événement, ajoutez un nœud image au document Tiptap avec src égal à cette publicUrl ; les attributs facultatifs width (sm, md, full) et align (left, center, right) règlent la taille et la position, exactement comme dans l'éditeur. Chaque appel en écriture est consigné dans votre journal d'audit avec le préfixe de la clé, pour toujours savoir quelle intégration a modifié quoi.

La boutique via l'API

Le tag Shop de la spécification couvre le catalogue et le traitement : GET /api/v1/products (filtres ?kind=physical|digital et ?active=true|false), POST/PATCH pour les produits, POST /api/v1/products/{id}/file/presign + PUT /api/v1/products/{id}/file pour téléverser le fichier d'un produit numérique, /api/v1/shipping-methods, GET /api/v1/shipments pour la liste de travail, POST /api/v1/orders/{id}/ship et POST /api/v1/orders/{id}/lines/{lineId}/fulfil pour marquer une commande expédiée ou une ligne à retirer comme remise. GET /api/v1/orders/{id} renvoie le kind de la commande (tickets, pass ou shop), ses lines[] avec l'état de traitement, le compteur de téléchargements et les unités remboursées, et un bloc shipping (mode, adresse, transporteur, suivi). GET /api/v1/stats/products (scope stats:read, Studio/Pro) donne les unités, commandes et revenus par produit, par canal (shop / event) et avec les remboursements ; les assistants IA obtiennent la même chose via l'outil get_product_sales.

Le reste de la boutique se gère aussi via l'API : les catégories sous /api/v1/product-categories (lister, créer, modifier, supprimer et réordonner ; la catégorie d'un produit se définit avec categoryId sur le produit), l'ordre du catalogue avec POST /api/v1/products/reorder ({ "ids": [...] }) et les paramètres de la boutique — boutique ouverte ou fermée, texte d'introduction, politique de livraison et de retour, texte de consentement numérique, adresse d'expédition et affichage des catégories — avec GET/PATCH /api/v1/shop/settings. Les widgets boutique sont des widgets ordinaires sous /api/v1/widgets (voir plus haut).

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 — c'est la référence complète des endpoints résumés ci-dessus.

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.