API pro QR kódy: QR kód nebo platební QR kód SEPA na jedno volání

Jedno HTTP volání a obdržíš obrázek QR kódu připravený k nalepení na plakát, fakturu nebo web. Text, odkaz, Wi-Fi nebo rovnou SEPA převod, který tvůj klient už jen naskenuje svou bankovní aplikací.

Žádná knihovna k instalaci, žádný účet u služby, která ti doprostřed kódu nalepí své logo. API přímo vrací soubor PNG nebo SVG a tím to končí. Takhle vypadá výsledek:

Zdarma nebo PRO: co dostaneš

Obě varianty dělají přesně totéž, se stejnými formáty a stejnými velikostmi. Není tu žádný vodoznak ani QR kód, kterému vyprší platnost. Jediný rozdíl je v počtu kódů za den. Zelený pruh ukazuje, kolik jich můžeš za jeden den vygenerovat.

Počítadlo se resetuje o půlnoci UTC, tedy ve Francii v 1 nebo 2 ráno podle ročního období. A dobrá zpráva pro nešiky: špatně vytvořený požadavek, například falešný IBAN nebo prázdný text, se odmítne ještě před kontrolou tvého klíče, takže nic nestojí.

Získání klíče

Zabere to minutu: vytvoř si účet, potvrď svou e-mailovou adresu a pak zkopíruj klíč zobrazený ve svém účtu. Je to stejný klíč jako pro mé ostatní služby. Posílá se v hlavičce Authorization každého požadavku místo VotreCleApi v následujících příkladech.

Používal jsi starou verzi s userId v URL nebo v JSONu? Tento parametr už se nečte, klíč teď prochází pouze v hlavičce. Důsledek: adresu už nejde jen tak vložit do adresního řádku prohlížeče. Pro testování myší je tu Swagger, vrátím se k němu níže.

Klasický QR kód: text, odkaz, Wi-Fi

Jde o volání NormalQr, jednoduchý GET. Zadáte text, obdržíte obrázek:

curl -H "Authorization: Bearer VotreCleApi" "https://qr.digital3d.com/api/QrCreator/NormalQr?text=https%3A%2F%2Fdigital3d.com&format=Png&size=6" -o qr.png

To, co je na tom zábavné, je, že text nemusí být odkaz. Telefon umí interpretovat několik formátů. Nejp praktičtější doma: QR kód Wi-Fi, který vytiskneš a nalepíš na lednici pro hosty. Text, který se má zakódovat, vypadá takto:

WIFI:T:WPA;S:NomDuReseau;P:MotDePasse;;

Stejný princip s mailto:quelquun@example.com pro otevření e-mailu nebo s vCard (formát kontaktních karet), aby sken přidal tvoje kontaktní údaje do adresáře.

Platební QR SEPA

Tenhle mám moc rád. Na fakturu dáš QR, tvůj klient ho naskenuje svou bankovní aplikací a převod je předvyplněný: příjemce, IBAN, částka, zpráva. Už nikdo nepřepisuje IBAN špatně. Jde o volání PaymentQr, POST s tělem JSON:

curl -X POST "https://qr.digital3d.com/api/QrCreator/PaymentQr" \
  -H "Authorization: Bearer VotreCleApi" \
  -H "Content-Type: application/json" \
  -o paiement.svg \
  -d '{
    "beneficiaryName": "ACME SRL",
    "iban": "BE68539007547034",
    "bic": "GKCCBEBB",
    "amount": 12.34,
    "remittance": "Facture 2026-001",
    "outputFormat": "Svg",
    "size": 8
  }'

Jedna výhrada, protože nějaká být musí: tento QR kód se řídí evropskou normou, ale ne všechny bankovní aplikace ho umějí načíst. V Belgii, Nizozemsku nebo Německu je to velmi rozšířené. Jinde si to nejdřív vyzkoušejte u vlastní banky, než jich vytisknete pět set.

Pod kapotou

Pro ty, které zajímá, co se děje uvnitř, tu jsou technická rozhodnutí.

Platební QR kód dodržuje normu EPC069-12 Evropské rady pro platby. Konkrétně jde o krátký text o několika řádcích (verze, příjemce, IBAN, částka, zpráva) seřazených v předepsaném pořadí, který se pak zakóduje jako jakýkoli jiný QR kód. API tento text vytvoří za vás a předem zkontroluje pole.

Všechny kódy se generují s úrovní opravy chyb M. QR kód obsahuje data duplicitně, aby zůstal čitelný i po poškození: u úrovně M může být přibližně 15 % plochy zašpiněných, přehnutých nebo zakrytých, aniž by to bránilo načtení. Je to ostatně úroveň, kterou norma pro platební QR kódy vyžaduje.

Co se formátu týče, vezměte PNG pro e-mail nebo webovou stránku, s dostatečně velkou hodnotou size, abyste ho nemuseli roztahovat. Na všechno, co míří do tiskárny, vezměte SVG: je to vektorová kresba, která se zvětší až na velikost reklamního banneru, aniž by se rozmazala. Odpověď má správný typ, image/png nebo image/svg+xml, a její tělo je přímo soubor, ne JSON, který je potřeba dekódovat.

Poslední detail: jsou to statické QR kódy. Když někdo kód naskenuje, nic neprochází přes můj server, veškerý obsah je v obrázku. Bude tedy fungovat ještě za deset let, ať už moje služba bude existovat, nebo ne.

Sledování vašeho kvóty

Jakmile je klíč přijatý, každá odpověď obsahuje tři hlavičky: X-RateLimit-Limit (váš denní limit), X-RateLimit-Remaining (kolik vám zbývá) a X-RateLimit-Reset (čas vynulování, v unixových sekundách).

Co se týče chyb, je třeba počítat se čtyřmi:

• 400 : požadavek je neplatný (prázdný text, velikost mimo povolený rozsah, chybný IBAN). Zdarma, nic se neodečítá.
• 401 : klíč chybí, je špatně napsaný nebo účet ještě nebyl ověřený. Také zdarma.
• 429 : denní kvóta je vyčerpaná. Hlavička Retry-After udává počet sekund, které je třeba počkat do vynulování.
• 503 : služba nemohla ověřit klíč. Zkuste to znovu o 30 sekund později.

Testování bez napsání jediného řádku kódu

Všechno je zdokumentované ve Swaggeru API (stránka, která uvádí volání a umožňuje je spustit z prohlížeče). Klikněte na „Authorize“, vložte svůj klíč a pak vyzkoušejte každé volání pomocí tlačítka „Try it out“. Obrázek se zobrazí na stránce. Pozor ale: tyto pokusy se počítají do vašeho limitu stejně jako jakýkoli požadavek.

Proč předplatné?

Protože to všechno běží na serveru, který platím. Bezplatná verze tu zůstává pro testování a lehké používání a deset kódů denně bohatě pokryje potřeby jednotlivce. Pokud API napojíte na fakturační software nebo web, předplatné PRO za 12 € měsíčně zvýší limit na 1000 kódů denně, zahrnuje kompletní televizní program a všechny moje programy a díky němu služba přežívá. Komerční používání bez předplatného není povoleno.