Appliquer un changement d'unité avec écriture folio atomique (ADR-00D97)

POST

/v1/reservations/{id}/unit-change

curl --request POST \
  --url https://example.com/v1/reservations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/unit-change \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'idempotency-key: example' \
  --data '{ "targetUnitId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "targetRatePlanId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "decision": "charge", "reason": "example" }'

Authorizations

• ApiKeyAuth
• BearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Header Parameters

idempotency-key

required

string

>= 8 characters <= 200 characters

Clé d’idempotence (8-200 car.) — REQUISE pour éviter le double-posting folio sur réseau flaky.

Request Body ^required

Changement d’unité assisté. targetRatePlanId requis (le prix vit sur le plan, pas sur le type d’unité). decision : charge (supplément) / offer (geste commercial) / refund (crédit manuel V1).

Media type application/json

object

targetUnitId

required

string format: uuid

targetRatePlanId

required

Rate plan à appliquer sur l’unité cible (doit correspondre au targetRatePlanId de la preview)

string format: uuid

decision

required

Charge = facture le supplément ; offer = geste commercial (charge + void immédiat) ; refund = move + creditDueCents info (avoir manuel V1)

string

Allowed values: charge offer refund

reason

required

Motif audité (NF203 append-only, tracé dans origin_reference et description de la charge)

string

>= 1 characters <= 500 characters

Responses

200

Changement d’unité réalisé (move + écriture folio atomiques)

Media type application/json

object

data

required

object

reservationId

required

string format: uuid

fromUnitTypeId

required

string format: uuid

toUnitTypeId

required

string format: uuid

decision

required

string

Allowed values: charge offer refund

deltaTtcCents

required

Delta TTC signé en centimes (string bigint-safe)

string

chargeEntryId

ID de la ligne de charge postée (null si delta=0 ou refund)

string format: uuid

nullable

voidEntryId

ID de la contre-écriture (null si decision≠offer)

string format: uuid

nullable

creditDueCents

required

Crédit dû en centimes (string bigint-safe) — LIMITE V1 : remboursement reste manuel. “0” si decision≠refund.

string

currency

required

string

Allowed values: EUR GBP

folioPostingSkipped

required

True si la réservation est Confirmed sans folio de dépôt et que le delta est non nul — l’ajustement n’a pas pu être posté automatiquement.

boolean

Example

{
  "data": {
    "decision": "charge",
    "currency": "EUR"
  }
}

400

Corps invalide ou Idempotency-Key absente/invalide

Media type application/json

object

code

required

Code machine de l’erreur

string

message

required

Message lisible

string

origin

Origine domaine de l’erreur (optionnel)

object

boundedContext

string

module

string

status

required

integer

traceId

required

Identifiant de corrélation pour le support

string

Example

{
  "code": "RESERVATION_NOT_FOUND",
  "message": "Réservation introuvable",
  "status": 404
}

401

Non authentifié

Media type application/json

object

code

required

Code machine de l’erreur

string

message

required

Message lisible

string

origin

Origine domaine de l’erreur (optionnel)

object

boundedContext

string

module

string

status

required

integer

traceId

required

Identifiant de corrélation pour le support

string

Example

{
  "code": "RESERVATION_NOT_FOUND",
  "message": "Réservation introuvable",
  "status": 404
}

403

Permission refusée (stay.room_move) ou scope IDOR

Media type application/json

object

code

required

Code machine de l’erreur

string

message

required

Message lisible

string

origin

Origine domaine de l’erreur (optionnel)

object

boundedContext

string

module

string

status

required

integer

traceId

required

Identifiant de corrélation pour le support

string

Example

{
  "code": "RESERVATION_NOT_FOUND",
  "message": "Réservation introuvable",
  "status": 404
}

404

Réservation, séjour ou unité cible introuvable

Media type application/json

object

code

required

Code machine de l’erreur

string

message

required

Message lisible

string

origin

Origine domaine de l’erreur (optionnel)

object

boundedContext

string

module

string

status

required

integer

traceId

required

Identifiant de corrélation pour le support

string

Example

{
  "code": "RESERVATION_NOT_FOUND",
  "message": "Réservation introuvable",
  "status": 404
}

409

Statut incompatible, même unité, ou unité indisponible

Media type application/json

object

code

required

Code machine de l’erreur

string

message

required

Message lisible

string

origin

Origine domaine de l’erreur (optionnel)

object

boundedContext

string

module

string

status

required

integer

traceId

required

Identifiant de corrélation pour le support

string

Example

{
  "code": "RESERVATION_NOT_FOUND",
  "message": "Réservation introuvable",
  "status": 404
}