L'API de réservation que nous voudrions si nous étions le revendeur

La plupart des API de réservation de parking se résument à un appel de création, et rien d'autre. Tout ce qui est difficile dans la relation repart ensuite par email, où quelqu'un le lit et le ressaisit dans un autre système.

Nous sommes du côté qui reçoit. ParkAgenda intègre les réservations des revendeurs pour des parkings hors aéroport, donc nous passons nos journées à lire les payloads et les emails de confirmation des autres. Ce texte est écrit depuis l'autre rive. Si nous étions le revendeur qui s'intègre à un parking, voici ce que nous demanderions, et voici ce que ParkAgenda expose vraiment aujourd'hui.

Quatre pannes suffisent à expliquer presque tout

Une intégration revendeur casse à quatre endroits, et chacun a une forme d'API qui l'empêche. Une création rejouée qui réserve deux fois la même voiture, une annulation qui laisse la commission dans le flou, une disponibilité qui ne veut pas dire la même chose des deux côtés, et une modification faite par l'exploitant qui ne remonte jamais.

Rien d'exotique là-dedans. Les quatre se décident dans le contrat d'API, avant que qui que ce soit n'écrive une ligne de code en face.

L'idempotence à la création, sinon vous doublez un samedi de février

Chaque appel de création a besoin d'une clé fournie par l'appelant, et un second appel portant la même clé doit renvoyer la première réservation au lieu d'en créer une nouvelle. Sans cela, un timeout produit un doublon à tous les coups.

Voici l'exemple. Les chiffres sont construits pour montrer la mécanique, ils ne viennent d'aucun client. Prenons un parking de 300 places qui vend 65 pour cent de son volume via des revendeurs. Le samedi du premier départ en vacances d'hiver, un revendeur pousse 140 arrivées pour la journée. Quatre appels expirent au niveau de la passerelle au bout de trente secondes. L'écriture avait déjà réussi. La réponse n'est jamais revenue, donc la file du revendeur a rejoué, ce qui est exactement ce qu'une file bien faite doit faire.

Le parking porte maintenant 144 réservations pour 140 voitures. Quatre fantômes, c'est un peu plus de un pour cent du site. Ça a l'air supportable. Ça ne l'est pas, parce que la journée de pointe affichait déjà une occupation réservationnelle au-dessus de 100 pour cent, et que ces quatre lignes sont la raison pour laquelle l'exploitant a coupé la vente à seize heures le meilleur jour du mois.

Deux détails décident si l'idempotence sert à quelque chose ou si elle est décorative.

• La clé doit être la référence de réservation du revendeur. C'est la valeur que les deux camps savent retrouver pendant un appel d'assistance. Un identifiant généré par le parking ne dit rien à la personne au téléphone.
• Le rejeu doit renvoyer la réservation d'origine, avec le même identifiant, et indiquer qu'il s'agit d'un rejeu. Un 409 sec, sans corps de réponse, n'est pas de l'idempotence. C'est une énigme laissée à un développeur à vingt-trois heures.

Une annulation doit répondre à la question de l'argent

Une annulation qui ne renvoie qu'un statut oblige l'exploitant à reconstruire la commission à la main en fin de mois. La réponse doit porter ce que le client a payé, ce qui est remboursable, et si la commission reste acquise.

Prenons une réservation vendue 92 EUR avec 18 pour cent de commission, soit 16,56 EUR pour le revendeur. Le client annule 40 heures avant l'arrivée. Le revendeur garde-t-il sa commission sur un séjour annulé ? Certains la gardent, d'autres non, d'autres encore la gardent en deçà de 48 heures et la libèrent au-delà. Les trois positions se défendent commercialement. Aucune ne se lit dans un champ qui dit cancelled.

À 70 annulations par mois réparties sur trois revendeurs, ce flou devient un rapprochement de tableur qu'un responsable fait le dernier vendredi. C'est la première cause d'écart entre le chiffre de commission de l'exploitant et le relevé du revendeur.

La disponibilité doit renvoyer ce que l'exploitant accepte de vendre

Un appel de disponibilité doit répondre en unités vendables, avec l'heure du calcul, pas en capacité moins réservations. Ce sont deux nombres différents et l'écart est volontaire.

L'occupation réservationnelle d'une date est la somme des fenêtres de séjour rapportée à la capacité, et elle a le droit de dépasser 100 pour cent, parce que les voitures partent le matin et arrivent le soir. Sur le même site de 300 places, 312 séjours peuvent se croiser un dimanche sans que rien ne coince, parce que le nombre maximum de voitures présentes au même instant est de 284. Si l'appel répond zéro place, l'exploitant perd des ventes qu'il aurait honorées. S'il répond 300 moins 312, il répond un nombre négatif, et le revendeur arrête de vendre un site qui a de la place.

C'est donc l'exploitant qui fixe le chiffre. Il décide jusqu'où il accepte d'aller au-delà du comptage physique, et l'appel renvoie ce chiffre-là. Deux règles le rendent utilisable.

• Horodatez-le. Une disponibilité en cache sans heure de calcul est une rumeur.
• Une lecture ne pose jamais d'option. Seul l'appel de création réserve quelque chose, et il doit avoir le droit de refuser.

Prévenir le revendeur quand l'exploitant modifie

Les exploitants modifient des réservations toute la journée, et presque aucun logiciel de parking ne le dit à la source. Un rappel sur la poignée d'événements qui comptent, plus un point d'entrée avec curseur pour rattraper ce qu'on a manqué, supprime un appel téléphonique quotidien.

Les événements qui méritent d'être poussés sont peu nombreux. Un no-show. Un départ constaté plusieurs heures après l'heure prévue. Une plaque corrigée. Deux doublons fusionnés. Une annulation prise au comptoir plutôt qu'en ligne.

Maintenant la partie honnête. ParkAgenda n'envoie aucun webhook sortant. Nous en recevons, de notre prestataire de paiement pour notre propre facturation et de notre routeur d'emails pour les événements de distribution, et nous n'en émettons aucun. C'est le plus gros écart entre l'API décrite ci-dessus et celle que nous exploitons, et il vaut mieux le dire ici que le découvrir ensemble au deuxième rendez-vous.

Ce que ParkAgenda expose aujourd'hui

Il y a une vraie API REST, un document OpenAPI 3 derrière, une authentification par jeton porteur, et quatre chemins qui fonctionnent pour faire entrer une réservation. Ce n'est pas un programme d'API en libre-service et nous ne le présentons pas comme tel.

• REST sur HTTPS, avec des routes de ressources pour les réservations, les parkings, les organisations, les shifts, les trajets de navette, les analyses, la caisse et les états des lieux véhicule.
• Un document OpenAPI 3 qui couvre les opérations, leurs paramètres, leurs corps de requête et leurs réponses.
• Authentification par JWT porteur sur notre propre annuaire d'identités. Il n'y a ni clé d'API ni identifiants client, donc tout appelant a besoin d'une identité que nous créons.
• Quatre entrées possibles pour une réservation : le format d'email du revendeur, lu par un adaptateur écrit pour lui, une récupération par API sur curseur quand la source en propose une, l'import CSV pour une reprise d'historique ou pour une source qui n'offre ni l'un ni l'autre, et la saisie au comptoir. Les quatre produisent la même fiche de réservation, rattachée à sa source.
• Tout ce qui ne peut pas être appliqué sans risque part en quarantaine avec le message brut et le motif. Une personne promeut, retraite, met l'expéditeur en liste blanche ou écarte. Rien n'est perdu en silence.
• Des exports en sortie pour les réservations, les données brutes d'analyse et le récapitulatif de caisse.

Ce qu'il n'expose pas, dit clairement

• Pas de programme d'API public ou partenaire, pas d'inscription en libre-service, pas de clés d'API.
• Pas de webhooks sortants, pas d'abonnement aux événements.
• Pas de synchronisation bidirectionnelle. Une récupération est une lecture. Nous n'écrivons jamais dans le système d'un revendeur.
• Pas de place de marché de connecteurs, pas de catalogue d'intégrations. Une nouvelle source se construit un adaptateur à la fois, et c'est exactement comme cela que les deux sources en production ont été branchées.

Si vous voulez que ParkAgenda parle à un système que vous exploitez déjà, nous construisons le connecteur avec votre fournisseur. C'est un projet avec un périmètre et une date, pas une case à cocher dans un écran de réglages. Plus lent qu'une place de marché, et vrai. Ce que veut dire s'intégrer à un parking détaille qui fait quoi.

Les questions d'hébergement qu'un acheteur technique pose toujours

ParkAgenda tourne sur Microsoft Azure, dans une région européenne. Le trafic passe en TLS, le stockage est chiffré au repos par la plateforme, tous les horodatages sont conservés en UTC, et chaque parking porte son propre fuseau IANA, pour qu'un récapitulatif envoyé à vingt heures parte à vingt heures sur le site concerné et pas à l'heure du siège.

L'ingestion est idempotente aussi. Un email de réservation livré deux fois est dédoublonné sur son Message-ID ou sur une empreinte de son corps. C'est la même discipline qu'une clé d'idempotence à la création, appliquée à un canal qui n'en a jamais proposé.

Nous ne publions aucun pourcentage de disponibilité. Il n'y a pas d'engagement de service derrière, et un chiffre sans méthode de mesure ni avoir associé n'est qu'une décoration. Le jour où il y aura un engagement, il dira comment la disponibilité est mesurée et ce qui se passe quand elle n'est pas tenue.

Le backend, la console exploitant et ce site sont construits et exploités par JADEV, le groupe derrière ParkAgenda. Les gens qui écrivent le code d'ingestion sont ceux qui lisent les intakes en échec le lundi matin.

Questions fréquentes

On peut avoir une clé d'API et commencer cette semaine ?

Non. L'accès passe par une identité dans notre annuaire, que nous créons, et l'intégration se cadre avec nous d'abord. Il n'y a pas de chemin en libre-service aujourd'hui. Si c'est bloquant pour votre projet, autant le savoir maintenant.

ParkAgenda renvoie-t-il les mises à jour au revendeur ?

Non. L'ingestion va dans un seul sens. Quand l'exploitant annule au comptoir, le revendeur l'apprend comme il l'a toujours appris. C'est pour cela que la section sur les rappels est dans notre liste de travaux et pas dans notre documentation.

Notre revendeur n'a aucune API, seulement des emails de confirmation.

C'est le cas le plus fréquent et il est traité. Un adaptateur est écrit pour son format, donc il n'a rien à changer de son côté. Lire un email de réservation de revendeur explique ce que cela demande vraiment et pourquoi ce n'est jamais réglé une fois pour toutes.

Et ensuite

Si votre revendeur a une API que vous n'arrivez pas à exploiter, envoyez-nous sa documentation. Nous vous dirons lequel des quatre chemins convient, ce que représenterait le connecteur, et ce que nous ne saurions pas faire. La liste des fonctionnalités est la version courte de la même réponse.