Aller au contenu
KelkiDéveloppeurs

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

  1. 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.
  2. 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.
  3. Les choix. GET /trades/{trade_id} donne les prestations et les délais à afficher en boutons, et le texte d'accord.
  4. Le lieu. GET /places?q=Créteil → fr-creteil-94000.
  5. 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.
  6. L'accord. L'application affiche recap, puis consent.text tel quel, case non cochée ; la personne qui sera rappelée coche.
  7. 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.
  8. 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
Interfacevos écrans, les listes de Kelkiun fil de discussion, l'agent pose les questions
Modèle d'IAaucunpour le texte libre seulement
FinPOST …/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