Pour les développeurs et les agences

API de test de sécurité de site web : une clé, deux appels.

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.

  • Incluse dans l'offre gratuite
  • Réponses en JSON, en français
  • Rapport PDF et webhook
Démarrer

Trois étapes, moins de cinq minutes.

1. Créez votre clé

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.

2. Lancez une analyse

POST /v1/scans
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é.

3. Lisez le résultat

GET /v1/scans/{id}
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 :

Réponse
{
  "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.

Référence

Tous les appels.

Adresse de base : https://api.quetzalshield.fr/v1. Chaque appel porte l'en-tête Authorization: Bearer qs_….

AppelRôle
POST /scansLance 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.pdfRapport PDF d'une analyse terminée, à votre marque avec l'offre Agence.
GET /accountVotre offre, vos analyses restantes ce mois-ci et le nombre de sites utilisés.

Quotas par offre

OffreAnalyses par API et par moisSites
Gratuit301
Pro5005
Agence5 00050

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é.

Tests approfondis

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.

  • Le scan actif et les audits Firebase et Supabase ne sont lancés que sur un site dont vous avez prouvé la propriété, depuis Mon espace. La preuve est revérifiée au début de chaque analyse.
  • Ils consomment les mêmes quotas et crédits que depuis le site.
  • Le scan connecté, avec un compte de test, se lance uniquement depuis Mon espace.

Être prévenu à la fin (webhook)

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 :

Vérifier la signature (Node.js)
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é

Erreurs

Une erreur renvoie toujours { "error": "code", "message": "explication en français" }.

StatutCodesSignification
400invalid_input, invalid_urlLe corps de la requête ou l'adresse du site est invalide.
401unauthenticated, invalid_api_keyClé absente, inconnue ou révoquée.
402quota_exceeded, site_limit, plan_required, module_not_purchasedQuota du mois atteint, site hors de votre offre, ou test non inclus.
403verification_requiredTest approfondi demandé sur un site dont la propriété n'est pas vérifiée.
404scan_not_foundAnalyse inconnue pour cette clé.
409scan_not_finished, site_archivedRapport demandé avant la fin de l'analyse, ou site remplacé dans votre espace.
429too_soon, too_many_running, domain_rate_limited, rate_limitedTrop d'appels ou d'analyses rapprochées : réessayez après le délai indiqué (retryAfterMs).
Exemples

Prêts à copier.

JavaScript (Node.js 18 ou plus)

scan.mjs
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);

GitHub Actions : un diagnostic chaque semaine

Ajoutez votre clé dans les secrets du dépôt sous le nom QUETZAL_API_KEY.

.github/workflows/securite.yml
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" ]
Questions fréquentes

Vos questions sur l'API.

L'API est-elle payante ?

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.

Puis-je analyser n'importe quel site ?

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é.

Combien de temps dure une analyse ?

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.

Que faire si ma clé a fuité ?

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.

Votre site est-il protégé ?

Gratuit, sans inscription et sans risque pour votre site. Résultat en une minute environ.