Code examples
The same calls in curl, JavaScript and Python, without dependencies. Run them with a test key: no real request, no e-mail.
curl
# OAuth token (or use a kk_test_… key directly as Bearer)
curl -s https://kelki.ai/api/v1/oauth/token -u "$KELKI_CLIENT_ID:$KELKI_CLIENT_SECRET" \
-d grant_type=client_credentials -d "scope=catalog.read requests.write requests.read"
# Draft
curl -s https://kelki.ai/api/v1/requests \
-H "Authorization: Bearer $KELKI_TOKEN" -H "Content-Type: application/json" \
-H "Idempotency-Key: resa-0042-draft-1" \
-d '{"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"},
"reference":"resa-2026-0042"}'
# E-mail confirmation, AFTER the person has consented on the summary
curl -s https://kelki.ai/api/v1/requests/req_01JC00000000000000000000RQ/confirmation \
-H "Authorization: Bearer $KELKI_TOKEN" -H "Content-Type: application/json" \
-H "Idempotency-Key: resa-0042-confirmation-1" \
-d '{"method":"email","consent_text_version":"v2026-10-18","consent_given":true}'
# Status
curl -s https://kelki.ai/api/v1/requests/req_01JC00000000000000000000RQ \
-H "Authorization: Bearer $KELKI_TOKEN"
JavaScript (Node 18+, fetch)
const API = "https://kelki.ai/api/v1";
const headers = (extra = {}) => ({ Authorization: `Bearer ${process.env.KELKI_KEY}`, "Content-Type": "application/json", ...extra });
async function call(method, path, body, idem) {
const r = await fetch(API + path, { method, headers: headers(idem ? { "Idempotency-Key": idem } : {}),
body: body ? JSON.stringify(body) : undefined });
const data = await r.json();
if (!r.ok) throw Object.assign(new Error(data.title), { problem: data }); // RFC 9457
return data;
}
// 1. the need → trades (to offer to the person)
const { data: matches } = await call("POST", "/trade-matches", { need: "Volet roulant bloqué", country: "FR", lang: "fr" });
// 2. draft, then display draft.recap and draft.consent.text in the app
const draft = await call("POST", "/requests", {
trade_id: matches[0].trade.id, service: "Autre besoin", other_need: "Volet roulant bloqué en bas",
delay: "Dès que possible", place_id: "fr-creteil-94000",
contact: { name: "Camille Exemple", phone: "+33639980042", email: "camille.exemple@example.com" },
reference: "resa-2026-0042" }, "resa-0042-draft-1");
// 3. once the person has ticked the box
await call("POST", `/requests/${draft.id}/confirmation`,
{ method: "email", consent_text_version: draft.consent.version, consent_given: true }, "resa-0042-confirmation-1");
Python (standard library)
import json, os, urllib.error, urllib.request
API = "https://kelki.ai/api/v1"
def call(method, path, body=None, idem=None):
h = {"Authorization": f"Bearer {os.environ['KELKI_KEY']}", "Content-Type": "application/json"}
if idem:
h["Idempotency-Key"] = idem
req = urllib.request.Request(API + path, method=method, headers=h,
data=json.dumps(body).encode() if body is not None else None)
try:
with urllib.request.urlopen(req, timeout=15) as r:
return json.load(r)
except urllib.error.HTTPError as e: # application/problem+json body
raise RuntimeError(json.load(e)) from None
trade = call("GET", "/trades/plombier?country=FR&lang=fr")
draft = call("POST", "/requests", {
"trade_id": "plombier", "service": trade["services"][0], "delay": trade["delays"][0]["label"],
"place_id": "fr-creteil-94000",
"contact": {"name": "Camille Exemple", "phone": "+33639980042", "email": "camille.exemple@example.com"},
}, idem="resa-0042-draft-1")
# … show draft["recap"] and draft["consent"]["text"], unticked box …
call("POST", f"/requests/{draft['id']}/confirmation",
{"method": "email", "consent_text_version": draft["consent"]["version"], "consent_given": True},
idem="resa-0042-confirmation-1")
Verifying a webhook
JavaScript (Node):
import crypto from "node:crypto";
function verify(rawBody, header, secret, toleranceS = 300) {
const parts = Object.fromEntries(header.split(",").map(p => p.split("=")).map(([k, ...v]) => [k, v.join("=")]));
const sigs = header.split(",").filter(p => p.startsWith("v1=")).map(p => p.slice(3));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceS) return false;
const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
return sigs.some(s => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
}
Python:
import hashlib, hmac, time
def verify_webhook(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
parts = [p.split("=", 1) for p in header.split(",")]
t = next(v for k, v in parts if k == "t")
if abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return any(k == "v1" and hmac.compare_digest(v, expected) for k, v in parts)
Check the signature on the raw body, before any JSON decoding. During a secret rotation, the header carries two v1=: either one is enough.