Introduction

VillaSlot réserve des villas au créneau. Une villa a des horaires d’ouverture et une grille tarifaire ; un client réserve une heure, une matinée ou une journée ; la réservation est confirmée, payée, terminée — ou annulée.

C’est tout le produit, et tout ce qu’il fait est accessible en HTTP.

Les cinq choses que VillaSlot connaît

1

Organisation

Votre équipe et vos villas. Tout ce qui suit appartient à une seule organisation, et rien ne passe de l’une à l’autre. Votre offre limite le nombre de villas, de réservations et de clients qu’elle contient.

2

Villa

Un lieu que vous louez au créneau. Elle porte ses horaires d’ouverture — une grille hebdomadaire, jour par jour — et sa grille tarifaire, qui donne un prix à une durée. En dehors de ses horaires, rien ne peut être réservé.

3

Client

Celui qui réserve. Un nom, un moyen de le joindre, et son historique. Un client peut recevoir un lien d’accès : il le connecte à son propre espace, où il voit ses réservations et son solde, et rien d’autre.

4

Réservation

Une villa, un client, un créneau. Elle passe par des états — en attente, confirmée, terminée, annulée — et peut porter un paiement.

5

Paiement

Une réservation peut être payée en totalité, en partie, ou pas du tout. Un lien de paiement part vers le client ; Stripe répond et la réservation suit.

Deux portes d’entrée

L’interface — le calendrier, les pages des villas, la liste des clients. Faite pour la personne qui a le client au téléphone.

L’API — les mêmes données, les mêmes règles, sans navigateur. Faite pour un script, un site ou un agent. Une clé API appartient à une organisation et porte les droits de la personne qui l’a créée : rien n’est possible par l’API que cette même personne ne pourrait faire à la main.

L’API est la moitié intéressante de cette documentation. Rendez-vous sur API — c’est la carte de tous les endpoints, avec une page par appel.

Les règles à connaître avant tout

  • Un créneau en dehors des horaires d’ouverture d’une villa est refusé, tout comme une durée absente de sa grille tarifaire. Les deux sont propres à la villa, pas à l’organisation. Les séjours de plusieurs jours sont la seule exception aux horaires : une villa louée à la nuit ne se juge pas comme un shooting à l’heure.
  • Deux réservations confirmées ne peuvent pas se chevaucher sur la même villa. Le refus vient de la base de données, pas d’une vérification qu’une requête concurrente pourrait devancer.
  • Les montants sont des entiers dans l’unité mineure de votre devise. 1500000 en IDR vaut 15 000 roupies. Ne divisez jamais par 100 sans connaître la devise.
  • Votre offre a des limites sur les villas, les réservations et les clients. En atteindre une répond 409, dans l’interface comme dans l’API.

Et ensuite

  • Premiers pas — la première réservation, de bout en bout
  • Réservation publique — laissez vos clients réserver en ligne, et intégrez-la à votre site
  • Intégrations — envoyez vos clients vers une liste email ou un webhook
  • API — l’authentification, l’enveloppe de réponse, et chaque endpoint