Ressource QrCode

La ressource QrCode expose tout ce dont vous avez besoin pour créer, gérer et distribuer des QR codes avec Twilee. Ce guide parcourt chaque opération disponible, les structures de données associées et des exemples reflétant les réponses réelles de l’API.

Représentation de la ressource

Les réponses exposent un document structuré séparant les données d’identification, les options d’apparence, les attributs hébergés et l’analytique. Voici un payload réel :

{
  "id": "68ef5bc4e581e7223e010b2e",
  "name": "Event test API",
  "type": "event",
  "content": {
    "name": "Test event",
    "eventType": "Test",
    "location": "Paris",
    "description": "lorem ipsum",
    "hostedPageBackgroundColor": "#f9fAfb",
    "hostedPagePrimaryColor": "#0ea5e9"
  },
  "metadata": {
    "shortToken": "frnKYa3c",
    "createdAt": "2025-10-15T08:31:00+00:00",
    "updatedAt": "2025-10-15T08:31:00+00:00"
  },
  "appearance": {
    "shape": "square",
    "predefinedImage": null,
    "uploadedImage": null,
    "margin": 10,
    "qrOptionsTypeNumber": 0,
    "qrOptionsMode": "Byte",
    "qrOptionsErrorCorrectionLevel": "Q",
    "imageOptionsHideBackgroundDots": true,
    "imageOptionsImageSize": 0.4,
    "imageOptionsMargin": 0,
    "dotsOptionsColor": "#0f172a",
    "dotsOptionsType": "extra-rounded",
    "dotsOptionsRoundSize": true,
    "dotsOptionsGradientType": null,
    "dotsOptionsGradientRotation": null,
    "dotsOptionsGradientColorStops": null,
    "backgroundOptionsColor": "#ffffff",
    "backgroundOptionsGradientType": null,
    "backgroundOptionsGradientRotation": null,
    "backgroundOptionsGradientColorStops": null,
    "cornersSquareOptionsColor": "#0f172a",
    "cornersSquareOptionsType": "extra-rounded",
    "cornersSquareOptionsGradientType": null,
    "cornersSquareOptionsGradientRotation": null,
    "cornersSquareOptionsGradientColorStops": null,
    "cornersDotOptionsColor": "#0f172a",
    "cornersDotOptionsType": "dot",
    "cornersDotOptionsGradientType": null,
    "cornersDotOptionsGradientRotation": null,
    "cornersDotOptionsGradientColorStops": null
  },
  "attributes": {
    "dynamicUrl": "https://qr-click-me.local/r/frnKYa3c",
    "hostedPageUrl": "https://twilee.local/p/frnKYa3c"
  },
  "links": [
    {
      "rel": "self",
      "href": "/qr_codes/68ef5bc4e581e7223e010b2e",
      "method": "GET"
    },
    {
      "rel": "https://twilee.com/rels/download",
      "href": "/qr_codes/68ef5bc4e581e7223e010b2e/download",
      "method": "POST"
    },
    {
      "rel": "https://twilee.com/rels/schema-org",
      "href": "/qr_codes/68ef5bc4e581e7223e010b2e/schemaorg",
      "method": "GET"
    },
    {
      "rel": "https://twilee.com/rels/scan-logs",
      "href": "/qr_codes/68ef5bc4e581e7223e010b2e/scans",
      "method": "GET"
    },
    {
      "rel": "https://twilee.com/rels/page-views",
      "href": "/qr_codes/68ef5bc4e581e7223e010b2e/page-views",
      "method": "GET"
    }
  ],
  "analytics": {
    "scans": 0,
    "views": 0
  }
}

Référence des champs

Métadonnées

Apparence

L’objet appearance reprend les options proposées dans le concepteur Twilee. Les propriétés sont regroupées par composant de rendu.

Général

Options QR

Options d’image

Options des modules

Options d’arrière-plan

Options des carrés d’angle

Options des points d’angle

Attributs

Analytique

Types de contenu (payload content)

Définissez le champ type avec l’une des valeurs supportées ci-dessous, puis fournissez la structure content correspondante. Le tableau résume le payload renvoyé par l’API pour chaque type :

Remarque : Les types compatibles avec une page hébergée (text, links, audio, event) exposent hostedPageBackgroundColor, hostedPagePrimaryColor et publicFilePath pour ajuster le style de la page d’atterrissage.

Lister les QR codes — GET /qr_codes

Récupérez une liste paginée de tous les QR codes associés à votre équipe.

curl -X GET "https://api.twilee.com/qr_codes" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Accept: application/json"

Réponse (JSON-LD)

{
  "@context": "/contexts/QrCode",
  "@id": "/qr_codes",
  "@type": "Collection",
  "totalItems": 1,
  "member": [
    {
      "@id": "/qr_codes/68cdbbe0ed096c7b590277c6",
      "@type": "QrCode",
      "id": "68cdbbe0ed096c7b590277c6",
      "name": "Redirects to https://twilee.com",
      "type": "url",
      "content": { "url": "https://twilee.com" },
      "metadata": { "shortToken": "frbORDRQ", "createdAt": "2024-05-01T09:15:24+00:00", "updatedAt": "2024-05-02T11:02:31+00:00" },
      "appearance": { "shape": "square", "predefinedImage": null, "uploadedImage": null, "margin": 10, "qrOptionsTypeNumber": 0, "qrOptionsMode": "Byte", "qrOptionsErrorCorrectionLevel": "Q", "imageOptionsHideBackgroundDots": true, "imageOptionsImageSize": 0.4, "imageOptionsMargin": 0, "dotsOptionsColor": "#000000", "dotsOptionsType": "square", "dotsOptionsRoundSize": true, "dotsOptionsGradientType": null, "dotsOptionsGradientRotation": null, "dotsOptionsGradientColorStops": null, "backgroundOptionsColor": "#ffffff", "backgroundOptionsGradientType": null, "backgroundOptionsGradientRotation": null, "backgroundOptionsGradientColorStops": null, "cornersSquareOptionsColor": null, "cornersSquareOptionsType": null, "cornersSquareOptionsGradientType": null, "cornersSquareOptionsGradientRotation": null, "cornersSquareOptionsGradientColorStops": null, "cornersDotOptionsColor": null, "cornersDotOptionsType": null, "cornersDotOptionsGradientType": null, "cornersDotOptionsGradientRotation": null, "cornersDotOptionsGradientColorStops": null },
      "attributes": { "dynamicUrl": "https://qr.twilee.com/r/frbORDRQ" },
      "links": [
        { "rel": "self", "href": "/qr_codes/68cdbbe0ed096c7b590277c6", "method": "GET" }
      ],
      "analytics": { "scans": 0 }
    }
  ]
}

Utilisez le paramètre de requête page pour la pagination :

GET /qr_codes?page=2

Récupérer un QR code — GET /qr_codes/{id}

Récupérez un QR code appartenant à l’équipe de l’utilisateur authentifié. Le corps de la réponse correspond à la structure décrite dans la section Représentation de la ressource.

curl -X GET "https://api.twilee.com/qr_codes/{id}" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Accept: application/json"

Si le QR code est introuvable ou appartient à une autre équipe, l’API renvoie 400 Bad Request avec le message « QR code not found ».

Représentation schema.org — GET /qr_codes/{id}/schemaorg

Cet endpoint expose une représentation alternative destinée aux crawlers de données structurées. La réponse regroupe les métadonnées du QR code et le contenu encodé en deux sections :

{
  "id": "68cdbbe0ed096c7b590277c6",
  "qrCode": {
    "@context": "https://schema.org",
    "@type": "BarCode",
    "identifier": "frbORDRQ",
    "name": "Redirects to twilee.com",
    "caption": "Scan me",
    "creator": { "@type": "Person", "name": "[email protected]" },
    "maintainer": { "@type": "Organization", "name": "My Team" },
    "dateCreated": { "@type": "DateTime", "dateCreated": "2024-05-01T09:15:24+00:00" },
    "description": "Campaign QR code",
    "provider": "Twilee"
  },
  "content": {
    "@context": "https://schema.org",
    "@type": "Event",
    "identifier": "frbORDRQ",
    "name": "Product Launch",
    "startDate": "2024-05-10T18:00:00+00:00",
    "endDate": "2024-05-10T21:00:00+00:00",
    "url": "https://twilee.com/p/frbORDRQ"
  }
}

Un traitement spécifique est appliqué aux types event et vcard pour les convertir en structures schema.org adaptées ; les autres types renvoient le payload content brut.

Créer un QR code — POST /qr_codes

Créez un nouveau QR code en envoyant des données JSON. Fournissez les champs décrits dans la table de représentation de la ressource ci-dessus ; les clés non prises en charge sont ignorées.

curl -X POST "https://api.twilee.com/qr_codes" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Launch landing page",
    "type": "url",
    "content": { "url": "https://twilee.com" },
    "appearance": {
      "shape": "circle",
      "margin": 12,
      "qrOptionsErrorCorrectionLevel": "H",
      "imageOptionsHideBackgroundDots": false,
      "dotsOptionsColor": "#111111",
      "dotsOptionsType": "rounded",
      "backgroundOptionsColor": "#f1f5f9",
      "cornersSquareOptionsType": "extra-rounded",
      "cornersSquareOptionsColor": "#111111"
    }
  }'

Points de validation clés

• name : 1 à 255 caractères
• type : doit correspondre à une valeur de l’énumération (url, text, email, call, sms, geo, wifi, vcard, file, links, audio, event)
• appearance.shape : doit être square ou circle
• appearance.qrOptionsTypeNumber : entier compris entre 0 et 40
• appearance.qrOptionsMode : optionnel, mais si renseigné doit être Numeric, Alphanumeric, Byte ou Kanji
• appearance.qrOptionsErrorCorrectionLevel : doit être L, M, Q ou H
• appearance.imageOptionsImageSize : valeur flottante comprise entre 0 et 1
• appearance.margin, appearance.imageOptionsMargin : entiers supérieurs ou égaux à 0
• Champs de couleur (dotsOptionsColor, backgroundOptionsColor, cornersSquareOptionsColor, cornersDotOptionsColor) : hexadécimal sur 6 caractères (ex. #123abc)
• Sélecteurs de forme (dotsOptionsType, cornersSquareOptionsType, cornersDotOptionsType) : utiliser l’une des valeurs listées dans les tableaux ci-dessus

Une création réussie renvoie 201 Created avec la nouvelle ressource dans le corps de la réponse.

Mettre à jour un QR code — PUT /qr_codes/{id}

Envoyez une représentation complète (ou au moins tous les champs que vous souhaitez conserver) pour mettre à jour un QR code existant. Les règles de validation sont identiques à celles de la création.

curl -X PUT "https://api.twilee.com/qr_codes/{id}" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated launch landing page",
    "type": "url",
    "content": { "url": "https://twilee.com" },
    "appearance": {
      "dotsOptionsColor": "#000000",
      "backgroundOptionsColor": "#ffffff"
    }
  }'

En cas de succès, l’API répond avec 200 OK et le payload du QR code mis à jour.

Supprimer un QR code — DELETE /qr_codes/{id}

Supprimez un QR code existant. Une suppression réussie renvoie 204 No Content.

curl -X DELETE "https://api.twilee.com/qr_codes/{id}" \
  -H "Authorization: Bearer VOTRE_CLE_API"

Télécharger un QR code — POST /qr_codes/{id}/download

Déclenchez la génération d’une image de QR code pour la ressource spécifiée. L’appel doit être authentifié avec une clé API autorisée à accéder à l’équipe du QR code.

curl -X POST "https://api.twilee.com/qr_codes/{id}/download" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -o qr-code.png \
  -d '{
    "format": "png",
    "size": 600,
    "margin": 10
  }'

Options du corps de requête

Avis : L’endpoint de téléchargement ne prend pas encore en charge le stylisme avancé ; la sortie utilise le thème par défaut.

La réponse est un fichier binaire avec un nom dérivé du QR code et du format choisi. Twilee nettoie automatiquement le fichier temporaire après l’envoi.

Gestion des erreurs

• Les erreurs de validation renvoient 400 Bad Request avec un message descriptif (par exemple options de téléchargement invalides ou champs content manquants).
• L’accès à un QR code appartenant à une autre équipe produit également 400 Bad Request (« QR code not found ») afin d’éviter de divulguer l’existence d’autres ressources.
• Les requêtes non authentifiées renvoient 401 Unauthorized, tandis qu’un utilisateur authentifié sans accès au QR code reçoit 403 Forbidden.

Avec ces opérations, vous pouvez gérer les QR codes Twilee de bout en bout : création, personnalisation, analytique, publication schema.org et téléchargement des assets.