Guide : une conciergerie
Une conciergerie gère des logements de courte durée. Une fuite, une serrure bloquée, un volet coincé : dans son application, un bouton « Trouver un professionnel » lance la recherche, et la bonne personne est rappelée par un professionnel du bon métier.
Le parcours
- Le clic. Le gestionnaire ou le voyageur décrit le souci en quelques mots ; l'application connaît déjà le logement (ville) et la réservation.
- Le métier.
POST /trade-matchesavec{"need": "fuite sous l'évier", "country": "FR"}: l'application propose les 2 ou 3 premiers métiers, la personne choisit. - Les choix.
GET /trades/{trade_id}donne les prestations et les délais à afficher en boutons, et le texte d'accord. - Le lieu.
GET /places?q=Créteil→fr-creteil-94000. - Le brouillon.
POST /requestsavecreference= numéro de réservation et un en-têteIdempotency-Keydérivé de la réservation : un double clic ne crée rien de plus. - L'accord. L'application affiche
recap, puisconsent.texttel quel, case non cochée ; la personne qui sera rappelée coche. - La confirmation.
POST /requests/{request_id}/confirmation("method": "email") : la personne reçoit l'e-mail « Confirmer ma demande » qui nomme la conciergerie ; un clic, et la demande part vers les professionnels du secteur. - Le suivi. Le webhook
request.status_changed(avec lareference) met à jour la fiche de la réservation :awaiting_confirmation,transmitted,sold, puiscalled_backsi la personne confirme avoir été rappelée.
Qui donne son accord ? Toujours la personne qui sera rappelée, avec ses propres coordonnées. La conciergerie n'envoie pas les coordonnées d'un tiers sans son accord ; l'e-mail de confirmation le garantit : rien ne part sans le clic du destinataire.
Deux façons d'intégrer
| Listes (déterministe) | Agent Kelki (conversation) | |
|---|---|---|
| Routes | /trade-matches, /trades/{trade_id}, /places, /requests | /agent/conversations puis …/messages |
| Interface | vos écrans, les listes de Kelki | un fil de discussion, l'agent pose les questions |
| Modèle d'IA | aucun | pour le texte libre seulement |
| Fin | POST …/confirmation | {"consent": true} à l'étape recap → même demande |
Le parcours avec l'agent : guide de l'Agent.
Le cœur du code (Python, bibliothèque standard)
matches = call("POST", "/trade-matches", {"need": need, "country": "FR", "lang": "fr"})
trade_id = matches["data"][0]["trade"]["id"] # après le choix de la personne
trade = call("GET", f"/trades/{trade_id}?country=FR&lang=fr")
place = call("GET", "/places?" + urlencode({"q": flat_city, "country": "FR"}))["data"][0]
draft = call("POST", "/requests", {
"trade_id": trade_id, "service": chosen_service, "delay": chosen_delay,
"place_id": place["id"],
"contact": {"name": guest["name"], "phone": guest["phone"], "email": guest["email"]},
"reference": booking_id,
}, idem=f"concierge-{booking_id}-draft")
# … afficher draft["recap"] puis draft["consent"]["text"], case non cochée …
call("POST", f"/requests/{draft['id']}/confirmation",
{"method": "email", "consent_text_version": draft["consent"]["version"], "consent_given": True},
idem=f"concierge-{booking_id}-confirmation")
La fonction call et la vérification des webhooks : exemples de code.
Bonnes pratiques
- Gardez la clé côté serveur ; l'application mobile ou web parle à votre serveur, pas à l'API Kelki.
- Affichez les listes de Kelki telles quelles (prestations, délais) : ce sont celles que les professionnels reçoivent.
- Mettez dans
referencevotre identifiant de réservation, jamais un nom ou un numéro de téléphone ; dansend_user_ref, un pseudonyme stable de l'utilisateur. - Prévoyez
contact_limit_reached(3 demandes par 24 heures pour une même personne) : proposez-lui de confirmer celles déjà reçues par e-mail.