Passerelle Amenitiz

Version 1.0.0 — API de lecture, protégée par clé, au-dessus de l’API interne du PMS.

Ce n’est pas une API officielle Amenitiz. Elle rejoue les appels que fait l’interface d’administration, depuis un navigateur authentifié par le cookie de session du compte. Amenitiz peut la casser sans préavis. Lecture seule : aucune route n’écrit. Les réponses contiennent des noms de clients et des états de paiement — la clé est un secret, et ces réponses ne se mettent pas en cache côté public.

Prise en main

Toute requête porte la clé, au choix dans X-API-Key ou dans Authorization: Bearer :

curl -H "X-API-Key: $CLE" "https://amenitiz.endurance.tools/v1/day"

Les réponses sont enveloppées. data porte la donnée, meta dit d’où elle sort :

{
  "data": { … },
  "meta": {
    "route": "/v1/day",
    "cache": "succès",           // succès | partiel | absent | périmé
    "age_ms": 12043,             // âge de la donnée servie
    "upstream": ["/fr/api/v2/property/rooms", …],
    "upstream_budget_remaining": 287
  }
}

?raw=1 retire l’enveloppe. ?fresh=1 ignore le cache — à réserver aux vrais besoins : chaque appel non caché est une requête de plus chez Amenitiz, et le budget horaire est partagé.

Le cache est mémorisé par URL amont : 10 min pour le référentiel et les séries de performance, 1 min pour tout ce qui bouge. Si Amenitiz devient injoignable, une réponse périmée de moins de 15 min est servie avec meta.cache = "périmé" et un meta.warning — plutôt qu’une erreur.

Référentiel

GET `/v1/rooms`

Les chambres physiques, avec leur numéro, leur nom et leur état de ménage.

Paramètre	Type	Défaut	Description
`sort`	texte	`asc`	Tri par numéro de chambre. Admises : `asc`, `desc`

Source amont : GET /fr/api/v2/property/rooms

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/rooms"

GET `/v1/room-categories`

Les catégories de chambre et leur tarif par défaut.

Aucun paramètre.

Source amont : GET /fr/api/v2/property/room_categories

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/room-categories"

Planning

GET `/v1/reservations`

Les réservations chevauchant la fenêtre demandée, chambre par chambre.

Une réservation occupe la nuit du jour J si arrival_date ≤ J < departure_date. La fenêtre remonte donc aussi les départs du premier jour et les arrivées du dernier : filtrer côté appelant. Champs à ne pas croire : `has_comments` vaut exactement « source = Booking.com » (ce n’est pas une note client), `check_in_status` vaut `without_status` partout (la fonction check-in n’est pas utilisée), `extras` est toujours vide. Vérifié sur 422 réservations le 01/09/2026. `payment_status`, lui, est fiable.

Paramètre	Type	Défaut	Description
`start_date`	date	obligatoire	Premier jour de la fenêtre (inclus).
`end_date`	date	obligatoire	Dernier jour de la fenêtre (exclu pour les nuitées).
`booking_statuses`	liste	calculé	Statuts retenus. Défaut = les quatre statuts « vivants ». Ajouter `cancelled` fait remonter les annulations. Admises : `confirmed`, `modified`, `quote_confirmed`, `quote_pending`, `cancelled`, `no_show`
`unallocated`	booleen	`false`	true = uniquement les réservations SANS chambre attribuée (anomalie à surveiller).
`room_category_ids`	liste	—	Identifiants de catégorie, séparés par des virgules. Omis = toutes. Volontairement optionnel : une catégorie créée plus tard serait absente d’une liste figée.

Source amont : GET /fr/api/v2/reservations/rooms

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/reservations?start_date=2026-09-01&end_date=2026-09-01"

GET `/v1/blocks`

Les blocages manuels du calendrier : fermetures, travaux, et séjours saisis à la main.

🔑 À ne jamais ignorer. Le 01/09/2026, quatre chambres sur neuf étaient occupées par des séjours saisis en BLOCAGE et non en réservation : ne lire que /v1/reservations sous-estimait l’occupation de moitié. Un blocage ne porte AUCUN nombre de personnes, et son statut ne dit pas s’il s’agit d’un client ou d’une fermeture — un `ooi` « hors vente » portait un nom de personne, un `ooo` portait « Travaux ». Le motif est du texte libre.

Paramètre	Type	Défaut	Description
`start_date`	date	obligatoire	Premier jour de la fenêtre (inclus).
`end_date`	date	obligatoire	Dernier jour de la fenêtre (exclu pour les nuitées).
`statuses`	liste	calculé	Types de blocage retenus. Admises : `ooi`, `ooo`, `pre_booked`
`room_category_ids`	liste	—	Identifiants de catégorie, séparés par des virgules. Omis = toutes. Volontairement optionnel : une catégorie créée plus tard serait absente d’une liste figée.

Source amont : GET /fr/api/v2/calendar/rooms

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/blocks?start_date=2026-09-01&end_date=2026-09-01"

GET `/v1/unavailable-rooms`

Les couples chambre/date fermés à la vente.

Paramètre	Type	Défaut	Description
`start_date`	date	obligatoire	Premier jour de la fenêtre (inclus).
`end_date`	date	obligatoire	Dernier jour de la fenêtre (exclu pour les nuitées).
`room_category_ids`	liste	—	Identifiants de catégorie, séparés par des virgules. Omis = toutes. Volontairement optionnel : une catégorie créée plus tard serait absente d’une liste figée.

Source amont : GET /fr/api/v2/calendar/unavailable_rooms

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/unavailable-rooms?start_date=2026-09-01&end_date=2026-09-01"

GET `/v1/pricing`

Les prix posés par catégorie et par date, pour un plan tarifaire.

Seules les dates dont le prix a été explicitement modifié apparaissent ; ailleurs, c’est le `default_price` de la catégorie qui s’applique.

Paramètre	Type	Défaut	Description
`start_date`	date	obligatoire	Premier jour de la fenêtre (inclus).
`end_date`	date	obligatoire	Dernier jour de la fenêtre (exclu pour les nuitées).
`rate_plan`	texte	`default`	Plan tarifaire. Seul « default » (Standard) est confirmé sur cette propriété.

Source amont : GET /fr/api/v2/pricing/rate_plans/{plan}/pricing_calendars

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/pricing?start_date=2026-09-01&end_date=2026-09-01"

GET `/v1/day`

Vue consolidée d’une nuit : qui occupe quelle chambre, réservations ET blocages réunis.

La route à utiliser en premier. Elle fusionne les deux sources d’occupation, rattrape les longs séjours commencés avant la fenêtre, et distingue arrivées, départs et recouches. Un blocage n’ayant pas de nombre de personnes, `personnes` y vaut null — jamais 0.

Paramètre	Type	Défaut	Description
`date`	date	calculé	Jour observé (défaut : aujourd’hui, fuseau Europe/Paris).
`history_days`	entier	`180`	Profondeur de rattrapage des séjours commencés avant la date. 180 j couvre les blocages à l’année.

Source amont : GET /fr/api/v2/property/rooms, GET /fr/api/v2/property/room_categories, GET /fr/api/v2/reservations/rooms, GET /fr/api/v2/calendar/rooms

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/day"

Opérations

GET `/v1/dashboard`

Les indicateurs du jour : occupation, chiffre d’affaires, ADR, RevPAR, pickup.

Paramètre	Type	Défaut	Description
`date`	date	calculé	Jour observé (défaut : aujourd’hui, fuseau Europe/Paris).

Source amont : GET /fr/api/v1/dashboards/hero, GET /fr/api/v1/dashboards/todays_work_counts

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/dashboard"

GET `/v1/arrivals`

Les arrivées du jour, prêtes à afficher : chambre, effectif, paiement, état de propreté.

Paramètre	Type	Défaut	Description
`date`	date	calculé	Jour observé (défaut : aujourd’hui, fuseau Europe/Paris).

Source amont : GET /fr/api/v1/dashboards/arrivals

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/arrivals"

GET `/v1/housekeeping`

L’état d’entretien chambre par chambre : recouche, départ, arrivée, effectif, affectation.

Paramètre	Type	Défaut	Description
`date`	date	calculé	Jour observé (défaut : aujourd’hui, fuseau Europe/Paris).
`sort_by`	texte	`number`	Critère de tri. Admises : `number`, `status`, `name`
`sort_direction`	texte	`asc`	Sens du tri. Admises : `asc`, `desc`

Source amont : GET /fr/api/v1/housekeeping/individual_rooms.json

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/housekeeping"

GET `/v1/housekeeping/board`

Le tableau d’entretien tel que l’affiche le tableau de bord : recouches, remises à blanc, chambres prêtes.

Paramètre	Type	Défaut	Description
`date`	date	calculé	Jour observé (défaut : aujourd’hui, fuseau Europe/Paris).

Source amont : GET /fr/api/v1/dashboards/operations/housekeeping

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/housekeeping/board"

GET `/v1/housekeeping/staff`

Le personnel d’entretien déclaré.

Aucun paramètre.

Source amont : GET /fr/api/v1/housekeeping/staff

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/housekeeping/staff"

GET `/v1/payments/summary`

Le bandeau AmenitizPay : prochain versement, encaissements du jour, paiements en échec.

Paramètre	Type	Défaut	Description
`date`	date	calculé	Jour observé (défaut : aujourd’hui, fuseau Europe/Paris).

Source amont : GET /fr/api/v1/dashboards/apay_strip

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/payments/summary"

Performance

GET `/v1/performance/{metric}`

Séries temporelles : occupation, ADR, RevPAR, chiffre d’affaires, délai de réservation, durée de séjour.

⚠️ Piège de l’amont : le paramètre s’appelle `room_ids` mais attend des identifiants de CATÉGORIE. Ici il s’appelle `room_category_ids`, ce qu’il est réellement. Omis, toutes les catégories sont prises. Le champ `value` porte selon la métrique un pourcentage, un montant, des jours ou des nuits (voir `unit`). ⚠️ `granularity` est SANS EFFET : vérifié le 01/09/2026, daily, weekly et monthly renvoient une série strictement identique (même empreinte). L’amont ne sert que du quotidien et c’est la SPA qui agrège. La réponse annonce donc toujours `granularity: "daily"`, qui est la vérité de la donnée.

Paramètre	Type	Défaut	Description
`metric`chemin	texte	—	Valeurs : `occupancy`, `adr`, `revenue`, `revpar`, `lead_time`, `length_of_stay`
`start_date`	date	obligatoire	Premier jour de la fenêtre (inclus).
`end_date`	date	obligatoire	Dernier jour de la fenêtre (exclu pour les nuitées).
`room_category_ids`	liste	—	Identifiants de catégorie, séparés par des virgules. Omis = toutes. Volontairement optionnel : une catégorie créée plus tard serait absente d’une liste figée.
`granularity`	texte	`daily`	⚠️ SANS EFFET, accepté par fidélité à l’amont. La série est toujours quotidienne — agréger côté appelant. Admises : `daily`, `weekly`, `monthly`

Source amont : GET /fr/api/v1/performance/{metric}_report.json

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/performance/occupancy?start_date=2026-09-01&end_date=2026-09-01"

Client et dossier

GET `/v1/bookings/{booking_id}`

Le dossier complet d’une réservation : coordonnées du client, montants au centime, détail par chambre.

🔑 C’est le SEUL endroit où l’on obtient e-mail et téléphone du client — ni /v1/reservations ni /v1/day ne les portent, ils s’arrêtent au nom. L’identifiant à passer est le `booking.id` renvoyé par /v1/reservations, ou `booking_id` dans /v1/day. ⚠️ Sur un échantillon de 10 dossiers récents : e-mail et téléphone renseignés 10 fois sur 10, mais l’adresse des réservations OTA est un ALIAS de relais (@guest.booking.com) — utilisable pour joindre le client pendant le séjour, sans valeur pour une base de contacts durable. Les réservations directes portent le vrai domaine. Les montants sont en CENTIMES et incluent `city_tax_cents` (taxe de séjour), absente partout ailleurs.

Paramètre	Type	Défaut	Description
`booking_id`chemin	texte	—	Valeurs :

Source amont : GET /fr/api/v1/bookings/{id}

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/bookings/20339194"

GET `/v1/clients`

Une liste de clients avec e-mail, téléphone, ville et pays.

⚠️ Endpoint bridé, à ne pas prendre pour un annuaire. Il renvoie toujours les MÊMES 50 fiches, dans un ordre qui n’est ni l’ordre d’identifiant ni une date : c’est la liste qui alimente un sélecteur dans l’interface, pas un export. Sept noms de paramètre de pagination et de recherche ont été essayés le 01/09/2026 (`page`, `per_page`, `search`, `q`, `term`, `name`, `query`) : tous ignorés, réponse identique. Pour retrouver un client précis, passer par sa réservation et /v1/bookings/{id} ; pour un export complet, c’est `/fr/admin/clients-export.xlsx` côté Amenitiz. Taux de remplissage constaté : e-mail 94 %, téléphone 94 %, pays 92 %, ville 36 %, adresse 0 %.

Aucun paramètre.

Source amont : GET /fr/api/v1/clients

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/clients"

Facturation

GET `/v1/bills`

Les notes émises, paginées (10 par page).

Paramètre	Type	Défaut	Description
`page`	entier	`1`	Numéro de page.

Source amont : GET /fr/api/v1/bills

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/bills"

Contexte tarifaire

GET `/v1/price-advisor/policies`

Ce à quoi la propriété a droit côté conseil tarifaire, et sur quel horizon.

Aucun paramètre.

Source amont : GET /fr/api/v1/price_advisor/policies.json

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/price-advisor/policies"

GET `/v1/events`

Les événements et jours fériés susceptibles de peser sur la demande.

L’horizon est borné par l’abonnement : voir `last_day_of_holidays` dans /v1/price-advisor/policies.

Paramètre	Type	Défaut	Description
`start_date`	date	obligatoire	Premier jour de la fenêtre (inclus).
`end_date`	date	obligatoire	Dernier jour de la fenêtre (exclu pour les nuitées).

Source amont : GET /fr/api/v1/price_advisor/events.json

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/events?start_date=2026-09-01&end_date=2026-09-01"

GET `/v1/settings`

Réglages d’affichage du calendrier et régions de jours fériés — utile pour interpréter les couleurs et statuts.

Aucun paramètre.

Source amont : GET /fr/api/v1/calendar/settings.json, GET /fr/api/v1/holidays/settings.json

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/settings"

Messagerie

GET `/v1/conversations`

Les conversations voyageurs, et celles qui restent non lues.

⚠️ Ces deux endpoints amont vivent sous /api/v1/ SANS préfixe de langue, contrairement à tous les autres.

Paramètre	Type	Défaut	Description
`unread_only`	booleen	`false`	true = ne renvoyer que les non lues.

Source amont : GET /api/v1/messenger/conversations, GET /api/v1/messenger/unread_conversations

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/conversations"

Grille

GET `/v1/grid`

Disponibilité, prix et chambres déjà réservées pour une date — la seule source de la DISPONIBILITÉ.

⚠️ Route COÛTEUSE (~10 s) : la disponibilité n’est exposée par aucune API JSON, elle est lue dans le DOM de la grille tarifaire, que la page doit d’abord rendre. Ne couvre que la fenêtre affichée par Amenitiz (≈ aujourd’hui → +30 j). Une disponibilité à 0 signifie « fermée à la vente », pas « complet ».

Paramètre	Type	Défaut	Description
`date`	date	calculé	Jour observé (défaut : aujourd’hui, fuseau Europe/Paris).

Source amont : DOM /fr/admin/planning

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/grid"

Passe-plat

GET `/v1/raw/{chemin_amont}`

Relaie tel quel n’importe quel GET de l’API interne. Le chemin doit commencer par fr/api/v1, fr/api/v2 ou api/v1. La chaîne de requête est transmise intégralement, paramètres répétés compris. La réponse est le corps amont, sans enveloppe.

C’est la porte de sortie quand une route dédiée manque, et le moyen de continuer à travailler si Amenitiz publie un endpoint que cette passerelle ne connaît pas encore. Rien n’y est validé ni normalisé.

curl -H "X-API-Key: $CLE" \
  "https://amenitiz.endurance.tools/v1/raw/fr/api/v2/reservations/rooms?start_date=2026-09-01&end_date=2026-09-02&booking_statuses[]=confirmed"

Erreurs

{ "error": { "code": "SESSION_EXPIREE", "message": "…", "details": { … } } }

Code	HTTP	Ce qu’il faut faire
`PARAMETRE_INVALIDE`	400	Le message nomme le paramètre et les valeurs admises.
`CLE_MANQUANTE` / `CLE_INVALIDE`	401	Vérifier l’en-tête.
`ROUTE_INCONNUE`	404	Voir le sommaire ci-contre.
`TROP_DE_REQUETES`	429	Ralentir ; `Retry-After` indique le délai.
`SESSION_EXPIREE`	503	Le cookie Amenitiz est mort : refaire l’onboarding navigateur sur le serveur.
`BLOQUE_PAR_CLOUDFLARE`	503	Ne PAS réessayer en boucle. Prévenir l’administrateur.
`BUDGET_AMONT_EPUISE`	503	Trop d’appels non cachés dans l’heure. Attendre.
`AMONT_EN_ERREUR` / `REPONSE_NON_JSON`	502	Amenitiz a changé, ou est en panne.

Passerelle Amenitiz

Prise en main

Référentiel

GET /v1/rooms

GET /v1/room-categories

Planning

GET /v1/reservations

GET /v1/blocks

GET /v1/unavailable-rooms

GET /v1/pricing

GET /v1/day

Opérations

GET /v1/dashboard

GET /v1/arrivals

GET /v1/housekeeping

GET /v1/housekeeping/board

GET /v1/housekeeping/staff

GET /v1/payments/summary

Performance

GET /v1/performance/{metric}

Client et dossier

GET /v1/bookings/{booking_id}

GET /v1/clients

Facturation

GET /v1/bills

Contexte tarifaire

GET /v1/price-advisor/policies

GET /v1/events

GET /v1/settings

Messagerie

GET /v1/conversations

Grille

GET /v1/grid

Passe-plat

GET /v1/raw/{chemin_amont}

Erreurs

GET `/v1/rooms`

GET `/v1/room-categories`

GET `/v1/reservations`

GET `/v1/blocks`

GET `/v1/unavailable-rooms`

GET `/v1/pricing`

GET `/v1/day`

GET `/v1/dashboard`

GET `/v1/arrivals`

GET `/v1/housekeeping`

GET `/v1/housekeeping/board`

GET `/v1/housekeeping/staff`

GET `/v1/payments/summary`

GET `/v1/performance/{metric}`

GET `/v1/bookings/{booking_id}`

GET `/v1/clients`

GET `/v1/bills`

GET `/v1/price-advisor/policies`

GET `/v1/events`

GET `/v1/settings`

GET `/v1/conversations`

GET `/v1/grid`

GET `/v1/raw/{chemin_amont}`