QR-code-API: QR-codes automatisch aanmaken, wijzigen en analyseren

Waar een QR-code-API voor dient

Een QR-code-API is een programmeerinterface: in plaats van in de browser te klikken, stuurt je programma verzoeken naar de QR-codedienst en krijgt het antwoorden terug. Zo ontstaan QR-codes direct vanuit een webwinkel, een voorraadbeheersysteem, een script of een spreadsheet.

Dat loont zodra werk zich herhaalt: honderd QR-codes voor tafels of producten, maandelijkse scanrapporten, het omzetten van veel bestemmingen na een relaunch. En het werkt alleen met dynamische QR-codes. Een dynamische QR-code van Same-QR bevat een kort, gelijkblijvend adres, de bestemming erachter staat bij ons en is op elk moment te wijzigen zonder opnieuw te printen.

Wat de Same-QR-API dekt

De REST-API staat onder https://sameqr.com/api/v1. Ze roept dezelfde functies aan als het dashboard, met dezelfde abonnementsgrenzen en controles:

• QR-codes weergeven, lezen, aanmaken, wijzigen en verwijderen.
• De statistieken van een QR-code: scans, aanmaakdatum, aantal bestemmingswijzigingen.
• Gastpagina's zoals menukaart, prijslijst, openingstijden, linkpagina, actie, wijnhuis, wijn-e-label en contact aanmaken, wijzigen, publiceren en offline halen.
• Een menukaart inlezen uit maximaal zeven foto's of een PDF.
• Labels en klantprojecten beheren en aanvragen uit contactformulieren lezen.

Een machineleesbare beschrijving van alle verzoeken staat onder /api/v1/openapi.json, de handleiding op sameqr.com/entwickler.

API-sleutels en rechten

De sleutel maak je aan in het dashboard onder Account, in het gedeelte "Toegang voor CLI, scripts en agents". Je kiest een van drie niveaus, "alleen lezen", "lezen + schrijven" (aanmaken, namen en teksten wijzigen) of "volledig" (daarnaast bestemmingen wijzigen, offline halen, verwijderen), en een looptijd van 30, 90, 180 of 365 dagen, zo nodig ook onbeperkt. De sleutel begint met sqr_live_ en wordt precies één keer getoond. Bij ons wordt alleen een controlesom opgeslagen.

Een sleutel die alleen mag lezen, krijgt bij elk verzoek dat iets wijzigt een duidelijke afwijzing. Voor rapporten en analyses is dat de juiste keuze. Alles wat verandert waar een gedrukte QR-code naartoe leidt, is extra beveiligd: bestemmingen wijzigen, offline halen en verwijderen vereisen het niveau "volledig" en een bevestiging met de eerder gelezen status, en via de API mogen daarvan maximaal 10 per uur en 30 per dag. In het dashboard bestaat deze grens niet. Elke sleutel is op elk moment in te trekken en is dan meteen ongeldig.

Een typisch verloop

De sleutel hoort in de Authorization-header, nooit in een adres. De sleutel sla je eerst op als omgevingsvariabele. Zo geef je je QR-codes weer en wijzig je de bestemming van een QR-code:

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

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

De waarde voor X-Confirm, de status, levert het leesverzoek op /api/v1/qr/<id>. Er wordt alleen gewijzigd wat je meestuurt. Wie zeker wil weten dat niemand tussendoor dezelfde QR-code heeft gewijzigd, stuurt de gelezen status mee als _rev. Is er iets veranderd, dan wordt er niets overschreven en bevat het antwoord de actuele status. Fouten komen altijd in hetzelfde formaat terug, met status, QR-code en een begrijpelijke melding.

Grenzen en goede werkwijze

Per sleutel zijn maximaal 120 verzoeken per minuut mogelijk. Daarbovenop komt een grens per uur die van het abonnement afhangt: 60 in het gratis abonnement, 300 in Start, 1.000 in Pro en 5.000 in Agentur. De grenzen vangen fouten op, bijvoorbeeld een script in een eindeloze lus, en hinderen eerlijk gebruik niet.

• Probeer eerst met een leessleutel, schrijf pas daarna.
• Test nieuwe processen op één enkele QR-code en scan hem met je telefoon.
• Vermijd verwijderen waar een nieuwe bestemming volstaat. Verwijderde QR-codes en hun korte links komen niet terug.
• Maak voor elk programma een eigen sleutel aan en bewaar hem in een wachtwoordbeheerder of een omgevingsvariabele.

Conclusie: waarom Same-QR

Same-QR geeft je de API niet als duur extraatje, maar in elk abonnement, met dezelfde functies als in het dashboard: QR-codes, statistieken, menukaarten, gastpagina's, labels en projecten. Daarbij komen duidelijke rechten per sleutel, eerlijke foutmeldingen en een nachtelijke controle van alle bestemmingen die je per e-mail laat weten als er een onbereikbaar is.

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