Passer au contenu principal

​
Idempotency-Key

Une écriture peut réussir alors que sa réponse se perd en route. Envoyez une Idempotency-Key pour pouvoir la renvoyer sans risque de doublon.
  • Obligatoire sur les écritures d’une location : création, modification, suppression, actions (annulation, départ, retour, report, changements, options) et paiements. Absente, la requête répond 400. Facultative sur toutes les autres écritures, photos comprises.
  • Sur une opération qui accepte ?dryRun=true, l’aperçu n’exige pas de clé : il n’écrit rien.
  • Valeur : 1 à 255 caractères imprimables, unique par opération (un UUID, par exemple), réutilisée à l’identique pour chaque renvoi de cette opération. Portée : votre clé API, la méthode et le chemin. Durée : 24 h.
  • Même clé, même corps : la réponse d’origine est renvoyée à l’identique, avec l’en-tête Idempotent-Replayed: true.
  • Même clé, corps différent : 422 IDEMPOTENCY_KEY_REUSED.
  • Même clé, requête encore en cours : 409 IDEMPOTENCY_IN_FLIGHT avec Retry-After ; renvoyez après le délai.
  • Seul un succès (2xx) est mémorisé. Après un refus survenu avant toute écriture, la même clé exécute de nouveau l’opération.
  • Écriture faite, réponse perdue : sur les opérations qui déclarent IDEMPOTENCY_ALREADY_APPLIED (création de devis et de location, actions sur une location, paiements, enregistrement d’un entretien, suppression d’une photo), une écriture enregistrée dont la réponse a échoué (5xx) garde sa clé. Un renvoi répond 409 IDEMPOTENCY_ALREADY_APPLIED avec resourceId, et l’en-tête Location quand la ressource se relit par un GET. Ne renvoyez pas : relisez la ressource. Sur les autres écritures, relisez la ressource avant de renvoyer après un 5xx.
Photos. La préparation d’un dépôt (POST /rentals/{rentalId}/photo-uploads) et l’enregistrement des photos déposées (POST /rentals/{rentalId}/photos) ne sont pas mémorisés par l’Idempotency-Key : un renvoi exécute de nouveau l’opération, et l’enregistrement se reconnaît par son uploadId.

​
Que renvoyer

​
Numéro de commande

partnerReference est votre numéro de commande : unique par code partenaire, ce n’est pas un mécanisme de renvoi. Un doublon répond 409 ALREADY_EXISTS (field, conflictingId). N’y mettez jamais un identifiant de paiement : une réservation a sa propre identité, indépendante de son paiement.

​
Aperçu avant écriture

?dryRun=true exécute l’action jusqu’au bout puis l’annule : la réponse est celle de l’appel réel, y compris effects.priceChange et effects.overpayment, et rien n’est enregistré. Les actions qui l’acceptent sont marquées dans la référence.
  • Une action qui modifie le prix accepte expectedTotalTTC. Passez-y effects.priceChange.newTotalTTC de l’aperçu (ou totalTTC de la location si priceChange est nul) : si le total recalculé s’en écarte d’une unité mineure ou plus, l’action répond 409 PRICE_CHANGED sans rien écrire. Sans expectedTotalTTC, elle s’applique au prix du moment.
  • Une modification qui ferait passer le total sous le montant déjà encaissé exige overpaymentResolution (REFUND_PENDING ou NO_REFUND, scope payments.refund) ; sinon 409 OVERPAYMENT_RESOLUTION_REQUIRED. Une clé partenaire reçoit resolvableByKey: false : le loueur traite la baisse dans Lexio.