Как экранировать специальные символы в коде идентификации для передачи в «Честный ЗНАК»

Когда нужно экранировать специальные символы

Если код идентификации (КИ) содержит специальные символы, перед подачей сведений в ГИС МТ выполните их экранирование по рекомендациям для выбранного способа передачи данных.

Экранирование — это замена управляющих символов в тексте соответствующими текстовыми подстановками. Оно позволяет отделить текст от кода и управляющих символов.

Способ экранирования зависит от того, где передаётся КИ:

• В URL запроса API — применяется стандарт RFC 3986. Описание приведено в пункте 2.1: https://datatracker.ietf.org/doc/html/rfc3986.
• В строке JSON-тела запроса — применяется стандарт RFC 8259. Описание приведено в пункте 7: https://datatracker.ietf.org/doc/html/rfc8259.
• В загружаемом CSV-файле — всю строку КИ со специальными символами нужно поместить в двойные кавычки ("). Экранирование выполняется по стандарту RFC 4180: https://tools.ietf.org/html/rfc4180.
• В строке XML-тела запроса — применяется стандарт W3C: https://www.w3.org/TR/xml/.

Как экранировать специальные символы в URL

Если вы работаете через открытый API и используете GET-запросы, экранируйте все специальные символы в строке с КИ. Ниже перечислены символы и соответствующие им подстановки.

1. ! — восклицательный знак: %21.
2. \ — обратный слэш (бэкслэш): %5C.
3. " — двойная кавычка: %22.
4. % — знак процента: %25.
5. & — амперсанд: %26.
6. ' — одинарная кавычка (апостроф): %27.
7. * — звёздочка: %2A.
8. + — плюс: %2B.
9. - — минус (тире): %2D.
10. . — точка: %2E.
11. / — слэш: %2F.
12. _ — нижнее подчёркивание: %5F.
13. , — запятая: %2C.
14. : — двоеточие: %3A.
15. ; — точка с запятой: %3B.
16. = — равно: %3D.
17. < — меньше: %3C.
18. > — больше: %3E.
19. ? — вопросительный знак: %3F.
20. ( — открывающая круглая скобка: %28.
21. ) — закрывающая круглая скобка: %29.

Примеры КИ до и после экранирования

• До: 010463003407001221VrDpTmvic%XKb

После: 010463003407001221VrDpTmvic%25XKb

До: 010463003407001221bUT'4"g=MTs_<

После: 010463003407001221bUT%274%22g%3DMTs%5F%3C

До: 010463003407001221./>*HsakfSJ:V

После: 010463003407001221%2E%2F%3E%2AHsakfSJ%3AV

Практический совет. Подготовьте для сотрудника или разработчика несколько пар «исходный КИ — КИ в URL» из приведённых примеров. Такая памятка поможет быстрее сверять результат преобразования, особенно когда в одном коде встречается сразу несколько специальных символов.

При ручной замене легко пропустить один символ или применить не ту подстановку. Тогда придётся искать ошибку в подготовленном запросе и повторять работу, откладывая передачу сведений.

SelSup поддерживает работу с системой «Честный знак» и помогает сократить ручную подготовку данных о маркировке. Автоматизация повторяющихся операций позволяет сотрудникам меньше времени тратить на обработку кодов по одному.

Как экранировать специальные символы в JSON

При работе через открытый API с POST-запросами в формате JSON инструкция рекомендует экранировать в строке с КИ двойную кавычку (") и амперсанд (&). Для этого перед соответствующим символом ставится бэкслэш (\).

Примеры экранирования двойной кавычки и амперсанда

До: 010463003407001221bUT'4"g=MTs_<

После: 010463003407001221bUT'4\"g=MTs_<

До: 010463003407001221-GFL&PguP(/V+

После: 010463003407001221-GFL\&PguP(/V+

Как экранировать специальные символы в CSV

Если вы подаёте сведения в ГИС МТ загрузкой CSV-файла и КИ содержит специальные символы, подготовьте его следующим образом:

1. Поместите всю строку КИ в двойные кавычки (").
2. Если внутри КИ уже есть двойные кавычки, поставьте перед каждой ещё одну двойную кавычку.

Примеры КИ с двойными кавычками и без них

До: 010481097886269421"LLRY<%"JZTVZ

После: "010481097886269421""LLRY<%""JZTVZ"

До: 010463003407001221-GFL&PguP(/V+

После: "010463003407001221-GFL&PguP(/V+"

Исключение: экранирование апострофом

В исключительных случаях для отдельных операционных систем экранирование выполняется с помощью апострофа ('), если он входит в состав КИ. В этом случае поставьте второй апостроф перед первым, а всю строку заключите в апострофы.

Пример КИ с апострофом:

До: 010466006407038621I?NczVEs,'IpG

После: '010466006407038621I?NczVEs,''IpG'

Смешанные примеры: апостроф и двойная кавычка

До: 010466006407038621I?Nc’VEs,"IpG

После: "010466006407038621I?Nc''VEs,""IpG"

До: 010466006407038621I?Nc"VEs,IpG'

После: "010466006407038621I?Nc""VEs,IpG''"

Практический совет. Для внутренней проверки подготовки CSV заведите отдельные контрольные примеры: КИ без кавычек, с двойной кавычкой, с апострофом и со смешанной последовательностью. Сотруднику будет проще сопоставить свой случай с нужным образцом и проверить обработку строки без повторного разбора всей инструкции.

Если при ручной подготовке CSV пропустить внешние кавычки или не удвоить кавычку внутри КИ, строка не будет соответствовать описанному способу экранирования. Поиск и исправление таких мест в большом файле отнимают время сотрудников и задерживают подготовку сведений.

SelSup помогает организовать работу с маркированными товарами в одной системе: получать и печатать коды, проверять их при сборке заказов. Это позволяет сократить число ручных операций с кодами и упростить контроль маркировки, а не вести каждый этап отдельно.

Как экранировать специальные символы в XML

Если вы подаёте сведения в ГИС МТ загрузкой XML-файла и КИ содержит специальные символы, обрамите всю строку КИ специальными последовательностями:

• в начале строки — <![CDATA[;
• в конце строки — ]]>.

При таком оформлении дополнительно экранировать специальные символы внутри КИ не нужно.

Примеры оформления КИ в XML

До: 010463003407001221joMWPMeGOFt3r

После: <![CDATA[010463003407001221joMWPMeGOFt3r]]>

До: 010463003407001221bUT'4"g=MTs_<

После: <![CDATA[010463003407001221bUT'4"g=MTs_<]]>

Совет по организации работы. В памятке для сотрудника или в задаче разработчику отдельно зафиксируйте: для описанного XML-сценария используется обрамление всей строки, без дополнительных замен внутри КИ. Так при проверке результата будет проще отличить оформление XML от обработки того же кода для URL, JSON или CSV.

Сокращения и термины

• API — Application Programming Interface, интерфейс программирования приложений. Это программный интерфейс приложения: набор готовых классов, процедур, функций, структур и констант, которые приложение, библиотека, сервис или операционная система предоставляет для использования во внешних программных продуктах.
• CSV — Comma-Separated Values. Текстовый формат файла для представления табличных данных.
• JSON — JavaScript Object Notation. Текстовый формат обмена данными, основанный на JavaScript.
• URL — Uniform Resource Locator. Унифицированный указатель ресурса.
• XML — eXtensible Markup Language. Расширяемый язык разметки. Он состоит из набора тегов, их атрибутов и значений, а также правил, определяющих, какие атрибуты и элементы могут входить в состав других элементов.
• XSD — XML schema definition. Язык описания структуры XML-документа.
• ГИС МТ — государственная информационная система, созданная для автоматизации сбора и обработки информации об обороте товаров, подлежащих обязательной маркировке средствами идентификации. Система также предназначена для хранения этой информации, обеспечения доступа к ней, её предоставления и распространения, повышения эффективности обмена информацией и обеспечения прослеживаемости таких товаров. Другие цели её создания могут быть предусмотрены федеральными законами.
• КИ — код идентификации. Последовательность символов, представляющая собой уникальный номер экземпляра товара. Её формирует Оператор информационной системы мониторинга для идентификации товаров, в том числе в потребительской упаковке.
• Оператор — частный партнёр, действующий в качестве Оператора Единой системы маркировки в соответствии с распоряжением Правительства РФ от 8 мая 2019 г. № 899-р «О реализации проекта государственно-частного партнёрства, заключаемого в целях создания, эксплуатации и технического обслуживания объекта, предназначенного для обеспечения маркировки и прослеживаемости отдельных видов товаров» (https://честныйзнак.рф), распоряжением Правительства Российской Федерации от 3 апреля 2019 г. № 620-р «Об операторе государственной информационной системы мониторинга за оборотом товаров, подлежащих обязательной маркировке» и распоряжением № 2828-р от 18 декабря 2019 года.
• ТОРГ-2 — акт о расхождениях в количестве или качестве товара.
• УКД — универсальный корректировочный документ. Электронный документ, формат которого утверждает Федеральная налоговая служба. Предназначен для документирования изменения стоимости ранее осуществлённой поставки и (или) расхождения по количеству либо качеству продукции при её приёмке.
• УПД — универсальный передаточный документ. Электронный документ об отгрузке товаров, выполнении работ, оказании услуг или передаче имущественных прав. Его формат утверждает Федеральная налоговая служба.
• Участник оборота товаров — юридическое лицо или физическое лицо, зарегистрированное в качестве индивидуального предпринимателя, которое является налоговым резидентом Российской Федерации и осуществляет ввод товаров в оборот, их оборот и (или) вывод из оборота. К участникам не относятся юридические лица и физические лица, зарегистрированные в качестве индивидуальных предпринимателей, которые приобретают товары для использования в целях, не связанных с последующей реализацией (продажей).

Главный практический вывод: выбирайте способ экранирования по формату передачи данных. Для URL, JSON, CSV и XML в инструкции предусмотрены разные способы обработки КИ — один и тот же шаблон замены не подходит для всех сценариев.

Следующий вопрос — как организовать работу с кодами от получения до проверки при сборке заказа, чтобы сотрудники меньше обрабатывали их вручную. На демонстрации SelSup можно посмотреть получение и печать кодов, проверку маркировки при сборке и обсудить, какие операции в вашем процессе стоит автоматизировать.