QR-koder API

Översikt

Codes-API är hjärtat i qr3.app. Med den skapar, uppdaterar och raderar du dynamiska och statiska QR-koder.

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

Bindande REST-avtal

Följande avtal gäller för alla klienter:

POST /v1/codes accepterar endast typerna url, vcard, wifi, email, sms och location. Fälten är platta: url; minst vcard_first_name eller vcard_last_name; wifi_ssid; email_to; sms_phone; eller både location_lat och location_lng.
Endast url-koder kan vara dynamiska. Skapandeförfrågningar kan valfritt inkludera expires_at som en ISO 8601-tidsstämpel; ab_enabled, ab_target_url_b och ab_weight_a (A/B-destinationer) accepteras för dynamiska url-koder; redirect_after_expiry ingår inte i skapandekontraktet.
GET /v1/codes stöder endast limit, cursor och status (live, paused, flagged, draft).
POST /v1/codes/batch accepterar url, vcard och wifi. Gränsen är 10 för Free, 500 för Pro och 1 000 poster för Business/Agency/Enterprise per begäran. URL-skanningar körs synkront för högst 50 URL-objekt; över 50 krävs skip_url_scan: true.

Skapa QR-kod

`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

Svar (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-kodtyper

Typ	Beskrivning	Obligatoriska fält
`url`	Webbplats-URL (dynamisk eller statisk)	`url`
`vcard`	Visitkort (vCard 3.0)	`vcard_first_name` eller `vcard_last_name`
`wifi`	Wi-Fi-konfiguration	`wifi_ssid`
`email`	E-post (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Plats (geo:)	`location_lat`, `location_lng`

Batch-skapande

`POST /v1/codes/batch`

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

Svar (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
  }
}

Lista QR-koder

`GET /v1/codes`

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

Query-parametrar:

Parameter	Typ	Standard	Beskrivning
`cursor`	string	—	Cursor för paginering
`limit`	integer	20	Resultat per sida (max 100)
`status`	string	—	Filter: `live`, `paused`, `flagged`, `draft`

Hämta QR-kod

`GET /v1/codes/:id`

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

Uppdatera QR-kod

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

Dynamiska QR-koder gör det möjligt att ändra mål-URL:en när som helst — utan att behöva trycka om QR-koden.

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

Landningssida & externa länkar

För dynamiska url-koder kan du ställa in is_landing_page: true (vid skapande eller via PATCH). En skanning visar då en sida som qr3 är värd för med kodens offentliga filer och externa länkar, istället för att omdirigera. Externa länkar skickas som en 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 länkar per kod; label är 1–100 tecken; url måste vara http(s) (≤ 2048 tecken).
Varje URL kontrolleras med Google Web Risk — en osäker URL returnerar 422.
Om Web Risk inte är tillgängligt vid sparning accepteras länken ändå, men markeras för ny kontroll. Ett dagligt jobb kontrollerar sparade länkar igen (och kontrollerar regelbundet länkar som klassificerats som säkra) och pausar koden automatiskt om en länk senare identifieras som osäker.
"links": [] raderar alla länkar. Se guiden för landningssidor.

Radera QR-kod

`DELETE /v1/codes/:id`

Soft-delete — QR-koden arkiveras, skanningsdata bevaras.

Ett andra DELETE på samma kod returnerar 404, även om båda begärandena anländer samtidigt. Webhooken qr.deleted skickas exakt en gång.

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

Ladda ner QR-bilder

Alla bildformat är offentligt tillgängliga — ingen autentisering krävs.

Format	URL	Användning
SVG (vektor)	`/v1/codes/:code/qr.svg`	Webb, skalning, digitalt
PNG (raster)	`/v1/codes/:code/qr.png`	E-post, presentationer
PDF (vektor)	`/v1/codes/:code/qr.pdf`	Standard: kvadratisk (endast koden); `?format=a4` för ett utskriftsblad
EPS (vektor)	`/v1/codes/:code/qr.eps`	Professionella tryckarbetsflöden (Adobe, tryckerier)

Valfritt: ?size=N — Modulstorlek i pixlar (2–20, standard: 4) för SVG, PNG och EPS. PDF:en använder en fast modulstorlek.

Endast PDF: ?format=a4|square — Sidformat (standard: square — endast kod + tyst zon (quiet zone), inget vitt utrymme för A4; a4 för ett utskriftsklart A4-ark)

# 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

Färger och felkorrigering

Alla fyra bildrutter accepterar tre valfria parametrar. De gäller för denna specifika hämtning och har företräde framför färger som är sparade på koden (nästa avsnitt).

Parameter	Värden	Standard	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` eller `RGB`	`000000`	ritas	ritas som en tryckfärg
`bg`	Hex som `fg` eller `transparent`	`ffffff`	ritas	ritas som en tryckfärg
`ecc`	`L`, `M`, `Q`, `H`	`M`	tillämpas	tillämpas

Skrivsätt: Skiftläge spelar ingen roll, # är valfritt. Om det skickas med kodas det som %23.
Ogiltiga värden räknas som inte angivna. ?fg=lila returnerar färgen som sparats på koden, eller vanlig svart om ingen färg har sparats, med 200 och aldrig ett fel. Endast ett uttryckligt ?fg=000000 tvingar fram svart.
bg=transparent returnerar en SVG, PDF eller EPS utan bakgrund och en PNG med äkta alfakanal. Underlaget som koden placeras på måste vara ljust och lämna en tyst zon på 4 moduler runt om. En mörk kod på mörkt underlag är inte läsbar.
PDF och EPS skriver svart och grått som gråskala (endast svart färgkanal) och alla andra färger som CMYK i hela procent, till exempel 1F4E79 som C74 M36 Y0 K53. Så snart en färg väljs ligger en täckande yta bakom koden och dess tysta zon, vit eller i färgen för bg, precis som i SVG-filen. Utan färger förblir båda filerna oförändrade. Konvertering och begränsningar: Färger vid tryck.
Läsbarhet: Bildrutten kontrollerar inte kontrasten. Rekommenderat är minst 4:1 och mörka moduler på ljus bakgrund. #1F4E79 på vitt har 8,7:1, #ff6600 på vitt endast 2,9:1.
ecc ändrar punktmönstret, inte innehållet. En tryckt kod fortsätter att fungera, men gamla och nya tryckfiler får inte blandas. Q eller H gör koden mer robust, till exempel på wellpapp. En logotyp tvingar alltid fram H.
Med logotyp förblir ytan bakom logotypen vit, även vid färgad eller transparent bakgrund.
Cachning: Endast den faktiska standardbilden (svart på vitt, felkorrigering M, ingen logotyp) levereras som oföränderlig i 24 timmar; varje annan rendering i 5 minuter. För PDF och EPS räknas varje angiven bakgrund som en avvikelse: bg=ffffff ritar där en vit fyllning som standardfilen inte har.
Abonnemang: Färger och felkorrigering är tillgängliga i alla abonnemang, även i gratisversionen.

cURL
TypeScript SDK

# Dark blue code on white
curl "https://qr3.app/v1/codes/r7f3Kx/qr.svg?fg=1F4E79" -o qr-blue.svg

# Transparent PNG for a layout on a light surface
curl "https://qr3.app/v1/codes/r7f3Kx/qr.png?size=10&bg=transparent" -o qr-transparent.png

# More robust for corrugated board: error correction Q
curl "https://qr3.app/v1/codes/r7f3Kx/qr.pdf?ecc=Q" -o qr-q.pdf

// @qr3/sdk 1.2.0 or later — imageUrl() only builds the URL, it sends no request
// Dark blue code on white
qr3.codes.imageUrl('r7f3Kx', { format: 'svg', fg: '1F4E79' });
// → https://qr3.app/v1/codes/r7f3Kx/qr.svg?fg=1F4E79

// Transparent PNG for a layout on a light surface
qr3.codes.imageUrl('r7f3Kx', { format: 'png', size: 10, bg: 'transparent' });

// More robust for corrugated board: error correction Q
qr3.codes.imageUrl('r7f3Kx', { format: 'pdf', ecc: 'Q' });

Spara färger på koden

PATCH /v1/codes/:id sparar färger som appearance på koden. Bildrutterna ritar sedan ut dem som standard, utan parametrar.

cURL
TypeScript SDK

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"appearance": {"foreground_color": "#1F4E79"}}'

// @qr3/sdk 1.2.0 or later
const code = await qr3.codes.update('qr_a1b2c3d4', {
  appearance: { foreground_color: '#1F4E79' },
});
code.appearance; // { foreground_color: '#1F4E79', background_color: null }
code.issues;     // contrast check findings, absent when there are none

Svar (HTTP 200, förkortat):

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "appearance": { "foreground_color": "#1F4E79", "background_color": null }
  },
  "meta": { "request_id": "req_xyz", "issues": [] }
}

Värden: foreground_color som #RRGGBB, background_color som #RRGGBB eller transparent. Andra nycklar ger 400.
Sammanslagning: Ett utelämnat fält behåller sitt sparade värde. null återställer ett fält, "appearance": null båda. Svart och vitt sparas inte; svaret visar dem som null.
Varje kodsvar innehåller appearance, liksom webhookarna qr.created och qr.updated.
Ordning i bildrutterna: först parametern, sedan den sparade färgen, sedan standardvärdet. ?fg=000000 ger därför den svarta tryckfilen för en färgad kod.
Inbäddade bilder: En bild-URL följer de sparade färgerna såvida den inte själv anger dem med fg och bg: en URL utan parametrar för båda färgerna, ?fg=000000 för bakgrunden, ?ecc=Q likaså för båda. Efter en färgändring kan en sida som bäddar in en sådan URL fortfarande visa den gamla bilden: i upp till 24 timmar om URL:en fram till dess levererade standardbilden (svart på vitt, felkorrigering M, utan logotyp), annars i upp till 5 minuter. Lösningen är en egen parameter på URL:en som ändras vid varje färgändring, till exempel ?v=2 eller kodens updated_at som i Dashboard. Bildrutterna ignorerar okända parametrar.
Felkorrigering sparas aldrig. Den väljs per nedladdning med ?ecc=.
Endast via PATCH: POST /v1/codes, batchen och importen avvisar appearance med 422.
PDF och EPS ritar sparade färger som tryckfärger, precis som parametrarna. Eftersom vitt aldrig sparas får en kod med en sparad förgrundsfärg en vit fyllning där, precis som i SVG-filen.

Kontrastkontroll

API:et kontrollerar paret som uppstår av begäran och det sparade värdet:

Nivå	När	Svar
`blocked`	Kontrast under 1,5:1	`422`, inget sparas
`critical`	under 2:1 eller skillnad i ljusstyrka under 0,30; en varning tillsammans med en logotyp; alla transparenta bakgrunder	`200` med `meta.issues`
`warning`	under 4:1 eller skillnad i ljusstyrka under 0,50; ljusa moduler på mörk bakgrund	`200` med `meta.issues`
ok	allt annat	`200`, `meta.issues` är tom

Varje post i meta.issues har code, severity, field, message och valfritt hints som contrast_ratio — samma form som efterlevnadsmeddelandena för ett digitalt produktpass. En transparent bakgrund spärras aldrig, eftersom en ljus kod på en mörk förpackning är ett verkligt användningsfall. Underlaget behöver ändå en tydlig kontrast och en fri tyst zon på 4 moduler runt om.

Att ladda upp och ta bort en logotyp (POST och DELETE /v1/codes/:id/logo) gör samma kontroll av de sparade färgerna och returnerar också resultaten i meta.issues: med en logotyp blir en varning critical, utan en logotyp blir det en varning igen.

Om en annan begäran ändrar samma kod i samma ögonblick, tillämpar API:et ändringarna på den senaste versionen. Först när detta misslyckas tre gånger i rad svarar det med 409; klienten laddar då om koden och upprepar ändringen.

Logo

`POST /v1/codes/:id/logo`

Multipart-begäran, fältet file: PNG, JPEG eller WebP, max 1 MB, identifieras via magic bytes. Normaliserar bilden till en transparent 512×512-PNG och ersätter en befintlig logotyp.

curl -X POST https://qr3.app/v1/codes/qr_a1b2c3d4/logo \
  -H "Authorization: Bearer qr3_sk_..." \
  -F "[email protected]"

Svar (HTTP 201): den uppdaterade koden, med logo_file_id satt.

`DELETE /v1/codes/:id/logo`

Tar bort logotypen och raderar det sparade objektet. Idempotent — ett anrop utan en befintlig logotyp returnerar fortfarande 200.

Om en annan begäran ändrar samma kods logotyp i samma ögonblick (en andra uppladdning eller en borttagning), svarar POST och DELETE /v1/codes/:id/logo med 409 (errors/conflict) och ändrar ingenting; en uppladdad bild förkastas. Ladda om koden och försök igen. Två samtidiga anrop av DELETE /v1/codes/:id/logo är inte en konflikt; båda returnerar 200.

Om den är satt bäddar alla fyra formaten — qr.svg, qr.png, qr.pdf och qr.eps — in logotypens pixlar och höjer felkorrigeringen till H. Det fullständiga avtalet — inklusive vilken ändring (lägga till/ta bort kontra ersätta) som ändrar punktmönstret — samt tryckanvisningar finns under Logo i QR-koden.

Kommentarer

Kommentarer möjliggör feedback-loopar mellan byråer och kunder.

`GET /v1/codes/:id/comments`

`POST /v1/codes/:id/comments`

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

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

Dashboard-kommentarer tillskrivs den användare som skapade dem (author_id); kommentarer som skapats med en ren API-nyckel förblir oattribuerade (author_id: null). En kommentar får endast tas bort av författaren själv eller av en org_admin/ws_admin — rena API-nycklar kan endast ta bort oattribuerade API-kommentarer.

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