Branchez Otelvya sur n'importe quel site

1. Dans Otelvya, ouvrez Moteur de réservation › Intégrer à votre site : vous y trouvez l'identifiant de l'hôtel (slug).
2. Les lectures publiques (fiche, chambres, disponibilités, calendrier) ne demandent aucune clé et sont lisibles depuis un navigateur (CORS ouvert).
3. Pour créer des réservations, créez une clé avec la portée « Lecture + réservations » et appelez l'API depuis votre serveur.

Les endpoints de réservation exigent une clé d'API, transmise dans l'en-tête Authorization (Bearer) ou X-Api-Key. La clé n'est affichée qu'une fois à sa création ; seule son empreinte est conservée. Elle se garde côté serveur : les endpoints authentifiés n'acceptent pas les appels depuis un navigateur.

Portées : « read » (lecture) et « bookings » (création et consultation des réservations de l'hôtel de la clé). Une clé révoquée cesse immédiatement de fonctionner.

Idempotence

Envoyez un en-tête Idempotency-Key unique avec chaque création : rejouer la même requête (coupure réseau, nouvel essai) renvoie la même réservation au lieu d'en créer une seconde. La même clé avec un corps différent est refusée (409).

Prix recalculés côté serveur

Le montant d'une réservation est toujours recalculé par Otelvya. Transmettez expectedTotal (le total affiché au client) : si le prix a changé entre-temps, la réservation est refusée avec price_changed plutôt que facturée à un autre montant.

Comme les interfaces POS et back-office d'OPERA : n'importe quelle caisse, logiciel de facturation, de comptabilité ou de paie peut se brancher dès aujourd'hui sur Otelvya, sans accord partenaire. L'hôtel crée une clé dans Intégrations › Interfaces avec les portées nécessaires.

Portées : « pos » — recherche d'un client en séjour et imputation sur la chambre ; « exports » — factures émises, encaissements et écritures comptables ; « hr » — effectif sans données sensibles. Une clé « read » ou « bookings » ne peut ni imputer ni exporter.

Imputation sur la chambre

Le client doit être en séjour (arrivée enregistrée) et le module Réception actif pour l'hôtel. Le montant est TTC dans la devise de l'hôtel. La référence externe est unique par point de vente : renvoyer le même ticket ne crée pas de doublon (réponse 200, en-tête Idempotent-Replayed). Refus explicites : 409 not_in_house, folio_closed, module_inactive.

curl "https://otelvya.com/api/v1/hotels/riad-atlas/inhouse?room=101" \
  -H "Authorization: Bearer $OTELVYA_API_KEY"

curl -X POST "https://otelvya.com/api/v1/hotels/riad-atlas/folio-charges" \
  -H "Authorization: Bearer $OTELVYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "room": "101",
    "amount": 185.50, "taxRate": 10,
    "label": "Ticket 4512 — dîner 2 couverts",
    "reference": "T-4512", "outlet": "Restaurant"
  }'

curl -X POST "https://otelvya.com/api/v1/hotels/riad-atlas/folio-charges/<charge.id>/void" \
  -H "Authorization: Bearer $OTELVYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Ticket saisi sur la mauvaise chambre" }'

Exports facturation, comptabilité et paie

Formats JSON (défaut) ou CSV (format=csv, UTF-8, séparateur virgule). Période de 366 jours au plus, 5 000 lignes au plus (en-tête X-Export-Truncated au-delà). Les écritures exigent le module Comptabilité, l'effectif le module RH ; l'effectif n'expose jamais le RIB, la CIN, le n° de sécurité sociale ni la situation familiale.

curl "https://otelvya.com/api/v1/hotels/riad-atlas/exports/invoices?from=2026-10-01&to=2026-10-31&format=csv" \
  -H "Authorization: Bearer $OTELVYA_API_KEY" -o factures.csv

curl "https://otelvya.com/api/v1/hotels/riad-atlas/exports/journal?from=2026-10-01&to=2026-10-31&format=csv" \
  -H "Authorization: Bearer $OTELVYA_API_KEY" -o ecritures.csv

curl "https://otelvya.com/api/v1/hotels/riad-atlas/exports/employees?format=csv" \
  -H "Authorization: Bearer $OTELVYA_API_KEY" -o effectif.csv

Évolution prévue

Pas de webhooks sortants pour l'instant : les logiciels interrogent l'API (par exemple chaque nuit pour les exports). L'envoi d'événements signés (imputation, facture émise) est une évolution prévue.

Description complète au format OpenAPI 3.1, à importer dans Postman, Insomnia ou un générateur de client : /api/v1/openapi.json

Erreurs

Toutes les erreurs ont la même forme, avec un code stable à tester dans votre code et un message lisible :

{ "error": { "code": "invalid_dates", "message": "La date d'arrivée est passée." } }

• Lectures publiques : 120 requêtes par minute et par adresse IP.
• Avec une clé : 600 requêtes par minute et par clé (utile pour les plugins, qui appellent depuis l'adresse de votre serveur).
• Créations de réservation : 10 par 10 minutes et par IP, 60 par 10 minutes et par clé.
• Chaque réponse indique X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset ; au-delà, réponse 429 avec Retry-After.

Disponibilité du service

Si le moteur de réservation d'un hôtel est hors ligne (abonnement) ou si la plateforme est en maintenance, l'API répond 503 avec un code explicite ; un hôtel inconnu répond 404. Aucune donnée interne n'est jamais exposée.

Une question technique ? Écrivez-nous depuis la page de contact.