API QR-Codes

Contrat REST de référence

Le contrat suivant s’applique à tous les clients :

POST /v1/codes accepte uniquement les types url, vcard, wifi, email, sms et location. Les champs sont plats : url ; au moins vcard_first_name ou vcard_last_name ; wifi_ssid ; email_to ; sms_phone ; ou location_lat et location_lng.
Seuls les codes url peuvent être dynamiques. Les requêtes de création peuvent facultativement inclure expires_at sous la forme d’un horodatage ISO 8601 ; ab_enabled, ab_target_url_b et ab_weight_a (destinations A/B) sont acceptés pour les codes url dynamiques ; redirect_after_expiry ne fait pas partie du contrat de création.
GET /v1/codes ne prend en charge que limit, cursor et status (live, paused, flagged, draft).
POST /v1/codes/batch accepte url, vcard et wifi. La limite est de 10 pour Free, 500 pour Pro et 1 000 enregistrements pour Business/Agency/Enterprise par requête. Les analyses d’URL s’exécutent de façon synchrone pour 50 éléments URL au maximum ; au-delà, skip_url_scan: true est nécessaire.

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`

Création par lot (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
  }'

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`

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.

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