openapi: 3.1.0 # docs/81-openapi.yaml — Spécification CIBLE de l'API publique de l'Agent Kelki, version 1 (11/11/2026). # Document de conception : rien n'est déployé. Explications et choix : docs/81-api-agent-kelki.md. # Aucune donnée personnelle réelle : noms « Exemple », domaines example.com (RFC 2606), numéro factice (plage ARCEP à vérifier, docs/81 § 13). info: title: API de l'Agent Kelki version: 1.0.0 summary: Trouver le bon professionnel et lui transmettre une demande de rappel, avec l'accord explicite de la personne. description: | L'API de l'Agent Kelki permet à une application tierce (conciergerie, gestion locative, assistant, CRM…) de : 1. trouver le métier et la prestation qui correspondent à un besoin, dans la langue et le pays de la personne ; 2. vérifier le lieu de l'intervention ; 3. préparer un **brouillon** de demande, le montrer à la personne avec le **texte d'accord** ; 4. faire **confirmer** la demande par la personne (lien envoyé par e-mail, ou attestation de consentement d'un partenaire agréé) ; 5. suivre la demande : transmise, vendue à **un seul professionnel**, rappel confirmé par la personne. Mêmes règles que le formulaire « Rappelez-moi », le connecteur MCP (`https://kelki.ai/mcp`) et l'Agent Kelki. Aucune réponse ne contient la coordonnée d'un professionnel, ni la source d'acquisition de la demande. Erreurs au format RFC 9457 (`application/problem+json`). Pagination par curseur. `Idempotency-Key` obligatoire sur les créations. Débit limité par clé (en-têtes `RateLimit` et `RateLimit-Policy`). Gratuite pour les partenaires. Encadrée par trois textes (12/11/2026, `/developers/fr/terms/`) : conditions d'utilisation de l'API, accord de traitement des données (article 28 du RGPD : Kelki responsable du traitement, partenaire sous-traitant pour la collecte et l'envoi des demandes), politique d'usage acceptable. termsOfService: https://kelki.ai/developers/fr/terms/ contact: name: Kelki — équipe API url: https://kelki.ai/developers/fr/support/ license: name: Propriétaire — conditions d'utilisation de l'API Kelki url: https://kelki.ai/developers/fr/terms/ servers: - url: https://kelki.ai/api/v1 description: Production et bac à sable. Le mode dépend des identifiants (kk_live_… ou kk_test_…), jamais de l'adresse. security: - ApiKey: [] - OAuth2: - catalog.read tags: - name: Authentification description: Jeton OAuth 2.0 « client credentials » (RFC 6749 § 4.4) et révocation (RFC 7009). - name: Référentiel description: Pays, métiers, prestations, lieux et textes d'accord. Lecture seule, même source que le site et le connecteur MCP. - name: Demandes description: Brouillon, confirmation par la personne, suivi. Une demande confirmée suit le circuit normal (Leads Hub puis vente à un seul professionnel). - name: Agent description: Conversation avec l'Agent Kelki (même cerveau que la bulle du site et l'A2A). - name: Webhooks description: Abonnements aux changements de statut, signés en HMAC-SHA256. - name: Compte description: Plan, plafonds et consommation du compte partenaire. - name: Bac à sable description: Outils réservés au mode test. paths: /oauth/token: post: tags: [Authentification] operationId: createAccessToken summary: Obtenir un jeton d'accès (client credentials) description: | Échange `client_id` + `client_secret` (HTTP Basic, RFC 6749 § 2.3.1) contre un jeton opaque de 15 minutes. Les portées demandées doivent être accordées au client. Le mode (test / live) est celui du client. security: - ClientBasic: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/TokenRequest' examples: lecture_et_demandes: value: grant_type: client_credentials scope: catalog.read requests.write requests.read responses: '200': description: Jeton délivré. headers: Cache-Control: $ref: '#/components/headers/CacheControlNoStore' content: application/json: schema: $ref: '#/components/schemas/TokenResponse' examples: jeton: value: access_token: kat_test_EXEMPLE0000000000000000000000000000000 token_type: Bearer expires_in: 900 scope: catalog.read requests.write requests.read '400': description: Requête invalide (RFC 6749 § 5.2). content: application/json: schema: $ref: '#/components/schemas/OAuthError' examples: portee: value: error: invalid_scope error_description: La portée consent.attest n'est pas accordée à ce client. '401': description: Client inconnu, secret invalide ou révoqué. content: application/json: schema: $ref: '#/components/schemas/OAuthError' examples: client: value: error: invalid_client error_description: Identifiants du client invalides. '429': $ref: '#/components/responses/TooManyRequests' /oauth/revoke: post: tags: [Authentification] operationId: revokeAccessToken summary: Révoquer un jeton d'accès (RFC 7009) security: - ClientBasic: [] requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/RevokeRequest' responses: '200': description: Jeton révoqué (réponse identique si le jeton était déjà invalide, RFC 7009 § 2.2). '401': description: Client inconnu ou secret invalide. content: application/json: schema: $ref: '#/components/schemas/OAuthError' /countries: get: tags: [Référentiel] operationId: listCountries summary: Lister les pays et leurs langues description: Pays couverts, langues, devise, et disponibilité (`live` = demandes acceptées ; `preparing` = référentiel consultable, demandes refusées). security: - ApiKey: [] - OAuth2: [catalog.read] responses: '200': description: Liste des pays. headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/CountryList' examples: pays: value: 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 '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /trades: get: tags: [Référentiel] operationId: listTrades summary: Catalogue des métiers ouverts à l'API description: | 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. security: - ApiKey: [] - OAuth2: [catalog.read] parameters: - $ref: '#/components/parameters/Country' - $ref: '#/components/parameters/Lang' - name: family in: query description: Famille de métiers (ex. depannage, maison). schema: type: string maxLength: 40 - name: scope in: query description: Portée du métier. schema: $ref: '#/components/schemas/TradeScope' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/StartingAfter' responses: '200': description: Une page du catalogue. headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Link: $ref: '#/components/headers/Link' content: application/json: schema: $ref: '#/components/schemas/TradeList' examples: page: value: 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/ '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/TooManyRequests' /trades/{trade_id}: get: tags: [Référentiel] operationId: getTrade summary: Détail d'un métier (prestations, délais, texte d'accord) description: Équivalent de l'outil MCP `lister_prestations`. Les listes sont fermées, comme dans le formulaire. security: - ApiKey: [] - OAuth2: [catalog.read] parameters: - $ref: '#/components/parameters/TradeId' - $ref: '#/components/parameters/Country' - $ref: '#/components/parameters/Lang' responses: '200': description: Le métier. headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Trade' examples: plombier: $ref: '#/components/examples/TradePlombier' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' /trades/{trade_id}/services: get: tags: [Référentiel] operationId: listTradeServices summary: Catalogue détaillé des prestations d'un métier description: | 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`. security: - ApiKey: [] - OAuth2: [catalog.read] parameters: - $ref: '#/components/parameters/TradeId' - $ref: '#/components/parameters/Country' - $ref: '#/components/parameters/Lang' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/StartingAfter' responses: '200': description: Une page de prestations. content: application/json: schema: $ref: '#/components/schemas/ServiceList' examples: page: value: 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 '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' /trade-matches: post: tags: [Référentiel] operationId: matchTrades summary: Trouver les métiers correspondant à un besoin description: | É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. security: - ApiKey: [] - OAuth2: [catalog.read] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeMatchQuery' examples: fuite: value: need: Fuite d'eau sous l'évier de la cuisine country: FR lang: fr responses: '200': description: Métiers probables, du plus pertinent au moins pertinent. content: application/json: schema: $ref: '#/components/schemas/TradeMatchList' examples: fuite: value: 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: [] '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/TooManyRequests' /places: get: tags: [Référentiel] operationId: searchPlaces summary: Vérifier un lieu (ville ou code postal) description: Équivalent de l'outil MCP `verifier_lieu`. Renvoie des lieux existants ; utilisez leur `id` dans la demande. security: - ApiKey: [] - OAuth2: [catalog.read] parameters: - name: q in: query required: true description: Nom de ville ou code postal (pas d'adresse précise). schema: type: string minLength: 2 maxLength: 120 example: Créteil - $ref: '#/components/parameters/Country' - $ref: '#/components/parameters/Lang' - $ref: '#/components/parameters/Limit' responses: '200': description: Lieux correspondants. content: application/json: schema: $ref: '#/components/schemas/PlaceList' examples: creteil: value: 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 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /consent-texts/{version}: get: tags: [Référentiel] operationId: getConsentText summary: Lire une version du texte d'accord description: Versions datées et immuables. Le texte à afficher pour une demande est celui renvoyé dans son brouillon (`consent`). security: - ApiKey: [] - OAuth2: [catalog.read] parameters: - name: version in: path required: true schema: type: string pattern: '^v\d{4}-\d{2}-\d{2}$' example: v2026-10-18 - $ref: '#/components/parameters/Lang' responses: '200': description: Le texte d'accord. content: application/json: schema: $ref: '#/components/schemas/ConsentText' examples: v20261110: value: 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' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /requests: post: tags: [Demandes] operationId: createRequest summary: Créer un brouillon de demande description: | Valide la demande avec les règles du formulaire et renvoie un **brouillon** (`status: draft`) avec le récapitulatif et le texte d'accord à montrer à la personne. **Rien n'est transmis** à ce stade. Le brouillon expire au bout de 2 heures ; ses coordonnées sont alors effacées. security: - ApiKey: [] - OAuth2: [requests.write] parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RequestCreate' examples: fuite_creteil: $ref: '#/components/examples/RequestCreateFuite' responses: '201': description: Brouillon créé. headers: Location: description: Adresse de la demande. schema: type: string Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' Kelki-Mode: $ref: '#/components/headers/KelkiMode' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' content: application/json: schema: $ref: '#/components/schemas/Request' examples: brouillon: $ref: '#/components/examples/RequestDraft' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' get: tags: [Demandes] operationId: listRequests summary: Lister vos demandes description: Demandes du compte et du mode de l'identifiant utilisé, de la plus récente à la plus ancienne. security: - ApiKey: [] - OAuth2: [requests.read] parameters: - name: status in: query schema: $ref: '#/components/schemas/RequestStatus' - name: reference in: query description: Votre référence. schema: $ref: '#/components/schemas/PartnerReference' - name: created_after in: query schema: type: string format: date-time - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/StartingAfter' responses: '200': description: Une page de demandes. headers: Link: $ref: '#/components/headers/Link' content: application/json: schema: $ref: '#/components/schemas/RequestList' examples: page: value: object: list has_more: false next_cursor: null data: - id: req_01JC00000000000000000000RQ object: request mode: live status: called_back status_changed_at: '2026-11-13T18:02:11Z' created_at: '2026-11-11T09:41:58Z' reference: resa-2026-0042 channel: requests country: FR lang: fr trade: id: plombier name: Plombier service: Recherche de fuite delay: Dès que possible place: id: fr-creteil-94000 label: Créteil (94000) callback: reported: 'yes' reported_at: '2026-11-13T18:02:11Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /requests/{request_id}: get: tags: [Demandes] operationId: getRequest summary: Lire une demande et son statut security: - ApiKey: [] - OAuth2: [requests.read] parameters: - $ref: '#/components/parameters/RequestId' responses: '200': description: La demande. Coordonnées masquées ; jamais de professionnel, jamais de provenance. content: application/json: schema: $ref: '#/components/schemas/Request' examples: vendue: $ref: '#/components/examples/RequestSold' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' patch: tags: [Demandes] operationId: updateRequest summary: Modifier un brouillon description: Possible seulement au statut `draft`. Le récapitulatif est recalculé ; l'accord doit être redonné ensuite. security: - ApiKey: [] - OAuth2: [requests.write] parameters: - $ref: '#/components/parameters/RequestId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/merge-patch+json: schema: $ref: '#/components/schemas/RequestUpdate' examples: delai: value: delay: Dans la semaine responses: '200': description: Brouillon modifié. content: application/json: schema: $ref: '#/components/schemas/Request' examples: brouillon: $ref: '#/components/examples/RequestDraft' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationFailed' delete: tags: [Demandes] operationId: cancelRequest summary: Annuler une demande non transmise description: | Brouillon ou demande en attente de confirmation : annulée, coordonnées effacées immédiatement. Une demande déjà transmise ne peut plus être annulée par l'API : la personne exerce ses droits auprès de Kelki (lien dans ses e-mails). security: - ApiKey: [] - OAuth2: [requests.write] parameters: - $ref: '#/components/parameters/RequestId' - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: Demande annulée. content: application/json: schema: $ref: '#/components/schemas/Request' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' /requests/{request_id}/confirmation: post: tags: [Demandes] operationId: confirmRequest summary: Lancer la confirmation par la personne description: | Deux méthodes : - `email` (par défaut, tous les comptes) : Kelki envoie à la personne l'e-mail « Confirmer ma demande » (48 h, page `/confirmer/` de kelki.ai). Le lien n'est **jamais** donné au partenaire. Statut `awaiting_confirmation`, puis `transmitted` après le clic, ou `abandoned` sans clic sous 48 h. - `partner_attestation` (portée `consent.attest`, comptes agréés sous contrat) : le partenaire atteste avoir montré le récapitulatif et le texte d'accord, et recueilli l'accord explicite de la personne authentifiée. Statut `transmitted` immédiatement ; Kelki envoie à la personne un e-mail d'information avec un lien « Ce n'était pas moi ». security: - ApiKey: [] - OAuth2: [requests.write] - OAuth2: [requests.write, consent.attest] parameters: - $ref: '#/components/parameters/RequestId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConfirmationCreate' examples: email: value: method: email consent_text_version: v2026-10-18 consent_given: true attestation: value: method: partner_attestation consent_text_version: v2026-10-18 consent_given: true attestation: consented_at: '2026-11-11T09:42:10Z' language_shown: fr recap_shown: true checkbox_unticked_by_default: true subject_authentication: account_email_verified evidence_id: conc-evt-000123 responses: '202': description: E-mail de confirmation envoyé (méthode `email`). content: application/json: schema: $ref: '#/components/schemas/Request' examples: attente: $ref: '#/components/examples/RequestAwaiting' '201': description: Attestation acceptée, demande transmise (méthode `partner_attestation`). content: application/json: schema: $ref: '#/components/schemas/Request' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/TooManyRequests' /requests/{request_id}/events: get: tags: [Demandes] operationId: listRequestEvents summary: Historique des statuts d'une demande security: - ApiKey: [] - OAuth2: [requests.read] parameters: - $ref: '#/components/parameters/RequestId' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/StartingAfter' responses: '200': description: Événements, du plus ancien au plus récent. content: application/json: schema: $ref: '#/components/schemas/RequestEventList' examples: historique: value: object: list has_more: false next_cursor: null data: - id: evt_01JC0000000000000000000001 type: request.status_changed status: awaiting_confirmation occurred_at: '2026-11-11T09:42:12Z' - id: evt_01JC0000000000000000000002 type: request.status_changed status: transmitted occurred_at: '2026-11-11T09:47:03Z' - id: evt_01JC0000000000000000000003 type: request.status_changed status: sold occurred_at: '2026-11-11T10:15:40Z' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /sandbox/requests/{request_id}/simulate: post: tags: [Bac à sable] operationId: simulateRequestStatus summary: Faire avancer une demande de test description: Mode test uniquement (identifiants kk_test_…). Déclenche les mêmes webhooks qu'en production. security: - ApiKey: [] - OAuth2: [requests.write] parameters: - $ref: '#/components/parameters/RequestId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SimulateStatus' examples: vendue: value: status: sold responses: '200': description: Statut appliqué. content: application/json: schema: $ref: '#/components/schemas/Request' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' /agent/conversations: post: tags: [Agent] operationId: createConversation summary: Démarrer une conversation avec l'Agent Kelki description: Conversation rattachée au compte et au mode. Oubliée 2 heures après le dernier message. security: - ApiKey: [] - OAuth2: [agent] parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/ConversationCreate' examples: conciergerie: value: country: FR lang: fr first_message: Le volet roulant du salon est bloqué en position basse. reference: resa-2026-0042 responses: '201': description: Conversation créée, avec la première réponse de l'agent. content: application/json: schema: $ref: '#/components/schemas/Conversation' examples: debut: $ref: '#/components/examples/ConversationStart' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' /agent/conversations/{conversation_id}: get: tags: [Agent] operationId: getConversation summary: Lire l'état d'une conversation security: - ApiKey: [] - OAuth2: [agent] parameters: - $ref: '#/components/parameters/ConversationId' responses: '200': description: État de la conversation. content: application/json: schema: $ref: '#/components/schemas/Conversation' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /agent/conversations/{conversation_id}/messages: post: tags: [Agent] operationId: sendConversationMessage summary: Envoyer un message à l'Agent Kelki description: | Un message contient **un seul** de : `text` (texte libre, passe par le modèle), `choice` (valeur d'un bouton), `data` (champs structurés), `consent` (accord de la personne à l'étape `recap`). `consent: true` crée un brouillon puis lance la confirmation par e-mail, exactement comme `POST /requests` + `POST /requests/{id}/confirmation` (portée `requests.write` exigée en plus). security: - ApiKey: [] - OAuth2: [agent] - OAuth2: [agent, requests.write] parameters: - $ref: '#/components/parameters/ConversationId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentMessage' examples: choix: value: choice: metier:volets-roulants accord: value: consent: true consent_text_version: v2026-10-18 responses: '200': description: Réponse de l'agent. content: application/json: schema: $ref: '#/components/schemas/Conversation' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' /webhook-endpoints: get: tags: [Webhooks] operationId: listWebhookEndpoints summary: Lister vos adresses de webhooks security: - ApiKey: [] - OAuth2: [webhooks.manage] responses: '200': description: Adresses déclarées pour le mode courant. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointList' '401': $ref: '#/components/responses/Unauthorized' post: tags: [Webhooks] operationId: createWebhookEndpoint summary: Déclarer une adresse de webhook description: HTTPS seulement, nom de domaine public (pas d'adresse IP), certificat valide. Le secret est montré une seule fois. security: - ApiKey: [] - OAuth2: [webhooks.manage] parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointCreate' examples: statuts: value: url: https://hooks.conciergerie.example.com/kelki events: [request.status_changed] description: Statuts des demandes responses: '201': description: Adresse créée. `secret` n'apparaîtra plus jamais. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointCreated' examples: cree: value: id: we_01JC00000000000000000000AA url: https://hooks.conciergerie.example.com/kelki events: [request.status_changed] description: Statuts des demandes mode: test enabled: true created_at: '2026-11-11T09:00:00Z' secret: whsec_EXEMPLE_NE_PAS_UTILISER_000000000000 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationFailed' /webhook-endpoints/{endpoint_id}: get: tags: [Webhooks] operationId: getWebhookEndpoint summary: Lire une adresse de webhook security: - ApiKey: [] - OAuth2: [webhooks.manage] parameters: - $ref: '#/components/parameters/EndpointId' responses: '200': description: L'adresse (sans le secret). content: application/json: schema: $ref: '#/components/schemas/WebhookEndpoint' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' delete: tags: [Webhooks] operationId: deleteWebhookEndpoint summary: Supprimer une adresse de webhook security: - ApiKey: [] - OAuth2: [webhooks.manage] parameters: - $ref: '#/components/parameters/EndpointId' responses: '204': description: Supprimée. '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /webhook-endpoints/{endpoint_id}/test: post: tags: [Webhooks] operationId: testWebhookEndpoint summary: Envoyer un événement « ping » security: - ApiKey: [] - OAuth2: [webhooks.manage] parameters: - $ref: '#/components/parameters/EndpointId' responses: '202': description: Ping mis en file d'envoi. '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' /webhook-endpoints/{endpoint_id}/rotate-secret: post: tags: [Webhooks] operationId: rotateWebhookSecret summary: Remplacer le secret de signature description: Pendant 24 heures, chaque événement porte deux signatures (`v1=` ancien et nouveau secret). security: - ApiKey: [] - OAuth2: [webhooks.manage] parameters: - $ref: '#/components/parameters/EndpointId' responses: '200': description: Nouveau secret, montré une seule fois. content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointCreated' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /account: get: tags: [Compte] operationId: getAccount summary: Lire le compte, le plan et les plafonds security: - ApiKey: [] - OAuth2: [catalog.read] responses: '200': description: Le compte. content: application/json: schema: $ref: '#/components/schemas/Account' examples: compte: value: id: acc_01JC00000000000000000000CC name: Conciergerie Exemple mode: test plan: standard live_enabled: false limits: requests_per_minute: 120 requests_per_day: 20000 live_requests_per_day: 50 agent_messages_per_day: 500 webhook_endpoints: 5 credential: type: api_key prefix: kk_test_Ab12Cd34 scopes: [catalog.read, requests.read, requests.write, agent] '401': $ref: '#/components/responses/Unauthorized' /account/usage: get: tags: [Compte] operationId: getAccountUsage summary: Consommation par jour security: - ApiKey: [] - OAuth2: [catalog.read] parameters: - name: from in: query required: true schema: type: string format: date - name: to in: query required: true schema: type: string format: date responses: '200': description: Compteurs par jour (au plus 92 jours). content: application/json: schema: $ref: '#/components/schemas/UsageList' examples: jour: value: object: list has_more: false next_cursor: null data: - date: '2026-11-11' calls: 412 rate_limited: 0 errors: 3 drafts_created: 9 requests_transmitted: 7 requests_sold: 4 callbacks_confirmed: 2 agent_messages: 31 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' webhooks: request.status_changed: post: tags: [Webhooks] operationId: onRequestStatusChanged summary: Changement de statut d'une demande description: | Envoyé à chaque changement de statut. Vérifiez `Kelki-Signature` : `t=,v1=` calculé sur `"."` avec le secret `whsec_…`, comparaison à durée constante, tolérance 5 minutes. Dédoublonnez sur `Kelki-Event-Id`. Répondez 2xx en moins de 5 secondes ; sinon nouvel essai à 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h. parameters: - name: Kelki-Signature in: header required: true schema: type: string example: t=1762854000,v1=0000000000000000000000000000000000000000000000000000000000000000 - name: Kelki-Event-Id in: header required: true schema: type: string example: evt_01JC0000000000000000000003 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookEvent' examples: vendue: value: id: evt_01JC0000000000000000000003 type: request.status_changed api_version: '1' mode: live created_at: '2026-11-11T10:15:41Z' data: request: id: req_01JC00000000000000000000RQ object: request mode: live status: sold status_changed_at: '2026-11-11T10:15:40Z' reference: resa-2026-0042 country: FR trade: id: plombier name: Plombier service: Recherche de fuite delay: Dès que possible place: id: fr-creteil-94000 label: Créteil (94000) created_at: '2026-11-11T09:41:58Z' responses: '2XX': description: Événement reçu. '4XX': description: Refusé par le partenaire (nouvel essai selon le calendrier, sauf 410 qui désactive l'adresse). components: securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: kk_live_… ou kk_test_… description: Clé API du partenaire, dans `Authorization`. Jamais dans l'adresse. Stockée hachée chez Kelki. OAuth2: type: oauth2 description: Client credentials (RFC 6749 § 4.4). Jeton opaque de 15 minutes. flows: clientCredentials: tokenUrl: https://kelki.ai/api/v1/oauth/token refreshUrl: https://kelki.ai/api/v1/oauth/token scopes: catalog.read: Lire le référentiel, le compte et la consommation. requests.read: Lire vos demandes et leurs statuts. requests.write: Créer, modifier, annuler et faire confirmer vos demandes. consent.attest: Attester le consentement de la personne (partenaires agréés sous contrat). agent: Converser avec l'Agent Kelki. webhooks.manage: Gérer vos adresses de webhooks. ClientBasic: type: http scheme: basic description: client_id et client_secret du client OAuth (point d'accès /oauth/token seulement). parameters: Country: name: country in: query description: Pays (ISO 3166-1 alpha-2, majuscules). Défaut FR. schema: $ref: '#/components/schemas/CountryCode' Lang: name: lang in: query description: Langue (ISO 639-1). Défaut = langue principale du pays. `Accept-Language` est lu en repli. schema: $ref: '#/components/schemas/LanguageCode' Limit: name: limit in: query description: Taille de page (1 à 100). schema: type: integer minimum: 1 maximum: 100 default: 20 StartingAfter: name: starting_after in: query description: Curseur opaque `next_cursor` de la page précédente. schema: type: string maxLength: 200 IdempotencyKey: name: Idempotency-Key in: header required: true description: 8 à 64 caractères, unique par opération. Même clé + même corps sous 24 h = même réponse. schema: type: string pattern: '^[A-Za-z0-9_\-]{8,64}$' example: 3f1c9e2a-resa-0042-v1 TradeId: name: trade_id in: path required: true description: Identifiant stable du métier (slug français historique, ex. plombier). schema: type: string pattern: '^[a-z0-9-]{2,60}$' example: plombier RequestId: name: request_id in: path required: true schema: type: string pattern: '^req_[0-9A-Z]{26}$' example: req_01JC00000000000000000000RQ ConversationId: name: conversation_id in: path required: true schema: type: string pattern: '^conv_[0-9A-Za-z]{20,40}$' example: conv_01JC00000000000000000000CV EndpointId: name: endpoint_id in: path required: true schema: type: string pattern: '^we_[0-9A-Z]{26}$' example: we_01JC00000000000000000000AA headers: RateLimit: description: Quota restant de la politique en cours (draft-ietf-httpapi-ratelimit-headers), ex. `"minute";r=118;t=42`. schema: type: string RateLimitPolicy: description: Politique appliquée à la clé, ex. `"minute";q=120;w=60`. schema: type: string RetryAfter: description: Secondes à attendre avant de réessayer. schema: type: integer XRequestId: description: Identifiant de la requête, à citer au support. Repris dans `instance` des erreurs. schema: type: string Link: description: Lien `rel="next"` vers la page suivante (RFC 8288). schema: type: string IdempotentReplayed: description: '`true` si la réponse est rejouée depuis une requête précédente de même Idempotency-Key.' schema: type: string enum: ['true'] KelkiMode: description: Mode de l'identifiant (`test` ou `live`). schema: type: string enum: [test, live] CacheControlNoStore: description: Toujours `no-store` sur les réponses authentifiées. schema: type: string const: no-store responses: BadRequest: description: Requête mal formée (JSON invalide, paramètre inconnu, corps trop gros). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: json: value: type: https://kelki.ai/api/problems/invalid_json title: Corps JSON invalide status: 400 detail: Le corps n'est pas un JSON UTF-8 valide. instance: /api/v1/requests#rq_7f3a2c code: invalid_json request_id: rq_7f3a2c Unauthorized: description: Identifiants absents, invalides, expirés ou révoqués. headers: WWW-Authenticate: description: Schéma attendu (`Bearer`). schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: cle: value: type: https://kelki.ai/api/problems/invalid_credentials title: Identifiants invalides status: 401 detail: Clé inconnue, révoquée ou expirée. instance: /api/v1/trades#rq_1b2c3d code: invalid_credentials request_id: rq_1b2c3d Forbidden: description: Portée manquante, compte non autorisé en live, pays non ouvert, compte suspendu. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: portee: value: type: https://kelki.ai/api/problems/insufficient_scope title: Portée insuffisante status: 403 detail: Cette opération exige la portée consent.attest. instance: /api/v1/requests/req_01JC00000000000000000000RQ/confirmation#rq_9a8b7c code: insufficient_scope request_id: rq_9a8b7c NotFound: description: Ressource inconnue, ou appartenant à un autre compte ou à un autre mode (même réponse). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: demande: value: type: https://kelki.ai/api/problems/not_found title: Introuvable status: 404 detail: Aucune demande avec cet identifiant pour ce compte. instance: /api/v1/requests/req_01JC00000000000000000000ZZ#rq_4d5e6f code: not_found request_id: rq_4d5e6f Conflict: description: Transition impossible (ex. modifier une demande déjà transmise) ou requête idempotente en cours. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: statut: value: type: https://kelki.ai/api/problems/invalid_state title: Statut incompatible status: 409 detail: La demande est déjà transmise et ne peut plus être modifiée. instance: /api/v1/requests/req_01JC00000000000000000000RQ#rq_5e6f7a code: invalid_state request_id: rq_5e6f7a ValidationFailed: description: Valeur refusée par les règles du formulaire (listes fermées, lieu, coordonnées, accord, limites anti-abus). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: prestation: value: type: https://kelki.ai/api/problems/validation_failed title: Demande invalide status: 422 detail: Un champ ne respecte pas les règles du formulaire. instance: /api/v1/requests#rq_2c3d4e code: validation_failed request_id: rq_2c3d4e errors: - pointer: /service detail: Prestation hors liste pour Plombier. allowed: [Recherche de fuite, Réparation de fuite, Débouchage, Autre besoin] TooManyRequests: description: Débit ou quota dépassé. headers: Retry-After: $ref: '#/components/headers/RetryAfter' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: debit: value: type: https://kelki.ai/api/problems/rate_limited title: Trop de requêtes status: 429 detail: Limite de 120 requêtes par minute atteinte pour cette clé. instance: /api/v1/places#rq_6f7a8b code: rate_limited request_id: rq_6f7a8b ServiceUnavailable: description: Service en pause ou en maintenance (ex. agent en pause, création live suspendue). headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: TradePlombier: value: 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' RequestCreateFuite: value: country: FR lang: fr trade_id: plombier service: Recherche de fuite delay: Dès que possible place_id: fr-creteil-94000 contact: name: Camille Exemple phone: '+33639980042' email: camille.exemple@example.com message: Fuite sous l'évier de la cuisine, robinet d'arrêt fermé. reference: resa-2026-0042 end_user_ref: u_7d9f2b1c RequestDraft: value: id: req_01JC00000000000000000000RQ object: request mode: test status: draft status_changed_at: '2026-11-11T09:41:58Z' created_at: '2026-11-11T09:41:58Z' expires_at: '2026-11-11T11:41:58Z' reference: resa-2026-0042 channel: requests country: FR lang: fr trade: id: plombier name: Plombier service: Recherche de fuite delay: Dès que possible place: id: fr-creteil-94000 label: Créteil (94000) contact_masked: name: C••• phone: +33 6 •• •• •• 42 email: c•••@example.com recap: Plombier — Recherche de fuite, dès que possible, à Créteil (94000). Rappel de C••• au +33 6 •• •• •• 42. 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' RequestAwaiting: value: id: req_01JC00000000000000000000RQ object: request mode: live status: awaiting_confirmation status_changed_at: '2026-11-11T09:42:12Z' created_at: '2026-11-11T09:41:58Z' expires_at: '2026-11-13T09:42:12Z' reference: resa-2026-0042 channel: requests country: FR lang: fr trade: id: plombier name: Plombier service: Recherche de fuite delay: Dès que possible place: id: fr-creteil-94000 label: Créteil (94000) contact_masked: name: C••• phone: +33 6 •• •• •• 42 email: c•••@example.com confirmation: method: email sent_at: '2026-11-11T09:42:12Z' expires_at: '2026-11-13T09:42:12Z' RequestSold: value: id: req_01JC00000000000000000000RQ object: request mode: live status: sold status_changed_at: '2026-11-11T10:15:40Z' created_at: '2026-11-11T09:41:58Z' reference: resa-2026-0042 channel: requests country: FR lang: fr trade: id: plombier name: Plombier service: Recherche de fuite delay: Dès que possible place: id: fr-creteil-94000 label: Créteil (94000) contact_masked: name: C••• phone: +33 6 •• •• •• 42 email: c•••@example.com confirmation: method: email sent_at: '2026-11-11T09:42:12Z' confirmed_at: '2026-11-11T09:47:03Z' callback: reported: null reported_at: null ConversationStart: value: id: conv_01JC00000000000000000000CV object: conversation mode: test step: metier_choix text: Lequel de ces professionnels correspond à votre besoin ? choices: - value: metier:volets-roulants label: Réparateur de volets roulants - value: metier:serrurier label: Serrurier recap: null consent: null request_id: null fallback: null expires_at: '2026-11-11T11:43:00Z' schemas: CountryCode: type: string pattern: '^[A-Z]{2}$' default: FR examples: [FR] LanguageCode: type: string pattern: '^[a-z]{2}$' examples: [fr] PartnerReference: type: string pattern: '^[A-Za-z0-9._:\-]{1,64}$' description: Votre référence (ex. n° de réservation). Sans donnée personnelle. Renvoyée dans les webhooks. TradeScope: type: string enum: [local, national] description: '`local` : diffusion par cercles de distance ; `national` : diffusion triée par avis, sans distance. Le lieu reste obligatoire.' RequestStatus: type: string enum: [draft, draft_expired, awaiting_confirmation, abandoned, cancelled, transmitted, sold, not_taken, called_back] description: | draft : brouillon, rien n'est transmis · draft_expired : brouillon expiré (2 h), coordonnées effacées · awaiting_confirmation : e-mail envoyé, en attente du clic (48 h) · abandoned : pas de clic sous 48 h, coordonnées effacées · cancelled : annulée par le partenaire avant transmission · transmitted : confirmée et proposée aux professionnels · sold : prise par un seul professionnel · not_taken : aucun professionnel ne l'a prise pendant la durée de l'offre · called_back : la personne a confirmé avoir été rappelée. ListMeta: type: object required: [object, has_more, next_cursor] properties: object: type: string const: list has_more: type: boolean next_cursor: type: [string, 'null'] Problem: type: object description: Détails d'un problème (RFC 9457), avec des membres d'extension. required: [type, title, status, code, request_id] properties: type: type: string format: uri description: URI stable du type de problème ; elle mène à sa documentation. title: type: string status: type: integer minimum: 400 maximum: 599 detail: type: string instance: type: string format: uri-reference code: type: string description: Code stable, lisible par une machine. enum: [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: type: string errors: type: array items: $ref: '#/components/schemas/FieldError' FieldError: type: object required: [pointer, detail] properties: pointer: type: string description: JSON Pointer (RFC 6901) du champ en cause. detail: type: string allowed: type: array items: type: string description: Valeurs acceptées, quand la liste est fermée. OAuthError: type: object required: [error] properties: error: type: string enum: [invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope] error_description: type: string TokenRequest: type: object required: [grant_type] properties: grant_type: type: string const: client_credentials scope: type: string description: Portées séparées par des espaces. Par défaut, toutes les portées accordées au client. TokenResponse: type: object required: [access_token, token_type, expires_in, scope] properties: access_token: type: string token_type: type: string const: Bearer expires_in: type: integer description: Durée de validité en secondes. scope: type: string RevokeRequest: type: object required: [token] properties: token: type: string token_type_hint: type: string enum: [access_token] Country: type: object required: [code, name, languages, default_language, currency, availability] properties: code: $ref: '#/components/schemas/CountryCode' name: type: string languages: type: array items: $ref: '#/components/schemas/LanguageCode' default_language: $ref: '#/components/schemas/LanguageCode' currency: type: string pattern: '^[A-Z]{3}$' availability: type: string enum: [live, preparing] CountryList: allOf: - $ref: '#/components/schemas/ListMeta' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/Country' TradeSummary: type: object required: [id, name, family, scope] properties: id: type: string description: Identifiant stable, identique dans toutes les langues. name: type: string description: Nom dans la langue demandée. family: type: string scope: $ref: '#/components/schemas/TradeScope' page_url: type: string format: uri description: Page publique du métier dans le pays et la langue (`/{pays}/{langue}/…`). TradeList: allOf: - $ref: '#/components/schemas/ListMeta' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/TradeSummary' Delay: type: object required: [label, urgent] properties: label: type: string urgent: type: boolean ConsentText: type: object required: [version, lang, text, valid_from] properties: version: type: string pattern: '^v\d{4}-\d{2}-\d{2}$' lang: $ref: '#/components/schemas/LanguageCode' text: type: string description: À afficher mot pour mot, à côté d'une case non cochée par défaut. valid_from: type: string format: date Trade: allOf: - $ref: '#/components/schemas/TradeSummary' - type: object required: [country, lang, services, other_need_label, delays, consent] properties: country: $ref: '#/components/schemas/CountryCode' lang: $ref: '#/components/schemas/LanguageCode' services: type: array description: Liste fermée des prestations utilisables dans une demande (dont « Autre besoin »). items: type: string other_need_label: type: string description: Libellé de la prestation libre ; exige `other_need` dans la demande. delays: type: array items: $ref: '#/components/schemas/Delay' consent: $ref: '#/components/schemas/ConsentText' Service: type: object required: [id, label, requestable] properties: id: type: string label: type: string requestable: type: boolean description: true si l'intitulé fait partie de la liste fermée du formulaire. ServiceList: allOf: - $ref: '#/components/schemas/ListMeta' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/Service' TradeMatchQuery: type: object additionalProperties: false required: [need] properties: need: type: string minLength: 3 maxLength: 300 description: Besoin en mots courants. Ni conservé ni journalisé. country: $ref: '#/components/schemas/CountryCode' lang: $ref: '#/components/schemas/LanguageCode' limit: type: integer minimum: 1 maximum: 10 default: 5 TradeMatch: type: object required: [rank, trade, suggested_services] properties: rank: type: integer minimum: 1 trade: $ref: '#/components/schemas/TradeSummary' suggested_services: type: array items: type: string TradeMatchList: allOf: - $ref: '#/components/schemas/ListMeta' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/TradeMatch' Place: type: object required: [id, city, postal_code, label, country] properties: id: type: string pattern: '^[a-z]{2}-[a-z0-9-]{2,120}$' city: type: string postal_code: type: string label: type: string region: type: string subdivision: type: string description: Département, province, canton, comté… selon le pays. subdivision_code: type: string country: $ref: '#/components/schemas/CountryCode' PlaceList: allOf: - $ref: '#/components/schemas/ListMeta' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/Place' Contact: type: object additionalProperties: false required: [name, phone, email] properties: name: type: string minLength: 2 maxLength: 80 phone: type: string pattern: '^\+[1-9]\d{6,14}$' description: Format E.164. Doit être un numéro valide du pays de la demande. email: type: string format: email maxLength: 254 description: Reçoit l'e-mail de confirmation (méthode email) ou d'information (attestation). RequestCreate: type: object additionalProperties: false required: [trade_id, service, delay, place_id, contact] properties: country: $ref: '#/components/schemas/CountryCode' lang: $ref: '#/components/schemas/LanguageCode' trade_id: type: string maxLength: 60 service: type: string maxLength: 120 description: Une valeur de `Trade.services`. other_need: type: string minLength: 3 maxLength: 160 description: Obligatoire avec « Autre besoin ». delay: type: string maxLength: 60 description: Un libellé de `Trade.delays`. place_id: type: string maxLength: 130 description: Identifiant renvoyé par GET /places. contact: $ref: '#/components/schemas/Contact' message: type: string maxLength: 2000 description: Précisions de la personne. Pas de donnée de santé. reference: $ref: '#/components/schemas/PartnerReference' end_user_ref: type: string pattern: '^[A-Za-z0-9_\-]{6,64}$' description: Identifiant opaque et stable de l'utilisateur chez vous (pseudonyme, jamais un e-mail ou un numéro). Sert aux limites anti-abus par utilisateur. RequestUpdate: type: object additionalProperties: false minProperties: 1 properties: service: type: string maxLength: 120 other_need: type: string maxLength: 160 delay: type: string maxLength: 60 place_id: type: string maxLength: 130 contact: $ref: '#/components/schemas/Contact' message: type: [string, 'null'] maxLength: 2000 reference: $ref: '#/components/schemas/PartnerReference' MaskedContact: type: object properties: name: type: string phone: type: string email: type: string Confirmation: type: object required: [method] properties: method: type: string enum: [email, partner_attestation] sent_at: type: [string, 'null'] format: date-time expires_at: type: [string, 'null'] format: date-time confirmed_at: type: [string, 'null'] format: date-time Callback: type: object description: Réponse de la personne à la question « Avez-vous été rappelé ? » (e-mail envoyé 2 jours après la vente). required: [reported, reported_at] properties: reported: type: [string, 'null'] enum: ['yes', not_yet, null] reported_at: type: [string, 'null'] format: date-time Request: type: object description: Aucune coordonnée en clair, aucun professionnel, aucune provenance, aucun identifiant interne. required: [id, object, mode, status, status_changed_at, created_at, country, trade, service, delay, place] properties: id: type: string pattern: '^req_[0-9A-Z]{26}$' object: type: string const: request mode: type: string enum: [test, live] status: $ref: '#/components/schemas/RequestStatus' status_changed_at: type: string format: date-time created_at: type: string format: date-time expires_at: type: [string, 'null'] format: date-time description: Fin du brouillon (2 h) ou de la confirmation (48 h). reference: type: [string, 'null'] channel: type: string enum: [requests, agent] country: $ref: '#/components/schemas/CountryCode' lang: $ref: '#/components/schemas/LanguageCode' trade: type: object required: [id, name] properties: id: type: string name: type: string service: type: string other_need: type: string delay: type: string place: type: object required: [id, label] properties: id: type: string label: type: string contact_masked: $ref: '#/components/schemas/MaskedContact' recap: type: string description: Récapitulatif à montrer à la personne avant son accord (brouillon seulement). consent: $ref: '#/components/schemas/ConsentText' confirmation: $ref: '#/components/schemas/Confirmation' callback: $ref: '#/components/schemas/Callback' RequestList: allOf: - $ref: '#/components/schemas/ListMeta' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/Request' RequestEvent: type: object required: [id, type, status, occurred_at] properties: id: type: string type: type: string const: request.status_changed status: $ref: '#/components/schemas/RequestStatus' occurred_at: type: string format: date-time RequestEventList: allOf: - $ref: '#/components/schemas/ListMeta' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/RequestEvent' Attestation: type: object additionalProperties: false required: [consented_at, language_shown, recap_shown, checkbox_unticked_by_default, subject_authentication, evidence_id] properties: consented_at: type: string format: date-time description: Horodatage UTC du clic de la personne. Au plus 15 minutes avant l'appel. language_shown: $ref: '#/components/schemas/LanguageCode' recap_shown: type: boolean const: true checkbox_unticked_by_default: type: boolean const: true subject_authentication: type: string enum: [account_email_verified, account_phone_verified, one_time_code] description: Comment la personne est authentifiée chez vous ; l'e-mail ou le téléphone de la demande doit être celui que vous avez vérifié. evidence_id: type: string pattern: '^[A-Za-z0-9._:\-]{4,64}$' description: Identifiant de votre preuve (journal), sans donnée personnelle. Produite sur demande de Kelki. ConfirmationCreate: description: Méthode de confirmation, choisie par `method`. oneOf: - $ref: '#/components/schemas/EmailConfirmationCreate' - $ref: '#/components/schemas/AttestationConfirmationCreate' discriminator: propertyName: method mapping: email: '#/components/schemas/EmailConfirmationCreate' partner_attestation: '#/components/schemas/AttestationConfirmationCreate' EmailConfirmationCreate: type: object additionalProperties: false required: [method, consent_text_version, consent_given] properties: method: type: string const: email consent_text_version: type: string pattern: '^v\d{4}-\d{2}-\d{2}$' description: Version du texte montré ; doit être celle du brouillon. consent_given: type: boolean const: true description: La personne a coché la case d'accord après avoir vu le récapitulatif. AttestationConfirmationCreate: type: object additionalProperties: false required: [method, consent_text_version, consent_given, attestation] properties: method: type: string const: partner_attestation consent_text_version: type: string pattern: '^v\d{4}-\d{2}-\d{2}$' description: Version du texte montré ; doit être celle du brouillon. consent_given: type: boolean const: true attestation: $ref: '#/components/schemas/Attestation' SimulateStatus: type: object additionalProperties: false required: [status] properties: status: type: string enum: [transmitted, abandoned, sold, not_taken, called_back] ConversationCreate: type: object additionalProperties: false properties: country: $ref: '#/components/schemas/CountryCode' lang: $ref: '#/components/schemas/LanguageCode' first_message: type: string maxLength: 600 reference: $ref: '#/components/schemas/PartnerReference' end_user_ref: type: string pattern: '^[A-Za-z0-9_\-]{6,64}$' AgentMessage: type: object additionalProperties: false minProperties: 1 properties: text: type: string maxLength: 600 choice: type: string maxLength: 200 data: type: object additionalProperties: false properties: trade_id: type: string service: type: string other_need: type: string delay: type: string place_id: type: string contact: $ref: '#/components/schemas/Contact' message: type: string maxLength: 2000 consent: type: boolean const: true consent_text_version: type: string pattern: '^v\d{4}-\d{2}-\d{2}$' oneOf: - required: [text] - required: [choice] - required: [data] - required: [consent, consent_text_version] Choice: type: object required: [value, label] properties: value: type: string label: type: string hint: type: string Conversation: type: object required: [id, object, mode, step, text, choices, expires_at] properties: id: type: string object: type: string const: conversation mode: type: string enum: [test, live] step: type: string enum: [metier, metier_choix, besoin, besoin_libre, delai, lieu, lieu_choix, coordonnees, recap, envoyee] text: type: string description: Texte de l'agent ; tout e-mail ou numéro y est masqué. choices: type: array items: $ref: '#/components/schemas/Choice' recap: type: [string, 'null'] description: Récapitulatif masqué (étape recap). consent: oneOf: - $ref: '#/components/schemas/ConsentText' - type: 'null' request_id: type: [string, 'null'] description: 'Demande créée après `consent: true`.' fallback: type: [string, 'null'] enum: [form, null] description: '`form` : l''agent passe la main (budget, panne du modèle) ; continuez avec POST /requests.' expires_at: type: string format: date-time WebhookEndpointCreate: type: object additionalProperties: false required: [url, events] properties: url: type: string format: uri pattern: '^https://' maxLength: 500 events: type: array minItems: 1 items: type: string enum: [request.status_changed] description: type: string maxLength: 120 WebhookEndpoint: type: object required: [id, url, events, mode, enabled, created_at] properties: id: type: string url: type: string format: uri events: type: array items: type: string description: type: string mode: type: string enum: [test, live] enabled: type: boolean created_at: type: string format: date-time disabled_reason: type: [string, 'null'] enum: [too_many_failures, gone, null] WebhookEndpointCreated: allOf: - $ref: '#/components/schemas/WebhookEndpoint' - type: object required: [secret] properties: secret: type: string description: Secret de signature whsec_…, montré une seule fois. WebhookEndpointList: allOf: - $ref: '#/components/schemas/ListMeta' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/WebhookEndpoint' WebhookEvent: type: object required: [id, type, api_version, mode, created_at, data] properties: id: type: string type: type: string enum: [request.status_changed, ping] api_version: type: string mode: type: string enum: [test, live] created_at: type: string format: date-time data: type: object properties: request: $ref: '#/components/schemas/Request' Account: type: object required: [id, name, mode, plan, live_enabled, limits, credential] properties: id: type: string name: type: string description: Nom affiché dans les e-mails envoyés aux personnes. Fixé par Kelki. mode: type: string enum: [test, live] plan: type: string live_enabled: type: boolean limits: type: object properties: requests_per_minute: type: integer requests_per_day: type: integer live_requests_per_day: type: integer agent_messages_per_day: type: integer webhook_endpoints: type: integer credential: type: object properties: type: type: string enum: [api_key, oauth_client] prefix: type: string description: Préfixe visible de la clé ou identifiant du client (jamais le secret). scopes: type: array items: type: string Usage: type: object required: [date, calls] properties: date: type: string format: date calls: type: integer rate_limited: type: integer errors: type: integer drafts_created: type: integer requests_transmitted: type: integer requests_sold: type: integer callbacks_confirmed: type: integer agent_messages: type: integer UsageList: allOf: - $ref: '#/components/schemas/ListMeta' - type: object required: [data] properties: data: type: array items: $ref: '#/components/schemas/Usage'