API voor QR codes: een QR code of een SEPA betaal QR in één oproep

Een HTTP-aanroep, en je krijgt de afbeelding van een QR-code die klaar is om op een affiche, een factuur of een website te plakken. Tekst, link, wifi, of zelfs een SEPA-overschrijving die je klant alleen nog maar met zijn bankapp hoeft te scannen.

Geen bibliotheek om te installeren, geen account bij een dienst die zijn logo midden in de code plakt. De API stuurt rechtstreeks een PNG- of SVG-bestand terug, en dat is alles wat ze doet. Zo ziet het resultaat eruit:

Gratis of PRO: wat je krijgt

De twee formules doen exact hetzelfde, met dezelfde formaten en dezelfde groottes. Er is geen watermerk en geen QR-code die verloopt. Het enige verschil is het aantal codes per dag. De groene balk toont wat je op één dag kunt genereren.

De teller springt om middernacht UTC terug op nul, dus om 1 of 2 uur 's nachts in Frankrijk, afhankelijk van het seizoen. En goed nieuws voor klunzen: een slecht opgemaakte aanvraag, een foute IBAN of lege tekst wordt geweigerd nog vóór er zelfs maar naar je sleutel wordt gekeken, dus die kost niets.

Je sleutel verkrijgen

Het duurt een minuut: maak een account aan, bevestig je e-mailadres en kopieer daarna de sleutel die in je account wordt weergegeven. Het is dezelfde sleutel als voor mijn andere diensten. Ze wordt meegestuurd in de header Authorization van elke aanvraag, in plaats van VotreCleApi in de voorbeelden die volgen.

Gebruikte je de oude versie met userId in de URL of in de JSON? Deze parameter wordt niet meer gelezen, de sleutel gaat nu uitsluitend via de header. Gevolg: je kunt het adres niet meer zomaar in de adresbalk van de browser plakken. Om met de muis te testen is er Swagger, daar kom ik verderop op terug.

De klassieke QR-code: tekst, link, wifi

Het is de aanroep NormalQr, een eenvoudige GET. Je geeft de tekst op, je krijgt de afbeelding:

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

Waar het leuk wordt, is dat de tekst geen link hoeft te zijn. Een telefoon kan verschillende formaten interpreteren. Het handigste thuis: de wifi-QR-code, om af te drukken en op de koelkast te plakken voor gasten. De te coderen tekst ziet er zo uit:

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

Hetzelfde principe met mailto:quelquun@example.com om een e-mail te openen, of met een vCard (het formaat van contactkaarten) zodat een scan je contactgegevens aan het adresboek toevoegt.

De SEPA-betaal-QR-code

Deze vind ik erg leuk. Je zet een QR-code op je factuur, je klant scant hem met zijn bankapp, en de overschrijving is vooraf ingevuld: begunstigde, IBAN, bedrag, mededeling. Niemand hoeft nog een IBAN verkeerd over te typen. Dit is de aanroep PaymentQr, een POST met een JSON-body:

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
  }'

Een kanttekening, want die moet er zijn: deze QR volgt een Europese norm, maar niet alle bankapps kunnen hem lezen. In België, Nederland of Duitsland is hij heel gebruikelijk. Elders probeer je het best eerst met je eigen bank voor je er vijfhonderd afdrukt.

Onder de motorkap

Voor wie graag weet wat er achter de schermen gebeurt, dit zijn de technische keuzes.

De betaal-QR voldoet aan de norm EPC069-12 van de Europese Betalingsraad. Concreet is het een korte tekst van enkele regels (versie, begunstigde, IBAN, bedrag, mededeling) die in een opgelegde volgorde staan, en daarna zoals elke QR gecodeerd wordt. De API bouwt die tekst voor je op en controleert vooraf de velden.

Alle codes worden gegenereerd met foutcorrectieniveau M. Een QR bevat gegevens dubbel om leesbaar te blijven, zelfs als hij beschadigd is: op niveau M mag ongeveer 15% van het oppervlak bevlekt, gekreukt of afgedekt zijn zonder het lezen te hinderen. Dat is trouwens het niveau dat de norm oplegt voor betaal-QR's.

Wat het formaat betreft, neem je PNG voor een e-mail of webpagina, met een waarde voor size die groot genoeg is om hem niet te moeten uitrekken. Voor alles wat naar de drukker gaat, neem je SVG: dat is vectoriële tekenkunst, die je kunt vergroten tot het formaat van een spandoek zonder wazig te worden. Het antwoord heeft het juiste type, image/png of image/svg+xml, en de body ervan is rechtstreeks het bestand, geen JSON die je nog moet decoderen.

Laatste detail: dit zijn statische QR's. Wanneer iemand de code scant, gaat er niets via mijn server, alle inhoud zit in de afbeelding. Hij werkt dus over tien jaar nog, of mijn dienst nu bestaat of niet.

Je quotum volgen

Zodra de sleutel aanvaard is, bevat elk antwoord drie headers: X-RateLimit-Limit (je limiet van vandaag), X-RateLimit-Remaining (wat je nog over hebt) en X-RateLimit-Reset (het tijdstip waarop de teller opnieuw op nul wordt gezet, in Unix-seconden).

Wat fouten betreft, zijn er vier waarmee je rekening moet houden:

• 400 : het verzoek is ongeldig (lege tekst, grootte buiten de grenzen, foute IBAN). Gratis, er wordt niets afgetrokken.
• 401 : de sleutel ontbreekt, is verkeerd geschreven, of de account is nog niet gevalideerd. Ook gratis.
• 429 : het quotum van vandaag is opgebruikt. De header Retry-After geeft het aantal seconden dat je moet wachten voor de teller opnieuw op nul wordt gezet.
• 503 : de service kon de sleutel niet verifiëren. Je probeert het 30 seconden later opnieuw.

Testen zonder één regel code te schrijven

Alles staat gedocumenteerd in de Swagger van de API (een pagina die de aanroepen opsomt en waarmee je ze vanuit de browser kunt uitvoeren). Klik op “Authorize”, plak je sleutel en probeer elke aanroep uit met de knop “Try it out”. De afbeelding verschijnt op de pagina. Let wel: deze tests tellen mee voor je quota, net als elke andere request.

Waarom een abonnement?

Omdat dit allemaal draait op een server die ik betaal. De gratis versie blijft beschikbaar om te testen en voor licht gebruik, en tien codes per dag dekken ruimschoots de behoeften van een particulier. Als je de API koppelt aan facturatiesoftware of aan een site, verhoogt het PRO-abonnement van €12 per maand de limiet naar 1000 codes per dag, bevat het de volledige TV-gids en al mijn software, en dat is wat de dienst in leven houdt. Commercieel gebruik zonder abonnement is niet toegestaan.