Conventions

- **Base URL** : `https://sannmerk.com/v1/sannmerk` - **Format** : `application/json` (GET only) - **Auth** : aucune pour les endpoints publics - **Cache** : 60s côté edge, 3600s pour les listings de taxonomie - **Rate limit** : 60 requêtes/minute par IP (burst 120) - **Erreurs** : HTTP standard, body `{"detail": "..."}`

Limites et quotas

- **Endpoints publics** : 60 requêtes/minute par IP (burst 120) - **Endpoints taxonomy** (`/facets`, `/sitemap`) : 30 requêtes/minute - **Pas d'authentification** sur les endpoints publics. Pour un SLA et un quota étendu, contactez /contact?intent=api. - **CORS** : tous les endpoints publics exposent `Access-Control-Allow-Origin: *`.

Enregistrer une souscription

Pour commencer, envoyez un POST à /v1/sannmerk/webhooks avec le body JSON suivant : ``` { "site_id": "<uuid du site>", "target_url": "https://example.com/webhooks/sannmerk", "event_types": ["product.recall", "product.updated"] } ``` La réponse contient un secret (à conserver en lieu sûr) qui sert à signer les livraisons. Si event_types est vide, la souscription reçoit tous les événements.

Vérification de la signature

Chaque livraison inclut un header `X-Sannmerk-Signature` au format `sha256=<hex>`. Pour vérifier : ``` mac = HMAC-SHA256(secret, raw_body) attendu = "sha256=" + mac.hexdigest() ``` Rejetez toute livraison dont la signature ne correspond pas. Le secret doit être traité comme un mot de passe : ne le stockez jamais en clair, ne l'embarquez pas dans le code, ne le transmettez pas en clair.

Sémantique de livraison

Les livraisons sont best-effort fire-and-forget. Le runtime POSTe l'événement, attend une réponse 2xx dans les 5 secondes, et journalise le code retour. Pas de file de retry dans cette version minimale — la fiabilité de bout en bout reste à la charge du consommateur (votre endpoint doit répondre vite et de manière idempotente). Un audit des dernières livraisons est disponible via `GET /v1/sannmerk/webhooks?site_id=...`.