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.
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,FRpar défaut.lang: code ISO 639-1, par défaut la langue principale du pays ;Accept-Languageest 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.
Conventions
- JSON UTF-8 ;
Content-Type: application/jsonen écriture,application/merge-patch+jsonpourPATCH(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.