Barcode Reference
Several of our API endpoints can add barcodes as a watermark or overlay to your PDFs. Barcodes can be a useful addition to all kinds of business documents:
• Invoices or order confirmations can include a barcode that links to a payment page
• Invitations can include links to sign-up or RSVP pages
• Documents that are intended for automated processing can have barcodes with the document number
• Likewise, machine readable forms can include the form's content as a barcode
An example can be seen in the documentation and sample code for the html/2/pdf endpoint.
Excerpt:
overlays: [
...
{
position: {
x: 'left',
y: '30mm',
},
type: 'barcode',
config: {
type: 19,
data: 'https://pdfteam.com'
},
}
...
]
This sample creates a QR code (code type: 19) with the content of "https://pdfteam.com" and puts it at the left margin of the page and at 30mm from the bottom. As a minimum, the user has to provide the data to be encoded. If no type is specified, the barcode module will default to creating a QR code with reasonable settings for size and other relevant parameters. However, the module has many more properties which will be explained in the following sections.
Likewise, some barcode types have certain requirements with regard to the encoded data. For example, Code EAN 13 encodes exactly thirteen digits and barcode creation will fail if the user supplies non-numeric data or too few or too many digits. Those requirements are listed below for each barcode type. We also provide a wide range of foundational articles on barcodes on our parent site, Softmatic.
If you are unsure what barcode type or settings to choose, please contact us us with your requirements.
Barcode types
Currently supported are the following barcode symbologies (definitions in TS/JS syntax):
const EAN_8 = 0
const EAN_13 = 1
const ISBN_10 = 2
const ISBN_13 = 3
const ISSN = 4
const UPC_A = 5
const UPC_E = 6
const CODE_128 = 7
const CODE_128_GS1 = 8
const CODE_25_INTERLEAVED = 9
const CODE_25_STANDARD = 10
const ITF_14 = 11
const CODE_39 = 12
const PZN = 13
const LAETUS = 14
const CODABAR = 15
const DATAMATRIX = 16
const DATAMATRIX_GS1 = 17
const PDF_417 = 18
const QR = 19
const AZTEC = 20
All supported barcode types at a glance:
High-resolution PDF with all barcode symbologies
Barcode options
Besides specifying data and code type, the actual barcode creation can be widely customized using the optional fields of the BarcodeConfig-structure as part of an overlay (again in TS/JS syntax):
BarcodeConfig {
// All codes
data: string;
type?: number;
auxTextOver?: string;
auxTextUnder?: string;
auxTextSize?: number;
humanReadableText?: boolean;
margin?: number;
// Retail codes
size?: number;
truncate?: number;
// Non-retail codes
moduleWidth?: number;
moduleHeight?: number;
humanReadableSize?: number;
}
data
Data to be encoded into the barcode. The following requirements apply:
Linear barcode types
Code EAN 8: 7 or 8 digits, e.g. "1234567"
Code EAN 13: 12 or 13 digits, e.g. "401234567890"
Code ISBN 10: Fully qualified ISBN-10 number, e.g. "817527566-0"
Code ISBN 13: Fully qualified ISBN-13 number, e.g. "978-3-453-08250-2"
Code UPC-A: 11 or 12 digits, e.g. "036000291452"
Code UPC-E: 7 or 8 digits, e.g. "01234558", must begin with "0" or "1"
Code 128: Full ASCII character set, max. 40 characters, e.g. "123ABCabc"
Code 128 GS1: Fully qualified GS1 data string, e.g. "(01)04012345678901"
Code 25 Interleaved: Digits 0-9, max. 40 characters, e.g. "123456"
Code 25 Standard: Digits 0-9, max. 20 characters, e.g. "123456"
ITF 14: Fully qualified GTIN-14, e.g "0 54 00141 28876 6"
Code 39: Digits 0-9, letters A-Za-z, max. 40 characters
PZN: Fully qualified PZN-8 no., e.g. "02530498"
Laetus: Digits 0-9, e.g. "12345", highest possible value is 131070
Codabar: Digits 0-9, max. 20 characters, e.g. "123456"
2D and matrix barcodes
Datamatrix: Unicode data, max. 2'000 characters
Datamatrix GS1: Fully qualified GS1 data string, e.g. "(01)04012345678901"
PDF 417: Full ANSI set with accented characters, limited support for Unicode data, max. 2'000 characters
QR: Unicode data, max. 2'000 characters
Aztec: Unicode data, max. 2'000 characters
type
Number between 0 and 20, defaults to 19 (QR)
auxTextOver
Additional text to put above the barcode, supports most ASCII characters, max. 30 characters, defaults to none
auxTextUnder
Additional text to put under the barcode, supports most ASCII characters, max. 30 characters, defaults to none
auxTextSize
Font size of additional text blocks in pt, 4-36pt, defaults to 10pt
humanReadableText
Put encoded data under the code, defaults to TRUE
margin
White space around the code in mm, 0-20mm, defaults to 4mm
The following two options apply to retail codes only (EAN 8/13, ISBN 10/13, UPC-A/E) and are ignored for all others:
size
Size of the code in SC nomination, SC0 = 0 until SC9 = 9, defaults to 2 (= SC2, the nominal or 100% size), table of EAN SC sizes
truncate
Reduce code height percentage-wise by truncation, value between 0 and 80, defaults to 0
The following three options apply to non-retail codes only and are ignored for all others:
moduleWidth
Width in mm of the thinnest bar in a barcode or, respectively, the size of a module with 2D codes, 0.25-2mm, defaults to 0.5mm
moduleHeight
Height in mm of barcode (not counting the human readable text line), ignored for 2D codes, 2-100mm, defaults to 25mm
humanReadableSize
Font size for human readable text line in pt, 4-40pt, defaults to 10pt
Remarks
• With retail codes, the size of the text line is calculated automatically to fit the text under the code
• Codes are created in pure black (CMYK 0 0 0 100) on white for maximum contrast
• Code 128 is created with auto-discrimination: The barcode module will select subtypes Code 128 A, B or C depending on the data to create the smallest possible barcode
• 2D codes are created without human readable text line but text can be added with auxTextOver and auxTextUnder
• As per GS1 recommendations, all text is created with an OCR-B font
• All codes are created with their respective check digits (ECC with 2D codes). Code 39, Code 2/5 Industrial and Code 2/5 Interleaved are created without check digit, please contact us if you have specific requirements
Sample Barcodes
Code 128 (type "7") with "123ABCabc":
overlays: [
{
...
type: 'barcode',
config: {
type: 7,
moduleWidth: 0.5,
moduleHeight: 15,
data: '123ABCabc',
}
}
]
Result:
Code 128 with "123ABCabc" but without text line:
overlays: [
{
...
type: 'barcode',
config: {
humanReadableText: false,
type: 7,
moduleWidth: 0.5,
moduleHeight: 15,
data: '123ABCabc',
}
}
]
Result:
Code EAN 13 (type "1") with 50% truncation and text above and below the code. We also increased the margin to 8mm so that the text would not be cut off:
overlays: [
{
...
type: 'barcode',
config: {
margin: 8,
truncate: 50,
auxTextOver: 'Paperclips, 100pcs.',
auxTextUnder: '$2.99',
type: 1,
data: '401234567890',
}
}
]
Result:
