Poster une charge manuelle sur le folio (extra, repas, parking, débours, pénalité…)

POST

/v1/folios/{id}/charges

curl --request POST \
  --url https://example.com/v1/folios/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/charges \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "chargeType": "ancillary", "amountTtcCents": "2200", "description": "example", "quantity": 1 }'

Ajoute une écriture inaltérable au folio (NF203 append-only). TVA résolue côté SERVEUR depuis le pays de l’établissement (règle de l’immeuble). businessDate dérivée côté SERVEUR (ADR-00D78) — ne pas envoyer. Permission : folio.charge (réceptionniste + manager). Types autorisés : ancillary, meal_plan, parking, laundry, phone, minibar, other, disbursement, penalty. Exclus (Night Audit exclusif) : room_night, tourism_tax, long_stay_installment. Idempotency-Key obligatoire (8–200 car.) — anti-double-click front.

Authorizations

• ApiKeyAuth
• BearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Identifiant du folio

Header Parameters

Idempotency-Key

required

string

Clé d’idempotence OBLIGATOIRE (8–200 car.) — anti-double-posting

Request Body ^required

Charge manuelle. Le montant est en centimes TTC (bigint string). TVA et businessDate résolues côté serveur.

Media type application/json

object

chargeType

required

Type de charge (liste fermée — Night-Audit-exclusifs rejetés)

string

Allowed values: ancillary meal_plan parking laundry phone minibar other disbursement penalty

Example

ancillary

amountTtcCents

required

Montant TTC en centimes (bigint string, > 0). Le serveur décompose HT + TVA.

string

Example

2200

description

Libellé / mention (obligatoire pour disbursement — opposabilité CGI 267-II-2°)

string

nullable >= 1 characters <= 500 characters

quantity

Quantité (défaut 1). Le total TTC = amountTtcCents × quantity.

integer

>= 1

Example

1

Responses

201

Charge enregistrée — écriture folio inaltérable ajoutée (NF203)

Media type application/json

object

data

required

object

entryId

required

Identifiant de la FolioEntry créée

string format: uuid

folioId

required

string format: uuid

chargeType

required

string

chargeNature

required

Nature fiscale résolue côté serveur

string

Allowed values: revenue disbursement penalty

amountHtCents

required

Montant HT en centimes (bigint string)

string

amountTaxCents

required

Montant TVA en centimes (bigint string)

string

businessDate

required

BusinessDate de l’établissement au moment du posting

string format: date

Example

{
  "data": {
    "chargeType": "ancillary",
    "chargeNature": "revenue"
  }
}

400

Body invalide (type inconnu, montant non numérique, description manquante pour disbursement, Idempotency-Key manquante)

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 ou périmètre fiscal du folio non vérifiable (fail-closed)

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

Ressource 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

Folio non-open, montant hors plage, businessDate non résolvable

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
}