API Cód QR

Foramharc

Is í an Codes-API croílár qr3.app. Leis seo, is féidir leat cóid QR dhinimiciúla agus statacha a chruthú, a thabhairt cothrom le dáta agus a scriosadh.

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

Conradh REST ceangailteach

Baineann an conradh seo a leanas le gach cliant:

Ní ghlacann POST /v1/codes ach leis na cineálacha url, vcard, wifi, email, sms agus location. Tá na réimsí cothrom: url; vcard_first_name nó vcard_last_name ar a laghad; wifi_ssid; email_to; sms_phone; nó location_lat agus location_lng araon.
Ní féidir ach cóid url a bheith dinimiciúil. Féadfaidh iarratais chruthaithe expires_at a áireamh go roghnach mar stampa ama ISO 8601; Glactar le ab_enabled, ab_target_url_b agus ab_weight_a (cinn scríbe A/B) do chóid url dhinimiciúla; ní cuid den chonradh cruthaithe é redirect_after_expiry.
Ní thacaíonn GET /v1/codes ach le limit, cursor agus status (live, paused, flagged, draft).
Glacann POST /v1/codes/batch le url, vcard agus wifi. Is é an teorainn ná 10 do Free, 500 do Pro, agus 1,000 taifead do Business/Agency/Enterprise in aghaidh na hiarrata. Ritheann scananna URL go sioncronach do 50 mír URL ar a mhéad; os cionn 50, tá skip_url_scan: true riachtanach.

Cód QR a Chruthú

`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

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

Cineálacha Cód QR

Cineál	Cur síos	Réimsí éigeantacha
`url`	URL suímh ghréasáin (dinimiciúil nó statach)	`url`
`vcard`	Cárta gnó (vCard 3.0)	`vcard_first_name` nó `vcard_last_name`
`wifi`	Cumraíocht Wi-Fi	`wifi_ssid`
`email`	Ríomhphost (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Suíomh (geo:)	`location_lat`, `location_lng`

Baisc-chruthú

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

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

Liosta Cód QR

`GET /v1/codes`

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

Paraiméadair Query:

Paraiméadar	Cineál	Réamhshocrú	Cur síos
`cursor`	string	—	Cúrsóir le haghaidh leathanachúcháin
`limit`	integer	20	Torthaí in aghaidh an leathanaigh (uas. 100)
`status`	string	—	Scagaire: `live`, `paused`, `flagged`, `draft`

Cód QR a Fháil

`GET /v1/codes/:id`

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

Cód QR a Nuashonrú

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

Ligeann cóid QR dhinimiciúla duit an sprioc-URL a athrú ag am ar bith — gan gá an cód QR a athphriontáil.

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

Leathanach Tuirlingthe & Naisc Sheachtracha

I gcás cóid url dhinimiciúla, is féidir leat is_landing_page: true a shocrú (le linn cruthaithe nó trí PATCH). Taispeánfaidh scanadh ansin leathanach arna óstáil ag qr3 ina bhfuil comhaid phoiblí agus naisc sheachtracha an chóid, in ionad ródú ar aghaidh. Seoltar naisc sheachtracha mar eagar links:

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

0–20 nasc in aghaidh an chóid; tá label idir 1–100 carachtar; caithfidh url a bheith mar http(s) (≤ 2048 carachtar).
Déantar gach URL a sheiceáil le Google Web Risk — seolann URL neamhshábháilte 422 ar ais.
Mura bhfuil Web Risk inrochtana le linn sábhála, glacfar leis an nasc mar sin féin, ach marcálfar é le haghaidh athsheiceála. Déanann post laethúil athsheiceáil ar naisc shábháilte (agus déanann sé athsheiceáil rialta ar naisc a rangaíodh mar ghlan) agus cuireann sé an cód ar sos go huathoibríoch má aimsítear go bhfuil nasc neamhshábháilte níos déanaí.
"links": [] scriosann gach nasc. Féach ar an treoir leathanach tuirlingthe.

Cód QR a Scriosadh

`DELETE /v1/codes/:id`

Scriosadh bog (Soft-Delete) — déantar an cód QR a chartlannú, coinnítear sonraí scanadh.

Seolann dara DELETE ar an gcód céanna 404 ar ais, fiú má thagann an dá iarratas ag an am céanna. Seoltar an webhook qr.deleted go díreach uair amháin.

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

Íomhánna QR a Íoslódáil

Tá gach formáid íomhá inrochtana go poiblí — níl aon fhíordheimhniú ag teastáil.

Formáid	URL	Úsáid
SVG (Veicteoir)	`/v1/codes/:code/qr.svg`	Gréasán, Scálú, Digiteach
PNG (Rastar)	`/v1/codes/:code/qr.png`	Ríomhphost, Cur i láthair
PDF (Veicteoir)	`/v1/codes/:code/qr.pdf`	Réamhshocrú: cearnach (an cód amháin); `?format=a4` le haghaidh bileog priontála
EPS (Veicteoir)	`/v1/codes/:code/qr.eps`	Sreafaí oibre priontála gairmiúla (Adobe, clódóirí)

Roghnach: ?size=N — Méid an mhodúil i bpicteilíní (2–20, Réamhshocrú: 4) do SVG, PNG agus EPS. Úsáideann an PDF méid modúil seasta.

PDF Amháin: ?format=a4|square — Formáid leathanaigh (Réamhshocrú: square — cód + Quiet Zone amháin, gan spás bán A4; a4 le haghaidh bileog A4 réidh le priontáil)

# 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

Dathanna agus Ceartú Earráidí

Glacann na ceithre bhealach íomhá go léir le trí pharaiméadar roghnacha. Baineann siad leis an aisghabháil shonrach seo agus tá tosaíocht acu ar dhathanna atá sábháilte ar an gcód (an chéad rannán eile).

Paraiméadar	Luachanna	Réamhshocrú	SVG, PNG	PDF, EPS
`fg`	Heics `RRGGBB` nó `RGB`	`000000`	tarraingthe	tarraingthe mar dhath clódóireachta
`bg`	Heics cosúil le `fg` nó `transparent`	`ffffff`	tarraingthe	tarraingthe mar dhath clódóireachta
`ecc`	`L`, `M`, `Q`, `H`	`M`	i bhfeidhm	i bhfeidhm

Litriú: Is cuma faoi chás na litreacha (mór nó beag), tá an # roghnach. Má sheoltar é, códaigh mar %23 é.
Áirítear luachanna neamhbhailí mar luachanna nach bhfuil socraithe. Seolann ?fg=lila an dath atá stóráilte ar an gcód ar ais, nó an gnáthdhath dubh mura bhfuil aon dath stóráilte, le 200 agus ní sheoltar earráid choíche. Ní chuireann ach ?fg=000000 sainráite dath dubh i bhfeidhm.
bg=transparent seolann sé SVG, PDF nó EPS gan chúlra agus PNG le fíor-chainéal alfa. Caithfidh an dromchla ar a gcuirtear an cód a bheith geal agus crios ciúnais de 4 mhodúl a fhágáil saor ar gach taobh. Níl cód dorcha ar dhromchla dorcha inléite.
Scríobhann PDF agus EPS dubh agus liath mar liathscála (pláta dubh amháin) agus aon dath eile mar CMYK i gcéatadáin iomlána, mar shampla 1F4E79 mar C74 M36 Y0 K53. Chomh luath agus a roghnaítear dath, bíonn líonadh teimhneach taobh thiar den chód agus dá chrios ciúnais, bán nó i ndath bg, mar atá sa SVG. Gan dathanna, fanann an dá chomhad gan athrú. Tiontú agus teorainneacha: Dathanna sa Chló.
Codarsnacht: Ní sheiceálann bealach na híomhá í. Moltar 4:1 ar a laghad agus modúil dhorcha ar chúlra geal. Tá 8,7:1 ag #1F4E79 ar bhán, ach níl ach 2,9:1 ag #ff6600 ar bhán.
ecc athraíonn sé an patrún poncanna, ní an t-ábhar. Leanann cód clóite ag feidhmiú, ach ná measc seanchomhaid chlóite agus comhaid nua. Déanann Q nó H an cód níos daingne, mar shampla ar chairtchlár rocach. Éilíonn lógó H i gcónaí.
Le lógó fanann an limistéar taobh thiar den lógó bán, fiú le cúlra daite nó trédhearcach.
Taisce: Ní sheoltar ach an fíor-íomhá chaighdeánach (dubh ar bhán, ceartú earráidí M, gan lógó) mar íomhá dho-athraithe ar feadh 24 uair an chloig; gach rindreáil eile ar feadh 5 nóiméad. Maidir le PDF agus EPS, áirítear aon chúlra sonraithe mar dhiall: tarraingíonn bg=ffffff líonadh bán ansin nach bhfuil ag an gcomhad caighdeánach.
Plean: Tá dathanna agus ceartú earráidí ar fáil i ngach plean, lena n-áirítear an plean saor in aisce.

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

Dathanna a shábháil ar an gcód

Sábhálann PATCH /v1/codes/:id dathanna mar appearance ar an gcód. Tarraingíonn na ródanna íomhá iad mar réamhshocrú ansin, gan pharaiméadair.

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

Freagra (HTTP 200, giorraithe):

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

Luachanna: foreground_color mar #RRGGBB, background_color mar #RRGGBB nó transparent. Ginfidh eochracha eile 400.
Cumasc: Coinníonn réimse a fágadh ar lár a luach sábháilte. Athshocraíonn null réimse amháin, athshocraíonn "appearance": null an dá réimse. Ní shábháiltear dubh agus bán; taispeánann an freagra iad mar null.
Tá appearance i ngach freagra cóid, chomh maith leis na webhooks qr.created agus qr.updated.
Ord sna ródanna íomhá: an paraiméadar ar dtús, ansin an dath sábháilte, ansin an réamhshocrú. Sin an fáth a soláthraíonn ?fg=000000 an comhad priontála dubh de chód daite.
Íomhánna leabaithe: Leanann URL íomhá na dathanna atá stóráilte chomh fada is nach socróidh sé féin iad le fg agus bg: URL gan pharaiméadair don dá dhath, ?fg=000000 don chúlra, ?ecc=Q don dá dhath chomh maith. Tar éis athrú datha, is féidir le leathanach a leabaíonn URL den sórt sin an seanimhá a thaispeáint fós: ar feadh suas le 24 uair an chloig má sheol an URL an réamhíomhá ar ais go dtí sin (dubh ar bhán, ceartú earráidí M, gan lógó), nó ar feadh suas le 5 nóiméad seachas sin. Is é an leigheas ná do pharaiméadar féin ar an URL a athraíonn le gach athrú datha, mar shampla ?v=2 nó updated_at an chóid mar atá sa deais. Déanann na ródanna íomhá neamhaird ar pharaiméadair anaithnide.
Ní shábháiltear ceartúchán earráidí choíche. Roghnaítear é in aghaidh an íoslódála le ?ecc=.
Trí PATCH amháin: Diúltaíonn POST /v1/codes, an baisc-phróiseas agus an t-allmhairiú do appearance le 422.
Tarraingíonn PDF agus EPS dathanna sábháilte mar dhathanna cló, díreach cosúil leis na paraiméadair. Toisc nach sábháiltear bán riamh, faigheann cód a bhfuil dath tulra sábháilte aige líonadh bán ansin, mar atá sa SVG.

Seiceáil codarsnachta

Seiceálann an API an péire a thagann as an iarratas agus as an luach sábháilte:

Leibhéal	Cathain	Freagra
`blocked`	Codarsnacht faoi bhun 1.5:1	`422`, ní shábháiltear aon rud
`critical`	faoi bhun 2:1 nó difríocht gile faoi bhun 0.30; rabhadh in éineacht le lógó; aon chúlra trédhearcach	`200` le `meta.issues`
`warning`	faoi bhun 4:1 nó difríocht gile faoi bhun 0.50; modúil gheala ar chúlra dorcha	`200` le `meta.issues`
ok	gach rud eile	`200`, tá `meta.issues` folamh

Tá code, severity, field, message agus, de rogha air sin, hints cosúil le contrast_ratio ag gach iontráil in meta.issues — an fhormáid chéanna le teachtaireachtaí comhlíonta de chuid pas táirge digiteach. Ní chuirtear bac ar chúlra trédhearcach choíche, toisc gur cás úsáide réadúil é cód geal ar phacáistíocht dhorcha. Mar sin féin, teastaíonn codarsnacht shoiléir ón dromchla agus limistéar ciúin saor de 4 mhodúl timpeall air.

Déanann uaslódáil agus baint lógó (POST agus DELETE /v1/codes/:id/logo) na dathanna stóráilte a sheiceáil ar an mbealach céanna agus seolann siad na torthaí ar ais in meta.issues freisin: le lógó déantar critical de rabhadh, gan lógó is rabhadh é arís.

Má athraíonn iarratas eile an cód céanna ag an am céanna, cuireann an API na hathruithe i bhfeidhm ar an leagan is déanaí. Mura n-éiríonn leis sin trí huaire as a chéile, freagraíonn sé le 409; déanann an cliant an cód a athlódáil ansin agus déanann sé an t-athrú arís.

Logo

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

Iarratas Multipart, réimse file: PNG, JPEG nó WebP, uasmhéid 1 MB, braite de réir na magic bytes. Normalaíonn sé an íomhá go dtí 512×512-PNG trédhearcach agus athsholáthraíonn sé lógó reatha.

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

Freagra (HTTP 201): an cód nuashonraithe, le logo_file_id socraithe.

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

Baineann sé an lógó agus scriosann sé an réad stóráilte. Idempótentach — filleann glao gan lógó reatha 200 i gcónaí.

Má athraíonn iarratas eile lógó an chóid chéanna ag an am céanna (dara uaslódáil nó baint), freagraíonn POST agus DELETE /v1/codes/:id/logo le 409 (errors/conflict) agus ní athraíonn siad aon rud; déantar íomhá uaslódáilte a chaitheamh i leataobh. Athlódáil an cód agus bain triail as arís. Ní coinbhleacht iad dhá ghlao chomhuaineacha ar DELETE /v1/codes/:id/logo; filleann an dá cheann 200.

Má tá sé socraithe, leabaíonn na ceithre fhormáid ar fad — qr.svg, qr.png, qr.pdf agus qr.eps — picteilíní an lógó agus ardaíonn siad an ceartúchán earráide go H. Tá an conradh iomlán — lena n-áirítear cén t-athrú (cur leis/baint chun siúil vs. athsholáthar) a athraíonn an patrún poncanna — chomh maith le treoracha priontála, le fáil faoi Lógó sa Chód QR.

Tráchtanna

Cumasaíonn tráchtanna lúba aiseolais idir gníomhaireachtaí agus cliaint.

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

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

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

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

Sannfar tráchtanna a chruthaítear sa Deais don úsáideoir a chruthaigh iad (author_id); fanann tráchtanna a chruthaítear le heochracha API simplí gan sannadh (author_id: null). Ní fhéadfaidh ach an t-údar féin nó org_admin/ws_admin trácht a scriosadh — ní féidir le heochracha API simplí ach tráchtanna API gan sannadh a scriosadh.

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