Billets, passes et e-mails

Ce qu'est un billet

Un billet est une entrée : une place à un événement à places réservées, ou une place à un événement en entrée libre. Sa référence est celle de la commande plus un numéro (TKT-1042-1), et il porte la place, le nom du titulaire pris dans la commande, le type de billet et ce qui a été payé pour lui.

Billets, PDF et fichiers de calendrier

• La confirmation de commande et Mes billets du participant affichent un billet par place, avec son code QR, la place, le titulaire et le type de billet, en anglais ou en arabe.
• Download tickets ouvre un PDF avec chaque billet valide de la commande, un par page A4, dessiné aux couleurs de l'événement avec son code QR ; un billet seul télécharge son propre PDF. Le texte du PDF est en caractères latins uniquement : la version arabe d'un billet est donc le billet web.
• Add to calendar télécharge un fichier de calendrier de l'événement, avec le lieu et un lien vers la page de l'événement.
• Les liens de téléchargement sont signés et valables 30 minutes ; la page en fait de nouveaux à chaque ouverture. Ils sont construits à partir du PUBLIC_API_URL de l'API : définissez-le donc avec l'adresse publique de l'API.

Codes QR

• Le code QR contient un code qui commence par TKY., une signature de la référence du billet faite avec TICKET_SECRET (le JWT_SECRET de l'API s'il n'est pas défini). Il ne contient rien de personnel.
• Seule l'empreinte de chaque code est stockée : la base ne contient donc jamais un billet utilisable.
• Définissez `TICKET_SECRET` une fois, avant de vendre. Le changer plus tard fait que chaque code QR déjà émis cesse de fonctionner à l'entrée.

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Les e-mails

• Définissez RESEND_API_KEY et MAIL_FROM (par exemple Ticketory <tickets@your-domain.com>) dans le .env de l'API pour les envoyer via Resend. Une réponse à un e-mail de billets va à l'e-mail de support de l'espace de travail. Chaque e-mail concernant une commande (billets, remboursements, avis d'annulation et rappel) est rédigé dans la langue de la commande, anglais ou arabe, avec le titre de l'événement dans cette langue ; un renvoi demandé depuis le site suit la langue de la page. Les e-mails de vérification et de réinitialisation suivent la page utilisée par le participant.
• Sans elles, chaque e-mail est écrit dans le journal de l'API au lieu d'être envoyé, c'est là qu'on lit un code de vérification sur une installation neuve (avec Docker : docker compose logs api). La confirmation indique alors que les billets sont prêts à télécharger.
• Un envoi échoué est retenté jusqu'à six fois, avec une attente croissante. La confirmation affiche l'état de l'e-mail et propose Resend email, une fois par minute.
• Les réglages Notifications du tableau de bord changent ce que l'équipe est informée ; ils n'empêchent jamais un e-mail d'atteindre un acheteur.

Rappels d'événement

• Un participant avec un compte qui garde Event reminders activé dans son profil (activé par défaut) reçoit un e-mail par événement, environ 24 heures avant la première session pour laquelle il a des billets valides, listant ces billets avec leurs places et un lien vers Mes billets.
• L'API cherche les rappels à envoyer une minute après son démarrage puis toutes les 15 minutes. Chacun est enregistré dans la table event_reminders avant d'être envoyé, si bien qu'aucun ne part deux fois, même après un redémarrage ou avec deux copies de l'API. Un envoi échoué est retenté jusqu'à trois fois tant que l'événement est encore à venir.
• Les billets remboursés, suspendus et annulés, les commandes impayées et les événements annulés ou en brouillon n'en reçoivent aucun, ni une commande payée après l'heure du rappel, puisque ses billets viennent d'être envoyés.
• EVENT_REMINDER_HOURS dans le .env de l'API change le délai (au plus 168, une semaine), et 0 désactive les rappels. Sans fournisseur d'e-mail, chaque rappel est écrit dans le journal de l'API, comme tous les autres e-mails.
• Le réglage News and offers du profil est seulement enregistré comme choix du participant : le template n'envoie aucun e-mail d'actualités ou d'offres.

• Paramètres des e-mails

Réémettre et annuler

• Reissue, sur un billet de la page de la commande, donne au billet un nouveau code QR : l'ancien cesse aussitôt de fonctionner à l'entrée, et les billets sont renvoyés par e-mail avec le nouveau code. Seul un billet valide peut être réémis.
• Void sert pour un billet que personne n'a payé, comme un billet gratuit. Sa place repart aussitôt en vente, sauf si son titulaire était déjà entré. Un billet payé est remboursé à la place, ce qui garde l'argent et l'entrée en accord.
• Les deux exigent tickets.manage, que détiennent les rôles Propriétaire et Finance des données d'exemple, et les deux sont inscrits dans la chronologie de la commande.

• Commandes, paiements et remboursements

Les routes derrière tout cela

• GET /api/orders/:reference/receipt répond avec la commande, ses billets avec une image QR tant que la commande est payée, l'état de l'e-mail et des downloads signés. Il exige le jeton d'accès de la commande ou celui du participant.
• GET /api/orders/:reference/tickets.pdf, GET /api/orders/:reference/calendar.ics et GET /api/tickets/:reference/pdf prennent un lien signé (?exp=&sig=) ; un lien erroné ou expiré donne un 404.
• POST /api/orders/:reference/resend-email remet l'e-mail en file ; moins d'une minute après donne un 429 COOLDOWN.
• POST /api/admin/tickets/:reference/reissue et /void exigent tickets.manage. Annuler un billet payé donne un 409 USE_REFUND.

• Référence de l'API