QR-koodide API

Ülevaade

Codes API on qr3.app süda. Selle abil saad luua, uuendada ja kustutada dünaamilisi ning staatilisi QR-koode.

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

Siduv REST-leping

Järgmine leping kehtib kõigile klientidele:

POST /v1/codes aktsepteerib ainult tüüpe url, vcard, wifi, email, sms ja location. Väljad on tasapinnalised: url; vähemalt vcard_first_name või vcard_last_name; wifi_ssid; email_to; sms_phone; või mõlemad location_lat ja location_lng.
Ainult url-koodid võivad olla dünaamilised. Loomistaotlused võivad soovi korral sisaldada expires_at ISO 8601 ajatemplina; ab_enabled, ab_target_url_b ja ab_weight_a (A/B sihtkohad) on lubatud dünaamiliste url-koodide puhul; redirect_after_expiry ei kuulu loomislepingusse.
GET /v1/codes toetab ainult limit, cursor ja status (live, paused, flagged, draft).
POST /v1/codes/batch aktsepteerib url, vcard ja wifi. Piirang on Free puhul 10, Pro puhul 500 ning Business/Agency/Enterprise puhul 1 000 kirjet päringu kohta. URL-i skannid töötavad sünkroonselt kuni 50 URL-i kirje puhul; üle 50 nõuab skip_url_scan: true.

QR-koodi loomine

`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

Vastus (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-koodi tüübid

Tüüp	Kirjeldus	Kohustuslikud väljad
`url`	Veebisaidi URL (dünaamiline või staatiline)	`url`
`vcard`	Visiitkaart (vCard 3.0)	`vcard_first_name` või `vcard_last_name`
`wifi`	Wi-Fi konfiguratsioon	`wifi_ssid`
`email`	E-post (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Asukoht (geo:)	`location_lat`, `location_lng`

Massloomine (Batch)

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

Vastus (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-koodide nimekiri

`GET /v1/codes`

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

Päringu parameetrid (Query parameters):

Parameeter	Tüüp	Vaikimisi	Kirjeldus
`cursor`	string	—	Kursor lehekülgede jaotamiseks (pagination)
`limit`	integer	20	Tulemusi lehe kohta (maksimaalselt 100)
`status`	string	—	Filter: `live`, `paused`, `flagged`, `draft`

QR-koodi hankimine

`GET /v1/codes/:id`

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

QR-koodi uuendamine

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

Dünaamilised QR-koodid võimaldavad siht-URL-i igal ajal muuta — ilma et peaksid QR-koodi uuesti trükkima.

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

Maandumisleht ja välised lingid

Dünaamiliste url-koodide puhul saad määrata is_landing_page: true (loomisel või PATCH kaudu). Skannimine kuvab siis qr3 majutatud lehte koodi avalike failide ja väliste linkidega, selle asemel et edasi suunata. Välised lingid edastatakse massiivina links:

{
  "is_landing_page": true,
  "links": [
    { "label": "Datenblatt", "url": "https://example.com/datenblatt.pdf" },
    { "label": "Zertifikat", "url": "https://example.com/zertifikat.pdf" }
  ]
}

0–20 linki koodi kohta; label on 1–100 märki; url peab olema http(s) (≤ 2048 märki).
Iga URL-i kontrollitakse Google Web Risk teenusega — ebaturbe URL tagastab vastuse 422.
Kui Web Risk pole salvestamise ajal kättesaadav, võetakse link siiski vastu, kuid märgistatakse uueks kontrolliks. Igapäevane taustatöö kontrollib salvestatud linke uuesti (ja puhtaks liigitatud linke regulaarselt üle) ja peatab koodi automaatselt, kui mõni link tuvastatakse hiljem ebaturbana.
"links": [] kustutab kõik lingid. Vaata maandumislehe juhendit.

QR-koodi kustutamine

`DELETE /v1/codes/:id`

Pehme kustutamine (Soft-Delete) — QR-kood arhiveeritakse, skannimisandmed säilivad.

Teine DELETE päring samale koodile tagastab vastuse 404, isegi kui mõlemad päringud saabuvad samal ajal. Webhook qr.deleted saadetakse täpselt üks kord.

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

QR-piltide allalaadimine

Kõik pildivormingud on avalikult kättesaadavad — autentimist pole vaja.

Vorming	URL	Kasutusala
SVG (vektor)	`/v1/codes/:code/qr.svg`	Veeb, skaleerimine, digitaalne
PNG (raster)	`/v1/codes/:code/qr.png`	E-post, esitlused
PDF (vektor)	`/v1/codes/:code/qr.pdf`	Vaikimisi: ruudukujuline (ainult kood); `?format=a4` trükilehe jaoks
EPS (vektor)	`/v1/codes/:code/qr.eps`	Professionaalsed trükitöövood (Adobe, trükikojad)

Valikuline: ?size=N — mooduli suurus pikslites (2–20, vaikimisi: 4) SVG, PNG ja EPS jaoks. PDF kasutab fikseeritud mooduli suurust.

Ainult PDF: ?format=a4|square — lehevorming (vaikimisi: square — ainult kood + turvaala (Quiet Zone), ilma A4 valge alata; a4 trükivalmis A4-lehe jaoks)

# 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

Värvid ja veaparandus

Kõik neli pildimarsruuti võtavad vastu kolm valikulist parameetrit. Need kehtivad selle ühe päringu kohta ja on prioriteetsemad koodi juurde salvestatud värvide suhtes (järgmine jaotis).

Parameeter	Väärtused	Vaikimisi	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` või `RGB`	`000000`	joonistatakse	joonistatakse trükivärvina
`bg`	Hex nagu `fg` või `transparent`	`ffffff`	joonistatakse	joonistatakse trükivärvina
`ecc`	`L`, `M`, `Q`, `H`	`M`	rakendub	rakendub

Kirjutusviis: Suur- ja väiketähed ei ole olulised, sümbol # on valikuline. Kui see kaasa saadetakse, tuleb see kodeerida kujul %23.
Vigased väärtused loetakse määramata väärtusteks. ?fg=lila tagastab koodile salvestatud värvi või salvestatud värvi puudumisel tavalise musta staatusega 200 ja mitte kunagi vea. Ainult selgesõnaline ?fg=000000 sunnib kasutama musta.
bg=transparent tagastab ilma taustata SVG, PDF-i või EPS-i ja tõelise alfakanaliga PNG. Aluspind, millele kood asetatakse, peab olema hele ja jätma ümberringi 4 mooduli suuruse vaba ruumi (vahetsooni). Tume kood tumedal taustal ei ole loetav.
PDF ja EPS kirjutavad musta ja halli halltoonina (ainult must osavärv) ning mis tahes muu värvi CMYK-vormingus täisprotsentides, näiteks 1F4E79 kui C74 M36 Y0 K53. Niipea kui värv on valitud, asub koodi ja selle vahetsooni taga kattev täitepind, mis on valge või parameetri bg värvi, nagu SVG-failis. Ilma värvideta jäävad mõlemad failid muutmata. Teisendamine ja piirangud: Värvid trükis.
Kontrastsus: Pildimarsruut seda ei kontrolli. Soovitatav on vähemalt 4:1 ja tumedad moodulid heledal taustal. #1F4E79 valgel taustal on suhe 8,7:1, #ff6600 valgel taustal vaid 2,9:1.
ecc muudab punktimustrit, mitte sisu. Prinditud kood töötab edasi, kuid vana ja uut prindifaili ei tohiks omavahel segada. Q või H muudavad koodi vastupidavamaks, näiteks lainepapil. Logo nõuab alati parameetrit H.
Logoga jääb logo tagune ala valgeks, seda ka värvilise või läbipaistva tausta puhul.
Vahemälu: Ainult tegelikku vaikimisi pilti (must valgel, veaparandus M, ilma logota) serveeritakse muutumatuna 24 tundi; kõiki teisi kujutisi 5 minutit. PDF- ja EPS-vormingu puhul loetakse mis tahes määratud taust kõrvalekaldeks: bg=ffffff joonistab sinna valge täite, mida vaikimisi failil ei ole.
Pakett: Värvid ja veaparandus on saadaval igas paketis, ka tasuta paketis.

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

Värvide salvestamine koodi juurde

PATCH /v1/codes/:id salvestab värvid koodi juurde kui appearance. Pildimarsruudid joonistavad need seejärel vaikimisi, ilma parameetriteta.

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

Vastus (HTTP 200, lühendatud):

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

Väärtused: foreground_color kujul #RRGGBB, background_color kujul #RRGGBB või transparent. Muud võtmed tagastavad koodi 400.
Ühendamine: Väljajäetud väli säilitab oma salvestatud väärtuse. null lähtestab ühe välja, "appearance": null mõlemad. Musta ja valget ei salvestata; vastus näitab neid väärtusena null.
Iga koodi vastus sisaldab välja appearance, samuti webhookid qr.created ja qr.updated.
Järjekord pildimarsruutides: esmalt parameeter, seejärel salvestatud värv, seejärel vaikeväärtus. ?fg=000000 tagastab seetõttu värvilise koodi musta trükifaili.
Sisseehitatud pildid: Pildi URL järgib salvestatud värve, kuivõrd ta ei määra neid ise parameetritega fg ja bg: parameetriteta URL mõlema värvi puhul, ?fg=000000 tausta puhul, ?ecc=Q samuti mõlema puhul. Pärast värvimuutust võib sellist URL-i sisaldav leht näidata veel vana pilti: kuni 24 tundi, kui URL tagastas seni vaikimisi pildi (must valgel, veaparandus M, ilma logota), muidu kuni 5 minutit. Abinõuks on URL-ile oma parameetri lisamine, mis muutub iga värvimuutusega, näiteks ?v=2 või koodi updated_at nagu Dashboardis. Pildimarsruudid eiravad tundmatuid parameetreid.
Veaparandust ei salvestata kunagi. See valitakse iga allalaadimise puhul parameetriga ?ecc=.
Ainult PATCH kaudu: POST /v1/codes, partii ja import lükkavad appearance tagasi koodiga 422.
PDF ja EPS joonistavad salvestatud värve trükivärvidena, täpselt nagu parameetreid. Kuna valget ei salvestata kunagi, saab salvestatud esiplaanivärviga kood seal valge täite, nagu SVG-s.

Kontrastsuse kontroll

API kontrollib paari, mis moodustub päringust ja salvestatud väärtusest:

Tase	Millal	Vastus
`blocked`	Kontrast alla 1,5:1	`422`, midagi ei salvestata
`critical`	alla 2:1 või heleduse erinevus alla 0,30; hoiatus koos logoga; mis tahes läbipaistev taust	`200` koos `meta.issues`
`warning`	alla 4:1 või heleduse erinevus alla 0,50; heledad moodulid tumedal taustal	`200` koos `meta.issues`
ok	kõik muu	`200`, `meta.issues` on tühi

Igal kirjel jaotises meta.issues on code, severity, field, message ja valikuliselt hints nagu contrast_ratio — sama kuju nagu digitaalse tootepassi vastavusteadetel. Läbipaistvat tausta ei blokeerita kunagi, sest hele kood tumedal pakendil on reaalne kasutusjuht. Aluspind vajab sellegipoolest selget kontrasti ja koodi ümber vaba 4 mooduli suurust vaikset tsooni.

Logo üleslaadimine ja eemaldamine (POST ja DELETE /v1/codes/:id/logo) kontrollivad salvestatud värve samamoodi ja tagastavad tulemused samuti jaotises meta.issues: logoga muutub hoiatus staatuseks critical, ilma logota on see uuesti hoiatus.

Kui mõni teine päring muudab sama koodi samal hetkel, rakendab API muudatused uusimale olekule. Alles siis, kui see ebaõnnestub kolm korda järjest, vastab see koodiga 409; seejärel laadib klient koodi uuesti ja kordab muudatust.

Logo

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

Multipart-päring, väli file: PNG, JPEG või WebP, maksimaalselt 1 MB, tuvastatakse Magic Bytes abil. Normaliseerib pildi läbipaistvaks 512×512-PNG-ks ja asendab olemasoleva logo.

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

Vastus (HTTP 201): uuendatud kood, millel on määratud logo_file_id.

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

Eemaldab logo ja kustutab salvestatud objekti. Idempotentne — päring ilma olemasoleva logota tagastab ikkagi 200.

Kui mõni teine päring muudab samal hetkel sama koodi logo (teine üleslaadimine või eemaldamine), vastavad POST ja DELETE /v1/codes/:id/logo koodiga 409 (errors/conflict) ega muuda midagi; üleslaaditud pilt hüljatakse. Laadi kood uuesti ja proovi uuesti. Kaks samaaegset päringut DELETE /v1/codes/:id/logo ei tekita konflikti; mõlemad tagastavad 200.

Kui see on määratud, põimivad kõik neli vormingut — qr.svg, qr.png, qr.pdf ja qr.eps — logo pikslid ning tõstavad veaparanduse tasemele H. Täielik kokkulepe — sealhulgas see, milline muudatus (lisamine/eemaldamine vs. asendamine) muudab punktimustrit — ja trükijuhised on saadaval jaotises Logo QR-koodis.

Kommentaarid

Kommentaarid võimaldavad tagasisideahelaid agentuuride ja klientide vahel.

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

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

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

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

Dashboardi kommentaarid seostatakse need loonud kasutajaga (author_id); pelgalt API-võtmetega loodud kommentaarid jäävad seostamata (author_id: null). Kommentaari tohib kustutada ainult autor ise või org_admin/ws_admin — pelgalt API-võtmega saab kustutada ainult seostamata API-kommentaare.

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