# Rateshopper

> API JSON de lecture temps reel des disponibilites et tarifs hoteliers. On donne l'URL du moteur
> de reservation d'un hotel et des dates ; le service identifie le moteur, l'interroge et rend les
> offres normalisees.

Base : https://rateshopper.vadech.tech
Contrat machine : https://rateshopper.vadech.tech/openapi.json
Documentation : https://rateshopper.vadech.tech/docs

## Authentification

Toutes les routes de donnees exigent une clef d'API, en en-tete :

    Authorization: Bearer <clef>      (ou)      X-API-Key: <clef>

Sans clef : HTTP 401 `UNAUTHORIZED`. La clef est fournie par l'exploitant du service ; ne jamais
la demander a l'utilisateur final ni l'inscrire dans une URL.

## Routes

- GET /rates?url=&checkin=&checkout=|nights=&adults=&children=&childrenAges=&rooms=&currency=&lang=
  Tarifs d'un sejour precis. La route qui fait foi des qu'il s'agit d'annoncer un prix.
- GET /calendar?url=&from=&to=|days=&nights=&anchors=
  Grille par date d'arrivee. Lire `support` avant les montants.
- POST /rates/batch  {urls:[], dates:[{checkin,checkout|nights}], adults, ...}
  N hotels x M dates en un appel. Resultats partiels, jamais un echec global.
- GET /engines   moteurs supportes et valeur de leur calendrier (`calendar: null` = pas de grille).
  Sans clef, comme /health et les deux documents ci-dessus.
- GET /resolve?url=   quel moteur derriere cette URL. Gratuit, aucun appel amont.
- GET /health    etat du service. Sans clef.

## Trois regles a ne pas enfreindre

1. Complet n'est pas une erreur. `available:false` + `offers:[]` en HTTP 200 signifie « rien de
   disponible ». Une source injoignable rend une erreur typee (502/504). Ne pas confondre : dire
   « complet » quand la source etait injoignable est une faute.
2. Ne jamais multiplier un montant `basis:"night"` par le nombre de nuits. Le moteur n'a publie
   qu'un prix d'appel par nuit ; les nuits suivantes peuvent valoir tout autre chose. Sans `basis`,
   ou avec `"stay"`, le montant couvre le sejour entier.
3. Ne jamais recomposer un prix a partir d'un calendrier `support.source:"inventory"`, ni d'une
   case marquee `packaged:true` : le montant ignore alors des articles lies au tarif et se trouve
   *sous-evalue* (120 EUR d'ecart mesures sur un cas reel). Pour un prix vendable : /rates.

Autres precautions : `meta.fallbackUsed:true` signale un prix Booking.com servi a la place du
tarif direct — c'est un prix OTA, le dire. `meta.cached:true` signale une valeur de cache
(15 min) ; `noCache=true` force la lecture amont, mais coute une requete chez l'hotelier, donc
seulement si la fraicheur prime.

## Codes d'erreur

INVALID_QUERY (400, corriger la requete) · UNAUTHORIZED (401, clef absente ou invalide) ·
UNSUPPORTED_ENGINE (422, URL non reconnue) · BATCH_TOO_LARGE (422) · ENGINE_NOT_IMPLEMENTED (501,
ce moteur ne publie pas cette surface) · UPSTREAM_ERROR / BLOCKED / PARSE_ERROR (502) ·
BROWSER_DISABLED (503) · UPSTREAM_TIMEOUT (504). Les 5xx se reessaient plus tard, pas en boucle.

## Moteurs reconnus

- thais — Thais (http, calendrier room-rate/engine-calendar, night)
- mews — Mews Distributor (http, calendrier room-rate/engine-search, stay)
- dedge — D-EDGE (Availpro / Fastbooking) (http, calendrier best/engine-calendar, night)
- misterbooking — Misterbooking (http, calendrier best/engine-restrictions, stay)
- reservit — Reservit (browser, calendrier best/engine-search, stay)
- ihotelier — iHotelier (Amadeus / TravelClick) (http, calendrier best/engine-calendar, night)
- mygroomservice — Neo (My Groom Service) (http, calendrier best/engine-calendar, night)
- louvre — Louvre Hotels Group (Campanile, Kyriad, Premiere Classe, Golden Tulip) (http, pas de calendrier)
- siteminder — SiteMinder (TheBookingButton / direct-book) (http, calendrier best/engine-calendar, night)
- roomcloud — RoomCloud (http, calendrier best/engine-restrictions, stay)
- booking — Booking.com (repli OTA) (http, calendrier best/engine-calendar, stay)