API billetteries

En bref

• Une clé par organisateur, remise par l'équipe Pass&Go. Elle ne donne accès qu'aux événements de cet organisateur.
• Quatre appels : lister les événements, lire un événement, envoyer des billets, consulter l'état d'un billet.
• Envoyer deux fois le même billet ne crée pas de doublon : le billet est mis à jour.
• Les billets ne sont ni modifiés ni signés par Pass&Go. Le QR code imprimé reste celui de votre billetterie.
• Les adresses e-mail des acheteurs restent dans notre base. Elles ne descendent jamais sur les scanners.

Pour obtenir une clé, écrivez à contact@passgo-pro.com en précisant l'organisateur concerné.

Authentification

Chaque appel porte la clé dans l'en-tête Authorization. Les échanges se font en JSON, en HTTPS uniquement.

curl https://api.passgo-pro.com/v1/events \
  -H "Authorization: Bearer pgk_live_VOTRE_CLE"

Gardez la clé côté serveur, jamais dans une page web ou une application mobile. Si elle fuite, demandez sa révocation : une nouvelle clé vous sera remise.

Lister vos événements

GET https://api.passgo-pro.com/v1/events

{
  "evenements": [
    {
      "id": "8f1c…",
      "nom": "Festival des Lagunes",
      "lieu": "Palais de la Culture",
      "ville": "Abidjan",
      "debut": "2026-12-12T18:00:00Z",
      "fin": "2026-12-13T02:00:00Z",
      "ouverture_portes": "2026-12-12T17:00:00Z",
      "statut": "pret",
      "accepte_billets": true
    }
  ]
}

statut vaut brouillon, pret, en_cours ou termine. Un événement terminé n'accepte plus de billets.

Lire un événement

GET https://api.passgo-pro.com/v1/events/{id}

Renvoie les mêmes champs, plus les portes, les types de billets et le nombre de billets déjà reçus.

{
  "id": "8f1c…",
  "nom": "Festival des Lagunes",
  "statut": "pret",
  "portes": [ { "code": "A", "nom": "Entrée principale", "capacite": 4000 } ],
  "types":  [ { "nom": "VIP", "emoji": "🏆", "personnes_max": 1,
                "entrees_par_jour": "une_par_personne", "valide_du": null, "valide_au": null } ],
  "billets": { "total": 1250, "valides": 1238, "annules": 9, "rembourses": 3 }
}

Utilisez les code des portes et les nom des types dans vos envois. Les portes et les types se créent dans le back-office Pass&Go, pas par l'API.

Envoyer des billets

POST https://api.passgo-pro.com/v1/events/{id}/tickets

curl -X POST https://api.passgo-pro.com/v1/events/8f1c…/tickets \
  -H "Authorization: Bearer pgk_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{
    "tickets": [
      { "id": "CMD-1042-1", "qr": "QR-7F3A9C21", "porte": "A", "type": "VIP",
        "nom": "Awa Koné", "email": "awa@example.com", "achete_le": "2026-11-10T14:32:00Z" },
      { "id": "CMD-1042-2", "qr": "QR-7F3A9C22", "porte": "A" }
    ]
  }'

Champs d'un billet

Règles

• 1 000 billets au plus par appel. Au-delà, découpez en plusieurs appels.
• Un billet déjà reçu est mis à jour. Seuls les champs envoyés changent : les autres gardent leur valeur.
• Un champ envoyé vide, "" ou null, efface la valeur enregistrée.
• Pour annuler un billet, envoyez seulement { "id": "CMD-1042-2", "statut": "annule" }. Il sera refusé à l'entrée.
• Un billet en erreur n'empêche pas les autres d'être enregistrés.

Réponse

{
  "recus": 2,
  "importes": 1,
  "mis_a_jour": 0,
  "erreurs": [
    { "ligne": 2, "id": "CMD-1042-2", "motif": "Porte Z inconnue", "niveau": "erreur" }
  ]
}

ligne est la position du billet dans votre envoi, à partir de 1. Un niveau avertissement signale un billet enregistré malgré tout, par exemple avec un type inconnu. Si l'événement est encore en brouillon, un champ avertissement le rappelle : les scanners ne chargent les billets qu'une fois l'événement prêt.

Consulter un billet

GET https://api.passgo-pro.com/v1/events/{id}/tickets/{id_billet}

Utile quand un client vous dit qu'on lui a refusé l'entrée.

{
  "id": "CMD-1042-1",
  "statut": "valide",
  "porte": "A",
  "type": "VIP",
  "entre": true,
  "premiere_entree": { "le": "2026-12-12T19:04:11Z", "porte": "A" },
  "derniere_action": { "action": "entree", "le": "2026-12-12T19:04:11Z", "porte": "A" },
  "entrees": 1,
  "refus": 0
}

derniere_action.action vaut entree, entree_forcee ou sortie. Les scans faits sans réseau remontent dès que le scanner retrouve une connexion : l'état peut donc avoir quelques minutes de retard.

Erreurs

Toute erreur renvoie un JSON { "error": "message en français" } avec l'un de ces codes.

Limite : 60 appels par minute et par clé. Avec 1 000 billets par appel, cela suffit pour 60 000 billets par minute.

Bon à savoir

• Envoyez les billets au fil des ventes, ou en un seul lot avant l'événement. Les deux fonctionnent.
• Les scanners chargent les billets avant l'ouverture des portes. Un billet vendu pendant l'événement leur parvient dès qu'ils ont du réseau, en quelques minutes au plus.
• Un billet annulé après le chargement est refusé dès que le scanner reçoit la mise à jour. Un scanner resté sans réseau ne la reçoit qu'à son retour.

Une question technique ? Écrivez à contact@passgo-pro.com.