Aller au contenu
KelkiDéveloppeurs

Guide : formulaire sans agent

Vos écrans, les listes de Kelki, aucun modèle d'IA. Le parcours reprend celui du formulaire « Rappelez-moi » de kelki.ai : le service, le délai, le lieu, vos coordonnées, puis l'accord.

Les écrans types

  1. Le service. Métier choisi par la personne (après POST /trade-matches ou dans GET /trades), puis une prestation de services. « Autre besoin » (other_need_label) ouvre un champ libre other_need de 3 à 160 caractères.
  2. Le délai. Un libellé de delays (urgent: true signale les délais urgents).
  3. Le lieu. Champ « ville ou code postal » → GET /places?q=… → la personne choisit un lieu ; gardez son id. Pas d'adresse précise.
  4. Les coordonnées. Nom (2 à 80 caractères), téléphone au format E.164 valide pour le pays de la demande (+33639980042), e-mail (il reçoit la confirmation) ; précisions facultatives (message, 2 000 caractères au plus, aucune donnée de santé).
  5. Le récapitulatif et l'accord. POST /requests, puis recap et le texte d'accord mot pour mot, case non cochée, puis POST /requests/{request_id}/confirmation (règles).

Listes fermées

Les valeurs de service et de delay doivent venir exactement des listes du métier, dans la langue de la demande. Une valeur hors liste est refusée :

{
  "type": "https://kelki.ai/api/problems/validation_failed",
  "title": "Demande invalide",
  "status": 422,
  "code": "validation_failed",
  "errors": [{"pointer": "/service", "detail": "Prestation hors liste pour Plombier.",
              "allowed": ["Recherche de fuite", "Réparation de fuite", "Débouchage", "Autre besoin"]}]
}

errors[].pointer désigne le champ ; allowed donne les valeurs acceptées : votre écran peut proposer la correction directement. Le schéma est fermé : tout champ inconnu est refusé.

Les champs de POST /requests

ChampRègle
trade_ididentifiant d'un métier ouvert à l'API
serviceune valeur de services du métier
other_needobligatoire avec « Autre besoin » (3 à 160 caractères)
delayun libellé de delays
place_ididentifiant renvoyé par GET /places
contactname, phone, email de la personne à rappeler
messagefacultatif, 2 000 caractères au plus, pas de donnée de santé
referencefacultatif : votre référence (ex. numéro de réservation), sans donnée personnelle
end_user_reffacultatif : pseudonyme stable de l'utilisateur chez vous (jamais un e-mail ou un numéro)
country, langfacultatifs : FR et la langue principale du pays par défaut

Corriger un brouillon

PATCH /requests/{request_id} (application/merge-patch+json) au statut draft : le récapitulatif est recalculé, l'accord doit être redonné ensuite. DELETE annule et efface les coordonnées.