Содержание
Актуально на 11 июля 2026 г.

Внешний API Checkmark v1

Внешний API v1 находится под /api/integrations/v1/*. Это стабильный серверный интерфейс для подключения учетных, складских, кассовых, WMS/ERP и внутренних IT-систем к данным Checkmark без прямого доступа к базе.

Для чего

API нужен, чтобы внешние системы могли автоматизировать работу с Checkmark: проверять коды маркировки, читать справочники и остатки, создавать и отслеживать кейсы пересорта, а также получать статусы обработки и печати.

Что может

  • Показать, к какому клиенту и организации относится текущий API-токен.
  • Вернуть адреса, ИНН и поставщиков организации.
  • Проверить полный КМ через тот же контур классификации, который используется в интерфейсе Checkmark.
  • Дать список проверенных КМ без раскрытия полного raw-кода в ответах.
  • Вернуть остатки по адресу, кейсы пересорта и статусы печати.
  • Создать кейс пересорта с защитой от дублей через Idempotency-Key.

Как использовать

Администратор создает API-клиента в настройках Checkmark, передает интеграции client_id и одноразово показанный client_secret. Интеграция получает короткий Bearer-токен и вызывает только методы /api/integrations/v1/* с нужными правами доступа.

Активный API-клиент занимает один слот в лимите устройств ЛК. Если лимит устройств уже исчерпан, сначала отключите лишнее устройство или отзовите ненужного API-клиента.

Авторизация

  1. Администратор создает клиента в API-клиентах.
  2. Интеграция получает Bearer-токен:
POST /api/integrations/oauth/token
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "chm_example",
  "client_secret": "chmsec_example",
  "scope": "directories:read marks:check resort:write"
}
  1. Дальше интеграция передает токен:
Authorization: Bearer <access_token>

Токен короткоживущий. По умолчанию срок жизни - 15 минут.

Права

  • directories:read - адреса, ИНН и поставщики.
  • marks:read - чтение КМ.
  • marks:check - проверка КМ.
  • inventory:read - чтение остатков.
  • resort:read - чтение кейсов пересорта.
  • resort:write - создание кейсов пересорта.
  • print:read - чтение статусов печати.

Если права не хватает, API возвращает 403. Если токен отсутствует или недействителен, API возвращает 401.

Операции v1

  • GET /api/integrations/v1/me
  • GET /api/integrations/v1/facilities
  • GET /api/integrations/v1/legal-entities
  • GET /api/integrations/v1/suppliers
  • POST /api/integrations/v1/marks/check
  • GET /api/integrations/v1/marks
  • GET /api/integrations/v1/marks/{scanId}
  • GET /api/integrations/v1/inventory/marks?facilityId=...
  • GET /api/integrations/v1/resort/cases
  • GET /api/integrations/v1/resort/cases/{caseId}
  • POST /api/integrations/v1/resort/cases
  • GET /api/integrations/v1/print-jobs
  • GET /api/integrations/v1/openapi.json

Idempotency-Key

Записывающие методы принимают заголовок Idempotency-Key. Повтор запроса с тем же ключом от того же клиента возвращает исходный результат. Тот же ключ с другим телом запроса отклоняется конфликтом.

Используйте idempotency для операций, которые интеграция может повторить после сетевого сбоя: проверка КМ и создание кейса пересорта.

Данные КМ

Полный raw КМ принимается только во входных запросах, где это нужно для проверки или создания операции. В списках и чтении API возвращает HRI ki, GTIN, serial, статусы, владельца и идентификаторы объектов, но не полный raw КМ по умолчанию.

Адрес проверки и ИНН

Получите адреса ЛК перед проверкой марки:

GET /api/integrations/v1/facilities
Authorization: Bearer <access_token>

Ответ содержит id, название адреса, основной inn, kpp, признак активности и allowedInns. Передайте facilityId в проверку КМ, чтобы Checkmark сразу сравнил владельца марки из Честного ЗНАКа с ИНН выбранного адреса:

POST /api/integrations/v1/marks/check
Authorization: Bearer <access_token>
Idempotency-Key: mark-check-address-0001
Content-Type: application/json

{
  "rawMark": "<full Data Matrix>",
  "facilityId": "00000000-0000-0000-0000-000000000000",
  "operationContext": "check"
}

Учетная система может добавить свой список ИНН для конкретной проверки. Поле allowedInns принимает от 1 до 200 ИНН, каждый ИНН должен содержать 10 или 12 цифр. Если одновременно переданы facilityId и allowedInns, Checkmark проверяет владельца КМ по объединенному списку: ИНН адреса, разрешенные ИНН адреса и ИНН из запроса.

POST /api/integrations/v1/marks/check
Authorization: Bearer <access_token>
Idempotency-Key: mark-check-inn-list-0001
Content-Type: application/json

{
  "rawMark": "<full Data Matrix>",
  "facilityId": "00000000-0000-0000-0000-000000000000",
  "allowedInns": ["7701000001", "7701000002", "500100000000"],
  "source": "accounting-system",
  "operationContext": "check"
}

Если владелец КМ совпал с одним из проверяемых ИНН, результат будет Affiliated, пересорт не создается, а следующая операция остается учетной проверкой. Если совпадения нет, Checkmark применяет общие правила: чужой КМ в обороте блокируется до вывода текущим владельцем, а чужой КМ, выведенный с причиной пересорта, становится кандидатом на кейс пересорта.

Когда facilityId или allowedInns переданы без lookupMode, API требует авторитетную проверку через Честный ЗНАК ЛК. Для проверки только по уже сохраненным данным передайте lookupMode: "cached".

Пример проверки КМ

Интеграция отправляет полный КМ только во входном запросе проверки. Если lookupMode не передан, Checkmark выполняет обычную проверку через Честный ЗНАК по настройкам ЛК:

POST /api/integrations/v1/marks/check
Authorization: Bearer <access_token>
Idempotency-Key: mark-check-20260710-0001
Content-Type: application/json

{
  "rawMark": "<full Data Matrix>",
  "facilityId": "00000000-0000-0000-0000-000000000000",
  "operationContext": "resort"
}

Успешный ответ содержит идентификаторы строки и проверки, результат классификации, данные Честного ЗНАКа и разобранные поля КМ:

{
  "scanId": "00000000-0000-0000-0000-000000000000",
  "checkId": "00000000-0000-0000-0000-000000000000",
  "classification": "Unknown",
  "checkSource": "Cz",
  "structureStatus": "Valid",
  "gtin": "04650075195857",
  "ownerInn": "7720514281",
  "czStatus": "EMITTED",
  "productName": "Название товара",
  "scenario": "RemarkingCandidate",
  "queue": "Error",
  "nextAction": "review-error"
}

Если не переданы ни адрес, ни allowedInns, Checkmark сохраняет проверку без сравнения со списком ИНН. В ответе и в списке КМ будет ошибка о том, что адрес не выбран.

Проверка только по кэшу

Чтобы не делать запрос в Честный ЗНАК, передайте lookupMode: "cached":

POST /api/integrations/v1/marks/check
Authorization: Bearer <access_token>
Idempotency-Key: cached-check-20260710-0001
Content-Type: application/json

{
  "rawMark": "<full Data Matrix>",
  "lookupMode": "cached",
  "source": "customer-import",
  "operationContext": "check"
}

В этом режиме API ищет последнюю сохраненную проверку того же KI и затем запись кэша ЧЗ. Внешнего запроса в ЧЗ нет. Если данные найдены, ответ содержит checkSource: "Cached" и сохраненные owner/status/shelf-life/price поля. Если данных нет, проверка сохраняется как Unknown с ошибкой CACHE_MISS.

Кэшированная проверка справочная и не считается авторитетной для создания кейса пересорта. Для юридически значимого решения используйте обычный режим без lookupMode или с lookupMode: "cz".

Пример чтения результата

После проверки сохраните scanId и перечитайте строку через read-only endpoint:

GET /api/integrations/v1/marks/00000000-0000-0000-0000-000000000000
Authorization: Bearer <access_token>

Ответ возвращает HRI ki, GTIN, serial, продукт, владельца, статус ЧЗ, срок годности, сценарий, очередь обработки и ошибки. Поле rawMark и полный исходный Data Matrix в ответе не возвращаются.

Пример пакетной проверки

Для файла или очереди сканирований отправляйте каждый КМ отдельным запросом и задавайте уникальный Idempotency-Key:

POST /api/integrations/v1/marks/check
Authorization: Bearer <access_token>
Idempotency-Key: import-20260710-line-0001
Content-Type: application/json

{
  "rawMark": "<full Data Matrix>",
  "source": "customer-import",
  "operationContext": "check",
  "comment": "import line 1"
}

Повтор того же запроса с тем же ключом возвращает тот же результат. Для чтения сохраненных строк используйте пагинацию:

GET /api/integrations/v1/marks?page=1&pageSize=200
Authorization: Bearer <access_token>

pageSize ограничен сверху значением 200.

Коды коробок и SSCC

POST /api/integrations/v1/marks/check принимает SSCC/код коробки как входную строку, например:

POST /api/integrations/v1/marks/check
Authorization: Bearer <access_token>
Idempotency-Key: package-check-20260710-0001
Content-Type: application/json

{
  "rawMark": "(00)012345678901234567",
  "source": "customer-import",
  "operationContext": "aggregation"
}

В v1 это сохраняется как короткая строка проверки с markCodeType: "Unknown" и ошибкой, если код не найден как КМ/КИ в Честном ЗНАКе. Полноценные публичные операции агрегации коробок и состава упаковки в v1 еще не открыты.

Пример чтения остатков

Остатки по адресу доступны отдельным read-only запросом:

GET /api/integrations/v1/inventory/marks?facilityId=00000000-0000-0000-0000-000000000000
Authorization: Bearer <access_token>

Документ OpenAPI доступен по /api/integrations/v1/openapi.json.

Что еще почитать

Окно API-клиенты