API QR-Codes

Aperçu

L’API Codes est au cœur de qr3.app. Elle vous permet de créer, mettre à jour et supprimer des QR-Codes dynamiques et statiques.

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

Créer un 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

Réponse (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" }
}

Types de QR-Codes

Type	Description	Champs obligatoires
`url`	URL de site web (dynamique ou statique)	`url`
`vcard`	Carte de visite (vCard 3.0)	`vcard_first_name` ou `vcard_last_name`
`wifi`	Configuration Wi-Fi	`wifi_ssid`
`email`	E-mail (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Localisation (geo:)	`location_lat`, `location_lng`

Tests A/B

Testez deux URL de destination différentes avec une redirection pondérée :

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

Expiration (Expiry)

Les QR-Codes peuvent expirer automatiquement :

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

Après expiration, l’utilisateur est soit redirigé vers redirect_after_expiry, soit une page 410 est affichée.

Création par lot (Batch)

`POST /v1/codes/batch`

Crée jusqu’à 1 000 QR-Codes en une seule requête. Idéal pour les applications de masse.

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

Réponse (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
  }
}

Liste des QR-Codes

`GET /v1/codes`

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

Paramètres de requête (Query Parameters) :

Paramètre	Type	Par défaut	Description
`cursor`	string	—	Curseur pour la pagination
`limit`	integer	20	Résultats par page (max. 100)
`status`	string	—	Filtre : `live`, `paused`, `flagged`, `draft`

Récupérer un QR-Code

`GET /v1/codes/:id`

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

Mettre à jour un QR-Code

`PATCH /v1/codes/:id`

Les QR-Codes dynamiques permettent de modifier l’URL de destination à tout moment — sans avoir à réimprimer le 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" }'

Page d’atterrissage (Landing page) & liens externes

Pour les codes url dynamiques, vous pouvez définir is_landing_page: true (lors de la création ou via PATCH). Un scan affichera alors une page hébergée par qr3 contenant les fichiers publics et les liens externes du code, au lieu de rediriger. Les liens externes sont transmis sous forme de tableau links :

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

0 à 20 liens par code ; label doit faire entre 1 et 100 caractères ; url doit être au format http(s) (≤ 2048 caractères).
Chaque URL est vérifiée avec Google Web Risk — une URL non sécurisée renvoie une erreur 422.
Si Web Risk n’est pas accessible lors de l’enregistrement, le lien est tout de même accepté, mais marqué pour une nouvelle vérification. Une tâche quotidienne vérifie à nouveau les liens enregistrés (et réévalue régulièrement les liens classés comme sûrs) et suspend automatiquement le code si un lien est ultérieurement détecté comme non sécurisé.
"links": [] supprime tous les liens. Voir le guide de la page d’atterrissage.

Supprimer un QR-Code

`DELETE /v1/codes/:id`

Soft-delete (suppression logique) — le QR-Code est archivé, les données de scan sont conservées.

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

Télécharger les images de QR-Codes

Tous les formats d’image sont accessibles publiquement — aucune authentification n’est requise.

Format	URL	Utilisation
SVG (vectoriel)	`/v1/codes/:code/qr.svg`	Web, mise à l’échelle, numérique
PNG (matriciel)	`/v1/codes/:code/qr.png`	E-mail, présentations
PDF (vectoriel)	`/v1/codes/:code/qr.pdf`	Par défaut : carré (uniquement le code) ; `?format=a4` pour une feuille d’impression
EPS (vectoriel)	`/v1/codes/:code/qr.eps`	Flux de travail d’impression professionnels (Adobe, imprimeries)

Optionnel : ?size=N — Taille du module en pixels (2–20, par défaut : 4) pour SVG, PNG et EPS. Le PDF utilise une taille de module fixe.

Uniquement PDF : ?format=a4|square — Format de page (par défaut : square — uniquement le code + zone de silence, pas de marge blanche A4 ; a4 pour une feuille A4 prête à imprimer)

# 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

Commentaires

Les commentaires permettent des boucles de rétroaction entre les agences et les clients.

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