API Codici QR

Panoramica

L’API dei codici è il cuore di qr3.app. Ti consente di creare, aggiornare e eliminare codici QR dinamici e statici.

URL di base: https://qr3.app/v1/codes

Creare un codice QR

`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

Risposta (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 di codici QR

Tipo	Descrizione	Campi obbligatori
`url`	URL del sito web (dinamico o statico)	`url`
`vcard`	Biglietto da visita (vCard 3.0)	`vcard_first_name` o `vcard_last_name`
`wifi`	Configurazione Wi-Fi	`wifi_ssid`
`email`	E-mail (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Posizione (geo:)	`location_lat`, `location_lng`

Test A/B

Testa due diversi URL di destinazione con reindirizzamento ponderato:

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

Scadenza (Expiry)

I codici QR possono scadere automaticamente:

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

Dopo la scadenza, l’utente viene reindirizzato a redirect_after_expiry oppure viene mostrata una pagina 410.

Creazione batch

`POST /v1/codes/batch`

Crea fino a 1.000 codici QR in una singola richiesta. Ideale per applicazioni di 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
  }'

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

Elenco dei codici QR

`GET /v1/codes`

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

Parametri di query:

Parametro	Tipo	Predefinito	Descrizione
`cursor`	string	—	Cursore per la paginazione
`limit`	integer	20	Risultati per pagina (max. 100)
`status`	string	—	Filtro: `live`, `paused`, `flagged`, `draft`

Recuperare un codice QR

`GET /v1/codes/:id`

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

Aggiornare un codice QR

`PATCH /v1/codes/:id`

I codici QR dinamici consentono di modificare l’URL di destinazione in qualsiasi momento, senza dover ristampare il codice QR.

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 e link esterni

Per i codici url dinamici, puoi impostare is_landing_page: true (durante la creazione o tramite PATCH). Una scansione mostrerà quindi una pagina ospitata da qr3 con i file pubblici e i link esterni del codice, invece di reindirizzare. I link esterni vengono passati come array links :

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

Da 0 a 20 link per codice; label deve essere compreso tra 1 e 100 caratteri; url deve essere http(s) (≤ 2048 caratteri).
Ogni URL viene verificato con Google Web Risk — un URL non sicuro restituisce 422.
Se Web Risk non è raggiungibile al momento del salvataggio, il link viene comunque accettato, ma contrassegnato per una nuova verifica. Un processo giornaliero ricontrolla i link salvati (e periodicamente quelli classificati come sicuri) e mette in pausa automaticamente il codice se un link viene successivamente rilevato come non sicuro.
"links": [] elimina tutti i link. Consulta la guida alle landing page.

Eliminare un codice QR

`DELETE /v1/codes/:id`

Soft-delete — il codice QR viene archiviato, i dati di scansione vengono conservati.

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

Scaricare le immagini dei codici QR

Tutti i formati di immagine sono accessibili pubblicamente — non è richiesta alcuna autenticazione.

Formato	URL	Utilizzo
SVG (vettoriale)	`/v1/codes/:code/qr.svg`	Web, ridimensionamento, digitale
PNG (raster)	`/v1/codes/:code/qr.png`	E-mail, presentazioni
PDF (vettoriale)	`/v1/codes/:code/qr.pdf`	Predefinito: quadrato (solo il codice); `?format=a4` per un foglio di stampa
EPS (vettoriale)	`/v1/codes/:code/qr.eps`	Flussi di lavoro di stampa professionali (Adobe, tipografie)

Opzionale: ?size=N — dimensione del modulo in pixel (2–20, predefinito: 4) per SVG, PNG ed EPS. Il PDF utilizza una dimensione del modulo fissa.

Solo PDF: ?format=a4|square — formato di pagina (predefinito: square — solo codice + quiet zone, senza spazio bianco A4; a4 per un foglio A4 pronto per la stampa)

# 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

Commenti

I commenti consentono cicli di feedback tra agenzie e clienti.

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