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

QR-code maken

`POST /v1/codes`

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

const code = await qr3.codes.create({
  type: 'url',
  url: 'https://example.com',
  title: 'Mein erster QR-Code',
  tags: ['marketing', 'q1'],
  is_dynamic: true,
});

qr3 create https://example.com --title "Mein QR-Code" --tags marketing,q1

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

Type	Beschrijving	Verplichte velden
`url`	Website-URL (dynamisch of statisch)	`url`
`vcard`	Visitekaartje (vCard 3.0)	`vcard_first_name` of `vcard_last_name`
`wifi`	Wifi-configuratie	`wifi_ssid`
`email`	E-mail (mailto:)	`email_to`
`sms`	Sms	`sms_phone`
`location`	Locatie (geo:)	`location_lat`, `location_lng`

A/B-testing

Test twee verschillende bestemmings-URL’s met gewogen doorsturing:

{
  "type": "url",
  "url": "https://version-a.example.com",
  "ab_enabled": true,
  "ab_target_url_b": "https://version-b.example.com",
  "ab_weight_a": 50
}

Vervaldatum (Expiry)

QR-codes kunnen automatisch vervallen:

{
  "type": "url",
  "url": "https://aktionsseite.example.com",
  "expires_at": "2026-12-31T23:59:59Z",
  "redirect_after_expiry": "https://archiv.example.com"
}

Na het vervallen wordt er ofwel doorgestuurd naar redirect_after_expiry of er wordt een 410-pagina getoond.

Batch-creatie

`POST /v1/codes/batch`

Maakt tot wel 1.000 QR-codes in een enkele aanvraag. Ideaal voor bulktoepassingen.

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`

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

Query-parameters:

Parameter	Type	Standaard	Beschrijving
`cursor`	string	—	Cursor voor paginering
`limit`	integer	20	Resultaten per pagina (max. 100)
`status`	string	—	Filter: `live`, `paused`, `flagged`, `draft`

QR-code ophalen

`GET /v1/codes/:id`

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

QR-code bijwerken

`PATCH /v1/codes/:id`

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.

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.

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.

Formaat	URL	Gebruik
SVG (vector)	`/v1/codes/:code/qr.svg`	Web, schalen, digitaal
PNG (raster)	`/v1/codes/:code/qr.png`	E-mail, presentaties
PDF (vector)	`/v1/codes/:code/qr.pdf`	Standaard: vierkant (alleen de code); `?format=a4` voor een printvel
EPS (vector)	`/v1/codes/:code/qr.eps`	Professionele 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)

# 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`

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