Kvíz ke každému článku

Co umíme

• Kvíz k článku

  Z textu článku na zadané adrese. Otázky vycházejí jen z něj — nic, co v článku není, se v kvízu neobjeví.

• Kvíz k tématu

  Když článek nemáte, stačí téma. Kvíz pak stojí na obecně ověřitelných faktech.

• Kvíz dne

  Bez jediného volání API: z vašeho RSS vybereme každé ráno nejnovější vhodný článek a kvíz připravíme sami.

• Embed i JSON

  Hotový kvíz dostanete jako data, nebo ho vložíte jako iframe, který odpovědi kontroluje na našem serveru.

Jak to funguje

1. Od nás dostanete API klíč. Posílá se v hlavičce Authorization: Bearer <klíč>.
2. POST na /api/klient/kviz s adresou článku nebo tématem. Odpověď 202 nese id kvízu.
3. Kvíz se generuje na pozadí, obvykle do dvou minut. Stav zjistíte přes GET /api/klient/kviz/<id>, nebo počkáte na webhook.
4. Hotový kvíz zobrazíte z JSONu po svém, nebo vložíte embed, jehož adresu odpověď obsahuje.

Požadavek

Přesně jedno z polí url a tema. Volitelně pocet (5–15, výchozí 7), obtiznost (lehka, stredni, tezka) a webhook — adresa, která přebije tu nastavenou u vás.

curl -X POST https://quizdesk.tomasgrasl.cz/api/klient/kviz \
  -H "Authorization: Bearer $QUIZDESK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://<váš-web>/clanek/123", "pocet": 7}'

# 202 Accepted
{ "id": "9b1c…", "stav": "ceka", "odkaz": "/api/klient/kviz/9b1c…" }

Odpověď

Hotový kvíz. Pole spravna je index správné možnosti (0–3) — v JSONu ho máte, embed ho čtenáři pošle až po odpovědi.

curl https://quizdesk.tomasgrasl.cz/api/klient/kviz/9b1c… \
  -H "Authorization: Bearer $QUIZDESK_KEY"

{
  "id": "9b1c…",
  "stav": "hotovo",
  "zadani": {
    "url": "https://<váš-web>/clanek/123",
    "pocet": 7
  },
  "kviz": {
    "nazev": "Kvíz k článku",
    "otazky": [
      {
        "otazka": "Kolik minut denně doporučuje článek chodit?",
        "moznosti": [
          "10",
          "20",
          "30",
          "60"
        ],
        "spravna": 2,
        "vysvetleni": "Článek doporučuje třicet minut svižné chůze denně."
      }
    ],
    "zdroj": "https://<váš-web>/clanek/123",
    "embedUrl": "https://quizdesk.tomasgrasl.cz/embed/kviz/9b1c…"
  }
}

Stavy kvízu

ceka

Přijatý, čeká ve frontě.

generuje

Právě se píše a kontroluje.

ke_schvaleni

Hotový, čeká na schválení u nás (jen pokud je tak domluveno).

hotovo

Hotový — pole kviz je vyplněné.

selhalo

Nepovedlo se. Pole duvod říká proč — třeba že článek neobsahuje dost textu. Takový pokus se neúčtuje.

zamitnuto

Hotový kvíz jsme při kontrole zamítli.

Limity

• Počet kvízů za den, počet rozpracovaných najednou a měsíční rozpočet má každý klient svůj, podle domluvy.
• Po vyčerpání odpovídáme 429 s hlavičkou Retry-After (v sekundách).
• Stejná adresa článku ve stejný den vrátí totéž id — dvojí odeslání nic nestojí.
• Nejvýš 120 požadavků za minutu na klíč.

Webhook

Když kvíz doběhne (hotovo i selhalo), pošleme POST se stejným JSONem, jaký vrací GET. Hlavička X-Podpis nese sha256=<HMAC-SHA256 těla> podepsaný tajemstvím, které od nás máte. Při neúspěchu to zkusíme znovu po minutě, po deseti minutách a po hodině.

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

const expected = "sha256=" +
  createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");
const ok = timingSafeEqual(
  Buffer.from(expected),
  Buffer.from(request.headers["x-podpis"] ?? "")
);

Embed

Vložte iframe kamkoli do článku. Výšku si embed hlásí sám zprávou postMessage, pokud chcete, aby rámec rostl s obsahem.

<iframe src="https://quizdesk.tomasgrasl.cz/embed/kviz/9b1c…"
  title="Kvíz" loading="lazy"
  style="width:100%;border:0;min-height:520px"></iframe>

window.addEventListener("message", (event) => {
  if (event.origin !== "https://quizdesk.tomasgrasl.cz") return;
  if (event.data?.type !== "quizdesk:height") return;
  document.querySelector("iframe[src^='https://quizdesk.tomasgrasl.cz']")
    .style.height = event.data.height + "px";
});

• Žádné cookies, žádné měření, žádná reklama, žádný souhlas k odkliknutí.
• Správné odpovědi jsou jen na našem serveru — čtenář je uvidí, až odpoví.
• Vykreslí se jen na vašich doménách; jinde ho prohlížeč odmítne.

Kvíz dne

Pošlete nám adresu RSS a případně rubriky. Každé ráno v domluvený čas vybereme nejnovější článek, který ještě kvíz nemá, a připravíme ho stejnou cestou jako kvíz na požádání. Embed s pevnou adresou vložíte jednou a každý den ukazuje dnešní kvíz.

<iframe src="https://quizdesk.tomasgrasl.cz/embed/kviz/dnes?klient=<zkratka>"
  title="Kvíz dne" loading="lazy"
  style="width:100%;border:0;min-height:520px"></iframe>

curl https://quizdesk.tomasgrasl.cz/api/klient/kviz/dnes -H "Authorization: Bearer $QUIZDESK_KEY"

Chyby

401

Chybí klíč, nebo je neznámý či zneplatněný.

403

Kvíz patří jinému klientovi.

404

Takový kvíz neexistuje.

422

Neplatný požadavek — pole chyba říká, co je špatně.

429

Vyčerpaný limit; Retry-After říká, kdy znovu.

Spolupráce

Klíč, limity a podmínky domluvíte s provozovatelem. Napište nám: support@tomasgrasl.cz

Tomáš Grasl