QR kodu API

Pārskats

Codes API ir qr3.app sirds. Ar to jūs varat izveidot, atjaunināt un dzēst dinamiskos un statiskos QR kodus.

Bāzes URL: https://qr3.app/v1/codes

Saistošais REST līgums

Šis līgums attiecas uz visiem klientiem:

POST /v1/codes pieņem tikai tipus url, vcard, wifi, email, sms un location. Lauki ir plakani: url; vismaz vcard_first_name vai vcard_last_name; wifi_ssid; email_to; sms_phone; vai abi location_lat un location_lng.
Dinamiski var būt tikai url kodi. Izveides pieprasījumos pēc izvēles var ietvert expires_at kā ISO 8601 laika zīmogu; ab_enabled, ab_target_url_b un ab_weight_a (A/B galamērķi) tiek pieņemti dinamiskiem url kodiem; redirect_after_expiry nav daļa no izveides līguma.
GET /v1/codes atbalsta tikai limit, cursor un status (live, paused, flagged, draft).
POST /v1/codes/batch pieņem url, vcard un wifi. Limits ir 10 Free, 500 Pro un 1 000 Business/Agency/Enterprise ierakstu vienā pieprasījumā. URL skenēšana sinhroni darbojas ne vairāk kā 50 URL vienumiem; ja to ir vairāk par 50, nepieciešams skip_url_scan: true.

QR koda izveide

`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

Atbilde (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 kodu veidi

Veids	Apraksts	Obligātie lauki
`url`	Mājaslapas URL (dinamisks vai statisks)	`url`
`vcard`	Vizītkarte (vCard 3.0)	`vcard_first_name` vai `vcard_last_name`
`wifi`	Wi-Fi konfigurācija	`wifi_ssid`
`email`	E-pasts (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Atrašanās vieta (geo:)	`location_lat`, `location_lng`

Masveida izveide (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
  }'

Atbilde (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 kodu saraksts

`GET /v1/codes`

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

Vaicājuma parametri (Query parameters):

Parametrs	Tips	Noklusējums	Apraksts
`cursor`	string	—	Kursors lapošanai (pagination)
`limit`	integer	20	Rezultātu skaits lapā (maks. 100)
`status`	string	—	Filtrs: `live`, `paused`, `flagged`, `draft`

QR koda iegūšana

`GET /v1/codes/:id`

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

QR koda atjaunināšana

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

Dinamiskie QR kodi ļauj jebkurā laikā mainīt mērķa URL — bez nepieciešamības vēlreiz drukāt QR kodu.

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

Mērķlapa un ārējās saites

Dinamiskiem url kodiem varat iestatīt is_landing_page: true (izveides laikā vai izmantojot PATCH). Skenējot kodu, tā vietā, lai veiktu novirzīšanu, tiks parādīta qr3 mitināta lapa ar koda publiskajiem failiem un ārējām saitēm. Ārējās saites tiek nodotas kā links masīvs:

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

0–20 saites katram kodam; label ir 1–100 rakstzīmes; url jābūt http(s) (≤ 2048 rakstzīmes).
Katrs URL tiek pārbaudīts ar Google Web Risk — nedrošs URL atgriež 422.
Ja saglabāšanas brīdī Web Risk nav sasniedzams, saite tik un tā tiek pieņemta, taču tiek atzīmēta atkārtotai pārbaudei. Ikdienas fona uzdevums atkārtoti pārbauda saglabātās saites (un regulāri pārbauda arī tās, kas iepriekš klasificētas kā drošas) un automātiski aptur kodu, ja kāda saite vēlāk tiek atzīta par nedrošu.
"links": [] dzēš visas saites. Skatiet mērķlapas rokasgrāmatu.

QR koda dzēšana

`DELETE /v1/codes/:id`

Mīkstā dzēšana (Soft-Delete) — QR kods tiek arhivēts, skenēšanas dati tiek saglabāti.

Otrais DELETE tam pašam kodam atgriež 404, pat ja abi pieprasījumi pienāk vienlaicīgi. Webhook qr.deleted tiek nosūtīts tieši vienu reizi.

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

QR attēlu lejupielāde

Visi attēlu formāti ir publiski pieejami — autentifikācija nav nepieciešama.

Formāts	URL	Izmantošana
SVG (vektors)	`/v1/codes/:code/qr.svg`	Tīmeklis, mērogošana, digitālie mediji
PNG (rasters)	`/v1/codes/:code/qr.png`	E-pasts, prezentācijas
PDF (vektors)	`/v1/codes/:code/qr.pdf`	Noklusējums: kvadrātveida (tikai kods); `?format=a4` apdrukājamai lapai
EPS (vektors)	`/v1/codes/:code/qr.eps`	Profesionālas drukāšanas darbplūsmas (Adobe, tipogrāfijas)

Izvēles: ?size=N — moduļa izmērs pikseļos (2–20, noklusējums: 4) formātiem SVG, PNG un EPS. PDF izmanto fiksētu moduļa izmēru.

Tikai PDF: ?format=a4|square — lapas formāts (noklusējums: square — tikai kods + klusā zona (Quiet Zone), bez A4 baltā laukuma; a4 drukāšanai gatavai A4 lapai)

# 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

Krāsas un kļūdu labošana

Visi četri attēlu maršruti pieņem trīs izvēles parametrus. Tie attiecas uz šo konkrēto pieprasījumu un ir prioritāri pār krāsām, kas saglabātas kodā (nākamā sadaļa).

Parametrs	Vērtības	Noklusējums	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` vai `RGB`	`000000`	tiek zīmēts	tiek zīmēts kā drukas krāsa
`bg`	Hex kā `fg` vai `transparent`	`ffffff`	tiek zīmēts	tiek zīmēts kā drukas krāsa
`ecc`	`L`, `M`, `Q`, `H`	`M`	tiek piemērots	tiek piemērots

Rakstība: Reģistrjutīgumam nav nozīmes (lielie/mazie burti), # ir neobligāts. Ja to sūta, tas jākodē kā %23.
Nederīgas vērtības tiek uzskatītas par neiestatītām. ?fg=lila atgriež kodā saglabāto krāsu vai, ja nekas nav saglabāts, parasto melno krāsu ar 200 un nekad neizraisa kļūdu. Tikai tieši norādīts ?fg=000000 piespiež izmantot melno krāsu.
bg=transparent atgriež SVG, PDF vai EPS bez fona un PNG ar reālu alfa kanālu. Pamatnei, uz kuras tiek novietots kods, jābūt gaišai un visapkārt jāatstāj brīva 4 moduļu klusā zona. Tumšs kods uz tumša fona nav nolasāms.
PDF un EPS raksta melno un pelēko krāsu kā pelēktoņu (tikai melnā plate) un jebkuru citu krāsu kā CMYK veselos procentos, piemēram, 1F4E79 kā C74 M36 Y0 K53. Tiklīdz ir izvēlēta krāsa, aiz koda un tā klusās zonas atrodas necaurspīdīgs laukums, balts vai bg krāsā, tāpat kā SVG. Bez krāsām abi faili paliek nemainīti. Konvertēšana un ierobežojumi: Krāsas drukā.
Kontrasts: Attēla maršruts to nepārbauda. Ieteicams ir vismaz 4:1 un tumši moduļi uz gaiša fona. #1F4E79 uz balta ir 8,7:1, #ff6600 uz balta tikai 2,9:1.
ecc maina punktu rakstu, nevis saturu. Izdrukāts kods turpina darboties, taču nevajadzētu jaukt vecās un jaunās drukas datnes. Q vai H padara kodu izturīgāku, piemēram, uz gofrētā kartona. Logo vienmēr pieprasa H.
Ar logo laukums aiz logo paliek balts, arī krāsaina vai caurspīdīga fona gadījumā.
Kešatmiņa: Tikai faktiskais standarta attēls (melns uz balta, kļūdu labošana M, bez logo) tiek piegādāts kā nemainīgs uz 24 stundām; jebkurš cits attēlojums uz 5 minūtēm. PDF un EPS formātiem jebkurš norādītais fons tiek uzskatīts par novirzi: bg=ffffff tur uzzīmē baltu laukumu, kāda standarta failā nav.
Tarifs: Krāsas un kļūdu labošana ir pieejama visos tarifu plānos, arī bezmaksas.

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

Krāsu saglabāšana pie koda

PATCH /v1/codes/:id saglabā krāsas kā appearance pie koda. Attēlu maršruti pēc tam tās zīmē pēc noklusējuma, bez parametriem.

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

Atbilde (HTTP 200, saīsināta):

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

Vērtības: foreground_color kā #RRGGBB, background_color kā #RRGGBB vai transparent. Citi atslēgvārdi dod 400.
Apvienošana: Izlaists lauks saglabā savu iepriekšējo vērtību. null atiestata lauku, "appearance": null atiestata abus. Melnā un baltā krāsa netiek saglabātas; atbilde tās uzrāda kā null.
Katra koda atbilde satur appearance, tāpat kā webhooks qr.created un qr.updated.
Secība attēlu maršrutos: vispirms parametrs, tad saglabātā krāsa, pēc tam noklusējuma vērtība. Tāpēc ?fg=000000 nodrošina krāsaina koda melno drukas failu.
Iegultie attēli: Attēla URL seko saglabātajām krāsām, ja vien tas pats tās neiestata ar fg un bg: URL bez parametriem abām krāsām, ?fg=000000 fonam, ?ecc=Q arī abām. Pēc krāsu maiņas lapa, kurā ir iegults šāds URL, joprojām var rādīt veco attēlu: līdz pat 24 stundām, ja URL līdz tam atgrieza noklusējuma attēlu (melns uz balta, kļūdu labošana M, bez logotipa), pretējā gadījumā līdz 5 minūtēm. Risinājums ir jūsu pašu parametrs URL adresē, kas mainās līdz ar katru krāsu maiņu, piemēram, ?v=2 vai koda updated_at, kā vadības panelī. Attēlu maršruti ignorē nezināmus parametrus.
Kļūdu labošana nekad netiek saglabāta. Tā tiek izvēlēta katrai lejupielādei ar ?ecc=.
Tikai caur PATCH: POST /v1/codes, batch un imports noraida appearance ar 422.
PDF un EPS zīmē saglabātās krāsas kā drukas krāsas, tieši tāpat kā parametrus. Tā kā baltā krāsa nekad netiek saglabāta, kods ar saglabātu priekšplāna krāsu tur iegūst baltu aizpildījumu, līdzīgi kā SVG.

Kontrasta pārbaude

API pārbauda pāri, kas veidojas no pieprasījuma un saglabātās vērtības:

Līmenis	Kad	Atbilde
`blocked`	Kontrasts zem 1,5:1	`422`, nekas netiek saglabāts
`critical`	zem 2:1 vai spilgtuma starpība zem 0,30; brīdinājums kopā ar logotipu; jebkurš caurspīdīgs fons	`200` ar `meta.issues`
`warning`	zem 4:1 vai spilgtuma starpība zem 0,50; gaiši moduļi uz tumša fona	`200` ar `meta.issues`
ok	viss pārējais	`200`, `meta.issues` ir tukšs

Katram ierakstam meta.issues ir code, severity, field, message un pēc izvēles hints, piemēram, contrast_ratio — tāda pati forma kā digitālā produkta pases atbilstības paziņojumiem. Caurspīdīgs fons nekad netiek bloķēts, jo gaišs kods uz tumša iepakojuma ir reāls izmantošanas gadījums. Tomēr pamatnei ir nepieciešams izteikts kontrasts un brīva klusuma zona 4 moduļu apmērā visapkārt.

Logotipa augšupielāde un noņemšana (POST un DELETE /v1/codes/:id/logo) veic tādu pašu saglabāto krāsu pārbaudi un arī atgriež rezultātus meta.issues objektā: ar logotipu brīdinājums kļūst par critical, bet bez tā — atkal par brīdinājumu.

Ja cits pieprasījums maina to pašu kodu tajā pašā brīdī, API piemēro izmaiņas jaunākajam stāvoklim. Tikai tad, ja tas neizdodas trīs reizes pēc kārtas, tā atbild ar 409; klients pēc tam pārlādē kodu un atkārto izmaiņas.

Logo

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

Multipart pieprasījums, lauks file: PNG, JPEG vai WebP, maksimāli 1 MB, identificēts pēc magic bytes. Normalizē attēlu uz caurspīdīgu 512×512-PNG un aizstāj esošo logo.

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

Antwort (HTTP 201): atjauninātais kods ar iestatītu logo_file_id.

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

Noņem logo un dzēš saglabāto objektu. Idempotents — izsaukums bez esoša logo joprojām atgriež 200.

Ja cits pieprasījums tajā pašā brīdī maina tā paša koda logo (otra augšupielāde vai noņemšana), POST un DELETE /v1/codes/:id/logo atbild ar 409 (errors/conflict) un neko nemaina; augšupielādētais attēls tiek atmests. Pārlādējiet kodu un mēģiniet vēlreiz. Divi vienlaicīgi DELETE /v1/codes/:id/logo izsaukumi nav konflikts; abi atgriež 200.

Ja tas ir iestatīts, visi četri formāti — qr.svg, qr.png, qr.pdf un qr.eps — iegulst logo pikseļus un paaugstina kļūdu labošanu līdz H. Pilna specifikācija — tostarp tas, kuras izmaiņas (pievienošana/noņemšana pret aizstāšanu) maina punktu rakstu — kā arī drukāšanas norādījumi ir pieejami sadaļā Logo QR kodā.

Komentāri

Komentāri nodrošina atgriezeniskās saites cilpas starp aģentūrām un klientiem.

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

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

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

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

Vadības panelī izveidotie komentāri tiek piesaistīti lietotājam, kurš tos izveidojis (author_id); komentāri, kas izveidoti ar parastu API atslēgu, paliek bez piesaistes (author_id: null). Dzēst komentāru drīkst tikai pats autors vai org_admin/ws_admin — ar parastu API atslēgu var dzēst tikai tādus komentārus bez piesaistes, kas izveidoti, izmantojot API.

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