API генерации этикеток Честный Знак и штрихкод

Запрос

POST https://barcode1.ru/api/v1/generate-labels/ Header: X-API-Key: <ваш ключ> Content-Type: multipart/form-data

Два поля в multipart:

file — PDF с DataMatrix-кодами Честного Знака. Имя файла любое, размер до 50 MB, не более 2000 КИЗ в одном файле. Если КИЗов больше — разбейте на несколько запросов.
data — JSON-строка с параметрами (см. ниже)

Поля JSON

Поле	Тип	Дефолт	Описание
`webhook_url`	string	обяз.	HTTPS-адрес, куда вернём результат
`payload`	object/array	—	Любые данные клиента (≤ 16 KB), вернутся в callback
`inner_dups`	string	stop	Действие с дублями внутри текущего PDF: `print`, `skip` или `stop`
`history_dups`	string	stop	Действие с дублями по истории пользователя: `print`, `skip` или `stop`
`text`	string	—	Текст на этикетке. HTML с форматированием (см. ниже)
`bcode`	string	—	Штрихкод (для EAN-13 — только 12-13 цифр)
`barcode_type`	string	code128	code128 / ean13 / gtin_ean13 / qr / none
`label_size_x`	int (мм)	58	Ширина этикетки
`label_size_y`	int (мм)	40	Высота этикетки
`include_eac`	bool	true	Знак EAC
`include_cz`	bool	true	Знак Честный Знак
`show_num`	bool	true	Номер этикетки
`num_start`	int	1	С какого числа начинать нумерацию
`nowrap`	bool	false	true = не переносить, сжать шрифт чтобы каждая строка влезла целиком. false = обычный перенос по словам
`name_h_align`	string	center	left / center / right

Дубликаты КИЗ

Поля inner_dups и history_dups управляют двумя независимыми проверками:

inner — повторы одного GTIN+serial внутри текущего PDF.
history — коды, которые уже были обработаны этим API-пользователем ранее.

Для каждого ключа доступны режимы:

stop — остановить генерацию до списания, если найдены дубли. Это дефолт.
skip — пропустить дубли. Для inner печатается первое вхождение, повторные строки пропускаются. Для history пропускаются все найденные в истории строки.
print — печатать всё, но вернуть информацию о дублях в webhook.

В списках webhook возвращается максимум 500 кодов суммарно; счётчики всегда точные. Если список обрезан, верхний флаг truncated будет true.

"inner_dups": "skip", "history_dups": "stop"

Форматирование поля text

Текст автоматически подгоняется под площадь этикетки — общий шрифт уменьшается. Параметр nowrap=true запрещает переносы внутри строк (каждая строка остаётся целиком, шрифт сжимается ещё сильнее). При nowrap=false — обычный перенос по словам. Переносы между строк всегда делайте через <br>.

Перед генерацией любой входящий HTML прогоняется через очистку (sanitize) — всё, что не из списка ниже, будет удалено молча.

Поддерживаемые теги (whitelist):

Тег	Что делает	Пример
`<b>...</b>` или `<strong>`	Жирный	`<b>Футболка</b>`
`<i>...</i>`	Курсив	`<i>хлопок</i>`
`<u>...</u>`	Подчёркнутый	`<u>Артикул</u>`
`<br>`	Перенос строки	`строка 1<br>строка 2`
`<span class="fs-sm">`	Мелкий шрифт (~8pt)	`<span class="fs-sm">Артикул 12345</span>`
`<span class="fs-lg">`	Крупный шрифт (~13pt)	`<span class="fs-lg">XL</span>`
Без обёртки	Обычный шрифт (~10pt)	`Просто текст`
Комбинации	Теги вкладываются	`<span class="fs-lg"><b>XL</b></span>`

Размеров шрифта всего три: мелкий / обычный / крупный. Произвольный размер в pt задать нельзя — поддерживаются только классы fs-sm, fs-lg и «без класса».

Цвета не поддерживаются. Любой style="color:..." или <font color="..."> будет удалён очисткой.

Что НЕ работает (вырезается очисткой):

<div>, <p> — не используйте. Они автоматически заменяются на <br>. Структуру стройте через <br> напрямую.
<font>, <span style="..."> с любым CSS (включая font-size, color) — стрипается, остаётся только текст.
<img>, <table>, <a>, <script>, <style> и т.п. — удаляются.
CSS3 (flexbox/grid), inline-стили, классы кроме fs-sm/fs-lg.

Особенности:

Спецсимволы JSON (", \) экранируйте по правилам JSON: \", \\.
Длина чистого текста (без тегов) — до 500 символов.
Выравнивание задаётся параметром name_h_align (left/center/right), не тегами.
Символы \n в строке автоматически конвертируются в <br>.
HTML-сущности (&, <) декодируются до фильтра — то есть <script> тоже будет вырезан, не вставится как текст.

Готовый пример:

"text": "<b>Футболка</b> хлопок<br><span class=\"fs-lg\">Размер L</span><br><span class=\"fs-sm\">Артикул: 12345</span>"

Доступные размеры этикетки (X×Y, мм): 58×40, 58×60, 20×20, 20×30, 20×40. При другом размере вернётся 400 со списком допустимых.

Ответ (немедленный)

202 Accepted { "task_id": "api:42:1731488400.123", "status": "accepted" }

Это означает что задача принята в обработку. Результат придёт асинхронно на ваш webhook_url.

Callback на webhook (успех)

Мы делаем POST на ваш webhook_url в формате multipart/form-data с двумя полями:

file — готовый PDF с этикетками
data — JSON:

{ "task_id": "api:42:1731488400.123", "payload": { ...то что вы прислали... }, "status": "success", "stats": { "total_kiz": 250, "printed_kiz": 250, "skipped_kiz": 0, "cost_kop": 0, "balance": 8750 }, "truncated": false, "inner_duplicates": { "mode": "print", "codes": 2, "excess": 3, "gtins": { "04600123456789": [{"code": "XYZ999", "count": 3}] } }, "history_duplicates": { "mode": "print", "codes": 4, "gtins": { "04600123456789": ["OLD111", "OLD222"] } } }

Callback на webhook (ошибка)

POST без поля file: передаём только form-поле data, внутри него JSON:

{ "task_id": "...", "payload": {...}, "status": "error", "error_code": "INSUFFICIENT_FUNDS", "message": "..." }

Возможные error_code: INVALID_PDF, PARSE_FAILED, TOO_MANY_KIZ (больше 2000 КИЗ), DUPLICATES_FOUND, ALL_KIZ_SKIPPED, INSUFFICIENT_FUNDS, GENERATION_FAILED.

Доставка webhook

Webhook отправляется одной попыткой. Если ваш сервер не ответил 2xx, задача помечается failed.

Стоимость

Как при обычной генерации: при активной подписке списывается с баланса (5 коп со штрихкодом, 3 коп без), иначе — бонусами (1 бонус за КИЗ). При нехватке средств webhook получит INSUFFICIENT_FUNDS.

Пример (curl)

curl -X POST https://barcode1.ru/api/v1/generate-labels/ \ -H "X-API-Key: ВАШ_КЛЮЧ" \ -F "file=@labels.pdf" \ -F 'data={ "webhook_url": "https://you.example/cb", "payload": {"order_id": 42}, "inner_dups": "skip", "history_dups": "stop", "text": "<b>Футболка</b> хлопок<br><span class=\"fs-lg\">L</span>", "bcode": "4607034567890", "barcode_type": "ean13", "label_size_x": 58, "label_size_y": 40 }'

Минимальный запрос

Обязательны два multipart-поля — file (PDF с КИЗ) и data (JSON). В самом JSON обязателен только webhook_url, остальное — опционально.

curl -X POST https://barcode1.ru/api/v1/generate-labels/ \ -H "X-API-Key: ВАШ_КЛЮЧ" \ -F "file=@labels.pdf" \ -F 'data={"webhook_url":"https://you.example/cb"}'

Получите PDF этикетки 58×40. Без bcode штрихкод не рендерится, без text этикетка только с DataMatrix и нумерацией.

Минимальные примеры на других языках

Python Node.js PHP Go

import requests r = requests.post( 'https://barcode1.ru/api/v1/generate-labels/', headers={'X-API-Key': 'ВАШ_КЛЮЧ'}, files={'file': open('labels.pdf', 'rb')}, data={'data': '{"webhook_url":"https://you.example/cb"}'}, ) print(r.json())

import fs from 'fs'; import FormData from 'form-data'; import axios from 'axios'; const form = new FormData(); form.append('file', fs.createReadStream('labels.pdf')); form.append('data', '{"webhook_url":"https://you.example/cb"}'); const r = await axios.post( 'https://barcode1.ru/api/v1/generate-labels/', form, { headers: { 'X-API-Key': 'ВАШ_КЛЮЧ', ...form.getHeaders() } } ); console.log(r.data);

<?php $ch = curl_init('https://barcode1.ru/api/v1/generate-labels/'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['X-API-Key: ВАШ_КЛЮЧ'], CURLOPT_POSTFIELDS => [ 'file' => new CURLFile('labels.pdf'), 'data' => '{"webhook_url":"https://you.example/cb"}', ], ]); echo curl_exec($ch);

body := &bytes.Buffer{} w := multipart.NewWriter(body) f, _ := os.Open("labels.pdf") fw, _ := w.CreateFormFile("file", "labels.pdf") io.Copy(fw, f) w.WriteField("data", `{"webhook_url":"https://you.example/cb"}`) w.Close() req, _ := http.NewRequest("POST", "https://barcode1.ru/api/v1/generate-labels/", body) req.Header.Set("X-API-Key", "ВАШ_КЛЮЧ") req.Header.Set("Content-Type", w.FormDataContentType()) resp, _ := http.DefaultClient.Do(req)

API для генерации этикеток