# Concepts Ce qu'il faut savoir avant d'écrire la première ligne : une demande naît brouillon, n'est transmise qu'avec l'accord confirmé de la personne, et n'est prise que par un seul professionnel. ## Cycle de vie d'une demande ``` POST /requests ──► draft ──(2 h sans suite)──► draft_expired (coordonnées effacées) │ PATCH (corrections) ; DELETE ──► cancelled │ └─ POST …/confirmation {method: email} ──► awaiting_confirmation ├─ clic + bouton sur la page de confirmation ──► transmitted ├─ 48 h sans clic ──► abandoned (coordonnées effacées) └─ DELETE ──► cancelled transmitted ──► sold (prise par un seul professionnel) ──► called_back (la personne dit avoir été rappelée) └──► not_taken (aucun professionnel pendant la durée de l'offre) ``` | Statut | Sens | | `draft` | Brouillon : rien n'est transmis. Modifiable (`PATCH`), annulable (`DELETE`). | | `draft_expired` | Brouillon sans suite depuis 2 heures ; coordonnées effacées. | | `awaiting_confirmation` | E-mail envoyé à la personne, en attente de son clic (48 heures). | | `abandoned` | Pas de clic sous 48 heures ; coordonnées effacées. | | `cancelled` | Annulée par vous avant la transmission. | | `transmitted` | Confirmée par la personne et proposée aux professionnels du métier de son secteur. | | `sold` | Prise par un seul professionnel, qui rappelle la personne. | | `not_taken` | Aucun professionnel ne l'a prise pendant la durée de l'offre. | | `called_back` | La personne a répondu « oui » à l'e-mail « Avez-vous été rappelé ? », envoyé 2 jours après la vente. Sans réponse, la demande reste `sold`. | ## Brouillon et accord La création (`POST /requests`) valide la demande avec les règles du formulaire et ne transmet rien. La transmission passe par une étape séparée, la confirmation, qui exige la version du texte d'accord montré à la personne (`consent_text_version`) et sa case cochée (`consent_given: true`). Puis la personne confirme elle-même, par e-mail. Détails : [consentement de la personne](https://kelki.ai/developers/fr/consent/). ## Un seul professionnel Une demande transmise suit le circuit normal de Kelki : elle est proposée aux professionnels du métier du secteur, et un seul la prend. Vous ne recevez jamais l'identité ni les coordonnées de ce professionnel. ## Métiers locaux et nationaux Chaque métier a une portée (`scope`) : `local`, diffusion par cercles de distance autour du lieu ; `national`, diffusion triée par avis, sans distance. Le lieu reste obligatoire dans les deux cas : le professionnel doit savoir où est la personne. Les métiers ouverts à l'API excluent la santé, les métiers en cours de relecture par Kelki et les exclusions propres à votre compte. Relisez le catalogue (`GET /trades`) plutôt que de le figer dans votre code. ## Pays et langues - `country` : code ISO 3166-1 alpha-2 en majuscules, `FR` par défaut. - `lang` : code ISO 639-1, par défaut la langue principale du pays ; `Accept-Language` est lu en repli. - Les noms de métiers, prestations, délais et textes sont dans la langue demandée ; les identifiants (`plombier`, `fr-creteil-94000`) ne changent jamais. ## Test et production Le mode dépend de l'identifiant, jamais de l'adresse : `kk_test_…` pour le bac à sable, `kk_live_…` pour la production. Chaque réponse porte l'en-tête `Kelki-Mode`. Une demande d'un mode est invisible depuis l'autre (`404`). Voir [bac à sable](https://kelki.ai/developers/fr/sandbox/). ## Conventions - JSON UTF-8 ; `Content-Type: application/json` en écriture, `application/merge-patch+json` pour `PATCH` (RFC 7396) ; corps de 16 Ko au plus. - Dates ISO 8601 en UTC (`2026-11-11T09:41:58Z`). - Identifiants opaques et préfixés : `req_` (demande), `evt_` (événement), `we_` (webhook), `conv_` (conversation), `acc_` (compte). - Aucune donnée personnelle dans l'adresse : le besoin libre passe en `POST`, la clé jamais en paramètre. ## Sur cette page - URL : https://kelki.ai/developers/fr/concepts/ - Langue : fr - fr : https://kelki.ai/developers/fr/concepts/ - en : https://kelki.ai/developers/en/concepts/ - x-default : https://kelki.ai/developers/ - Portail : https://kelki.ai/developers/llms.txt