Options & défauts
Cette page documente les valeurs par défaut par symbologie que l'API applique lorsqu'une balise de code-barres en ligne omet un emplacement, et les remplacements optionnels que les auteurs peuvent fournir.
Dimensionnement par défaut
Lorsque width|height est omis, l'API applique des valeurs par défaut par symbologie qui produisent un rendu sensé en ligne :
| Famille | Taille par défaut (L × H, points) |
|---|---|
| 2D matrix square (QR, DataMatrix, Aztec, MaxiCode, HIBC-DM) | 120 × 120 |
| Micro QR | 80 × 80 |
| Rectangular Micro QR (rMQR) | 200 × 60 |
| PDF417 / HIBC-PDF417 | 300 × 60 |
| Micro PDF417 / HIBC-Micro PDF417 | 180 × 60 |
| Code 16k / Codablock-F / HIBC-Codablock-F | 250 × 80 |
| DotCode / Han Xin / Grid Matrix / UPN QR / HIBC-Aztec | 120 × 120 |
| Ultracode | 200 × 120 |
| 1D linear (Code 128, Code 39, Code 93, Code 11, Codabar, ITF-14, Inter25, HIBC-128, HIBC-39, GS1-128, ExtendedCode39, Telepen, LOGMARS, VIN) | 250 × 50 |
| Telepen Numeric / MSI Plessey / Code 2 of 5 family / Flattermarken | 200 × 50 |
| Retail GTIN (EAN-13, EAN-8, UPC-A, UPC-E) | 250 × 50 |
| Postal narrow (Postnet, Planet, Royal Mail, Australia Post, Korea Post, Japan Post, KIX) | 160 × 20 |
| USPS Intelligent Mail | 200 × 20 |
| Deutsche Post Leitcode / Identcode | 250 × 30 |
| GS1 DataBar Omn / Ltd | 180 × 30 |
| GS1 DataBar Expanded | 250 × 30 |
| GS1 DataBar Stacked Omn | 180 × 60 |
| GS1 DataBar Expanded Stacked | 250 × 80 |
| Pharmacode / Pharma 2-Track | 100 × 40 |
| Channel Code | 80 × 40 |
Les dimensions fournies par l'auteur remplacent toujours les valeurs par défaut.
Forme DataMatrix
DataMatrix supporte à la fois les variantes carrées et rectangulaires. L'API déduit la forme à partir des dimensions demandées :
W == H→ DataMatrix carré (p. ex.100|100)W != H→ variante rectangulaire (p. ex.100|40)
Aucun mot-clé nécessaire.
Zones silencieuses par défaut
Les zones silencieuses (la marge blanche autour d'un code-barres que les scanners doivent détecter pour les limites des symboles) par défaut à la norme ISO minimale pour chaque famille de symbologie — suffisamment large pour que les scanners de production détectent de manière fiable les limites des symboles.
| Famille | Horizontal × Vertical (en multiples de module) |
|---|---|
| QR | 4 × 4 |
| DataMatrix / HIBC-DM | 1 × 1 |
| PDF417 / Micro PDF417 / Aztec / MaxiCode / DotCode / Grid Matrix / UltraCode / UPN QR / HIBC-Aztec / HIBC-PDF417 / HIBC-Micro PDF417 | 2 × 2 |
| Han Xin / Code 16k / Codablock-F / HIBC-Codablock-F | 4 × 4 |
| Micro QR / rMQR / HIBC-QR | 2 × 2 — 4 × 4 |
| 1D linear (Code 128, Code 39, Code 93, Code 11, Codabar, ITF-14, Inter25, HIBC-128, HIBC-39, GS1-128, ExtendedCode39, Telepen, LOGMARS, VIN) | 10 × 0 |
| Telepen Numeric / MSI Plessey / Code 2 of 5 / Flattermarken | 10 × 0 — 4 × 0 |
| EAN / UPC | 0 × 0 (intrinsic asymmetric zones already in symbology) |
| Postal | 2 × 0 |
| Pharmacode | 4 × 0 |
La zone silencieuse verticale est 0 pour les codes 1D — ils n'ont pas d'ambiguïté de ligne de balayage supérieure/inférieure, et ajouter un espace blanc vertical rétrécit juste la hauteur visible des barres. EAN/UPC appliquent 0 horizontal car la symbologie encode déjà des zones asymétriques intrinsèques (11 gauche + 7 droite par ISO).
Remplacer la zone silencieuse
Les valeurs plus serrées échangent la scannabilité pour la compacité visuelle. Utilisez uniquement après validation avec votre mélange de scanners réel.
{ "p": "[barcode, code128, DOC-2026-04521, 200|50, quiet=4]" }
Remplacements de couleur
Les couleurs de premier plan et d'arrière-plan peuvent être remplacées via des emplacements supplémentaires :
| Modèle | Effet |
|---|---|
#hex | Premier plan uniquement (p. ex. #1A1A2E) |
#fg|#bg | Premier plan + arrière-plan (p. ex. #FFFFFF|#1A1A2E) |
{ "p": "Brand QR: [barcode, qrcode, https://docpayload.example, 80|80, #1A1A2E]" }
{ "p": "Inverse: [barcode, qrcode, https://docpayload.example, 80|80, #FFFFFF|#1A1A2E]" }
Avertissement de contraste inverse — clair sur foncé est techniquement valide pour QR mais peu fiable sur les scanners détail bon marché. Préférez sombre sur clair pour la production.
Gestion des erreurs
Si l'encodeur rejette une charge utile (p. ex. EAN-13 avec le mauvais nombre de chiffres, ITF-14 plus long que 13 chiffres), le document est toujours généré — le code-barres incriminé est remplacé par un espace réservé de diagnostic en ligne affichant le message d'erreur exact de l'encodeur :
[barcode error: itf14 — Input too long (13 character maximum)]
Cela signifie qu'une mauvaise charge utile ne supprime jamais un document complet, et les auteurs de modèles voient exactement ce qui s'est mal passé sans fouiller les journaux. L'espace réservé est également écrit dans le journal du serveur au niveau d'avertissement pour la visibilité des opérations.
Conseils de validation
Contraintes de charge utile courantes par symbologie — vérifiez d'abord ces contraintes quand vous voyez un espace réservé d'erreur :
| Symbologie | Règle de charge utile |
|---|---|
| EAN-13 | Exactement 12 ou 13 chiffres |
| EAN-8 | Exactement 7 ou 8 chiffres |
| UPC-A | Exactement 11 ou 12 chiffres |
| UPC-E | Exactement 6, 7 ou 8 chiffres |
| ITF-14 | Exactement 13 ou 14 chiffres |
| GS1-128 | Identifiants d'application entre crochets [NN] |
| GS1 DataBar Limited | L'indicateur doit être 0 ou 1 (premier chiffre) |
| Codabar | Doit commencer et se terminer par A, B, C ou D |
| Code 11 | Chiffres et tirets uniquement |
| Pharmacode | Numérique, 3 à 131070 |
| Famille HIBC | La charge utile commence par + (pré-ajouté automatiquement) |
| VIN | 17 alphanumériques (par ISO 3779) |
| RM4SCC / Royal Mail | Chiffres uniquement dans cette implémentation |
| Postnet / Planet | 5, 9 ou 11 chiffres |