Ga naar inhoud
qr3.app Docs

QR-Codes API

Overzicht

De Codes-API is het hart van qr3.app. Hiermee kun je dynamische en statische QR-codes maken, bijwerken en verwijderen.

Basis-URL: https://qr3.app/v1/codes

Bindend REST-contract

Het volgende contract geldt voor alle clients:

  • POST /v1/codes accepteert uitsluitend de typen url, vcard, wifi, email, sms en location. Velden zijn plat: url; ten minste vcard_first_name of vcard_last_name; wifi_ssid; email_to; sms_phone; of beide location_lat en location_lng.
  • Alleen url-codes kunnen dynamisch zijn. Aanmaakverzoeken kunnen optioneel expires_at als ISO 8601-tijdstempel bevatten; ab_enabled, ab_target_url_b en ab_weight_a (A/B-bestemmingen) zijn toegestaan voor dynamische url-codes; redirect_after_expiry maakt geen deel uit van het aanmaakcontract.
  • GET /v1/codes ondersteunt alleen limit, cursor en status (live, paused, flagged, draft).
  • POST /v1/codes/batch accepteert url, vcard en wifi. De limiet is 10 voor Free, 500 voor Pro en 1.000 records voor Business/Agency/Enterprise per verzoek. URL-scans worden synchroon uitgevoerd voor maximaal 50 URL-items; boven 50 is skip_url_scan: true vereist.

QR-code maken

POST /v1/codes

Terminal window
curl -X POST https://qr3.app/v1/codes \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://example.com",
    "title": "Mein erster QR-Code",
    "tags": ["marketing", "q1"],
    "is_dynamic": true
  }'

Response (HTTP 201):

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "redirect_url": "https://qr3.app/r7f3Kx",
    "image_svg_url": "https://qr3.app/v1/codes/r7f3Kx/qr.svg",
    "image_png_url": "https://qr3.app/v1/codes/r7f3Kx/qr.png",
    "image_pdf_url": "https://qr3.app/v1/codes/r7f3Kx/qr.pdf",
    "image_eps_url": "https://qr3.app/v1/codes/r7f3Kx/qr.eps",
    "type": "url",
    "target_url": "https://example.com",
    "is_dynamic": true,
    "status": "live",
    "tags": ["marketing", "q1"],
    "total_scans": 0,
    "created_at": "2026-03-15T10:00:00.000Z"
  },
  "meta": { "request_id": "req_xyz123" }
}

QR-code-typen

TypeBeschrijvingVerplichte velden
urlWebsite-URL (dynamisch of statisch)url
vcardVisitekaartje (vCard 3.0)vcard_first_name of vcard_last_name
wifiWifi-configuratiewifi_ssid
emailE-mail (mailto:)email_to
smsSmssms_phone
locationLocatie (geo:)location_lat, location_lng

Batch-creatie

POST /v1/codes/batch

Terminal window
curl -X POST https://qr3.app/v1/codes/batch \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "url", "url": "https://produkt-1.example.com", "tags": ["batch"] },
      { "type": "url", "url": "https://produkt-2.example.com", "tags": ["batch"] },
      { "type": "wifi", "wifi_ssid": "GastWLAN", "wifi_password": "geheim123" }
    ],
    "skip_url_scan": false
  }'

Response (HTTP 201):

{
  "data": {
    "created": [
      { "id": "qr_...", "short_code": "abc123", "redirect_url": "https://qr3.app/abc123" },
      { "id": "qr_...", "short_code": "def456", "redirect_url": "https://qr3.app/def456" },
      { "id": "qr_...", "short_code": "ghi789", "status": "live" }
    ],
    "total": 3,
    "failed": 0
  }
}

QR-codelijst

GET /v1/codes

Terminal window
curl https://qr3.app/v1/codes?status=live&limit=20 \
  -H "Authorization: Bearer qr3_sk_..."

Query-parameters:

ParameterTypeStandaardBeschrijving
cursorstring—Cursor voor paginering
limitinteger20Resultaten per pagina (max. 100)
statusstring—Filter: live, paused, flagged, draft

QR-code ophalen

GET /v1/codes/:id

Terminal window
curl https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

QR-code bijwerken

PATCH /v1/codes/:id

Update contract: url may be changed only for an existing type: "url" code, and its value must use http:// or https://. Other code types must not receive url; invalid requests return 422.

Dynamische QR-codes maken het mogelijk om de bestemmings-URL op elk moment te wijzigen — zonder dat de QR-code opnieuw gedrukt hoeft te worden.

Terminal window
curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://neue-zielseite.example.com", "status": "live" }'

Bestemmingspagina & externe links

Voor dynamische url-codes kun je is_landing_page: true instellen (bij het maken of via PATCH). Een scan toont dan een door qr3 gehoste pagina met de openbare bestanden en externe links van de code, in plaats van door te sturen. Externe links worden doorgegeven als een links-array:

{
  "is_landing_page": true,
  "links": [
    { "label": "Datenblatt", "url": "https://example.com/datenblatt.pdf" },
    { "label": "Zertifikat", "url": "https://example.com/zertifikat.pdf" }
  ]
}
  • 0–20 links per code; label is 1–100 tekens; url moet http(s) zijn (≤ 2048 tekens).
  • Elke URL wordt gecontroleerd met Google Web Risk — een onveilige URL retourneert 422.
  • Als Web Risk bij het opslaan niet bereikbaar is, wordt de link toch geaccepteerd, maar gemarkeerd voor een nieuwe controle. Een dagelijkse taak controleert opgeslagen links opnieuw (en controleert als veilig geclassificeerde links regelmatig opnieuw) en pauzeert de code automatisch als een link later als onveilig wordt herkend.
  • "links": [] verwijdert alle links. Zie de handleiding voor bestemmingspagina’s.

QR-code verwijderen

DELETE /v1/codes/:id

Soft-delete — de QR-code wordt gearchiveerd, scangegevens blijven behouden.

Terminal window
curl -X DELETE https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

QR-afbeeldingen downloaden

Alle afbeeldingsformaten zijn openbaar toegankelijk — geen authenticatie vereist.

FormaatURLGebruik
SVG (vector)/v1/codes/:code/qr.svgWeb, schalen, digitaal
PNG (raster)/v1/codes/:code/qr.pngE-mail, presentaties
PDF (vector)/v1/codes/:code/qr.pdfStandaard: vierkant (alleen de code); ?format=a4 voor een printvel
EPS (vector)/v1/codes/:code/qr.epsProfessionele drukwerk-workflows (Adobe, drukkerijen)

Optioneel: ?size=N — modulegrootte in pixels (2–20, standaard: 4) voor SVG, PNG en EPS. De PDF gebruikt een vaste modulegrootte.

Alleen PDF: ?format=a4|square — paginaformaat (standaard: square — alleen code + quiet zone, geen A4-witruimte; a4 voor een printklaar A4-vel)

Terminal window
# SVG für Web
curl https://qr3.app/v1/codes/r7f3Kx/qr.svg


# PNG in hoher Auflösung
curl https://qr3.app/v1/codes/r7f3Kx/qr.png?size=10 -o qr-hires.png


# Kompaktes PDF (nur der Code, Standard)
curl https://qr3.app/v1/codes/r7f3Kx/qr.pdf -o qr.pdf


# Druckfertiges A4-Blatt
curl "https://qr3.app/v1/codes/r7f3Kx/qr.pdf?format=a4" -o qr-a4.pdf

Reacties

Reacties maken feedbackcycli tussen bureaus en klanten mogelijk.

GET /v1/codes/:id/comments

POST /v1/codes/:id/comments

PATCH /v1/codes/:id/comments/:commentId

DELETE /v1/codes/:id/comments/:commentId

Terminal window
# Kommentar hinzufügen
curl -X POST https://qr3.app/v1/codes/qr_a1b2c3d4/comments \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "body": "QR-Code bitte auf grünen Hintergrund abstimmen.", "author_name": "Max Müller" }'


# Offene Kommentare auflisten
curl "https://qr3.app/v1/codes/qr_a1b2c3d4/comments?resolved=false" \
  -H "Authorization: Bearer qr3_sk_..."


# Kommentar als erledigt markieren
curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4/comments/cmt_xyz \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "resolved": true }'