Construisez votre propre intégration

Qu’est-ce qu’une API, et vous en faut-il une ?

Une API est une porte à l’arrière de votre compte. Là où vous cliquez dans votre écran de gestion, un programme peut passer par cette porte pour lire vos données ou y écrire — sans personne devant un écran.

Vous n’en avez besoin que pour faire ce que l’écran de gestion ne fait pas : des chiffres dans votre propre système, des places sur votre propre site, des billets depuis une caisse que vous avez déjà. Si vous pouvez le cliquer, cliquer va plus vite.

Celui qui construit cette intégration — votre webmaster, votre logiciel comptable, quelqu’un qui sait programmer — a besoin de deux choses : l’adresse ci-dessous et une clé que vous créez vous-même.

Ce que vous pouvez construire

Démarrage rapide en cinq étapes

De rien du tout à une intégration qui sait qu’un paiement est arrivé. Chaque étape prend des minutes, pas des jours.

1. 1

   Créez une clé

   Ouvrez Paramètres → Accès API dans votre écran de gestion et créez une clé avec les seuls droits dont vous avez besoin. Le jeton complet n’apparaît qu’une fois ; conservez-le comme un mot de passe.

2. 2

   Faites votre premier appel

   Demandez GET /me avec votre clé dans l’en-tête Authorization. Vous recevez votre organisation, votre formule et les droits de la clé. Si cela marche, le reste marchera aussi.

3. 3

   Créez une commande

   Envoyez les lignes à vendre vers POST /orders, avec une Idempotency-Key — elle est obligatoire ici. Si la connexion casse en chemin, le même appel répété ne crée pas une deuxième commande. Le champ reserved_until indique jusqu’à quand les places vous sont réservées.

4. 4

   Envoyez l’acheteur vers le lien de paiement

   Demandez le lien de paiement avec POST /orders/{id}/checkout, en indiquant l’adresse où l’acheteur arrive après avoir payé. Envoyez l’acheteur vers ce lien, ou affichez-le dans votre propre page. Le paiement passe par le prestataire que vous avez déjà relié ; dès qu’il est reçu, les billets sont créés et envoyés.

5. 5

   Laissez un webhook vous prévenir

   Préparez une adresse sur votre site et enregistrez-la. Dès qu’un paiement, une annulation ou un scan a lieu, vous le recevez là — sans devoir demander sans cesse s’il s’est passé quelque chose.

curl "https://passavo.eu/api/v1/me" \
  -H "Authorization: Bearer pv_live_YOUR_API_KEY" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withToken('pv_live_YOUR_API_KEY')
    ->get('https://passavo.eu/api/v1/me');

$data = $response->json('data');

const response = await fetch('https://passavo.eu/api/v1/me', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer pv_live_YOUR_API_KEY',
  },
});

const { data } = await response.json();

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer pv_live_YOUR_API_KEY"}
response = requests.get("https://passavo.eu/api/v1/me", headers=headers)
data = response.json()["data"]

Authentification

Chaque requête porte votre clé comme jeton bearer. Une clé appartient à une seule organisation : cette organisation est le monde entier de la requête, et vous ne pouvez jamais y lire par mégarde les données de quelqu’un d’autre.

Authorization: Bearer pv_live_YOUR_API_KEY

Une clé normale commence par pv_live_, une clé bac à sable par pv_test_. Ce préfixe n’est pas un secret mais une aide : qui le voit dans un journal sait aussitôt d’où il vient.

Le jeton complet n’existe qu’un instant, à la création. Ensuite nous n’en gardons qu’une empreinte irréversible (sha256). Perdu veut donc dire perdu : révoquez la clé et créez-en une nouvelle.

Droits

Une clé sans droits ne peut rien. C’est volontairement l’inverse de ce qu’on attendrait : ces clés sont distribuées par des clients à des outils tiers, et là, la valeur par défaut doit être « rien » et pas « tout ».

read

Tout consulter : vos lieux, produits, prix, places libres, réductions, bons cadeaux et abonnements, ainsi que vos commandes, billets, acheteurs et les scans à l’entrée.

write

Créer des commandes, les faire régler, les annuler et les rembourser ; annuler ou renvoyer des billets ; enregistrer l’entrée des visiteurs ; émettre des bons cadeaux et des abonnements.

webhooks

Gérer vos propres destinations de webhooks.

external_payment

Marquer comme payée une commande qui coûte de l’argent sans prestataire de paiement, par exemple après un virement ou un paiement en espèces (POST /orders/{id}/mark-paid). Un droit à part, à côté de write, pour ne le donner qu’à une caisse ou une comptabilité que vous gérez vous-même. Confirmer une commande à zéro euro se fait aussi sans lui.

Quand quelque chose ne va pas

Chaque erreur a la même forme, avec un code fixé et un texte traduit. Lisez le code et pas le texte : le texte peut être réécrit, le code jamais.

{
  "error": {
    "code": "validation_failed",
    "message": "…",
    "details": {}
  }
}

Une ligne d’une autre organisation renvoie toujours not_found, jamais un message disant que vous n’y avez pas accès. Si cette différence était visible, n’importe qui muni d’une clé valable pourrait deviner combien de produits a le voisin en parcourant les numéros.

Pagination, tri et filtres

Les listes arrivent page par page. Vous ne demandez pas la page trois mais ce qui vient après la page précédente : la réponse porte un curseur que vous renvoyez pour lire la suite. Ainsi une liste ne saute jamais de lignes quand quelque chose s’ajoute en cours de route.

Un paramètre que l’endpoint ne connaît pas est une erreur, pas un silence. Qui se trompe dans le nom d’un filtre doit l’apprendre — et pas récupérer sans le savoir la liste entière sans filtre.

Il n’y a volontairement pas de total dans la réponse : sur des dizaines de milliers de lignes, ce comptage coûte plus cher que la page elle-même.

{
  "data": [ … ],
  "meta": { "next_cursor": "…" }
}

Envoyer deux fois, exécuter une fois

Joignez une Idempotency-Key à chaque appel qui crée ou modifie quelque chose — une chaîne unique et aléatoire. Si le même appel revient avec la même clé, vous recevez exactement la même réponse sans que rien ne se produise une seconde fois. Pour POST /orders, elle est obligatoire.

Idempotency-Key: 6f1c0b4a-6b2f-4a1b-9c7e-1f2d3e4a5b6c

La même clé avec un contenu différent donne conflict et rien ne se passe. Une clé conservée vit 24 heures, et vaut par organisation.

Versions

La version est dans le chemin (/api/v1) et ne change qu’en cas de rupture ; une deuxième version tourne alors à côté et pas à travers. Chaque petit ajout est daté dans l’en-tête Passavo-Version, aujourd’hui 2026-09-20.

Ce qui peut s’ajouter dans cette version : un champ, un endpoint, une nouvelle valeur de tri ou de filtre, un nouveau code d’erreur. Construisez donc votre intégration pour qu’un champ inconnu ne la renverse pas.

Ce qui n’arrive jamais dans cette version : supprimer ou renommer un champ, changer un type, donner un autre sens à un code, ou rendre un paramètre obligatoire.

Limite de débit

Une clé peut faire 120 appels par minute. La limite vaut par clé et non par adresse, pour que deux clients derrière le même hébergeur ne se gênent pas.

Chaque réponse indique où vous en êtes dans X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Au-delà, vous recevez rate_limited avec un Retry-After ; attendez simplement ce nombre de secondes.

Exemples de code

La même requête en quatre langages, par groupe d’endpoints. Remplacez YOUR_API_KEY par votre propre clé — et ne la mettez jamais dans du code qu’un visiteur peut télécharger.

curl "https://passavo.eu/api/v1/me" \
  -H "Authorization: Bearer pv_live_YOUR_API_KEY" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withToken('pv_live_YOUR_API_KEY')
    ->get('https://passavo.eu/api/v1/me');

$data = $response->json('data');

const response = await fetch('https://passavo.eu/api/v1/me', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer pv_live_YOUR_API_KEY',
  },
});

const { data } = await response.json();

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer pv_live_YOUR_API_KEY"}
response = requests.get("https://passavo.eu/api/v1/me", headers=headers)
data = response.json()["data"]

curl "https://passavo.eu/api/v1/events" \
  -H "Authorization: Bearer pv_live_YOUR_API_KEY" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withToken('pv_live_YOUR_API_KEY')
    ->get('https://passavo.eu/api/v1/events');

$data = $response->json('data');

const response = await fetch('https://passavo.eu/api/v1/events', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer pv_live_YOUR_API_KEY',
  },
});

const { data } = await response.json();

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer pv_live_YOUR_API_KEY"}
response = requests.get("https://passavo.eu/api/v1/events", headers=headers)
data = response.json()["data"]

curl "https://passavo.eu/api/v1/products/12/slots" \
  -H "Authorization: Bearer pv_live_YOUR_API_KEY" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withToken('pv_live_YOUR_API_KEY')
    ->get('https://passavo.eu/api/v1/products/12/slots');

$data = $response->json('data');

const response = await fetch('https://passavo.eu/api/v1/products/12/slots', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer pv_live_YOUR_API_KEY',
  },
});

const { data } = await response.json();

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer pv_live_YOUR_API_KEY"}
response = requests.get("https://passavo.eu/api/v1/products/12/slots", headers=headers)
data = response.json()["data"]

curl "https://passavo.eu/api/v1/discounts" \
  -H "Authorization: Bearer pv_live_YOUR_API_KEY" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withToken('pv_live_YOUR_API_KEY')
    ->get('https://passavo.eu/api/v1/discounts');

$data = $response->json('data');

const response = await fetch('https://passavo.eu/api/v1/discounts', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer pv_live_YOUR_API_KEY',
  },
});

const { data } = await response.json();

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer pv_live_YOUR_API_KEY"}
response = requests.get("https://passavo.eu/api/v1/discounts", headers=headers)
data = response.json()["data"]

curl "https://passavo.eu/api/v1/orders" \
  -H "Authorization: Bearer pv_live_YOUR_API_KEY" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withToken('pv_live_YOUR_API_KEY')
    ->get('https://passavo.eu/api/v1/orders');

$data = $response->json('data');

const response = await fetch('https://passavo.eu/api/v1/orders', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer pv_live_YOUR_API_KEY',
  },
});

const { data } = await response.json();

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer pv_live_YOUR_API_KEY"}
response = requests.get("https://passavo.eu/api/v1/orders", headers=headers)
data = response.json()["data"]

curl "https://passavo.eu/api/v1/tickets" \
  -H "Authorization: Bearer pv_live_YOUR_API_KEY" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withToken('pv_live_YOUR_API_KEY')
    ->get('https://passavo.eu/api/v1/tickets');

$data = $response->json('data');

const response = await fetch('https://passavo.eu/api/v1/tickets', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer pv_live_YOUR_API_KEY',
  },
});

const { data } = await response.json();

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer pv_live_YOUR_API_KEY"}
response = requests.get("https://passavo.eu/api/v1/tickets", headers=headers)
data = response.json()["data"]

curl "https://passavo.eu/api/v1/check-ins" \
  -H "Authorization: Bearer pv_live_YOUR_API_KEY" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withToken('pv_live_YOUR_API_KEY')
    ->get('https://passavo.eu/api/v1/check-ins');

$data = $response->json('data');

const response = await fetch('https://passavo.eu/api/v1/check-ins', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer pv_live_YOUR_API_KEY',
  },
});

const { data } = await response.json();

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer pv_live_YOUR_API_KEY"}
response = requests.get("https://passavo.eu/api/v1/check-ins", headers=headers)
data = response.json()["data"]

curl "https://passavo.eu/api/v1/customers" \
  -H "Authorization: Bearer pv_live_YOUR_API_KEY" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withToken('pv_live_YOUR_API_KEY')
    ->get('https://passavo.eu/api/v1/customers');

$data = $response->json('data');

const response = await fetch('https://passavo.eu/api/v1/customers', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer pv_live_YOUR_API_KEY',
  },
});

const { data } = await response.json();

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer pv_live_YOUR_API_KEY"}
response = requests.get("https://passavo.eu/api/v1/customers", headers=headers)
data = response.json()["data"]

curl "https://passavo.eu/api/v1/openapi.json" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->get('https://passavo.eu/api/v1/openapi.json');

$data = $response->json('data');

const response = await fetch('https://passavo.eu/api/v1/openapi.json', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
  },
});

const { data } = await response.json();

import requests

headers = {"Accept": "application/json"}
response = requests.get("https://passavo.eu/api/v1/openapi.json", headers=headers)
data = response.json()["data"]

curl "https://passavo.eu/api/v1/webhook-deliveries" \
  -H "Authorization: Bearer pv_live_YOUR_API_KEY" \
  -H "Accept: application/json"

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()
    ->withToken('pv_live_YOUR_API_KEY')
    ->get('https://passavo.eu/api/v1/webhook-deliveries');

$data = $response->json('data');

const response = await fetch('https://passavo.eu/api/v1/webhook-deliveries', {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer pv_live_YOUR_API_KEY',
  },
});

const { data } = await response.json();

import requests

headers = {"Accept": "application/json", "Authorization": "Bearer pv_live_YOUR_API_KEY"}
response = requests.get("https://passavo.eu/api/v1/webhook-deliveries", headers=headers)
data = response.json()["data"]

Webhooks

Un webhook est l’inverse d’un appel : au lieu de demander sans cesse si le paiement est arrivé, nous envoyons un message à une adresse à vous dès que cela se produit. Cela évite des milliers d’appels par jour et vous le savez aussitôt plutôt qu’au passage suivant.

Vous gérez vos destinations dans votre écran de gestion sous Paramètres → Accès API, onglet Webhooks, ou via l’API avec une clé qui porte le droit webhooks. Chaque destination a son propre secret ; il vous sert à vérifier qu’un message vient bien de nous.

# De handtekening narekenen vanaf de opdrachtregel.
# T is de waarde van t= uit de header Passavo-Signature,
# het resultaat hoort gelijk te zijn aan de waarde van v1=.
printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET"

// De RUWE body, niet $request->all().
$body = $request->getContent();

// "t=1758355200,v1=9f86d0…" uit elkaar halen.
$delen = [];
foreach (explode(',', (string) $request->header('Passavo-Signature')) as $stuk) {
    [$sleutel, $waarde] = array_pad(explode('=', trim($stuk), 2), 2, '');
    $delen[$sleutel] = $waarde;
}

$t = $delen['t'] ?? '';
$verwacht = hash_hmac('sha256', $t . '.' . $body, $secret);

// hash_equals vergelijkt in constante tijd; de tijdstempel
// houdt een opgevangen bericht tegen dat later opnieuw komt.
if (! ctype_digit($t) || abs(time() - (int) $t) > 300 || ! hash_equals($verwacht, $delen['v1'] ?? '')) {
    abort(400);
}

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: de ruwe body als string, bv. via express.raw().
const header = request.headers['passavo-signature'] ?? '';
const delen = Object.fromEntries(header.split(',').map((s) => s.trim().split('=', 2)));

const verwacht = createHmac('sha256', secret).update(delen.t + '.' + rawBody).digest('hex');
const gekregen = delen.v1 ?? '';

const vers = /^\d+$/.test(delen.t ?? '')
  && Math.abs(Date.now() / 1000 - Number(delen.t)) <= 300;
const geldig = vers
  && verwacht.length === gekregen.length
  && timingSafeEqual(Buffer.from(verwacht), Buffer.from(gekregen));

import hashlib, hmac, time

# raw_body: de ruwe body als bytes, bv. request.get_data() in Flask.
header = request.headers.get("Passavo-Signature", "")
delen = dict(stuk.strip().split("=", 1) for stuk in header.split(",") if "=" in stuk)
t = delen.get("t", "")

verwacht = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()

# compare_digest vergelijkt in constante tijd.
geldig = (t.isdigit()
          and abs(time.time() - int(t)) <= 300
          and hmac.compare_digest(verwacht, delen.get("v1", "")))

La liste complète des événements et de leur contenu se trouve dans la référence. →

Ce qui change

Chaque changement qui mérite d’être signalé reçoit une nouvelle version datée. Si votre intégration reste sur une date ancienne, elle continue de fonctionner — la date dit seulement contre quel comportement elle a été construite.

1. 2026-09-20

   La première version

   Des clés avec droits, un bac à sable, un format de réponse unique et une pagination par curseur. En lecture : votre organisation, vos lieux, produits, créneaux, événements, réductions, bons cadeaux et abonnements, commandes, billets, acheteurs et scans. En écriture : créer, régler, annuler et rembourser des commandes, annuler des billets, enregistrer des entrées, émettre des bons cadeaux et des abonnements. Et des webhooks sortants, signés par destination.