Lancez un diagnostic après chaque mise en ligne, suivez la note de vos sites dans vos propres outils, ou bloquez un déploiement quand un point important apparaît.
Dans Mon espace, onglet API, créez une clé et copiez-la : elle n'est affichée qu'une fois. Gardez-la côté serveur (variable d'environnement, secret de votre intégration continue), jamais dans le code d'une page web. Vous pouvez avoir jusqu'à 5 clés et en révoquer une à tout moment.
curl -X POST https://api.quetzalshield.fr/v1/scans \
-H "Authorization: Bearer qs_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{"url": "https://www.monsite.fr"}'La réponse arrive tout de suite, avec l'identifiant de l'analyse (id) et l'état queued. Si le site n'est pas encore dans votre espace, il y est ajouté.
curl https://api.quetzalshield.fr/v1/scans/IDENTIFIANT \
-H "Authorization: Bearer qs_VOTRE_CLE"Tant que status vaut queued, running ou analyzing, réessayez quelques secondes plus tard. À done, vous obtenez la note, le résumé et chaque point à corriger avec sa solution :
{
"id": "Xk2f9…",
"site": "www.monsite.fr",
"status": "done",
"progress": 100,
"grade": "B",
"provisional": false,
"unverified": [],
"counts": { "critical": 0, "high": 0, "medium": 2, "low": 3, "info": 4 },
"summary": "Votre site est correctement protégé. Deux réglages restent à faire…",
"modules": [],
"createdAt": "2026-11-22T10:00:00.000Z",
"finishedAt": "2026-11-22T10:01:04.000Z",
"error": null,
"findings": [
{
"id": "8dPq…",
"severity": "medium",
"title": "Aucune politique de sécurité du contenu",
"explanation": "…",
"impact": "…",
"fix": "…",
"effort": "minutes",
"category": "headers"
}
]
}grade va de A à F. Il vaut null si la page d'accueil du site n'a pas pu être lue (site protégé contre les robots, par exemple) : nous ne contournons jamais ces protections. provisional indique une note provisoire, quand les contrôles listés dans unverified n'ont pas pu conclure.
Adresse de base : https://api.quetzalshield.fr/v1. Chaque appel porte l'en-tête Authorization: Bearer qs_….
| Appel | Rôle |
|---|---|
POST /scans | Lance une analyse. Corps : url (obligatoire), webhookUrl et modules (facultatifs). |
GET /scans/{id} | État de l'analyse, puis note, résumé et points à corriger. |
GET /scans/{id}/report.pdf | Rapport PDF d'une analyse terminée, à votre marque avec l'offre Agence. |
GET /account | Votre offre, vos analyses restantes ce mois-ci et le nombre de sites utilisés. |
| Offre | Analyses par API et par mois | Sites |
|---|---|---|
| Gratuit | 30 | 1 |
| Pro | 500 | 5 |
| Agence | 5 000 | 50 |
Pour ménager les sites analysés, deux analyses d'un même site sont espacées d'au moins 2 minutes, et un même domaine ne peut pas être analysé plus de 12 fois par heure. L'API accepte 120 appels par minute et par clé.
Par défaut, l'API lance le diagnostic de base, qui se limite à ce que fait un navigateur. Le champ modules ajoute des tests approfondis : deep_analysis (analyse approfondie), active_scan (scan actif), firebase_audit et supabase_audit.
Ajoutez "webhookUrl": "https://votre-serveur.fr/quetzal" au lancement. À la fin de l'analyse, nous envoyons à cette adresse un message POST en JSON : { "event": "scan.finished", "sentAt": "…", "scan": { … } }, où scan a la même forme que la réponse ci-dessus, sans la liste findings. L'adresse doit être en https et publique. Nous faisons jusqu'à trois tentatives ; gardez la lecture par GET comme solution de repli.
Chaque message est signé avec le secret whsec_… reçu à la création de la clé, dans l'en-tête X-Quetzal-Signature :
import { createHmac, timingSafeEqual } from "node:crypto";
// corps : le texte brut reçu, avant tout JSON.parse
function vientDeQuetzal(corps, signature, secret) {
const attendu = "sha256=" + createHmac("sha256", secret).update(corps).digest("hex");
return signature.length === attendu.length && timingSafeEqual(Buffer.from(signature), Buffer.from(attendu));
}
// signature : en-tête X-Quetzal-Signature ; secret : whsec_… reçu à la création de la cléUne erreur renvoie toujours { "error": "code", "message": "explication en français" }.
| Statut | Codes | Signification |
|---|---|---|
| 400 | invalid_input, invalid_url | Le corps de la requête ou l'adresse du site est invalide. |
| 401 | unauthenticated, invalid_api_key | Clé absente, inconnue ou révoquée. |
| 402 | quota_exceeded, site_limit, plan_required, module_not_purchased | Quota du mois atteint, site hors de votre offre, ou test non inclus. |
| 403 | verification_required | Test approfondi demandé sur un site dont la propriété n'est pas vérifiée. |
| 404 | scan_not_found | Analyse inconnue pour cette clé. |
| 409 | scan_not_finished, site_archived | Rapport demandé avant la fin de l'analyse, ou site remplacé dans votre espace. |
| 429 | too_soon, too_many_running, domain_rate_limited, rate_limited | Trop d'appels ou d'analyses rapprochées : réessayez après le délai indiqué (retryAfterMs). |
const API = "https://api.quetzalshield.fr/v1";
const headers = { Authorization: `Bearer ${process.env.QUETZAL_API_KEY}`, "Content-Type": "application/json" };
const start = await fetch(`${API}/scans`, { method: "POST", headers, body: JSON.stringify({ url: "https://www.monsite.fr" }) });
if (!start.ok) throw new Error((await start.json()).message);
let scan = await start.json();
while (scan.status !== "done" && scan.status !== "failed") {
await new Promise((r) => setTimeout(r, 5000));
scan = await (await fetch(`${API}/scans/${scan.id}`, { headers })).json();
}
console.log(scan.grade, scan.counts);Ajoutez votre clé dans les secrets du dépôt sous le nom QUETZAL_API_KEY.
name: Sécurité du site
on:
workflow_dispatch:
schedule:
- cron: "0 6 * * 1" # chaque lundi matin
jobs:
quetzal:
runs-on: ubuntu-latest
steps:
- name: Diagnostic Quetzal Shield
env:
QUETZAL_API_KEY: ${{ secrets.QUETZAL_API_KEY }}
run: |
API="https://api.quetzalshield.fr/v1"
ID=$(curl -sf -X POST "$API/scans" -H "Authorization: Bearer $QUETZAL_API_KEY" \
-H "Content-Type: application/json" -d '{"url":"https://www.monsite.fr"}' | jq -r .id)
while :; do
sleep 10
SCAN=$(curl -sf "$API/scans/$ID" -H "Authorization: Bearer $QUETZAL_API_KEY")
STATUS=$(echo "$SCAN" | jq -r .status)
[ "$STATUS" = "done" ] || [ "$STATUS" = "failed" ] && break
done
echo "$SCAN" | jq '{grade, counts}'
# Échec si un point critique ou important est trouvé.
[ "$(echo "$SCAN" | jq '.counts.critical + .counts.high')" = "0" ]Non. Elle est incluse dans toutes les offres : 30 analyses par mois avec l'offre gratuite, 500 avec l'offre Pro, 5 000 avec l'offre Agence.
Le diagnostic de base ne fait que ce qu'un navigateur fait en visitant un site : il est autorisé sur toute adresse publique, dans la limite du nombre de sites de votre offre. Les tests approfondis ne sont lancés que sur un site dont vous avez prouvé la propriété.
Environ une minute pour le diagnostic de base. Interrogez le résultat toutes les 5 à 10 secondes, ou donnez une adresse de webhook pour être prévenu à la fin.
Révoquez-la depuis Mon espace, onglet API : elle cesse de fonctionner aussitôt. Créez-en une autre, vos autres clés ne sont pas touchées.
Gratuit, sans inscription et sans risque pour votre site. Résultat en une minute environ.