QR-code aanmaken via REST-API: handleiding met curl-voorbeelden

Stap 1: sleutel aanmaken

In het dashboard maak je onder Account, in het onderdeel „Toegang voor CLI, scripts en agents”, een sleutel aan. Voor de eerste proeven is „alleen lezen” genoeg. Kies een korte looptijd, bijvoorbeeld 30 dagen. De sleutel begint met sqr_live_ en wordt maar één keer getoond. Zet hem in een omgevingsvariabele, zodat hij niet in je shellgeschiedenis terechtkomt, bijvoorbeeld via je wachtwoordmanager.

Stap 2: het eerste verzoek

De API staat op https://sameqr.com/api/v1. De sleutel hoort in de Authorization-header, nooit in het adres:

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/konto
curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr

Het eerste verzoek toont je account, je abonnement en je grenzen, het tweede je QR-codes met code, naam, bestemming, labels, aantal scans en de stand _rev.

Stap 3: een QR-code aanmaken

Om aan te maken heb je een tweede sleutel nodig met „lezen + schrijven”. Met een leessleutel antwoordt de API op verzoeken die iets wijzigen met 403 en de code NUR_LESEN. Een nieuwe QR-code heeft minimaal een naam en een bestemming nodig:

curl -X POST https://sameqr.com/api/v1/qr \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Speisekarte","targetUrl":"https://example.com/karte"}'

Scan de nieuwe QR-code met je telefoon voordat je verdergaat. Om aan te maken moet je e-mailadres bevestigd zijn, en de QR-code telt mee voor het quotum van je abonnement.

Stap 4: de bestemming wijzigen

Wijzigingen van de bestemming zijn extra beschermd. Je hebt een sleutel „volledig” nodig en stuurt de actuele stand van de QR-code mee als kopregel X-Confirm. De stand krijg je van het leesverzoek:

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr/<id>

curl -X PATCH https://sameqr.com/api/v1/qr/<id> \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -H "X-Confirm: <stand>" \
  -d '{"targetUrl":"https://example.com/karte-neu"}'

Alleen de meegestuurde velden worden gewijzigd. Wijkt de stand af, omdat iemand de QR-code intussen heeft aangepast, dan wordt er niets overschreven. Via de API zijn hoogstens 10 wijzigingen van de bestemming per uur en 30 per dag mogelijk, in het dashboard bestaat deze grens niet. In het gratis abonnement is het aantal wijzigingen van de bestemming per QR-code beperkt.

Stap 5: fouten en grenzen begrijpen

Fouten komen altijd in dezelfde vorm terug: een object error met status, code en message. Werk ze in je programma uit in plaats van gewoon door te gaan.

• 401: sleutel ontbreekt, is onjuist, verlopen of ingetrokken.
• 403: de sleutel mist het vereiste niveau, of je abonnement staat de actie niet toe.
• 400 met BESTAETIGUNG_FEHLT: voor het wijzigen van de bestemming, offline zetten of verwijderen ontbreekt X-Confirm met de actuele stand.
• 409: iemand heeft de QR-code tussendoor gewijzigd.
• 429: te veel verzoeken. Per sleutel kunnen er 120 per minuut, per uur 60 in het gratis abonnement, 300 in Start, 1.000 in Pro en 5.000 in Agentur.

Alle verzoeken staan beschreven in /api/v1/openapi.json, de handleiding staat op sameqr.com/entwickler.

Conclusie: waarom Same-QR

De REST-API van Same-QR is overzichtelijk, goed gedocumenteerd en zit in elk abonnement. Ze kan alles wat het dashboard kan, beschermt gedrukte QR-codes met bevestiging en grenzen tegen onbedoelde wijzigingen van de bestemming, kent sleutels in drie niveaus en antwoordt met fouten die je begrijpt.

Begin meteen: registreer je gratis op sameqr.com, 20 dynamische QR-codes zijn blijvend gratis. API, CLI en MCP-server zijn er in elk abonnement, de documentatie staat op sameqr.com/entwickler.

Veelgestelde vragen