Développeurs

Encaisser des réservations depuis un autre point de vente

Laissez un point de vente externe lire le montant d'une réservation et renvoyer la vente, pour que la réservation soit terminée.

Ce que c'est

Le relais d'encaissement, c'est une adresse avec deux appels : GET et POST /api/v1/{slug}/appointments/{id}/checkout. GET renvoie le montant de la réservation : chaque prestation et chaque supplément avec son lineId et la personne qui l'a fait, le prix, les remises, les lignes de taxe, l'acompte déjà payé, et dueCents, qui est exactement ce qu'il faut encaisser. POST enregistre la vente que votre point de vente a encaissée, termine la réservation et lui rattache la vente, avec le même code d'encaissement que le point de vente de Bookatu.

À quoi ça sert

Personne n'encaisse une visite deux fois, et la réservation, la vente, le crédit de l'équipe et l'argent concordent dans Bookatu comme si son propre point de vente avait encaissé. L'envoi est idempotent sur votre externalSaleId, donc une nouvelle tentative après une connexion coupée renvoie replayed: true et n'écrit rien.

Comment l'utiliser

  1. 1Les propriétaires et les admins créent la clé dans Settings, puis API & monitoring, sous API keys. Dans What this key may do, cochez les deux cases de la ligne Checkout at another point of sale : See what a booking comes to at checkout (checkout:read) et Check bookings out from another point of sale (checkout:write). Elles ne sont jamais cochées d'office, et une clé créée avant les périmètres ne les porte jamais. La personne qui crée la clé doit pouvoir voir l'agenda de tout le monde (pour checkout:read) et modifier l'agenda (pour checkout:write). Ajoutez See bookings (bookings:read) pour lister les réservations du jour avec GET /appointments, et See clients (customers:read) si votre point de vente a besoin du nom, de l'e-mail et du téléphone du client. Sans cela, le client n'arrive que par son id.
  2. 2Envoyez la clé en Authorization: Bearer à chaque appel. Appelez GET /api/v1/{slug}/appointments/{id}/checkout et saisissez ses lignes dans votre caisse. checkout.allowed indique si la réservation peut être encaissée maintenant, et checkout.blocked donne la raison : not_live, deposit_pending, already_checked_out ou invoiced. invoiced signifie que la réservation figure sur une facture et se paie sur celle-ci, n'encaissez donc pas d'argent pour elle à votre point de vente.
  3. 3Encaissez l'argent, puis faites un POST à la même adresse avec { externalSaleId, source, amountCents, currency, tender, tipCents, tipSplit, lines }. externalSaleId est l'id de vente propre à votre point de vente. source nomme votre point de vente, comme front_desk_pos (par défaut external, et jamais bookatu). amountCents doit être égal à dueCents. currency est facultatif mais doit être celle de l'établissement. tender vaut card, cash ou other. lines, sous la forme [{ lineId, staffId }], crédite une ligne à quelqu'un d'autre.
  4. 4Envoyer à nouveau le même externalSaleId depuis le même point de vente renvoie la vente d'origine avec replayed: true. Les refus n'écrivent rien et donnent une raison : 400 card_number (externalSaleId ou source ressemble à un numéro de carte, ce qui n'est jamais accepté) ; 409 amount_mismatch (avec expectedCents), already_checked_out, external_sale_used, lines_changed (relisez l'encaissement), not_live, deposit_pending ou invoiced (la réservation se paie sur sa facture) ; 422 currency ou tip_split ; 503 tant que le relais est encore en cours d'activation pour l'établissement.
  5. 5Pour être informé de chaque encaissement, ajoutez un webhook dans la carte Webhooks de la même page et cochez booking.checked_out sous Only if you tick it. Il n'est jamais envoyé à un point de terminaison qui reçoit tous les événements. Il se déclenche aussi pour les encaissements au point de vente de Bookatu (sale.source bookatu), avec le même contenu que GET et le client par son id uniquement.
  6. 6La référence complète, avec chaque champ et des exemples, se trouve dans la documentation développeurs sur /developers#checkout-handoff, et en markdown sur /developers.md.

Was this helpful?

Vous n'avez pas trouvé ce qu'il vous faut ?

Contacter le support ou consultez la FAQ.