# Barcodes

> Generate QR code, Code 128 or Data Matrix images in curl or .NET with barcodes/create: size, colors and text, plus length and validity checks of the text first.

- **Product:** DS Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** DS Server > Document Processing > Barcodes
- **2810 words**
- **Web URL:** https://docs.textcontrol.com/ds-server/document-processing/barcodes/
- **LLMs URL:** https://docs.textcontrol.com/ds-server/document-processing/barcodes/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/ds-server/document-processing/barcodes/llms-full.txt

---

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](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/barcodes-create/post/llms-full.txt). The type and the image are set in query parameters, the content in a JSON body:

| Part of the request | Content |
|---|---|
| `barcodeType` | The barcode type, such as `QRCode`, `Code128` or `Datamatrix`. The types are listed in [Choose the Barcode Type](#choose-the-barcode-type) |
| `imageFormat` | The image format: `BMP`, `EMF`, `GIF`, `JPEG`, `PNG` or `TIFF`. The default is `PNG` |
| `width`, `height` | The size of the image. The default is `200` for both |
| Body | A JSON object, the `Barcode`, with the content type `application/json`. Its property `text` holds the data to encode and is required |
| Response | The barcode image as a Base64 string in a JSON string |

Always set `barcodeType`: the endpoint reference gives it no default. Every request needs an access token, as [Authentication](https://docs.textcontrol.com/ds-server/document-processing/authentication/llms-full.txt) 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](https://docs.textcontrol.com/ds-server/overview/core-classic/#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*:

```bash
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`:

```csharp
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](#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](#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`:

| Property | Content |
|---|---|
| `text` | The data encoded in the barcode. Required |
| `showText` | Whether the text is rendered with the barcode, `true` or `false` |
| `textAlignment` | Where the text is rendered: `"Bottom"` or `"Top"` |
| `additionalText` | Additional text that is rendered with the barcode |
| `upperTextLength` | The upper text length of the barcode |
| `alignment` | The alignment of the barcode in the image: `"TopLeft"`, `"TopCenter"`, `"TopRight"`, `"MiddleLeft"`, `"MiddleCenter"`, `"MiddleRight"`, `"BottomLeft"`, `"BottomCenter"` or `"BottomRight"` |
| `angle` | The rotation angle of the barcode image |
| `foreColor`, `backColor` | The colors of the bars and of the background, such as `"#000000"` and `"#ffffff"` |
| `width`, `height` | The size of the barcode |

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

```json
{
  "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`:

| Endpoint | Returns |
|---|---|
| [GET /documentprocessing/barcodes/defaulttext](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/barcodes-defaulttext/get/llms-full.txt) | The default text of the type, as a JSON string. The reference example returns `"A"` for `qrcode` |
| [GET /documentprocessing/barcodes/minimumtextlength](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/barcodes-minimumtextlength/get/llms-full.txt) | The minimum length of a text the type encodes |
| [GET /documentprocessing/barcodes/maximumtextlength](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/barcodes-maximumtextlength/get/llms-full.txt) | The maximum length of a text the type encodes. The reference example returns `3700` for `qrcode` |
| [GET /documentprocessing/barcodes/istextvalid](https://docs.textcontrol.com/ds-server/reference/web-api/documentprocessing/barcodes-istextvalid/get/llms-full.txt) | Whether the text in the `text` parameter is valid for the type. For an invalid text, the response says why |

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

```bash
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`:

```text
"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](https://docs.textcontrol.com/ds-server/document-processing/thumbnails/llms-full.txt): render the pages of a document as images.
- [Merging Templates](https://docs.textcontrol.com/ds-server/document-processing/mail-merge/llms-full.txt): create documents from a template and JSON data.
- [Supported File Formats](https://docs.textcontrol.com/ds-server/overview/file-formats/llms-full.txt): the image formats of each endpoint.
- [Errors and Status Codes](https://docs.textcontrol.com/ds-server/document-processing/errors/llms-full.txt): what a refused request means.

---

## Nearby

- **Previous:** [PDF Form Fields](https://docs.textcontrol.com/ds-server/document-processing/pdf-forms/llms-full.txt)
- **Next:** [Errors and Status Codes](https://docs.textcontrol.com/ds-server/document-processing/errors/llms-full.txt)