Barcodes

A QR code with a payment link on an invoice, a Code 128 label with an order number, a Data Matrix code on a shipping document: the DocumentProcessing Web API creates barcode images from a text in 20 barcode types. Four smaller endpoints tell your application what a barcode type accepts before it creates one: the default text, the shortest and the longest text it encodes, and whether a text is valid for it.

How Creating Barcodes Works

The endpoint is POST /documentprocessing/barcodes/create. The type and the image are set in query parameters, the content in a JSON body:

Always set barcodeType: the endpoint reference gives it no default. Every request needs an access token, as Authentication describes.

When DS Server runs on Linux, the Core build saves images as PNG, JPG and BMP only; GIF and TIFF it can only open, as Limits on Linux lists. Use PNG, JPEG or BMP there.

Create a Barcode With curl

The following commands create a QR code of 300 × 300 that encodes a URL, and save it as qrcode.png:

DS=http://localhost:5000
TOKEN="<access_token>"

curl --request POST "$DS/documentprocessing/barcodes/create?barcodeType=QRCode&imageFormat=PNG&width=300&height=300" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"text": "https://www.textcontrol.com", "showText": false}' \
  --output barcode.json

# Decode the Base64 string of the response
jq -r . barcode.json | base64 -d > qrcode.png

The commands work as follows:

• The query parameters select the type, the image format and the size.
• The body holds the text to encode. showText sets whether the text is rendered with the barcode as well.
• The response is a JSON string. jq -r . removes its quotes, and base64 -d decodes it into the image file.

Create a Barcode With .NET

The package TXTextControl.DocumentServices.DocumentProcessing has the barcode methods in its Barcodes property. The settings of the barcode are a BarcodeSettings object, in the namespace TXTextControl.DocumentServices.DocumentProcessing.Barcodes:

using TXTextControl.DocumentServices.DocumentProcessing;
using TXTextControl.DocumentServices.DocumentProcessing.Barcodes;
using TXTextControl.DocumentServices.DocumentProcessing.OAuth;

var oauthSettings = new OAuthSettings("<client ID>", "<client secret>");
var documentProcessing = new DocumentProcessing("http://localhost:5000", oauthSettings);

var settings = new BarcodeSettings
{
    Text = "https://www.textcontrol.com",
    ShowText = false
};

// A QR code as a PNG image of 300 x 300
byte[] image = await documentProcessing.Barcodes.Create(
    settings, BarcodeType.QRCode, BarcodeImageFormat.PNG, 300, 300);

File.WriteAllBytes("qrcode.png", image);

The code works as follows:

• The DocumentProcessing constructor takes the service URL and the credentials of a security profile, and requests an access token.
• BarcodeSettings holds the content and the appearance: Text, ShowText, TextAlignment, AdditionalText, UpperTextLength, Alignment, Angle, ForeColor and BackColor, the properties of the JSON body in Pascal case.
• Barcodes.Create takes the settings, a BarcodeType value, a BarcodeImageFormat value and the width and the height. The last four arguments are optional, with the defaults QRCode, PNG, 200 and 200. The package decodes the Base64 string of the response and returns the image file itself.

BarcodeType has the 20 barcode types of Choose the Barcode Type, and BarcodeImageFormat the values BMP, EMF, GIF, JPEG, PNG and TIFF. Barcodes.Create also has an overload without BarcodeSettings; it sends no text, which the endpoint requires, so pass the settings. The four GET endpoints of Check the Text Before Creating a Barcode are the methods GetDefaultText, GetMinimumTextLength, GetMaximumTextLength and IsTextValid of Barcodes.

Set the Appearance

The Barcode object in the body has more properties than text:

The following body creates a Code 128 barcode in dark blue with its text below the bars:

{
  "text": "ORDER-4711",
  "showText": true,
  "textAlignment": "Bottom",
  "foreColor": "#1a237e",
  "backColor": "#ffffff",
  "alignment": "MiddleCenter"
}

Send it with barcodeType=Code128 in the query. Values of the wrong type, such as a number for alignment or a string for angle, are refused with 400 and a validation error that names the property.

Choose the Barcode Type

barcodeType takes one of these 20 values: QRCode, Code128, EAN13, UPCA, EAN8, Interleaved2of5, Postnet, Code39, AztecCode, IntelligentMail, Datamatrix, PDF417, MicroPDF, Codabar, FourState, Code11, Code93, PLANET, RoyalMail and Maxicode. The examples of the endpoint reference also write them in lowercase, such as qrcode and code128.

The four GET endpoints below refuse an unknown barcode type with 400 Bad Request, as their reference lists.

Check the Text Before Creating a Barcode

Each barcode type accepts only some texts: a type encodes a limited number of characters, and some types accept only certain characters. Four GET endpoints answer for a given barcodeType:

The following commands ask for the maximum length of a QR code and check a text for an EAN-13 barcode:

curl --get "$DS/documentprocessing/barcodes/maximumtextlength" \
  --header "Authorization: Bearer $TOKEN" \
  --data-urlencode "barcodeType=QRCode"

curl --get "$DS/documentprocessing/barcodes/istextvalid" \
  --header "Authorization: Bearer $TOKEN" \
  --data-urlencode "barcodeType=EAN13" \
  --data-urlencode "text=ORDER-4711"

--get sends the --data-urlencode values as query parameters and encodes characters such as spaces and umlauts, which matters for the text of istextvalid. The reference example of istextvalid returns this message for a text with characters outside ISO 8859-1 and the type qrcode:

"The text is invalid. For the barcode type QR Code, only ASCII (ISO 8859-1) characters are allowed."

Check a text that users enter before you create the barcode, and show the message of istextvalid when it is not valid.

Next Steps

• Thumbnails: render the pages of a document as images.
• Merging Templates: create documents from a template and JSON data.
• Supported File Formats: the image formats of each endpoint.
• Errors and Status Codes: what a refused request means.