# 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-matches` avec `{"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 /requests` avec `reference` = numéro de réservation et un en-tête `Idempotency-Key` dérivé de la réservation : un double clic ne crée rien de plus. - L'accord. L'application affiche `recap`, puis `consent.text` tel 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 la `reference`) met à jour la fiche de la réservation : `awaiting_confirmation`, `transmitted`, `sold`, puis `called_back` si 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](https://kelki.ai/developers/fr/guides/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](https://kelki.ai/developers/fr/examples/). ## 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 `reference` votre identifiant de réservation, jamais un nom ou un numéro de téléphone ; dans `end_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. ## Sur cette page - URL : https://kelki.ai/developers/fr/guides/conciergerie/ - Langue : fr - fr : https://kelki.ai/developers/fr/guides/conciergerie/ - en : https://kelki.ai/developers/en/guides/concierge/ - x-default : https://kelki.ai/developers/ - Portail : https://kelki.ai/developers/llms.txt