API

Tout ce que l’application fait sur une villa, une réservation ou un client est accessible en HTTP. Un script — ou un agent — travaille sur les mêmes données que l’interface, sous les mêmes règles, sans session de navigateur.

Cette page est la carte : l’authentification, la forme de chaque réponse, et chaque endpoint avec la page qui le détaille. Chaque endpoint a sa propre page : un appel, ses paramètres, ses réponses et ce qu’il refuse.

Authentification

Chaque requête /api/v1 porte une clé API dans l’en-tête x-api-key. Une clé se crée depuis Compte → Clés API et appartient à une seule organisation : cette organisation est tout le périmètre de la clé.

curl -H "x-api-key: $VILLASLOT_API_KEY" \
  "https://villaslot.app/api/v1/me"

L’organisation n’est jamais dans la requête

Ni dans le corps, ni dans l’URL, ni dans un en-tête. Elle vient de la clé et de rien d’autre. Une ressource appartenant à une autre organisation répond 404, exactement comme un identifiant qui n’existe pas.

La clé agit comme la personne qui l’a créée

Une clé n’est pas une seconde identité avec ses propres pouvoirs. Elle porte les droits du membre qui l’a créée, dans l’organisation pour laquelle elle a été créée. Rien n’est possible par l’API que la même personne ne pourrait faire dans l’interface — et rien n’est refusé qu’elle pourrait faire.

Deux questions décident de chaque appel, et les deux doivent passer :

Qui peut faire quoi

Ce partage n’est pas une décision de l’API : c’est la matrice de permissions du produit lui-même. Un membre est souvent celui qui a le client au téléphone, et le produit réserve la configuration des villas au propriétaire et aux administrateurs de l’organisation.

Enveloppe de réponse

Unités et conventions

• Les montants sont des entiers dans l’unité mineure de la devise de l’organisation. 1500000 en IDR vaut 15 000 roupies ; 4500 en EUR vaut 45,00 €. Ne divisez jamais par 100 sans connaître la devise.
• Les instants sont en ISO 8601 et en UTC (startAt, endAt, createdAt).
• Les jours et les heures sont locaux à l’organisation : une réservation se crée avec date (YYYY-MM-DD) et startMinute (minutes depuis minuit local). Lisez settings.timezone dans GET /api/v1/me.
• Les horaires d’ouverture sont des minutes locales hebdomadaires, dayOfWeek allant de 0 dimanche … 6 samedi.

Chaque endpoint

Limite de débit

La limite est portée par la clé, pas par l’IP : 120 requêtes par minute. Une clé au-delà de sa limite répond 429 sur tous les endpoints. Ralentissez et réessayez — rien n’a été fait.

Par où commencer

Appelez d’abord GET /api/v1/me : il transforme une simple clé en contexte — l’organisation qu’elle ouvre, le rôle qu’elle porte, le fuseau horaire et la devise dont dépendent tous les autres appels, et la marge que laisse l’offre.

Puis le chemin habituel : trouver ou créer le client, demander les disponibilités d’une villa, et créer la réservation. Toute la séquence, avec ses refus, est parcourue dans Créer une réservation.