Costruisca la Sua integrazione

Che cos’è un’API, e Le serve?

Un’API è una porta sul retro del Suo account. Dove Lei clicca nella schermata di gestione, un programma può passare da quella porta per leggere i Suoi dati o scriverci — senza nessuno davanti a uno schermo.

Le serve solo quando vuole qualcosa che la schermata di gestione non fa: numeri nel Suo sistema, posti liberi sul Suo sito, biglietti da una cassa che ha già. Se può cliccarlo, cliccare è più veloce.

Chi costruisce l’integrazione — il Suo webmaster, il Suo gestionale contabile, qualcuno che sa programmare — ha bisogno di due cose: l’indirizzo qui sotto e una chiave che crea Lei stesso.

Che cosa può costruire

Avvio rapido in cinque passi

Da zero a un’integrazione che sa che è stato pagato. Ogni passo richiede minuti, non giorni.

1. 1

   Crei una chiave

   Apra Impostazioni → Accesso API nella schermata di gestione e crei una chiave con i soli diritti che Le servono. Il token completo lo vede una volta sola; lo conservi come conserva una password.

2. 2

   Faccia la prima chiamata

   Richieda GET /me con la Sua chiave nell’intestazione Authorization. Riceve la Sua organizzazione, il Suo piano e i diritti della chiave. Se questo funziona, funziona anche il resto.

3. 3

   Crei un ordine

   Invii le righe da vendere a POST /orders, con una Idempotency-Key — qui è obbligatoria. Se la connessione si interrompe a metà, la stessa chiamata ripetuta non produce un secondo ordine. Il campo reserved_until indica fino a quando i posti Le vengono riservati.

4. 4

   Mandi l’acquirente al link di pagamento

   Richieda il link di pagamento con POST /orders/{id}/checkout, insieme all’indirizzo dove l’acquirente arriva dopo aver pagato. Mandi l’acquirente a quel link, oppure lo mostri nella Sua pagina. Il pagamento passa dal fornitore che ha già collegato; appena è arrivato, i biglietti vengono creati e inviati.

5. 5

   Lasci che un webhook La avvisi

   Prepari un indirizzo sul Suo sito e lo registri. Appena qualcosa viene pagato, annullato o scansionato, lo riceve lì — senza dover continuare a chiedere se è successo qualcosa.

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

Autenticazione

Ogni richiesta porta la Sua chiave come bearer token. Una chiave appartiene a una sola organizzazione: quell’organizzazione è il mondo intero della richiesta, e non può mai recuperare per sbaglio i dati di qualcun altro.

Authorization: Bearer pv_live_YOUR_API_KEY

Una chiave normale inizia con pv_live_, una chiave sandbox con pv_test_. Quel prefisso non è un segreto ma un aiuto: chi lo vede in un registro sa subito da dove viene.

Il token completo esiste per un istante, alla creazione. Dopo ne conserviamo solo un’impronta irreversibile (sha256). Perso vuol dire davvero perso: revochi la chiave e ne crei una nuova.

Diritti

Una chiave senza diritti non può nulla. È volutamente il contrario di quello che ci si aspetterebbe: queste chiavi vengono date dai clienti a strumenti di terzi, e allora il valore predefinito deve essere «niente» e non «tutto».

read

Consultare tutto: le Sue sedi, prodotti, prezzi, posti liberi, sconti, buoni regalo e abbonamenti, e anche i Suoi ordini, biglietti, acquirenti e le scansioni all’ingresso.

write

Creare ordini, farli pagare, annullarli e rimborsarli; annullare o rinviare biglietti; registrare l’ingresso dei visitatori; emettere buoni regalo e abbonamenti.

webhooks

Gestire le proprie destinazioni webhook.

external_payment

Segnare come pagato un ordine che costa denaro senza fornitore di pagamento, per esempio dopo un bonifico o un pagamento in contanti (POST /orders/{id}/mark-paid). Un diritto a parte, accanto a write, così lo dà solo a una cassa o a una contabilità che gestisce Lei stesso. Confermare un ordine da zero euro si può anche senza.

Quando qualcosa va storto

Ogni errore ha la stessa forma, con un codice fisso e un testo tradotto. Legga il codice e non il testo: il testo può essere riscritto, il codice mai.

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

Una riga di un’altra organizzazione restituisce sempre not_found e mai un messaggio che dice che non può accedervi. Se quella differenza fosse visibile, chiunque con una chiave valida potrebbe scoprire quanti prodotti ha il vicino scorrendo i numeri.

Paginazione, ordinamento e filtri

Gli elenchi arrivano una pagina per volta. Non chiede la pagina tre ma quello che viene dopo la pagina precedente: la risposta porta un cursore, e Lei lo rimanda per continuare a leggere. Così un elenco non salta mai righe se qualcosa si aggiunge mentre sfoglia.

Un parametro che l’endpoint non conosce è un errore, non un silenzio. Chi sbaglia il nome di un filtro deve saperlo — e non ricevere senza accorgersene l’elenco intero senza filtro.

Nella risposta non c’è volutamente un totale: su decine di migliaia di righe quel conteggio costa più della pagina stessa.

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

Inviare due volte, eseguire una volta

Aggiunga una Idempotency-Key a ogni chiamata che crea o modifica qualcosa — una stringa casuale e unica. Se la stessa chiamata arriva di nuovo con la stessa chiave, riceve esattamente la stessa risposta senza che nulla accada una seconda volta. Per POST /orders è obbligatoria.

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

La stessa chiave con contenuto diverso dà conflict e non succede nulla. Una chiave conservata dura 24 ore e vale per organizzazione.

Versioni

La versione sta nel percorso (/api/v1) e cambia solo in caso di rottura; una seconda versione gira allora accanto e non attraverso. Ogni piccola aggiunta viene datata nell’intestazione Passavo-Version, oggi 2026-09-20.

Che cosa può aggiungersi in questa versione: un campo, un endpoint, un nuovo valore di ordinamento o di filtro, un nuovo codice di errore. Costruisca quindi l’integrazione in modo che un campo sconosciuto non la faccia cadere.

Che cosa non accade mai in questa versione: togliere o rinominare un campo, cambiare un tipo, dare a un codice un altro significato, o rendere obbligatorio un parametro.

Limite di chiamate

Una chiave può fare 120 chiamate al minuto. Il limite vale per chiave e non per indirizzo, così due clienti dietro lo stesso provider cloud non si ostacolano.

Ogni risposta Le dice a che punto è in X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Se supera il limite riceve rate_limited con un Retry-After; aspetti semplicemente quei secondi.

Esempi di codice

La stessa richiesta in quattro linguaggi, per gruppo di endpoint. Sostituisca YOUR_API_KEY con la Sua chiave — e non la metta mai in codice che un visitatore può scaricare.

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

Webhook

Un webhook è il contrario di una chiamata: invece di chiedere in continuazione se è arrivato il pagamento, mandiamo noi un messaggio a un Suo indirizzo appena succede. Questo risparmia migliaia di chiamate al giorno e Lei lo sa subito invece che al giro successivo.

Gestisce le Sue destinazioni nella schermata di gestione in Impostazioni → Accesso API, scheda Webhook, oppure tramite l’API con una chiave che porta il diritto webhooks. Ogni destinazione ha un proprio segreto; con quello verifica che un messaggio venga davvero da noi.

# 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", "")))

L’elenco completo degli eventi e del loro contenuto sta nel riferimento. →

Che cosa cambia

Ogni modifica che merita di essere segnalata riceve una nuova versione datata. Se la Sua integrazione resta su una data più vecchia, continua a funzionare — la data dice solo su quale comportamento è stata costruita.

1. 2026-09-20

   La prima versione

   Chiavi con diritti, una sandbox, un unico formato di risposta e paginazione a cursore. In lettura: la Sua organizzazione, sedi, prodotti, fasce orarie, eventi, sconti, buoni regalo e abbonamenti, ordini, biglietti, acquirenti e scansioni. In scrittura: creare, pagare, annullare e rimborsare ordini, annullare biglietti, registrare ingressi, emettere buoni regalo e abbonamenti. E webhook in uscita, firmati per destinazione.