Abundera QR Pro API

Úvod

Abundera QR Pro API umožňuje programově vytvárat, upravovat a analyzovat dynamické QR kódy, vše, co vývojář chce automatizovat z dashboardu. Správa týmu, fakturace a správa účtu zůstávají v rozhraní dashboardu; toto API je určeno pro operace s kódy na vývojářské úrovni.

Základní URL: https://pro.qr.abundera.ai/api

Formát požadavku: JSON (Content-Type: application/json) on POST / PATCH / DELETE.

Formát odpovědi: JSON (application/json; charset=utf-8).

Dostupnost: Přístup k API je funkcí plánu Business a vyšších. Plán Solo může používat dashboard, ale ne API.

Ověřování

Každý požadavek nese API klíč jako bearer token:

Authorization: Bearer abnd_qrpro_...

Klíče vytvářejte a odvolávejte na /account/keys (plán Business, Team nebo Agency). Surový token abnd_qrpro_... se zobrazí přesně jednou při vytvoření, uložte jej okamžitě. Ukládáme pouze jeho hash SHA-256; ztracený klíč nelze obnovit.

Neověřené požadavky vrátí 401 { "error": "not_signed_in" }. Neplatné nebo odvolané klíče vrátí 401 { "error": "invalid_api_key" }.

API klíče jsou vázány na uživatele, který je vytvořil. Pokud je tento uživatel členem týmu, níže uvedené endpointy automaticky pracují s kódy týmu (kontext aktuálního týmu je uložen v uživatelském účtu a spravován přes dashboard).

Limity rychlosti

Vynucuje se na API klíč. Každá odpověď obsahuje X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unixové sekundy, kdy se okno obnoví).

Požadavky překračující limit vrátí 429 { "error": "rate_limited", "window": "day", "retry_at": 1234567890 } s hlavičkou Retry-After v sekundách.

Skenování není omezeno, přesměrovací cesta (aqr.net/{shortcode}) nemá ověřování ani rozpočet na skenování. Každý plán má explicitní měsíční limit skenování (100 tis. / 1 mil. / 10 mil. / 30 mil.). Překročení limitu přesměrování stále funguje; pošleme vám e-mail, abyste mohli rozhodnout, zda upgradovat nebo přečkat jednorázový skok. Plánujete přes ~10 mil. denních skenů? Napište nám a domluvíme kapacitu.

Chyby

Každá chybová odpověď je JSON se strojově čitelným kódem error a případně dalším kontextem:

{ "error": "plan_limit", "plan": "business", "limit": 500, "current": 500 }

Kódy

Dynamické QR kódy: 7místný Base58 shortcode přesměrovávající přes aqr.net/{shortcode}. Ke každému kódu je záložní statický QR ke stažení z dashboardu, pokud přestanete platit, statická verze funguje dál bez našeho přesměrování.

GET /api/codes

Zobrazí všechny kódy ve vašem aktuálním rozsahu (osobním nebo týmovém). Vrátí pole se souhrnem skenů za 30 dní pro každý kód.

$ curl -H "Authorization: Bearer abnd_qrpro_..." \
       https://pro.qr.abundera.ai/api/codes

{
  "codes": [
    { "id": "uuid", "shortcode": "aBc123x",
      "url": "https://example.com/landing",
      "label": "Q2 campaign", "tags": "q2,print",
      "status": "active", "scans_30d": 1245,
      "created_at": 1713288000, "updated_at": 1713370000 }
  ],
  "plan": "business",
  "plan_limit": 500,
  "scope": { "type": "user" }
}

POST /api/codes

Vytvoří nový dynamický kód. Před vložením se zkontroluje limit aktivních a pozastavených kódů vašeho plánu. Minimální tělo požadavku:

{ "url": "https://example.com/landing" }

Plné přizpůsobení (vše volitelné):

{ "url":          "https://example.com/landing",
  "label":        "Spring campaign",
  "tags":         "q2,print",
  "qr_type":      "url",
  "style_json":   "{...}",
  "logo_key":     "instagram",
  "frame_style":  "scan-me",
  "frame_text":   "SCAN ME" }

Vrátí 201 + vytvořený záznam včetně vygenerovaného shortcode a short_url pro tisk.

GET /api/codes/{id}

Načte jeden kód. 404, pokud není ve vašem rozsahu.

PATCH /api/codes/{id}

Aktualizuje libovolné měnitelné pole. Nejčastější použití: změna cílové URL již vytištěného kódu.

$ curl -X PATCH \
       -H "Authorization: Bearer abnd_qrpro_..." \
       -H "Content-Type: application/json" \
       -d '{"url":"https://example.com/new-landing"}' \
       https://pro.qr.abundera.ai/api/codes/uuid

Změny se projeví v přesměrování během sekund. Platné hodnoty status pro PATCH: "active", "paused". Pro smazání použijte DELETE.

DELETE /api/codes/{id}

Soft-delete. Přechod do status=grace s grace_until = now + 90 dní. Přesměrování funguje dál po celou dobu lhůty, to je konkrétní naplnění slibu o ceně bez závazků. Po 90 dnech se kód stane expired a přesměrování vrátí 410 Gone.

POST /api/codes/import

Hromadné vytvoření z pole požadavků (používá ho i flow "Uložit do Pro" na qr.abundera.ai). Přijímá jeden kód nebo pole kódů. Limit plánu se kontroluje jednou před dávkou.

Analytika

GET /api/codes/{id}/analytics

Parametry dotazu:

• range=7d|30d|90d|1y|3y, omezeno retencí vašeho plánu (Solo 1y, Business 2y, Team/Agency 3y).
• granularity=day|hour, hodinové rozlišení jen pro Team a Agency; max. 7denní okno pro hodinová data.

{
  "range": "30d", "days": 30, "granularity": "day",
  "total": 4321,
  "timeseries": [
    { "bucket": "2026-04-01", "scans": 142 },
    { "bucket": "2026-04-02", "scans": 178 },
    ...
  ],
  "by_country": [
    { "key": "US", "total": 3012 },
    { "key": "CA", "total": 402 },
    { "key": "Other", "total": 108 }
  ],
  "by_device":  [
    { "key": "mobile",  "total": 3850 },
    { "key": "tablet",  "total": 312 },
    { "key": "desktop", "total": 159 }
  ]
}

Countries with fewer than 5 scans in the window are folded into "Other" for privacy (see Model ochrany soukromí).

API klíče

Klíče vytvářejte a odvolávejte na stránce /account/keys v dashboardu. Programatická správa přes API je pouze pro čtení, klíče lze zobrazit a odvolat, ale vytvoření nového klíče vyžaduje dashboard (problém slepice a vejce: k vytvoření klíče byste potřebovali klíč).

GET /api/keys

Zobrazí vaše API klíče. Nikdy nevrátí surový token, pouze metadata.

{
  "keys": [
    { "id": "uuid", "label": "Production server",
      "created_at": 1713288000, "last_used_at": 1713370000 }
  ],
  "allowed": true,
  "plan": "business"
}

DELETE /api/keys/{id}

Odvolá klíč. Klíč okamžitě přestane fungovat; každý požadavek s tímto klíčem vrátí 401 invalid_api_key.

Export dat

GET /api/user/export

Stáhne ZIP s celou datovou sadou, codes.csv (všechny kódy včetně lhůty a expirovaných), scans.csv (agregovaný denní souhrn) a README.txt vysvětlující formát. Archiv je vydán jako application/zip; uložte jej do souboru:

$ curl -H "Authorization: Bearer abnd_qrpro_..." \
       -o abundera-qr-export.zip \
       https://pro.qr.abundera.ai/api/user/export

Znovu importujte kdekoli. Toto je záruka přenosného formátu, pokud vlastníte svá data, závislost na dodavateli není možná.

Model ochrany soukromí

Agregát skenování je celý příběh ochrany soukromí. Co ukládáme za každý sken na přesměrovací cestě:

• code_id, který z vašich kódů byl skenován
• day_bucket, UTC datum (YYYY-MM-DD). V agregátu vraceném vám není sub-denní přesnost.
• country, ISO-3166-1 alpha-2 z Cloudflare hlavičky CF-IPCountry. Žádné město, žádný region, žádné geo-IP vyhledávání.
• device_type, mobile / tablet / desktop / unknown, klasifikováno krátkým User-Agent regexem. Surový UA řetězec je při klasifikaci zahozen.
• scan_count, agregovaný čítač, aktualizovaný při každém hitu.

Co neukládáme: IP adresy (hashované ani jinak), surové User-Agent řetězce, geo na úrovni města, sub-denní časová razítka, referer, cookies, retargetingové pixely ani žádný individuálně identifikující vektor. Práh šumu 5 potlačuje re-identifikaci z malých agregátů.

Plány Team a Agency navíc zapisují paralelní hodinový agregát s hour_bucket (YYYY-MM-DD-HH UTC). Stejný model ochrany soukromí, žádná časová razítka přesnější než hodina, stejný práh šumu, stejná absence dat o individuálních skenerech.

Přečtěte si celý příběh: /manifesto/ a /no-lock-in/ na webu volného nástroje.