Ondine — documentation de l'API

Commencer

L'accès à l'API est compris dans le palier Premium. Votre clé vous est remise par SDO Studio à l'ouverture de votre établissement ; elle ne s'affiche nulle part et ne se retrouve pas : gardez-la comme un mot de passe. Toutes les adresses commencent par :

https://europe-west1-comselenadorionserena.cloudfunctions.net/ondine

Chaque appel porte votre clé dans l'en-tête Authorization, en POST, avec un corps en JSON. Le serveur répond en JSON, toujours.

# le plus court des appels : une question d'hôte
curl -X POST https://europe-west1-comselenadorionserena.cloudfunctions.net/ondine/v1/conversation \
  -H "Authorization: Bearer VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -d '{"hote":"chambre-12","message":"Bonsoir, le spa ferme à quelle heure ?"}'

Vous préférez que nous le fassions

Le branchement d'Ondine dans votre logiciel de conciergerie ou de réservation peut être fait par nous : nous écrivons le raccordement, nous l'éprouvons avec vos équipes et nous vous le livrons en marche. Ce travail est chiffré sur devis, à la journée, après un échange sur votre système. Il ne fait pas partie de la mise en route, qui couvre la fiche de votre maison, vos documents, la bulle sur votre site et la formation de votre équipe.

Écrivez à contact@sdo-studio.com ou appelez le +33 6 12 45 35 53.

Les données sont hébergées en Europe. Une conversation d'hôte passée par l'API compte dans votre forfait au même titre qu'une conversation venue de la bulle.

1. La conversation

Vous transmettez le message d'un hôte, Ondine répond dans sa langue à partir de la fiche de votre maison, et vous dit ce qu'elle a fait.

POST/v1/conversation

Champ	Type	Rôle
`message`	texte	Obligatoire. Ce que l'hôte a écrit. 4 000 caractères au plus.
`hote`	texte	Votre repère pour cet hôte : un numéro de chambre, un identifiant de dossier. Sert à ouvrir un fil.
`conversation`	texte	L'identifiant rendu au premier appel. Renvoyez-le pour poursuivre le même échange ; Ondine se souvient de ce qui a été dit.
`langue`	texte	Facultatif, deux lettres. Sans lui, Ondine reconnaît la langue de l'hôte toute seule.
`stream`	1	Facultatif. La réponse arrive alors mot à mot, en `text/event-stream`.

// réponse
{
  "conversation": "api_belle-rive_chambre-12_m1x9k2",
  "reponse": "Bonsoir. Le spa est ouvert tous les jours de 9 h à 20 h…",
  "actions": [
    { "type": "demander_rendez_vous", "objet": "Soin duo 50 min",
      "quand": "Samedi 18 h 30", "details": "Deux personnes", "nom_hote": "Perrin" }
  ]
}

actions dit ce qu'Ondine a inscrit dans le journal pendant cette réponse : demander_rendez_vous quand l'hôte demande un soin, une table, un transfert ou une chambre, transmettre_a_l_equipe quand elle ne sait pas. Le tableau est vide si elle a simplement répondu.

2. La maison

Ce qu'Ondine sait de votre établissement. Vous pouvez le lire, et le tenir à jour depuis votre propre système : un tarif qui change, une piscine en travaux, un horaire d'été.

POST/v1/etablissement

Sans champ fiche, l'appel lit. Avec, il complète : seules les rubriques que vous envoyez sont modifiées, les autres restent en place.

# lire
curl -X POST …/v1/etablissement -H "Authorization: Bearer VOTRE_CLE" -d '{}'

# mettre à jour deux rubriques
curl -X POST …/v1/etablissement \
  -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" \
  -d '{"fiche":{"spa":"Spa ouvert de 9 h à 20 h. Piscine en travaux jusqu'"'"'au 30 septembre.",
                "restaurant":"Dîner de 19 h 30 à 22 h 30, fermé le lundi."}}'

Réponse	Contenu
`nom`, `type`, `ville`, `pays`	L'identité de la maison.
`fiche`	Les rubriques, en texte libre : `presentation`, `horaires`, `chambres`, `spa`, `restaurant`, `transferts`, `conditions`, `ton`, `langues`, `contact`, `acces`, et toute rubrique que vous ajoutez.
`documents`	Le nom des documents déposés (cartes, brochures) que lit Ondine.

Le nom d'une rubrique est en minuscules, sans accent ni espace. Pour un navire : itineraire, escales, retour_a_bord, ponts, restauration, excursions, cabines.

3. Le journal

Toutes les demandes prises par Ondine, et les décisions de votre équipe. C'est par là qu'un logiciel de conciergerie récupère les rendez-vous et renvoie les confirmations.

POST/v1/journal

Champ	Rôle
`statut`	Facultatif : `a_confirmer`, `transmis`, `confirme`, `refuse`, `traite`.
`limite`	Facultatif, 100 par défaut, 200 au plus. Les plus récentes d'abord.

{
  "journal": [
    { "id": "9935pGvGU93hoFz1SIIS", "type": "rendez_vous", "statut": "a_confirmer",
      "objet": "Table pour 4 au restaurant Les Rochers", "quand": "Samedi à 20 h",
      "details": "Réservation au nom de Perrin, 4 personnes", "hote": "Perrin",
      "langue": "fr", "canal": "api", "conversation": "api_belle-rive_…",
      "creeLe": "2026-09-09T18:41:02.113Z" }
  ]
}

POST/v1/journal/{id}/decision

Confirmer, refuser ou marquer traité. decision vaut confirme, refuse ou traite ; mot est facultatif, il reste dans le journal.

curl -X POST …/v1/journal/9935pGvGU93hoFz1SIIS/decision \
  -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" \
  -d '{"decision":"confirme","mot":"Table 12, en terrasse."}'

4. Le webhook

Pour être prévenu à la seconde, plutôt que d'interroger le journal. Dès qu'Ondine inscrit une demande, nous appelons votre adresse.

POST/v1/webhook

# poser l'adresse et le secret
curl -X POST …/v1/webhook \
  -H "Authorization: Bearer VOTRE_CLE" -H "Content-Type: application/json" \
  -d '{"url":"https://votre-serveur.com/ondine","secret":"un-secret-a-vous"}'

# lire ce qui est posé (le secret n'est jamais rendu)
curl -X POST …/v1/webhook -H "Authorization: Bearer VOTRE_CLE" -d '{}'

# retirer le webhook
curl -X POST …/v1/webhook -H "Authorization: Bearer VOTRE_CLE" -d '{"url":""}'

Nous appelons votre adresse en POST, une seule fois, avec huit secondes de patience. Si vous avez posé un secret, il voyage dans l'en-tête X-Ondine-Secret : comparez-le avant de faire confiance à l'appel. L'adresse doit être en https.

// ce que vous recevez
{
  "etablissement": "belle-rive",
  "envoyeLe": "2026-09-09T18:41:02.113Z",
  "evenement": "rendez_vous",          // ou "transmis"
  "id": "9935pGvGU93hoFz1SIIS",          // l'entrée du journal
  "objet": "Table pour 4 au restaurant Les Rochers",
  "quand": "Samedi à 20 h",
  "details": "Réservation au nom de Perrin, 4 personnes",
  "hote": "Perrin",
  "langue": "fr",
  "canal": "site",
  "conversation": "h_belle-rive_m1x9k2"
}

Répondez vite, avec un code 200. Nous ne réessayons pas : si votre serveur est absent, la demande reste dans le journal, rien n'est perdu.

Erreurs et limites

Code	Ce qu'il veut dire
`200`	C'est fait.
`400`	Un champ manque ou n'a pas la bonne forme. Le corps le dit en français, dans `erreur`.
`401`	Clé absente ou inconnue.
`403`	Abonnement inactif.
`404`	Porte ou demande inconnue.
`500`	Un ennui de notre côté. Réessayez dans un instant.

Toute erreur arrive avec un corps de la forme {"erreur":"…"}, écrit pour être montré tel quel à un humain.

La limite mensuelle

Chaque établissement a une limite de conversations par mois, réglable depuis l'espace de direction. Au-delà, l'API répond toujours 200, mais avec "limite": true : Ondine n'a pas répondu elle-même, elle a mis le message de l'hôte dans le journal et rendu un mot d'attente dans sa langue. Prévenez alors votre équipe.

Cadence

Aucune limite d'appels n'est imposée aujourd'hui. Nous vous préviendrions avant d'en poser une. Les conversations comptent dans votre forfait : au-delà du nombre inclus, elles sont facturées à l'unité selon vos conditions.

Une question

Écrivez à contact@sdo-studio.com ou appelez le +33 6 12 45 35 53. Vous parlerez à la personne qui a écrit cette API.

L'API d'Ondine