L'indice de citation de vos clients, dans vos propres outils

Authentification

Chaque requête porte votre clé dans l'en-tête X-Api-Key. Les clés se créent dans Paramètres → API (jusqu'à cinq clés actives), commencent par ck_live_ et ne sont affichées qu'une fois — nous n'en stockons qu'une empreinte. Une clé absente, inconnue, révoquée ou portée par une offre sans accès API reçoit la même réponse 401, sans distinction : une clé ne doit pas être sondable.

curl -H "X-Api-Key: ck_live_votre_cle" \
  https://api.citezmoi.com/api/v1/partner/sites

Webhooks

Un endpoint HTTPS par organisation, enregistré dans Paramètres → API. Deux événements existent : audit.ready (un audit vient de se terminer) et score.drop (l'indice d'un site suivi a nettement baissé d'une semaine sur l'autre). Vous pouvez n'écouter qu'un sous-ensemble ; ne rien choisir signifie « tout recevoir », y compris les événements ajoutés plus tard.

POST https://votre-endpoint.example.com/citezmoi
Content-Type: application/json
User-Agent: CitezMoi-Webhooks/1.0
X-CitezMoi-Event: audit.ready
X-CitezMoi-Signature: sha256=3f1a…

{"event":"audit.ready","created_at":"2026-09-14T06:01:13+00:00","data":{
  "audit_id":"9f2c11d0-…","site_id":"0b0e8a52-…",
  "domain":"cabinet-durand-lyon.com","score":47,"tier":"tracked",
  "report_url":"https://www.citezmoi.com/a/…"}}

{"event":"score.drop","created_at":"…","data":{
  "site_id":"0b0e8a52-…","domain":"cabinet-durand-lyon.com",
  "score":39,"previous":47,"delta":-8}}

Vérifier la signature

Chaque livraison est signée HMAC-SHA256 avec le secret montré une seule fois à l'enregistrement de l'endpoint : X-CitezMoi-Signature vaut sha256=<hex>, calculé sur les octets exacts du corps reçu. Vérifiez avant de re-sérialiser le JSON — un JSON ré-encodé ne redonne pas les mêmes octets.

import hashlib
import hmac

def verify(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, rawBody, header) {
  const expected =
    "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  return (
    header.length === expected.length &&
    timingSafeEqual(Buffer.from(header), Buffer.from(expected))
  );
}

Livraison, accusé et relances

• Toute réponse 2xx vaut accusé de réception. Une redirection n'est pas suivie : un 3xx compte comme un échec à corriger de votre côté. Délai de réponse : 10 secondes.
• En cas d'échec, la livraison est retentée jusqu'à cinq fois au total, étalées sur une quinzaine d'heures. Chaque relance renvoie exactement les mêmes octets — même signature, même created_at — donc dédupliquer sur le corps reçu suffit pour ne traiter chaque événement qu'une fois.
• L'historique des livraisons et leur relance manuelle sont dans Paramètres → API. Le secret n'est jamais ré-affiché ; le faire tourner = supprimer l'endpoint puis le ré-enregistrer.

Depuis votre assistant IA (MCP)

La même clé ouvre un serveur Model Context Protocol : votre assistant (Claude Code, ou tout client MCP qui parle le transport HTTP) interroge vos sites en langage naturel — « quels clients ont perdu des points cette semaine ? » — avec la même portée en lecture seule que l'API. Transport HTTP, clé dans X-Api-Key ou en Authorization: Bearer.

claude mcp add --transport http citezmoi https://api.citezmoi.com/api/v1/partner/mcp \
  --header "X-Api-Key: ck_live_votre_cle"

{
  "mcpServers": {
    "citezmoi": {
      "type": "http",
      "url": "https://api.citezmoi.com/api/v1/partner/mcp",
      "headers": { "X-Api-Key": "${CITEZMOI_API_KEY}" }
    }
  }
}

• Quatre outils : list_sites, get_score_history, get_source_decay (les sources qui nourrissent vos réponses d'une mesure à l'autre) et get_audit.
• Le serveur transmet à l'assistant les mêmes règles que nos rapports : un moteur marqué « (API) » ne répond pas comme son interface grand public, et une présence se lit en taux, jamais en « cité / pas cité ».
• Dans l'application Claude, un connecteur personnalisé peut transmettre la clé par le champ « Request headers » — une fonction encore en bêta chez Anthropic, pas ouverte à toutes les organisations.