{
  "openapi": "3.1.0",
  "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 :\n\n1. trouver le métier et la prestation qui correspondent à un besoin, dans la langue et le pays de la personne ;\n2. vérifier le lieu de l'intervention ;\n3. préparer un **brouillon** de demande, le montrer à la personne avec le **texte d'accord** ;\n4. faire **confirmer** la demande par la personne (lien envoyé par e-mail, ou attestation de consentement d'un\n   partenaire agréé) ;\n5. suivre la demande : transmise, vendue à **un seul professionnel**, rappel confirmé par la personne.\n\nMêmes règles que le formulaire « Rappelez-moi », le connecteur MCP (`https://kelki.ai/mcp`) et l'Agent Kelki.\nAucune réponse ne contient la coordonnée d'un professionnel, ni la source d'acquisition de la demande.\n\nErreurs au format RFC 9457 (`application/problem+json`). Pagination par curseur. `Idempotency-Key` obligatoire\nsur les créations. Débit limité par clé (en-têtes `RateLimit` et `RateLimit-Policy`).\n\nGratuite pour les partenaires. Encadrée par trois textes (12/11/2026, `/developers/fr/terms/`) : conditions\nd'utilisation de l'API, accord de traitement des données (article 28 du RGPD : Kelki responsable du traitement,\npartenaire sous-traitant pour la collecte et l'envoi des demandes), politique d'usage acceptable.\n",
    "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.\nLes portées demandées doivent être accordées au client. Le mode (test / live) est celui du client.\n",
        "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,\nexclusions propres au compte. Les métiers `national` n'ont pas de diffusion par distance.\n",
        "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\ndemande sont ceux qui ont `requestable: true` ; « Autre besoin » est toujours possible avec `other_need`.\n",
        "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\ncontenir des détails personnels. Il n'est ni conservé ni journalisé. Proposez les 2 ou 3 premiers résultats à\nla personne et laissez-la choisir. Lecture seule : pas d'Idempotency-Key.\n",
        "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\nrécapitulatif et le texte d'accord à montrer à la personne. **Rien n'est transmis** à ce stade. Le brouillon\nexpire au bout de 2 heures ; ses coordonnées sont alors effacées.\n",
        "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à\ntransmise ne peut plus être annulée par l'API : la personne exerce ses droits auprès de Kelki\n(lien dans ses e-mails).\n",
        "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 :\n- `email` (par défaut, tous les comptes) : Kelki envoie à la personne l'e-mail « Confirmer ma demande »\n  (48 h, page `/confirmer/<jeton>` de kelki.ai). Le lien n'est **jamais** donné au partenaire. Statut\n  `awaiting_confirmation`, puis `transmitted` après le clic, ou `abandoned` sans clic sous 48 h.\n- `partner_attestation` (portée `consent.attest`, comptes agréés sous contrat) : le partenaire atteste avoir\n  montré le récapitulatif et le texte d'accord, et recueilli l'accord explicite de la personne authentifiée.\n  Statut `transmitted` immédiatement ; Kelki envoie à la personne un e-mail d'information avec un lien\n  « Ce n'était pas moi ».\n",
        "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),\n`data` (champs structurés), `consent` (accord de la personne à l'étape `recap`). `consent: true` crée un\nbrouillon puis lance la confirmation par e-mail, exactement comme `POST /requests` + `POST\n/requests/{id}/confirmation` (portée `requests.write` exigée en plus).\n",
        "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=<horodatage unix>,v1=<HMAC-SHA256 hex>`\ncalculé sur `\"<t>.<corps brut>\"` avec le secret `whsec_…`, comparaison à durée constante, tolérance 5 minutes.\nDédoublonnez sur `Kelki-Event-Id`. Répondez 2xx en moins de 5 secondes ; sinon nouvel essai à 1 min, 5 min,\n30 min, 2 h, 6 h, 12 h, 24 h.\n",
        "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 ·\nawaiting_confirmation : e-mail envoyé, en attente du clic (48 h) · abandoned : pas de clic sous 48 h,\ncoordonnées effacées · cancelled : annulée par le partenaire avant transmission · transmitted : confirmée et\nproposée aux professionnels · sold : prise par un seul professionnel · not_taken : aucun professionnel ne l'a\nprise pendant la durée de l'offre · called_back : la personne a confirmé avoir été rappelée.\n"
      },
      "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"
                }
              }
            }
          }
        ]
      }
    }
  }
}
