API Reference

Ce document décrit ce qui est commun aux deux modèles (XML et JSON) : environnements, connexion, objets de données, erreurs, limites, fiabilité et API d'administration. Les détails de transport sont dans xml/README.md et json/README.md.

Environnements et versionnement

L'URL de production est communiquée par Bridg_ à la mise en service, une fois la certification passée. Les intégrations se développent et se certifient sur le staging.

L'API est versionnée dans le chemin : /api/pms/v1/. Les évolutions compatibles (nouveau champ optionnel, nouveau code d'erreur) ne changent pas la version. Un changement incompatible donnerait un nouveau préfixe /v2/.

Toutes les URL d'ingestion ont la forme :

{base}/api/pms/v1/connections/{connectionId}/{ressource}

La connexion

Une connexion relie un établissement Bridg_ à un PMS. Il y a au plus une connexion par établissement. Elle est créée par le propriétaire de l'établissement (ou par Bridg_) dans le tableau de bord, menu Interface PMS.

Fields

Statuts

L'activation est un geste explicite du propriétaire. Régénérer les identifiants invalide immédiatement l'ancien couple clientToken / secret.

Correspondance des codes (mapping)

Bridg_ ne crée jamais de type de chambre ni de plan tarifaire à partir d'un message. Chaque code du PMS doit être associé à un objet Bridg_ avant le premier message.

Un code non mappé est refusé item par item (UNMAPPED_UNIT_TYPE, UNMAPPED_RATE_PLAN) ; les autres items du même message sont appliqués. Le mapping se fait dans l'écran Interface PMS (onglet Correspondance des codes) ou par l'API d'administration.

Objets communs

ARI item

Quel que soit le format, un message ARI est traduit en items indépendants. Un item porte une seule nature (disponibilité, prix ou restrictions) sur une plage de nuits. En JSON l'item est envoyé tel quel ; en XML il est produit par la traduction des messages Fidelio.

Règles d'application :

• Disponibilité — le chiffre du PMS fait foi. S'il dépasse l'inventaire paramétré dans Bridg_, l'inventaire du type de chambre est relevé à ce niveau.
• Prix — l'occupation 2 est obligatoire (prix de référence du tarif ; les autres occupations dérivent des modificateurs du tarif Bridg_). Bridg_ retient gross si le tarif est paramétré TTC, net s'il est HT. Le prix doit être > 0. Une baisse de plus de 50 % par rapport au dernier prix connu sur une date est refusée (PRICE_DROP_REJECTED) — tout l'item est rejeté, rien n'est écrit. La devise est celle de l'établissement ; Bridg_ ne convertit pas.
• Restrictions — seuls les champs fournis sont écrits : un item minLos seul ne rouvre pas un tarif fermé et n'efface pas un CTA. Sans unitTypeCode la restriction porte sur le tarif ; avec, elle porte sur tarif × type et la vue tarif est recalculée comme l'agrégat des types connus (fermé seulement si tous les types sont fermés ; LOS la moins restrictive).
• Chaque item est appliqué indépendamment ; l'accusé détaille le résultat par item.
• Après application, Bridg_ relaie la donnée vers les OTA connectés.

Réservation (booking)

Les deux modèles véhiculent la même structure, dans les deux sens. En JSON elle est envoyée telle quelle (camelCase) ; en XML elle est traduite depuis/vers <Reservation> Fidelio ; en webhook JSON elle est envoyée en PascalCase.

Ligne de réservation (reservations[]) :

Règles :

• Une réservation de 2 chambres identiques = 2 lignes (01, 02).
• Modification = état complet : la réservation est renvoyée entière ; toute ligne absente est considérée annulée.
• Annulation : toutes les lignes en CANCELLED (XML), ou message d'annulation dédié (JSON).
• Bridg_ n'émet jamais vers le PMS une réservation qui vient de ce PMS (anti-boucle).
• Une réservation entrante est enregistrée avec la source PMS et la référence externe pms:<référence> ; elle ne repart ni vers les OTA ni vers le PMS, et ne modifie pas la disponibilité (seul le flux ARI le fait).

Accusé de traitement (result)

Erreurs

Hors accusé XML, toute erreur HTTP a le format :

{ "error": "Type d'unité \"SUP\" non mappé sur cette connexion", "code": "UNMAPPED_UNIT_TYPE" }

Codes par item ARI (dans results[] en JSON, dans resultMessage en XML) : UNMAPPED_UNIT_TYPE, UNMAPPED_RATE_PLAN, INVALID_DATE_RANGE, PRICE_DROP_REJECTED, VALIDATION_ERROR, INTERNAL_ERROR.

En XML, un refus déterministe est signalé par un RESULT d'échec mis en file (réponse HTTP 200), jamais par un 4xx — voir xml/README.md.

Limites

Fiabilité

• Écriture avant traitement. Tout message entrant est persisté tel quel (octets bruts) avant d'être appliqué. Un message reçu est appliqué ou visible en erreur, jamais perdu.
• Déduplication. Un identifiant de message déjà traité renvoie l'accusé mémorisé (200) sans retraiter. Reçu à nouveau pendant son traitement : 202 (en attente, ne pas retraiter).
• Reprise. Un échec transitoire (base indisponible…) répond 500 ; le message reste en inbox et est rejoué automatiquement (5 tentatives, toutes les 30 s). Le PMS doit réémettre sur 500 ; les deux filets se cumulent sans doublon.
• Échec déterministe (code non mappé, message illisible) : jamais rejoué. Réémettre le même message donnera le même refus tant que la cause n'est pas corrigée. Les octets sont conservés quand même — y compris pour un message que Bridg_ n'a pas su traduire — dès lors que l'enveloppe porte un identifiant : le message reste auditable et rejouable une fois la cause corrigée, au lieu de disparaître avec son refus.
• Réservations sortantes. File durable FIFO par connexion, ordre garanti par réservation (le MODIFY d'une réservation n'est jamais servi avant son CREATE). Échec transitoire : rejeu avec backoff exponentiel (30 s, 1 min, 2 min… plafonné à 30 min, 8 tentatives). Refus métier : dead-letter visible dans l'écran Interface PMS, rejouable à la main après correction.

Rétention

API d'administration

Base : {base}/api/pms/v1/admin. Authentification par session Bridg_ (JWT). Réservée au propriétaire de l'établissement et au super-administrateur. C'est l'API derrière l'écran Interface PMS ; un intégrateur n'a normalement pas à l'appeler.