API tal-QR Codes

Ħarsa Ġenerali

L-API tal-Codes hija l-qalba ta’ qr3.app. Biha tista’ toħloq, taġġorna u tħassar QR codes dinamiċi u statiċi.

URL Bażika: https://qr3.app/v1/codes

Kuntratt REST vinkolanti

Il-kuntratt li ġej japplika għall-klijenti kollha:

POST /v1/codes jaċċetta biss it-tipi url, vcard, wifi, email, sms u location. L-oqsma huma ċatti: url; mill-inqas vcard_first_name jew vcard_last_name; wifi_ssid; email_to; sms_phone; jew it-tnejn location_lat u location_lng.
Il-kodiċijiet url biss jistgħu jkunu dinamiċi. It-talbiet għall-ħolqien jistgħu b’mod fakultattiv jinkludu expires_at bħala timbru ta’ ħin ISO 8601; ab_enabled, ab_target_url_b u ab_weight_a (destinazzjonijiet A/B) huma aċċettati għal kodiċijiet url dinamiċi; redirect_after_expiry mhuwiex parti mill-kuntratt tal-ħolqien.
GET /v1/codes jappoġġa biss limit, cursor u status (live, paused, flagged, draft).
POST /v1/codes/batch jaċċetta url, vcard u wifi. Il-limitu huwa 10 għal Free, 500 għal Pro, u 1,000 rekord għal Business/Agency/Enterprise għal kull talba. L-iskans tal-URL isiru b’mod sinkroniku għal mhux aktar minn 50 element URL; ‘il fuq minn 50 huwa meħtieġ skip_url_scan: true.

Oħloq QR Code

`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

Rispons (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" }
}

Tipi ta’ QR Codes

Tip	Deskrizzjoni	Kampi Obbligatorji
`url`	URL tal-websajt (dinamika jew statika)	`url`
`vcard`	Karta tan-negozju (vCard 3.0)	`vcard_first_name` jew `vcard_last_name`
`wifi`	Konfigurazzjoni tal-Wi-Fi	`wifi_ssid`
`email`	E-mail (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Post (geo:)	`location_lat`, `location_lng`

Ħolqien f’Daqqa (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
  }'

Rispons (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 ta’ QR Codes

`GET /v1/codes`

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

Parametri tal-Query:

Parametru	Tip	Default	Deskrizzjoni
`cursor`	string	—	Cursor għall-paginazzjoni
`limit`	integer	20	Riżultati għal kull paġna (mass. 100)
`status`	string	—	Filtru: `live`, `paused`, `flagged`, `draft`

Ikseb QR Code

`GET /v1/codes/:id`

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

Aġġorna QR Code

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

QR codes dinamiċi jippermettulek tbiddel il-URL tad-destinazzjoni fi kwalunkwe ħin — mingħajr ma jkollok bżonn terġa’ tipprintja l-QR code.

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

Landing Page u Links Esterni

Għal codes url dinamiċi, tista’ tissettja is_landing_page: true (meta toħloqhom jew permezz ta’ PATCH). Skan imbagħad juri paġna ospitata minn qr3 bil-fajls pubbliċi u links esterni tal-code, minflok ma jidderieġi mill-ewwel. Il-links esterni jiġu mgħoddija bħala array ta’ links:

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

0–20 link għal kull code; label trid tkun bejn 1 u 100 karattru; url trid tkun http(s) (≤ 2048 karattru).
Kull URL tiġi vverifikata b’Google Web Risk — URL mhux sigura tirritorna 422.
Jekk Google Web Risk ma jkunx aċċessibbli waqt l-issejvjar, il-link xorta waħda tiġi aċċettata, iżda tiġi mmarkata biex terġa’ tiġi vverifikata. Proċess ta’ kuljum jerġa’ jivverifika l-links issejvjati (u jivverifika perjodikament dawk li qabel kienu kklassifikati bħala siguri) u jwaqqaf (pauses) il-code awtomatikament jekk link tinstab li mhix sigura aktar tard.
"links": [] iħassar il-links kollha. Ara l-gwida tal-landing page.

Ħassar QR Code

`DELETE /v1/codes/:id`

Soft-delete — il-QR code jiġi arkivjat, filwaqt li d-dejta tal-iskans tinżamm.

It-tieni DELETE fuq l-istess kodiċi jagħti 404, anke jekk iż-żewġ talbiet jaslu fl-istess ħin. Il-webhook qr.deleted jintbagħat eżattament darba.

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

Niżżel l-Immaġini tal-QR

Il-formati kollha tal-immaġini huma aċċessibbli pubblikament — m’hemm bżonn tal-ebda awtentikazzjoni.

Format	URL	Użu
SVG (Vettur)	`/v1/codes/:code/qr.svg`	Web, Skalar, Diġitali
PNG (Raster)	`/v1/codes/:code/qr.png`	E-mail, Preżentazzjonijiet
PDF (Vettur)	`/v1/codes/:code/qr.pdf`	Standard: kwadru (il-code biss); `?format=a4` għal folja tal-istampar
EPS (Vettur)	`/v1/codes/:code/qr.eps`	Flussi tax-xogħol tal-istampar professjonali (Adobe, stamperiji)

Mhux obbligatorju: ?size=N — Daqs tal-modulu f’pixels (2–20, default: 4) għal SVG, PNG u EPS. Il-PDF juża daqs tal-modulu fiss.

PDF biss: ?format=a4|square — Format tal-paġna (default: square — code biss + quiet zone, mingħajr spazju abjad A4; a4 għal folja A4 lesta għall-istampar)

# 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

Kuluri u korrezzjoni tal-iżbalji

L-erba’ rotot tal-immaġni kollha jaċċettaw tliet parametri fakultattivi. Dawn japplikaw għal din is-sejħa speċifika u jieħdu preċedenza fuq il-kuluri ssejvjati fil-kodiċi (it-taqsima li jmiss).

Parametru	Valuri	Standard	SVG, PNG	PDF, EPS
`fg`	Hex `RRGGBB` jew `RGB`	`000000`	jiġi ddisinjat	jiġi ddisinjat bħala kulur tal-istampar
`bg`	Hex bħal `fg` jew `transparent`	`ffffff`	jiġi ddisinjat	jiġi ddisinjat bħala kulur tal-istampar
`ecc`	`L`, `M`, `Q`, `H`	`M`	jaħdem	jaħdem

Mod ta’ kitba: L-ittri kbar jew żgħar ma jagħmlux differenza, il-# huwa fakultattiv. Min jibagħtu, għandu jikkodifikah bħala %23.
Valuri invalidi jgħoddu bħala mhux stabbiliti. ?fg=lila jagħti l-kulur maħżun fuq il-kodiċi, jew l-iswed normali jekk ma jkun maħżun l-ebda kulur, bl-istatus 200 u qatt żball. Biss ?fg=000000 espliċitu jġiegħel li jintuża l-iswed.
bg=transparent jagħti SVG, PDF jew EPS mingħajr sfond u PNG b’kanal alfa reali. L-isfond li fuqu jitqiegħed il-kodiċi għandu jkun ċar u jħalli żona kwieta ta’ 4 moduli madwaru kollu. Kodiċi skur fuq sfond skur ma jkunx jista’ jinqara.
PDF u EPS jiktbu l-iswed u l-griż bħala grayscale (pjanċa sewda biss) u kwalunkwe kulur ieħor bħala CMYK f’perċentwali sħaħ, pereżempju 1F4E79 bħala C74 M36 Y0 K53. Hekk kif jintgħażel kulur, mili opak jitqiegħed wara l-kodiċi u ż-żona kwieta tiegħu, abjad jew bil-kulur ta’ bg, bħal fl-SVG. Mingħajr kuluri, iż-żewġ fajls jibqgħu mhux mibdula. Konverżjoni u limiti: Kuluri fl-istampar.
Kuntrast: Ir-rotta tal-immaġni ma tiċċekkjax il-kuntrast. Huwa rakkomandat proporzjon ta’ mill-inqas 4:1 u moduli skuri fuq sfond ċar. #1F4E79 fuq l-abjad għandu 8.7:1, filwaqt li #ff6600 fuq l-abjad għandu biss 2.9:1.
ecc ibiddel il-mudell tal-punti, mhux il-kontenut. Kodiċi stampat jibqa’ jaħdem, iżda tħallatx fajls tal-istampar qodma u ġodda. Q jew H jagħmlu l-kodiċi aktar b’saħħtu, pereżempju fuq kartun korrugat. Logo dejjem iġiegħel l-użu ta’ H.
Bil-logo iż-żona wara l-logo tibqa’ bajda, anke b’sfond ikkulurit jew trasparenti.
Memorja cache: Hija biss l-immaġni standard attwali (iswed fuq abjad, korrezzjoni tal-iżbalji M, l-ebda logo) li tiġi pprovduta bħala li ma tinbidelx għal 24 siegħa; kull rappreżentazzjoni oħra għal 5 minuti. Għal PDF u EPS, kwalunkwe sfond mogħti jgħodd bħala devjazzjoni: bg=ffffff ipinġi wiċċ abjad hemmhekk li l-fajl standard m’għandux.
Pjan: Il-kuluri u l-korrezzjoni tal-iżbalji huma disponibbli f’kull pjan, anke f’dak b’xejn.

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

Issejvjar ta’ kuluri fuq il-kodiċi

PATCH /v1/codes/:id isejvja l-kuluri bħala appearance fuq il-kodiċi. Ir-rotot tal-immaġni mbagħad jippreżentawhom b’mod standard, mingħajr parametri.

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

Risposta (HTTP 200, imqassra):

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

Valuri: foreground_color bħala #RRGGBB, background_color bħala #RRGGBB jew transparent. Kwalunkwe ċavetta oħra tirriżulta f’400.
Amalgamazzjoni: Qasam li jitħalla barra jżomm il-valur issejvjat tiegħu. null jirrisettja qasam, filwaqt li "appearance": null jirrisettja t-tnejn. L-iswed u l-abjad ma jiġux issejvjati; ir-risposta turihom bħala null.
Kull risposta tal-kodiċi fiha appearance, kif ukoll il-webhooks qr.created u qr.updated.
Ordni fir-rotot tal-immaġni: l-ewwel il-parametru, imbagħad il-kulur issejvjat, u fl-aħħar l-istandard. Għalhekk, ?fg=000000 jipprovdi l-fajl tal-istampar iswed ta’ kodiċi kkulurit.
Immaġnijiet inkorporati: URL tal-immaġni ssegwi l-kuluri ssejvjati sakemm ma tistabbilixxihomx hija stess b’ fg u bg: URL mingħajr parametri għaż-żewġ kuluri, ?fg=000000 għall-isfond, u ?ecc=Q għat-tnejn ukoll. Wara bidla fil-kulur, paġna li tinkorpora URL bħal din tista’ xorta turi l-immaġni l-antika: sa 24 siegħa jekk il-URL kienet qed tipprovdi l-immaġni standard sa dak il-ħin (iswed fuq abjad, korrezzjoni tal-iżbalji M, mingħajr logo), inkella sa 5 minuti. Is-soluzzjoni hija parametru tiegħek stess fuq il-URL li jinbidel ma’ kull bidla fil-kulur, bħal ?v=2 jew l-updated_at tal-kodiċi bħal fid-Dashboard. Ir-rotot tal-immaġni jinjoraw parametri mhux magħrufa.
Korrezzjoni tal-iżbalji qatt ma tiġi ssejvjata. Din tintgħażel għal kull tniżżil permezz ta’ ?ecc=.
Biss permezz ta’ PATCH: POST /v1/codes, il-batch u l-importazzjoni jirrifjutaw appearance b’422.
PDF u EPS ipinġu l-kuluri ssejvjati bħala kuluri tal-istampar, l-istess bħall-parametri. Peress li l-abjad qatt ma jiġi ssejvjat, kodiċi b’kulur ta’ quddiem issejvjat jieħu mili abjad hemmhekk, bħal fl-SVG.

Verifika tal-kuntrast

L-API tivverifika l-par li jirriżulta mit-talba u l-valur issejvjat:

Livell	Meta	Risposta
`blocked`	kuntrast taħt 1.5:1	`422`, xejn ma jiġi ssejvjat
`critical`	taħt 2:1 jew differenza fil-luminożità taħt 0.30; twissija flimkien ma’ logo; kwalunkwe sfond trasparenti	`200` b’`meta.issues`
`warning`	taħt 4:1 jew differenza fil-luminożità taħt 0.50; moduli ċari fuq sfond skur	`200` b’`meta.issues`
ok	kull ħaġa oħra	`200`, `meta.issues` huwa vojt

Kull dħul f’meta.issues għandu code, severity, field, message u b’mod mhux obbligatorju hints bħal contrast_ratio — l-istess format bħan-notifiki ta’ konformità ta’ Passaport Diġitali tal-Prodott. Sfond trasparenti qatt ma jiġi bblokkat, peress li kodiċi ċar fuq ippakkjar skur huwa każ ta’ użu reali. Madankollu, l-isfond xorta waħda għandu bżonn kuntrast ċar u żona kwieta libera ta’ 4 moduli madwaru kollu.

It-tlugħ u t-tneħħija ta’ logo (POST u DELETE /v1/codes/:id/logo) jiċċekkjaw il-kuluri ffrankati bl-istess mod u jibagħtu wkoll is-sejbiet f’meta.issues: b’logo twissija ssir critical, mingħajr logo terġa’ ssir twissija.

Jekk talba oħra timmodifika l-istess kodiċi fl-istess mument, l-API tapplika l-bidliet fuq l-aktar stat reċenti. Biss jekk dan ifalli tliet darbiet konsekuttivi, hija twieġeb b’409; il-klijent imbagħad jerġa’ jġib il-kodiċi u jirrepeti l-bidla.

Logo

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

Talba multipart, qasam file: PNG, JPEG jew WebP, massimu ta’ 1 MB, identifikat mill-Magic Bytes. Jinnormalizza l-immaġni għal PNG trasparenti ta’ 512×512 u jissostitwixxi logo eżistenti.

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

Risposta (HTTP 201): il-kodiċi aġġornat, b’ logo_file_id issettjat.

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

Ineħħi l-logo u jħassar l-oġġett maħżun. Idempotenti — sejħa mingħajr logo eżistenti xorta waħda tirritorna 200.

Jekk talba oħra tbiddel il-logo tal-istess kodiċi fl-istess mument (it-tieni upload jew tneħħija), POST u DELETE /v1/codes/:id/logo jirritornaw 409 (errors/conflict) u ma jibdlu xejn; immaġni mtellgħa tiġi skartata. Erġa’ ġib il-kodiċi u pprova mill-ġdid. Żewġ sejħiet simultanji ta’ DELETE /v1/codes/:id/logo mhumiex kunflitt; it-tnejn jirritornaw 200.

Jekk ikun issettjat, l-erba’ formati kollha — qr.svg, qr.png, qr.pdf u qr.eps — jinkorporaw il-pixels tal-logo u jgħollu l-korrezzjoni tal-iżbalji għal H. Il-kuntratt sħiħ — inkluż liema bidla (żieda/tneħħija vs. sostituzzjoni) tbiddel il-mudell tal-punti — kif ukoll struzzjonijiet tal-istampar jinsabu taħt Logo fil-kodiċi QR.

Kummenti

Il-kummenti jippermettu feedback kontinwu bejn l-aġenziji u l-klijenti.

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

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

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

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

Il-kummenti tad-Dashboard huma attribwiti lill-utent li ħalaqhom (author_id); il-kummenti maħluqa permezz ta’ API keys sempliċi jibqgħu mhux attribwiti (author_id: null). Kumment jista’ jitħassar biss mill-awtur tiegħu stess jew minn org_admin/ws_admin — API keys sempliċi jistgħu jħassru biss kummenti tal-API li mhumiex attribwiti.

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