Idempotence

Votre serveur réessaie. C’est normal, et c’est souhaitable : un délai d’attente dépassé, une coupure réseau, un redémarrage au mauvais moment. Cette API est faite pour que vous puissiez réessayer sans jamais vous demander si le premier appel est passé.

Les deux clés

Objet	Clé d’unicité
Logement	(votre compte, external_property_id)
Réservation	(votre compte, external_reservation_id)

Ces contraintes sont posées dans notre base de données, pas dans notre code. Deux appels identiques lancés au même instant ne peuvent donc pas créer deux objets, même s’ils passent tous les deux au même moment le test d’existence : le second est refusé par le moteur.

Comment savoir ce qui s’est passé

Le code HTTP le dit.

Code	Ce que ça veut dire
201	Créé à l’instant.
200	Existait déjà. Votre rejeu n’a rien créé de neuf.

Sur un logement, la réponse porte aussi created et unchanged :

{ "listing_id": "…", "created": false, "unchanged": true, "status": "published", "missing": [] }

unchanged: true veut dire que vous nous avez renvoyé exactement le même contenu et que nous n’avons rien réécrit. C’est le cas normal d’une synchronisation périodique : vous pouvez pousser tout votre parc chaque nuit sans nous faire travailler pour rien.

Ce qui n’est pas idempotent

Les disponibilités et les tarifs sont des écritures d’état : renvoyer le même calendrier produit le même résultat, ce qui revient au même pour vous, mais nous réécrivons. Rejouez sans crainte, simplement ne le faites pas en boucle.

Choisir vos identifiants

Prenez ceux de votre propre système, ceux qui sont stables. N’utilisez jamais un identifiant qui change quand l’objet est modifié : nous créerions un second logement à chaque changement de titre.