QR codes - GetQR Docs

L’API GetQR est en version bêta et réservée à certains espaces de travail. Certains détails peuvent changer avant la disponibilité générale.

Dans GetQR, un QR code est une image associée à un lien court par lequel il est résolu. La création d’un QR code crée aussi son lien court : vous pouvez donc changer la destination plus tard sans réimprimer le code.

Méthode	Chemin	Description
`GET`	`/api/v1/qrs`	Lister les QR codes
`POST`	`/api/v1/qrs`	Créer un QR code
`GET`	`/api/v1/qrs/{qrId}`	Récupérer un QR code
`PATCH`	`/api/v1/qrs/{qrId}`	Modifier un QR code
`PUT`	`/api/v1/qrs/{qrId}`	Définir l’état de pause
`POST`	`/api/v1/qrs/{qrId}/pause`	Mettre un QR code en pause
`POST`	`/api/v1/qrs/{qrId}/activate`	Réactiver un QR code
`POST`	`/api/v1/qrs/{qrId}/duplicate`	Dupliquer un QR code
`DELETE`	`/api/v1/qrs/{qrId}`	Supprimer un QR code
`GET`	`/api/v1/qrs/{qrId}/download`	Télécharger l’image d’un QR code

Données des QR codes par type

Le format de data pour chacun des 16 types.

Personnalisation

Styles de points, couleurs, cadres et logos.

Règles d'accès

Programmation, limite de scans et mot de passe.

Pour les statistiques de scans d’un QR code, consultez Statistiques.

L’objet QR code

Tous les endpoints de QR codes répondent avec cet objet, sauf Supprimer et Télécharger. La liste en renvoie un tableau.

string

ID unique du QR code, par exemple qr_1EPcVfeHZAY2iNoVLsgW2Aqf.

string

Type du QR code, par exemple website. Consultez Données des QR codes par type pour les 16 valeurs.

string | null

Nom du QR code, affiché dans le tableau de bord.

string | null

Note libre sur le QR code.

string

Le payload stocké. Pour wifi, vcard, social, multilink, event et sms, c’est le payload que vous avez envoyé. Pour tous les autres types, c’est le lien court : lisez donc la destination dans url.

boolean

true quand le QR code est en pause.

boolean

true pour un QR code statique créé dans le tableau de bord, qui n’a pas de lien court. L’API crée toujours des QR codes dynamiques.

string | null

Lien court complet, par exemple https://getqr.sh/x7Kd2p1.

string | null

Domaine du lien court.

string | null

Slug du lien court.

boolean

true quand le slug a été choisi plutôt que généré.

string | null

Destination vers laquelle redirige le lien court.

string | null

Destination des visiteurs iOS, pour les QR codes app.

string | null

Destination des visiteurs Android, pour les QR codes app.

integer

Nombre total de scans.

object

Règles d’accès. Le mot de passe lui-même n’est jamais renvoyé. Consultez Règles d’accès.

Afficher properties

boolean

Indique si les visiteurs doivent saisir un mot de passe.

string | null

Début programmé, ISO 8601.

string | null

Fin programmée, ISO 8601.

integer | null

Nombre maximal de scans.

string

Lecture seule. custom est un design que l’API peut modifier entièrement. branded et ai sont un Branded design ou un AI design créé dans le tableau de bord. L’API ne peut pas modifier son image, mais la conserve quand vous modifiez d’autres champs.

object

Le design enregistré : styles, frameOptions et logoOptions, chacun étant un objet ou null. Ils ont la même structure que les champs de la requête : vous pouvez donc les renvoyer tels quels. Consultez Personnalisation.

object | null

Le fichier d’un QR code pdf, image ou video : id, name et size en octets.

string | null

Lecture seule. Nom affiché d’un QR code app créé dans le tableau de bord.

object | null

Lecture seule. Un QR code pdf avec plusieurs fichiers, créé dans le tableau de bord : title, layout et files.

object | null

Lecture seule. Un QR code image avec plusieurs images, créé dans le tableau de bord : title, layout et files.

string

Date de création, ISO 8601.

string

Date de dernière mise à jour, ISO 8601.

Les secrets et les ID internes (password, userId, workspaceId, projectId) ne sont jamais renvoyés.

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "description": null,
  "data": "https://getqr.sh/x7Kd2p1",
  "archived": false,
  "isStatic": false,
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "domain": "getqr.sh",
  "key": "x7Kd2p1",
  "keyIsCustom": false,
  "url": "https://example.com",
  "ios": null,
  "android": null,
  "scans": 128,
  "access": {
    "passwordProtected": false,
    "activeAt": null,
    "pauseAt": null,
    "scanLimit": null
  },
  "designKind": "custom",
  "design": {
    "styles": { "dotsOptions": { "type": "rounded", "color": "#1E40AF" }, … },
    "frameOptions": { "id": "card", "text": "Scan me!", … },
    "logoOptions": { "type": "suggested", "id": "logo-website-3", "scalePercent": 25 }
  },
  "file": null,
  "appName": null,
  "pdfBundle": null,
  "imageGallery": null,
  "createdAt": "2026-08-01T10:00:00.000Z",
  "updatedAt": "2026-08-01T10:00:00.000Z"
}

Lister les QR codes

GET /api/v1/qrs Renvoie les QR codes de votre espace de travail, une page à la fois.

integer

défaut:"1"

Page à renvoyer, 1 ou plus.

integer

défaut:"100"

QR codes par page, de 1 à 100. Une valeur plus grande est refusée.

string

Recherche dans le titre du QR code. Les recherches de plus de 2 caractères portent aussi sur le data stocké. Pour les types de lien, le data stocké est le lien court : les URL de destination ne sont donc pas recherchables.

string

défaut:"createdAt"

Champ de tri : createdAt, updatedAt, clicks (total des scans), lastClicked (dernier scan) ou type. type trie toujours par ordre décroissant et ignore sortOrder.

string

défaut:"desc"

Ordre de tri : asc ou desc.

boolean

défaut:"false"

Inclure les QR codes en pause.

boolean

défaut:"false"

Renvoyer uniquement les QR codes en pause. Prioritaire sur showArchived.

Les paramètres booléens prennent les chaînes true ou false. Demandez la page suivante tant que pagination.hasMore vaut true. Consultez Pagination.

curl "https://getqr.com/api/v1/qrs?page=1&pageSize=100" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "data": [
    {
      "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
      "qrType": "website",
      "title": "Landing page",
      "shortLink": "https://getqr.sh/x7Kd2p1",
      "url": "https://example.com",
      "scans": 128,
      "…": "…"
    }
  ],
  "pagination": { "page": 1, "pageSize": 100, "total": 1, "hasMore": false }
}

Créer un QR code

POST /api/v1/qrs Crée un QR code et son lien court en même temps. Répond 201 Created avec le nouveau QR code.

string

Votre propre jeton de nouvelle tentative. Répéter la requête avec la même clé dans les 24 heures renvoie la réponse d’origine au lieu de créer un second QR code. Consultez Nouvelles tentatives et doublons.

string

requis

Ce qu’encode le QR code. Détermine aussi le format attendu pour data. L’une des valeurs website, pdf, image, video, whatsapp, social, wifi, app, feedback, vcard, sms, payment, location, multilink, email, event.

string

requis

Le payload du type, vérifié selon qrType. Une chaîne vide saute la vérification. Le format de chaque type se trouve dans Données des QR codes par type.

object

Le lien court par lequel le QR code est résolu. Facultatif : s’il est omis, link.url suit data.

Afficher properties

string

Destination vers laquelle redirige le lien court. Omise ou vide, elle prend par défaut la valeur de data. Si les deux sont envoyés et diffèrent, link.url l’emporte. Les QR codes vcard, social, multilink et event pointent toujours vers leur page hébergée, et les QR codes pdf, image et video avec un fileId vers le fichier. Schémas acceptés : http:, https:, wifi:, mailto:, sms:, begin:.

string

Domaine du lien court. Il doit s’agir d’un domaine actif de votre espace de travail : un autre domaine renvoie 403, et un domaine pas encore actif renvoie 422. Par défaut, le domaine par défaut de l’espace de travail.

string

Slug du lien court, de 3 à 15 caractères, stocké en minuscules. Un slug non autorisé renvoie 422, et un slug déjà pris renvoie 409. S’il est omis, un slug aléatoire de 7 caractères est généré.

string | null

URL de destination pour les visiteurs sur iOS, pour les QR codes app.

string | null

URL de destination pour les visiteurs sur Android, pour les QR codes app.

string | null

Titre de l’aperçu du lien (og:title), stocké sur le lien court. Différent du title du QR code lui-même. Rien ne l’affiche pour l’instant.

string | null

Description de l’aperçu du lien (og:description), stockée sur le lien court. Rien ne l’affiche pour l’instant.

—

Non disponibles dans cette API : envoyer l’un ou l’autre renvoie 422. Utilisez access.pauseAt pour arrêter le QR code à un moment donné.

string

Nom du QR code, affiché dans le tableau de bord. Espaces superflus supprimés, de 1 à 40 caractères. S’il est omis, le QR code n’a pas de titre.

string

Note libre sur le QR code. Jusqu’à 280 caractères.

string

Le fichier d’un QR code pdf, image ou video, importé avec la cible correspondante. Pour vcard, social et multilink, une image de profil facultative importée avec la cible logo. event l’accepte aussi, mais sa page lit la couverture dans data.fileId. Les autres types renvoient 422. Importez d’abord le fichier avec Fichiers. Consultez Fichiers dans les QR codes.

string

Modèle dont le design est appliqué au nouveau QR code. Les champs de design que vous envoyez sont fusionnés par-dessus. Un modèle Branded design ou AI design renvoie 422 (art_template_unsupported). Un modèle inconnu, ou provenant d’un autre espace de travail, renvoie 404.

object

Formes et couleurs des points et des coins. Consultez Personnalisation.

object

Cadre dessiné autour du QR code et son texte d’appel à l’action. Consultez Personnalisation.

object

Logo au centre : un logo suggéré ou votre propre fichier importé avec la cible logo. Un fichier inconnu, un import inachevé ou un fichier d’une autre cible est refusé. Consultez Personnalisation.

object

Programmation, limite de scans et protection par mot de passe. Consultez Règles d’accès.

Afficher properties

string | null

Début programmé, ISO 8601.

string | null

Fin programmée, ISO 8601.

integer | null

Nombre maximal de scans, un entier positif.

string | null

Mot de passe que les visiteurs doivent saisir. L’envoyer active la protection.

boolean

Désactive ou réactive la protection, en conservant le mot de passe enregistré.

boolean

Indique si le QR code est en pause. true le crée en pause : les scans affichent la page de pause au lieu de la destination.

Les champs inconnus sont ignorés sans erreur. Consultez Non pris en charge par l’API.

curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: landing-page-2026-08" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page",
    "access": { "scanLimit": 500 }
  }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "qrType": "website",
  "title": "Landing page",
  "data": "https://getqr.sh/x7Kd2p1",
  "shortLink": "https://getqr.sh/x7Kd2p1",
  "url": "https://example.com",
  "scans": 0,
  "access": { "passwordProtected": false, "activeAt": null, "pauseAt": null, "scanLimit": 500 },
  "…": "…"
}

Nouvelles tentatives et doublons

Avec une clé. Avec un en-tête Idempotency-Key, la réponse est rejouée pendant 24 heures.
Sans clé. Un corps identique envoyé dans les 30 secondes est traité comme un doublon.
Rejeux. Un rejeu renvoie la réponse stockée avec x-idempotent-replay: true. Un nouveau QR code renvoie false.
En cours. Une seconde requête envoyée pendant que la première est encore en cours renvoie 409 conflict.
Échecs. Une création échouée libère immédiatement la clé : vous pouvez donc réessayer avec la même clé.
Au mieux. Si cette protection est indisponible, les créations passent sans protection.

Consultez aussi Idempotence.

Récupérer un QR code

GET /api/v1/qrs/{qrId} Renvoie un QR code avec son lien court, ses règles d’accès, son design et, pour les types basés sur un fichier, son fichier.

string

requis

ID du QR code, issu de la réponse de liste ou de création.

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

La réponse est l’objet QR code complet.

Modifier un QR code

PATCH /api/v1/qrs/{qrId} Modifie le contenu, la destination, le design ou les règles d’accès d’un QR code. N’envoyez que les champs à modifier. Répond avec le QR code mis à jour.

string

requis

ID du QR code.

Le corps accepte les mêmes champs que Créer un QR code, tous facultatifs, avec ces différences :

templateId. Non accepté.
link. Partiel. La destination actuelle est conservée si vous omettez link.url. link.domain et link.key renvoient 422 : le lien court est ce qu’encode le code imprimé, créez donc un nouveau QR code pour en utiliser un autre.
data. Vérifié selon le type résultant uniquement si data ou qrType change. Changer qrType sans data correspondant est refusé. Consultez Changer de type.
Design. styles, frameOptions et logoOptions sont fusionnés avec le design enregistré : un objet partiel ne modifie donc que ce qu’il mentionne. Choisir un autre logo le remplace mais conserve sa taille.
access. Chaque clé est appliquée si elle est présente. null efface une règle. Les règles d’accès se placent sous access : les envoyer sous link renvoie 422.
archived. Met en pause ou réactive le QR code et son lien court en même temps, comme Mettre en pause et Réactiver.

curl -X PATCH "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Autumn campaign",
    "access": { "password": "s3cr3t", "passwordProtected": true }
  }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "title": "Autumn campaign",
  "access": { "passwordProtected": true, "activeAt": null, "pauseAt": null, "scanLimit": null },
  "…": "…"
}

Ce que chaque type permet de modifier après impression est indiqué dans Données des QR codes par type.

Définir l’état de pause

PUT /api/v1/qrs/{qrId} Définit directement l’état de pause. Mettre en pause et Réactiver font la même chose, de façon plus lisible.

string

requis

ID du QR code.

boolean

requis

true pour mettre le QR code en pause, false pour le réactiver.

curl -X PUT "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

Mettre un QR code en pause

POST /api/v1/qrs/{qrId}/pause Empêche le QR code d’être résolu vers sa destination : les scans affichent la page de pause à la place. Le code imprimé et son lien court restent valides. Pas de corps de requête.

string

requis

ID du QR code.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/pause" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": true,
  "…": "…"
}

Réactiver un QR code

POST /api/v1/qrs/{qrId}/activate Permet à un QR code en pause d’être à nouveau résolu vers sa destination. Toute programmation et toute limite de scans s’appliquent toujours. Pas de corps de requête.

string

requis

ID du QR code.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/activate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf",
  "archived": false,
  "…": "…"
}

Dupliquer un QR code

POST /api/v1/qrs/{qrId}/duplicate Crée une copie avec le même contenu et le même design. Pas de corps de requête. Répond 201 Created avec le nouveau QR code.

string

requis

ID du QR code à copier.

Lien court. La copie reçoit son propre lien court, avec un slug aléatoire sur le domaine par défaut de l’espace de travail, et non sur le domaine de l’original. Ses scans sont comptés séparément.
Titre. Le titre reçoit le suffixe (Copy). Le résultat ne dépasse pas 40 caractères : un titre long est d’abord raccourci. Un QR code sans titre reste sans titre.
Non copiés. Les règles d’accès (mot de passe, programmation, limite de scans) et l’état de pause. La copie est toujours active.
Fichiers. Les fichiers PDF et image, y compris ceux des lots et des galeries, sont copiés : la copie en est donc propriétaire. Les fichiers vidéo et les fichiers de design, comme les logos, sont partagés avec l’original.

curl -X POST "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/duplicate" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "id": "qr_7Hk2PqWmX9cTnV4sLbR8YdZe",
  "title": "Landing page (Copy)",
  "shortLink": "https://getqr.sh/p2Wq9dL",
  "url": "https://example.com",
  "archived": false,
  "scans": 0,
  "…": "…"
}

Supprimer un QR code

DELETE /api/v1/qrs/{qrId} Supprime le QR code et son lien court. Répond avec l’ID supprimé.

La suppression est définitive. Le code imprimé et son lien court cessent de fonctionner, et l’historique des scans n’est plus accessible. Mettez plutôt le QR code en pause si vous risquez d’en avoir encore besoin.

string

requis

ID du QR code.

string

ID du QR code supprimé.

boolean

Toujours true.

curl -X DELETE "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{ "id": "qr_1EPcVfeHZAY2iNoVLsgW2Aqf", "deleted": true }

Télécharger l’image d’un QR code

GET /api/v1/qrs/{qrId}/download Génère le rendu du QR code avec son design et renvoie le fichier.

string

requis

ID du QR code à générer, issu de la réponse de liste ou de création.

string

défaut:"jpg"

Format de sortie : jpg, png, svg, pdf (une page A4) ou eps. Un Branded design ou un AI design se télécharge uniquement en jpg, png ou pdf.

integer

défaut:"1024"

Taille de l’image en pixels : 1024, 2048 ou 4096. svg et pdf l’ignorent. Un Branded design ou un AI design se télécharge uniquement en 1024.

`format`	`Content-Type`	Nom du fichier
`jpg`	`image/jpeg`	`<title>-<resolution>px.jpg`
`png`	`image/png`	`<title>-<resolution>px.png`
`svg`	`image/svg+xml`	`<title>.svg`
`pdf`	`application/pdf`	`<title>.pdf`
`eps`	`application/postscript`	`<title>-<resolution>px.eps`

Corps. Le corps de la réponse est le fichier. Le nom de fichier suggéré se trouve dans l’en-tête Content-Disposition. Il est construit à partir du titre, ou vaut qr-code pour un QR code sans titre.
Mise en cache. Les réponses incluent un ETag et Cache-Control: private, max-age=3600, must-revalidate. Renvoyez l’ETag dans If-None-Match pour obtenir 304 Not Modified si le QR code n’a pas changé.
Erreurs. Un format ou une résolution non pris en charge renvoie 400 bad_request. Le message d’erreur indique la raison : qr_download_invalid_format, qr_download_invalid_resolution, qr_download_art_format_unsupported ou qr_download_art_resolution_unsupported.

curl "https://getqr.com/api/v1/qrs/qr_1EPcVfeHZAY2iNoVLsgW2Aqf/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: attachment; filename="landing-page-1024px.png"
ETag: "9f2c0e1b5a7d43c8b016e2f4a9d5c3718be40f92"
Cache-Control: private, max-age=3600, must-revalidate

<binary image data>

Règles d’accès

Envoyez un objet access à la création ou à la modification pour programmer un début et une fin, plafonner le nombre de scans ou exiger un mot de passe. Les règles omises restent inchangées, et null en efface une. Le comportement complet, avec des exemples, est décrit dans Règles d’accès.

Objets de design

styles, frameOptions et logoOptions définissent les formes des points et des coins, les couleurs, le cadre et le logo. Ils fonctionnent de la même façon pour les QR codes, les modèles et les créations en masse. Les formes, cadres ou logos inconnus sont refusés. Toutes les valeurs acceptées et un exemple complet se trouvent dans Personnalisation.

Problèmes courants

422 lors de la définition d'un mot de passe, d'une programmation ou d'une limite de scans

Envoyez la règle sous access, pas sous link.

422 lors de la modification de link.domain ou link.key

Le lien court ne peut pas changer après la création, car le code imprimé l’encode. Créez plutôt un nouveau QR code.

422 "Expected … for qrType"

data ne correspond pas au format de qrType. Vérifiez le type dans Données des QR codes par type.

409 conflict lors de la création d'un QR code

Une création identique est encore en cours, ou link.key est déjà pris. Réessayez une fois la première requête terminée. Avec une Idempotency-Key, la nouvelle tentative renvoie le QR code d’origine.

Le téléchargement est un JPEG, pas un PNG

Les paramètres sont format et resolution, et format vaut jpg par défaut. Envoyez format=png.

404 pour un QR code visible dans le tableau de bord

Chaque requête s’exécute dans l’espace de travail de votre clé API. Vérifiez que le QR code lui appartient. Consultez Authentification.

Données des QR codes par type

Personnalisation

Règles d'accès

​L’objet QR code

​Lister les QR codes

​Créer un QR code

​Nouvelles tentatives et doublons

​Récupérer un QR code

​Modifier un QR code

​Définir l’état de pause

​Mettre un QR code en pause

​Réactiver un QR code

​Dupliquer un QR code

​Supprimer un QR code

​Télécharger l’image d’un QR code

​Règles d’accès

​Objets de design

​Problèmes courants

​Et ensuite

Données des QR codes par type

Personnalisation

Règles d'accès

Statistiques

L’objet QR code

Lister les QR codes

Créer un QR code

Nouvelles tentatives et doublons

Récupérer un QR code

Modifier un QR code

Définir l’état de pause

Mettre un QR code en pause

Réactiver un QR code

Dupliquer un QR code

Supprimer un QR code

Télécharger l’image d’un QR code

Règles d’accès

Objets de design

Problèmes courants

Et ensuite