API разрешительных документов (РД) позволяет программно передавать сертификаты, декларации о соответствии, свидетельства о государственной регистрации (СГР) и отметки «документ не требуется» и привязывать их к товарам — без ручной работы в Lamoda Seller и загрузки Excel-файлов. Удобно партнёрам с собственной платформой.
Эта статья описывает порядок работы с методами. Детали каждого метода (параметры, поля, тело запроса/ответа, примеры) смотрите в справочнике по ссылке на метод.
Бизнес-контекст, сроки и требования к документам — в статьях «Разрешительные документы на товары: что меняется с 1 сентября 2026 года» и «Работа с разделом „Разрешительные документы“» Академии.
Как устроен процесс
Обработка переданных РД проходит в несколько шагов:
- Вы отправляете пакет связок «документ ↔ товары» методом создания задачи с типом
ADD(добавить) илиREMOVE(отвязать). - В ответ получаете
jobId— идентификатор принятой в обработку задачи. - Опрашиваете статус задачи по
jobId, пока он не станетDONEилиFAILED. - В завершённой задаче вы видите, сколько строк обработано и по каким строкам возникли ошибки.
- После обработки отслеживаете результат проверки документов в реестрах — методом получения статусов.
ℹ️ После успешного добавления документы уходят на проверку в реестры контролирующих органов (Росаккредитация, Единый реестр ЕАЭС, реестр СГР) асинхронно. Результат проверки (пройдена / не пройдена) получайте методом POST /v2/product-certificates (см. Проверка статусов документов) — или в Lamoda Seller, раздел «Разрешительные документы».
|
Методы для работы с РД
POST /v2/product-certificates/jobs— создать задачу: добавить документ и привязать к товарам (type: ADD) или отвязать (type: REMOVE).GET /v2/product-certificates/jobs/{jobId}— статус задачи и построчные ошибки.GET /v2/product-certificates/jobs— список задач продавца (еслиjobIdне сохранён).POST /v2/product-certificates— список документов продавца со статусами проверки в реестрах.POST /v2/product-certificates/document— карточка одного документа со списком привязанных товаров.
ℹ️ Методы получения статусов проверки и карточки документа — POST (не GET): параметры передаются в теле запроса. Так номер документа со спецсимволами (например, «ЕАЭС N RU Д-FR.PA02.B.465283/23») передаётся без URL-энкодинга.
|
Типы документов
Поле type в каждой позиции:
| Значение | Описание | Обязательные поля |
CERTIFICATE | Сертификат соответствия | number, startDate |
DECLARATION | Декларация о соответствии | number, startDate |
SGR_CERTIFICATE | Свидетельство о государственной регистрации (СГР) | number, startDate |
DOCUMENT_NOT_REQUIRED | Документ не требуется | noDocumentReason |
Если endDate не указана — документ считается бессрочным.
Причины отсутствия документа
Для типа документа DOCUMENT_NOT_REQUIRED необходимо передать один из следующих идентификаторов причины отсутствия документа:
| ID | Описание |
| 1 | Продукция, в отношении которой не распространяются действующие ТР ТС (ТР ЕЭАС) и прочие НПА |
| 2 | Детская спортивная обувь |
| 3 | Детская спортивная одежда, использующаяся при организации детских тренировок и спортивных соревнований |
| 4 | Одежда и обувь, СИЗ, используемые для снижения рисков производственной среды, не вошедшие в ТР ТС 019/2011 |
| 5 | Аксессуары и предметы одежды, не являющиеся СИЗ, в отношении которых не распространяется ТР ТС 017/2011 и ТР ТС 007/2011 |
| 6 | Изделия и аксессуары из материалов, в отношении которых отсутствует методика испытаний |
| 7 | Изделия, в отношении которых не распространяется действие ТР ТС 009/2011, постановление РФ 2425 от 23.12.2021, решение комиссии ТС 299 от 28.05.2011 и прочие действующие НПА |
| 8 | Игрушки, предназначенные для пользователей старше 14 лет |
| 9 | Игрушки, включённые в приложение N 1 ТР ТС 008/2011 |
Порядок работы
1. Добавление документов
POST /v2/product-certificates/jobs с типом ADD создаёт задачу на добавление документов и привязку к товарам. В ответ — 202 Accepted, в заголовке Location путь к статусу задачи, в теле — jobId. Сохраните jobId — по нему отслеживается обработка. Параметры, тело и примеры — в справочнике метода.
2. Получение списка задач
GET /v2/product-certificates/jobs — страница задач продавца от новых к старым, с фильтрами по статусу и типу. Найдите нужную задачу и продолжите отслеживать её через jobId.
3. Отслеживание статуса задачи
GET /v2/product-certificates/jobs/{jobId} — возвращает статус задачи и постраничный список построчных ошибок (importErrors[]). Поля ответа и примеры — в справочнике метода.
| Статус | Значение | Что делать |
PENDING | Задача принята, ожидает обработки | Продолжайте опрашивать статус |
EXECUTING | Задача обрабатывается | Продолжайте опрашивать статус |
DONE | Задача завершена | Проверьте failedItems и importErrors — исправьте и повторите проблемные строки |
FAILED | Завершена с системной ошибкой (поле error) | Повторите задачу; при повторении ошибки обратитесь в поддержку |
ℹ️ Важно. Статус DONE означает только то, что импорт документов завершён, и не означает, что все документы прошли проверку в реестрах Росаккредитации, Едином Реестре ЕАЭС или СГР. Строки, не прошедшие обработку, перечислены в importErrors. Результат проверки документов в реестрах получайте методом Проверка статусов документов — или в ЛК Lamoda Seller (раздел «Разрешительные документы»).
|
4. Проверка статусов документов в реестрах
POST /v2/product-certificates возвращает страницу документов продавца со статусами проверки в реестрах контролирующих органов. Есть фильтры по статусу проверки (status), типу документа (type), товару (sku) и номеру (number). Поля ответа и примеры — в справочнике метода.
| Статус проверки | Значение |
IN_PROGRESS | Документ на проверке |
PASSED | Проверка пройдена |
FAILED | Проверка не пройдена. В поле statusText — расширенный статус из реестра (например, «Прекращен») |
У каждого документа возвращается skuCount — количество привязанных товаров. Записи с типом DOCUMENT_NOT_REQUIRED тоже входят в выдачу: number = null, заполнена noDocumentReason, статус PASSED.
5. Карточка документа со списком товаров
POST /v2/product-certificates/document возвращает один документ со статусом проверки и постраничным списком привязанных товаров (sku, parentSku, externalSku, externalParentSku). Полезно, чтобы узнать, к каким именно товарам привязан документ (например, перед удалением).
Документ идентифицируется теми же полями, что и при удалении:
CERTIFICATE,DECLARATION,SGR_CERTIFICATE:type+number+startDate(+endDate, если документ срочный);DOCUMENT_NOT_REQUIRED:type+noDocumentReason.
6. Удаление документов
POST /v2/product-certificates/jobs с типом REMOVE отвязывает документы от товаров. Тело и примеры — в справочнике метода.
Связка для удаления идентифицируется полями:
CERTIFICATE,DECLARATION,SGR_CERTIFICATE:sku+type+number+startDate(обязательны);endDate, если передан, дополнительно уточняет поиск;DOCUMENT_NOT_REQUIRED:sku+type+noDocumentReason.
ℹ️ Как обновить документ. Загрузка нового документа (ADD) не заменяет старый: привязка уникальна по сочетанию sku + type + number + startDate + endDate. Документ с другим номером или датами добавляется как отдельная связка, а прежний остаётся на товаре. Чтобы заменить документ — сначала отвяжите старый (REMOVE), затем добавьте новый (ADD) отдельной задачей.Повторная загрузка того же документа (совпадают type, number и обе даты) идемпотентна — дубль не создаётся. Проверить, что привязано к товару, можно методом POST /v2/product-certificates/document.
|
Ошибки
Ошибки бывают двух видов: уровня запроса (весь запрос отклонён сразу) и построчные (запрос принят, но отдельные строки не обработаны — в importErrors[]). Общий формат ошибок описан в статье «Начало работы и авторизация».
Уровня запроса
| HTTP | code | Причина | Что делать |
| 400 | VALIDATION_FAILED | items пустой, больше 1000 элементов или sellerId некорректен | Проверьте тело запроса и количество позиций |
| 401 | UNAUTHORIZED | Токен отсутствует или недействителен | Проверьте заголовок Authorization |
| 403 | FORBIDDEN | sellerId не соответствует токену | Укажите sellerId, соответствующий вашему токену |
| 404 | NOT_FOUND | Задача с таким jobId не найдена (в т.ч. если принадлежит другому продавцу) | Проверьте jobId и sellerId |
| 503 | SERVICE_UNAVAILABLE | Сервис временно недоступен | Повторите запрос позже |
Построчные
Возвращаются в importErrors[] при опросе статуса и не прерывают обработку остальных строк. Ошибки формата запроса (значение вне перечисления, лишние поля, неверные типы) отклоняются синхронно как 400 VALIDATION_FAILED ещё при создании задачи.
code | Причина | Что делать |
SKU_PARTNER_MISMATCH | Товар с таким SKU не найден у продавца | Проверьте, что SKU принадлежат вашему sellerId |
MISSING_REQUIRED_FIELD | Не заполнено обязательное для типа поле | Заполните number/startDate (для сертификата, декларации и СГР) или noDocumentReason |
INVALID_NO_DOCUMENT_REASON | noDocumentReason отсутствует в справочнике причин | Укажите корректный идентификатор причины |
INVALID_END_DATE | endDate раньше startDate | Исправьте даты действия документа |
UNEXPECTED_FIELD_FOR_TYPE | Поле недопустимо для указанного type | Уберите лишние поля (например, noDocumentReason у сертификата) |
DOWNSTREAM_ERROR | Ошибка при сохранении на стороне сервиса Разрешительных документов | Проверьте данные строки; при повторении обратитесь в поддержку |
Рекомендации
- Выполняйте проверку статуса обработки задачи (job) с интервалом. Например, раз в несколько секунд, а не непрерывно. Обработка пакета из 1000 позиций занимает около минуты.
- Нумерация
rowIndexначинается с 0 — это индексный номер позиции в отправленном массивеitems. - Идемпотентность. Повторный идентичный запрос (с теми же
sellerId,typeиitems), отправленный в то время, пока предыдущая задача с такими же параметрами ещё не завершена (находится в статусеPENDINGилиEXECUTING), не создаёт новую задачу. В этом случае вернётсяjobIdсуществующей задачи. После завершения такой же запрос создаст новую задачу; повторное применение того же пакета не меняет итоговое состояние привязок. - Не смешивайте операции. Операции добавления (
ADD) и отвязки РД (REMOVE) являются разными задачами: в одном запросе выполняется только один тип задачи.
См. также
Помогла эта информация?
Спасибо за отзыв