# Référentiel Pays, métiers, prestations, lieux et textes d'accord. Lecture seule, même source que le site et le connecteur MCP. Adresse de base : `https://kelki.ai/api/v1`. - GET /countries — Lister les pays et leurs langues - GET /trades — Catalogue des métiers ouverts à l'API - GET /trades/{trade_id} — Détail d'un métier (prestations, délais, texte d'accord) - GET /trades/{trade_id}/services — Catalogue détaillé des prestations d'un métier - POST /trade-matches — Trouver les métiers correspondant à un besoin - GET /places — Vérifier un lieu (ville ou code postal) - GET /consent-texts/{version} — Lire une version du texte d'accord ## GET `/countries` Lister les pays et leurs langues Pays couverts, langues, devise, et disponibilité (`live` = demandes acceptées ; `preparing` = référentiel consultable, demandes refusées). Authentification : clé API (`Authorization: Bearer kk_…`) ou jeton OAuth 2.0 (portée `catalog.read`). ### Réponses | Code | Description | Contenu | | `200` | Liste des pays. | `application/json` CountryList | | `401` | Identifiants absents, invalides, expirés ou révoqués. | `application/problem+json` Problem | | `429` | Débit ou quota dépassé. | `application/problem+json` Problem | ### Exemple de réponse ``` { "object": "list", "has_more": false, "next_cursor": null, "data": [ { "code": "FR", "name": "France", "languages": [ "fr" ], "default_language": "fr", "currency": "EUR", "availability": "live" }, { "code": "BE", "name": "Belgique", "languages": [ "fr", "nl" ], "default_language": "fr", "currency": "EUR", "availability": "preparing" } ] } ``` ## GET `/trades` Catalogue des métiers ouverts à l'API Métiers ouverts dans le pays, noms dans la langue demandée. Exclus : métiers de santé, métiers en relecture, exclusions propres au compte. Les métiers `national` n'ont pas de diffusion par distance. Authentification : clé API (`Authorization: Bearer kk_…`) ou jeton OAuth 2.0 (portée `catalog.read`). ### Paramètres | Nom | Où | Requis | Type | Description | | `country` | query | non | CountryCode | Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR. motif `^[A-Z]{2}$` · défaut `"FR"` | | `lang` | query | non | LanguageCode | Langue (ISO 639-1). Défaut = langue principale du pays. `Accept-Language` est lu en repli. motif `^[a-z]{2}$` | | `family` | query | non | string | Famille de métiers (ex. depannage, maison). max. 40 car. | | `scope` | query | non | TradeScope | Portée du métier. valeurs : `local`, `national` | | `limit` | query | non | integer | Taille de page (1 à 100). min. 1 · max. 100 · défaut `20` | | `starting_after` | query | non | string | Curseur opaque `next_cursor` de la page précédente. max. 200 car. | ### Réponses | Code | Description | Contenu | | `200` | Une page du catalogue. | `application/json` TradeList | | `400` | Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros). | `application/problem+json` Problem | | `401` | Identifiants absents, invalides, expirés ou révoqués. | `application/problem+json` Problem | | `422` | Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus). | `application/problem+json` Problem | | `429` | Débit ou quota dépassé. | `application/problem+json` Problem | ### Exemple de réponse ``` { "object": "list", "has_more": true, "next_cursor": "cur_plombier", "data": [ { "id": "plombier", "name": "Plombier", "family": "depannage", "scope": "local", "page_url": "https://kelki.ai/fr/fr/plombier/" } ] } ``` ## GET `/trades/{trade_id}` Détail d'un métier (prestations, délais, texte d'accord) Équivalent de l'outil MCP `lister_prestations`. Les listes sont fermées, comme dans le formulaire. Authentification : clé API (`Authorization: Bearer kk_…`) ou jeton OAuth 2.0 (portée `catalog.read`). ### Paramètres | Nom | Où | Requis | Type | Description | | `trade_id` | path | oui | string | Identifiant stable du métier (slug français historique, ex. plombier). motif `^[a-z0-9-]{2,60}$` | | `country` | query | non | CountryCode | Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR. motif `^[A-Z]{2}$` · défaut `"FR"` | | `lang` | query | non | LanguageCode | Langue (ISO 639-1). Défaut = langue principale du pays. `Accept-Language` est lu en repli. motif `^[a-z]{2}$` | ### Réponses | Code | Description | Contenu | | `200` | Le métier. | `application/json` Trade | | `401` | Identifiants absents, invalides, expirés ou révoqués. | `application/problem+json` Problem | | `404` | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | `application/problem+json` Problem | | `429` | Débit ou quota dépassé. | `application/problem+json` Problem | ### Exemple de réponse ``` { "id": "plombier", "name": "Plombier", "family": "depannage", "scope": "local", "page_url": "https://kelki.ai/fr/fr/plombier/", "country": "FR", "lang": "fr", "services": [ "Recherche de fuite", "Réparation de fuite", "Débouchage", "Remplacement de chauffe-eau", "Autre besoin" ], "other_need_label": "Autre besoin", "delays": [ { "label": "Dès que possible", "urgent": true }, { "label": "Dans la semaine", "urgent": false }, { "label": "Dans le mois", "urgent": false } ], "consent": { "version": "v2026-10-18", "lang": "fr", "text": "J’accepte que ma demande et mes coordonnées soient transmises à un ou plusieurs professionnels du métier de mon secteur, qui pourront me rappeler à ce sujet.", "valid_from": "2026-11-10" } } ``` ## GET `/trades/{trade_id}/services` Catalogue détaillé des prestations d'un métier Catalogue de prestations du métier (intitulés simples, `data/datasets/`). Les intitulés utilisables dans une demande sont ceux qui ont `requestable: true` ; « Autre besoin » est toujours possible avec `other_need`. Authentification : clé API (`Authorization: Bearer kk_…`) ou jeton OAuth 2.0 (portée `catalog.read`). ### Paramètres | Nom | Où | Requis | Type | Description | | `trade_id` | path | oui | string | Identifiant stable du métier (slug français historique, ex. plombier). motif `^[a-z0-9-]{2,60}$` | | `country` | query | non | CountryCode | Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR. motif `^[A-Z]{2}$` · défaut `"FR"` | | `lang` | query | non | LanguageCode | Langue (ISO 639-1). Défaut = langue principale du pays. `Accept-Language` est lu en repli. motif `^[a-z]{2}$` | | `limit` | query | non | integer | Taille de page (1 à 100). min. 1 · max. 100 · défaut `20` | | `starting_after` | query | non | string | Curseur opaque `next_cursor` de la page précédente. max. 200 car. | ### Réponses | Code | Description | Contenu | | `200` | Une page de prestations. | `application/json` ServiceList | | `401` | Identifiants absents, invalides, expirés ou révoqués. | `application/problem+json` Problem | | `404` | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | `application/problem+json` Problem | | `429` | Débit ou quota dépassé. | `application/problem+json` Problem | ### Exemple de réponse ``` { "object": "list", "has_more": false, "next_cursor": null, "data": [ { "id": "recherche-de-fuite", "label": "Recherche de fuite", "requestable": true }, { "id": "debouchage-canalisation", "label": "Débouchage de canalisation", "requestable": true } ] } ``` ## POST `/trade-matches` Trouver les métiers correspondant à un besoin Équivalent de l'outil MCP `trouver_service`. Le besoin passe dans le corps (jamais dans l'adresse) : il peut contenir des détails personnels. Il n'est ni conservé ni journalisé. Proposez les 2 ou 3 premiers résultats à la personne et laissez-la choisir. Lecture seule : pas d'Idempotency-Key. Authentification : clé API (`Authorization: Bearer kk_…`) ou jeton OAuth 2.0 (portée `catalog.read`). ### Corps de la requête `application/json` — TradeMatchQuery (obligatoire) ``` { "need": "Fuite d'eau sous l'évier de la cuisine", "country": "FR", "lang": "fr" } ``` ### Réponses | Code | Description | Contenu | | `200` | Métiers probables, du plus pertinent au moins pertinent. | `application/json` TradeMatchList | | `400` | Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros). | `application/problem+json` Problem | | `401` | Identifiants absents, invalides, expirés ou révoqués. | `application/problem+json` Problem | | `422` | Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus). | `application/problem+json` Problem | | `429` | Débit ou quota dépassé. | `application/problem+json` Problem | ### Exemple de réponse ``` { "object": "list", "has_more": false, "next_cursor": null, "data": [ { "rank": 1, "trade": { "id": "plombier", "name": "Plombier", "family": "depannage", "scope": "local", "page_url": "https://kelki.ai/fr/fr/plombier/" }, "suggested_services": [ "Recherche de fuite", "Réparation de fuite" ] }, { "rank": 2, "trade": { "id": "cuisiniste", "name": "Cuisiniste", "family": "maison", "scope": "local", "page_url": "https://kelki.ai/fr/fr/cuisiniste/" }, "suggested_services": [] } ] } ``` ## GET `/places` Vérifier un lieu (ville ou code postal) Équivalent de l'outil MCP `verifier_lieu`. Renvoie des lieux existants ; utilisez leur `id` dans la demande. Authentification : clé API (`Authorization: Bearer kk_…`) ou jeton OAuth 2.0 (portée `catalog.read`). ### Paramètres | Nom | Où | Requis | Type | Description | | `q` | query | oui | string | Nom de ville ou code postal (pas d'adresse précise). min. 2 car. · max. 120 car. | | `country` | query | non | CountryCode | Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR. motif `^[A-Z]{2}$` · défaut `"FR"` | | `lang` | query | non | LanguageCode | Langue (ISO 639-1). Défaut = langue principale du pays. `Accept-Language` est lu en repli. motif `^[a-z]{2}$` | | `limit` | query | non | integer | Taille de page (1 à 100). min. 1 · max. 100 · défaut `20` | ### Réponses | Code | Description | Contenu | | `200` | Lieux correspondants. | `application/json` PlaceList | | `400` | Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros). | `application/problem+json` Problem | | `401` | Identifiants absents, invalides, expirés ou révoqués. | `application/problem+json` Problem | | `429` | Débit ou quota dépassé. | `application/problem+json` Problem | ### Exemple de réponse ``` { "object": "list", "has_more": false, "next_cursor": null, "data": [ { "id": "fr-creteil-94000", "city": "Créteil", "postal_code": "94000", "label": "Créteil (94000)", "region": "Île-de-France", "subdivision": "Val-de-Marne", "subdivision_code": "94", "country": "FR" } ] } ``` ## GET `/consent-texts/{version}` Lire une version du texte d'accord Versions datées et immuables. Le texte à afficher pour une demande est celui renvoyé dans son brouillon (`consent`). Authentification : clé API (`Authorization: Bearer kk_…`) ou jeton OAuth 2.0 (portée `catalog.read`). ### Paramètres | Nom | Où | Requis | Type | Description | | `version` | path | oui | string | motif `^v\d{4}-\d{2}-\d{2}$` | | `lang` | query | non | LanguageCode | Langue (ISO 639-1). Défaut = langue principale du pays. `Accept-Language` est lu en repli. motif `^[a-z]{2}$` | ### Réponses | Code | Description | Contenu | | `200` | Le texte d'accord. | `application/json` ConsentText | | `401` | Identifiants absents, invalides, expirés ou révoqués. | `application/problem+json` Problem | | `404` | Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). | `application/problem+json` Problem | ### Exemple de réponse ``` { "version": "v2026-10-18", "lang": "fr", "text": "J’accepte que ma demande et mes coordonnées soient transmises à un ou plusieurs professionnels du métier de mon secteur, qui pourront me rappeler à ce sujet.", "valid_from": "2026-11-10" } ``` ## Schémas ### `CountryList` Type : ListMeta et object ### `Problem` Détails d'un problème (RFC 9457), avec des membres d'extension. | Champ | Type | Requis | Description | | `type` | string (uri) | oui | URI stable du type de problème ; elle mène à sa documentation. | | `title` | string | oui | | | `status` | integer | oui | min. 400 · max. 599 | | `detail` | string | non | | | `instance` | string (uri-reference) | non | | | `code` | string | oui | Code stable, lisible par une machine. valeurs : `invalid_json`, `invalid_parameter`, `payload_too_large`, `unsupported_media_type`, `invalid_credentials`, `expired_token`, `insufficient_scope`, `live_not_enabled`, `account_suspended`, `country_not_available`, `trade_not_available`, `not_found`, `invalid_state`, `idempotency_in_progress`, `idempotency_key_reused`, `validation_failed`, `consent_missing`, `consent_version_outdated`, `contact_limit_reached`, `duplicate_request`, `rate_limited`, `quota_exceeded`, `agent_paused`, `live_creation_paused`, `service_unavailable`, `internal_error` | | `request_id` | string | oui | | | `errors` | tableau de FieldError | non | | ### `CountryCode` Type : string — motif `^[A-Z]{2}$` · défaut `"FR"` ### `LanguageCode` Type : string — motif `^[a-z]{2}$` ### `TradeScope` `local` : diffusion par cercles de distance ; `national` : diffusion triée par avis, sans distance. Le lieu reste obligatoire. Type : string — valeurs : `local`, `national` ### `TradeList` Type : ListMeta et object ### `Trade` Type : TradeSummary et object ### `ServiceList` Type : ListMeta et object ### `TradeMatchQuery` | Champ | Type | Requis | Description | | `need` | string | oui | Besoin en mots courants. Ni conservé ni journalisé. min. 3 car. · max. 300 car. | | `country` | CountryCode | non | | | `lang` | LanguageCode | non | | | `limit` | integer | non | min. 1 · max. 10 · défaut `5` | ### `TradeMatchList` Type : ListMeta et object ### `PlaceList` Type : ListMeta et object ### `ConsentText` | Champ | Type | Requis | Description | | `version` | string | oui | motif `^v\d{4}-\d{2}-\d{2}$` | | `lang` | LanguageCode | oui | | | `text` | string | oui | À afficher mot pour mot, à côté d'une case non cochée par défaut. | | `valid_from` | string (date) | oui | | ### `ListMeta` | Champ | Type | Requis | Description | | `object` | string | oui | valeur : `list` | | `has_more` | boolean | oui | | | `next_cursor` | string | null | oui | | ### `FieldError` | Champ | Type | Requis | Description | | `pointer` | string | oui | JSON Pointer (RFC 6901) du champ en cause. | | `detail` | string | oui | | | `allowed` | tableau de string | non | Valeurs acceptées, quand la liste est fermée. | ### `TradeSummary` | Champ | Type | Requis | Description | | `id` | string | oui | Identifiant stable, identique dans toutes les langues. | | `name` | string | oui | Nom dans la langue demandée. | | `family` | string | oui | | | `scope` | TradeScope | oui | | | `page_url` | string (uri) | non | Page publique du métier dans le pays et la langue (`/{pays}/{langue}/…`). | ## Sur cette page - URL : https://kelki.ai/developers/fr/reference/catalog/ - Langue : fr - fr : https://kelki.ai/developers/fr/reference/catalog/ - en : https://kelki.ai/developers/en/reference/catalog/ - x-default : https://kelki.ai/developers/ - Portail : https://kelki.ai/developers/llms.txt