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

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`

Ittestjar A/B

Ittestja żewġ URLs ta’ destinazzjoni differenti b’ridirezzjoni ppeżata:

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

Skadenza (Expiry)

Il-QR codes jistgħu jiskadu awtomatikament:

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

Wara l-iskadenza, l-utent jiġi ridirezzjonat lejn redirect_after_expiry jew tintwera paġna 410.

Ħolqien f’Daqqa (Batch)

`POST /v1/codes/batch`

Joħloq sa 1,000 QR code f’talba waħda. Ideali għal applikazzjonijiet tal-massa.

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`

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.

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

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`

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