Программный интерфейс приложений (API)
для работы с ИС «ЭДО.Поток»

Версия 3.3 от 23.03.2021 Открыть pdf-файл

Введение

Описывается программный интерфейс приложений (API), предоставляющий возможность сторонним приложениям использовать данные из информационной системы (ИС) ЭДО.Поток для обмена юридически значимыми электронными документами.
Взаимодействие клиентского приложения и API производится путем отправки приложением HTTP-запросов к серверу и получением ответов на них. Для отправки запросов и получения ответов используется протокол HTTPS.
В случае возникновения проблем использования ИС «ЭДО.Поток», подробно опишите их и отправьте на edo@edo.ru.
Ниже описаны запросы HTTP, которыми реализуются функции API по работе с ИС «ЭДО.Поток».

1. Общий вид запроса и ответа в API

Кодировка, используемая в запросах и ответах — Windows-1251. Запросы выполняются методами POST и GET, параметры запроса располагаются в структуре данных формата JSON, передаваемой в блоке данных запроса (при использовании POST), также параметры могут передаваться в строке запроса (при использовании GET).
Ответы выдаются сервером в формате JSON и, в случае успешности ответа согласно его заголовку (код ответа по протоколу HTTP равен 200), данные имеют следующий обобщенный вид:

{
  "status": {
    "code": 0,
    "message": "string"
  }
  "result": {
  ...
  }
}

Здесь:

  • «result» — произвольный тип данных (часто — структура данных, вид которой определяется видом запроса);
  • «status» — структура, описывающая состояние обработки запроса.

Состав и назначение полей в данной структуре см. в таблице 3

2. Метод регистрации в ИС «ЭДО.Поток»

Метод позволяет зарегистрироваться в ИС «ЭДО.Поток» и получить логин и пароль дляпоследующей авторизации и работы с API

Используется метод POST следующего вида:

POST https://lk.edo.ru/api/edo/{version}/clients/registration

Здесь:

  • {version} — обозначение текущей версии системы. Текущая версия равна v1, но впоследствии номер версии может быть другим.

Запрос должен выглядеть следующим образом:

{
certificate: "MIIKJTCCCdKgAwIBAgIRAgHuzADNrbL....Строка"
email: "belka@ofd.ru"
fullLegalAddress: "г Москва"
fullName: "ИП Пирогова Александра Андреевна"
ifns: "7700"
inn: "772863973810"
kpp: ""
legalAddress: {fullName: "г Москва", area: null, building: null, city: "Москва", houseNumber: null, office: null,…}
area: null
building: null
city: "Москва"
fullName: "г Москва"
houseNumber: null
office: null
postalCode: "101000"
region: "Москва"
settlement: null
street: null
mailAddress: "г Москва"
name: "Виктория"
ogrn: "314774617000610"
password: "TestTest94"
phone: "99999999999"
}

Назначение полей структуры запроса регистрации приведено в таблице 1.

Таблица 1. Поля структуры запроса регистрации

Параметр Вложенные поля Формат значения Описание
certificate Строка Сертификат, экспортированный в формате base64
email Строка Email клиента
fullLegalAddress Строка Юридический адрес клиента (полный)
fullName Строка Полное название организации
ifns Строка Код ИФНС, состоит из 4-х цифр
inn Строка ИНН
kpp Строка КПП
legalAddress Структура Юридический адрес клиента (по составляющим)
fullName Строка Юридический адрес клиента (единое название), например «г Москва, ул Хуторская 2-я, д 38А стр 15»
area Строка Область
city Строка Город
street Строка Улица
houseNumber Строка Номер здания
building Строка Строение/корпус
office Строка Номер офиса
postalCode Строка Почтовый индекс
region Строка Регион
settlement Строка Поселок
mailAddress mailAddress Строка Адрес компании для корреспонденции (полный, например «г Москва, ул Хуторская 2-я, д 38А стр 15»)
name Строка ФИО пользователя
ogrn Строка ОГРН/ОГРИП компании
password Строка Пароль от личного кабинета EDO.ru
phone Строка Номер телефона

В ответ на запрос сервер возвращает структуру данных (приведены примеры значений):

{
  "result": {
    "clientId": "string",
    "password": "string"
  },
  "status": {
    "code": 0,
    "message": "some message here"
  }
}

Назначение полей структуры ответа на запрос регистрации приведено в таблице 2.

Таблица 2. Поля структуры ответа на запрос регистрации

Параметр Вложенные поля Формат значения Описание
result Структура Состояние запроса
clientId Строка логин клиента
password Строка пароль клиента
status Структура Состояние запроса
code Целое число Числовое представление статуса
message Строка Сообщение с описанием статуса/ошибки

3. Метод авторизации в ИС «ЭДО.Поток»

Доступ в ИС «ЭДО.Поток» возможен при использовании учетной записи пользователя.
Для получения доступа к учетной записи пользователя необходимо успешно пройти процедуру авторизации с помощью механизма AuthToken.

После успешной авторизации пользователь получает токен. И далее к каждому HTTP-запросу к ЭДО.Поток требуется добавлять HTTP-заголовок Authorization с параметром Token TOKEN1.

Authorization: Token TOKEN1

Здесь: TOKEN1 — токен, возвращенный в результате авторизации (см. п. 3.1).

Например, команда получения списка доступных входящих документов транслируется в следующий HTTP-запрос

GET https://lk.edo.ru/api/edo/v1/documents?direction=in
Authorization: Token 99a6f59f-4b2d-4b85-a8e8-0b3231983573

3.1. Авторизация через AuthToken

Авторизация посредством механизма AuthToken предполагает использование квалифицированной электронной подписи (КЭП). Для авторизации необходимо проделать следующую последовательность действий.

1. Со стороны клиента должен быть направлен запрос следующего вида:

GET https://lk.edo.ru/api/edo/{version}/clients/auth-with-ds?fingerprint={fprint1}

Здесь:

  • {version} — обозначение текущей версии системы. Текущая версия равна v1, но впоследствии номер версии может быть другим;
  • {fprint1} — отпечаток сертификата.

В ответ на запрос сервер возвращает структуру данных (приведены примеры значений):

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": "c698a3c9-d22f-4a93-9a8d-d8310cac326a"
}

Назначение полей структуры ответа на запрос авторизации приведено в таблице 3.

Таблица 3. Поля структуры ответа на запрос авторизации

Параметр Вложенные поля Формат значения Описание
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос
result Строка Поле с ключом «result» имеет тип данных «Строка», и в нем возвращается строка для подписания, которая будет использована в следующих шагах.
Действителен в течение суток с момента получения

2. Клиент подписывает строку для подписания с помощью КЭП, а затем отправляет ее вместе с подписью (CMS detached container), закодированную по алгоритму “Base64”, на тот же адрес URL с помощью запроса следующего вида:

POST https://lk.edo.ru/api/edo/{VERSION}/clients/auth-with-ds

Где {version} — обозначение текущей версии системы. Текущая версия равна v1.

Тело запроса содержит следующую структуру (приведены примеры значений):

{
  "cmsDetached": "UTA9STK1...",
  "content": "IDMYUTA9STK11070FQL..."
}

Назначение полей тела запроса на получение токена приведено в таблице 4.

Таблица 4. Поля структуры запроса на получение токена

Параметр Формат значения Описание
cmsDetached Строка Результат подписания строки (параметр result в ответе на запрос GET /auth-with-ds ), закодированный с помощью “Base64”. Результат, после кодировки должен быть представлен в виде строки (не забудьте удалить символы переноса срок, например '\n' и '\r')
content Строка Сама строка для подписания, полученная на предыдущем шаге (параметр result в ответе на запрос GET /auth-with-ds )

3. Сервер производит проверку переданной строки, и в случае успешной проверки возвращает структуру данных (приведены примеры значений):

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": {
    {
    "sessionId": "440d14a5-9070-49e1-abcd-baa013ff23ad",
    "edoOrgId": "2PS-24610035090000000000000095636522"
    }
  }
}

Назначение полей структуры ответа на запрос авторизации приведено в таблице 4.1.

Таблица 4.1. Поля структуры ответа на запрос авторизации

Параметр Вложенные поля Формат значения Описание
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос
result Структура Параметры авторизации
sessionId Строка Токен, далее используемый клиентом в качестве дополнительного параметра в последующих запросах к API.
Действителен в течение суток с момента получения
edoOrgId Строка Ваш идентификатор участника ЭДО

4. ЭДО.Поток

Запросы (функции) программного интерфейса приложений ИС «ЭДО.Поток» предназначены для выполнения операций документооборота (пересылка, сохранение, подписание документов) для внешних информационных систем, взаимодействующих с ИС «ЭДО.Поток». Большинство запросов и ответов имеет вид, описанный в разделе 2, если входные и выходные данные будут другого вида, это будет описываться дополнительно. Данные документов при передаче кодируются алгоритмом “Base64”. Запросы API ИС «ЭДО.Поток» можно разделить на три группы: запросы, связанные с документами, запросы связанные с клиентами и запросы, связанные с контрагентами. К запросам, связанным с клиентами относится также и авторизация пользователя в системе, описанная в разделе 3.

4.1. Запросы, связанные с документами

4.1.1. Получение списка документов клиента

Для получения списка документов клиента используется HTTP-метод “GET”, в ответ на запрос возвращается список документов клиента, в соответствии с переданным токеном. Список документов клиента может быть запрошен как по всему времени пользования системой, так и по заданному периоду (см. ниже).
Также может быть запрошен как полный список документов, так и его часть (страница), исходя из принципа деления списка на страницы равной длины. Длина страницы и номер выдаваемой страницы определяются в параметрах запроса (см. ниже).
Запрос на получение списка документов клиента имеет вид:

GET https://lk.edo.ru/api/edo/VERSION/documents?direction=DIRECTION&from=DATE1&to=DATE2&pageIndex=INDEX&pageRecords=NUM1&sortKey=KEY1&sortDirection=DIR1&typeOfDate=TYPE

Все параметры в данном запросе приведены в таблице 5.

Таблица 5. Параметры запроса на получение списка документов

Параметр Заменяемая строка Описание Значение по умолчанию Обязательно в запросе
VERSION Версия системы v1 да
direction DIRECTION Направление документооборота. Возможные значения:
in — входящие документы;
out — исходящие документы;
deleted — удаленные документы.
да
from DATE1 Начальная дата периода поиска документов в формате (dd.mm.yyyy), где dd — день, mm — месяц, yyyy — год нет
to DATE2 Начальная дата периода поиска документов в формате (dd.mm.yyyy) нет
pageIndex INDEX Номер запрашиваемой страницы списка документов; в виде десятичного целого числа 1 нет
pageRecords NUM Количество записей на странице. В виде десятичного целого числа 1000 нет
sortKey KEY1 Столбец для сортировки doc_id нет
sortDirection DIR1 Порядок сортировки. Возможные значения:
asc — восходящая (прямой порядок);
desc — нисходящая (обратный порядок).
desc нет
typeOfDate TYPE Способ интерпретации даты в полях from и to:
STATUS_CHANGE_DATE — дата изменения статуса;
RECEIVED_DATE — дата получения документа;
CREATION_IN_DOCUMENT_DATE — дата формирования документа.
RECEIVED_DATE нет

Далее здесь во всех запросах будет указана первая версия API (“v1”).

Пример запроса:

GET https://lk.edo.ru/api/edo/v1/documents?direction=out&from=31.08.2018&to=01.09.2018&pageIndex=1&pageRecords=50&sortKey=Doc_id&sortDirection=asc&docType=without_service_docs
Authorization: Token 99a6f59f-4b2d-4b85-a8e8-0b3231983573

Пример успешного ответа на запрос (приведены примеры значений, многоточие означает многократно повторяющуюся структуру):

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": {
    "data": [
      {
        "direction": "OUT",
        "docId": 2610,
        "fromOrgId": "2PS-003245025998032",
        "fromOrgName": "PS ST",
        "toOrgId": "2PS-00440111648005445",
        "toOrgName": "ИП Иванов",
        "edoIdFrom": "000-00010035090000000000000095600000",
        "edoIdTo": "000-0000000000003516438590065861909",
        "docTypeId": 1,
        "docTypeName": "Счёт-фактура",
        "docStateId": 0,
        "docStateName": "Создан",
        "sfStateName": "Подписано отправителем",
        "sfStateId": 3,
        "innFrom": "000000000",
        "innTo": "000000000000",
        "kppFrom": "00000000",
        "kppTo": null,
        "content": null,
        "xmlBody": "PD94bWwgdmVyc2...",
        "imgBody": null,
        "signature": "MIIGGAYJKoZIhvcNAQcCoII Строка...",
        "certificateSerialNumber": null,
        "fileName": "ON_SCHFDOPPR_2PS-0069110332410689418822_2PS-007841465194609667_20180820_80aa0ec5-d512-48a1-b504-7d84872d5dcf",
        "docName": null,
        "docNumber": "11321",
        "docDate": "01.09.2020 00:00:00",
        "sumAll": null,
        "sumNds": null,
        "updPokupatelyaId": null,
        "marking": false,
        "fingerprint": "4ff4214c64e8d8db2046defab0dAAAA",
        "mcDocState": "MC_NONE",
        "actions": [
          "ActionRemove",
          "ActionSentRefine",
          "ActionVisualization"
        ],
        "forDocument": [
          null
        ],
        "guid": null,
        "updated": "2018-08-31 13:17"
        "nds": false,
        "signRequested": false
       }
       ...
     ],
    "pageInfo": {
      "pageIndex": 1,
      "pageRecords": 1000,
      "pageCount": 1,
      "sortKey": "doc_id",
      "sortDirection": "desc"
    }
  }
}

Параметры структуры приведены в таблице 6.

Таблица 6. Параметры структуры ответа на запрос списка документов

Параметр Вложенные поля Вложенные поля Формат значения Описание
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос
result Структура Содержащая список документов
data Структура Данные списка документов
direction Строка Признак документа:
OUT — исходящий;
IN — входящий
docId Целое число Идентификационный номер (индекс) документа
fromOrgId Строка Идентификатор организации-отправителя
fromOrgName Строка Название организации-отправителя
edoIdFrom Строка Идентификатор в ЭДО организации-отправителя
edoIdTo Строка Идентификатор в ЭДО организации-получателя
toOrgId Строка Идентификатор организации-получателя
docTypeId Целое число Идентификатор типа документа
docTypeName Строка Название типа документа
docStateId Целое число Идентификатор статуса (состояния) документа
sfStateName Строка Статус подписи документа
sfStateId Целое число Идентификатор статуса подписи документа
innFrom Строка ИНН организации-отправителя
innTo Строка ИНН организации-получателя
kppFrom Строка КПП организации-отправителя
kppTo Строка КПП организации-получателя
content Строка Содержимое документа, закодированное с помощью алгоритма “Base 64”
xmlBody Строка Содержит тело документа в виде двоичного массива, закодированного с помощью алгоритма «Base 64”
imgBody Строка Содержит тело документа в виде двоичного массива, закодированного с помощью алгоритма «Base 64”
signature Строка Открепленная подпись в формате PKCS#7/CMS с публичной частью сертификата, закодированная с помощью алгоритма “Base 64”
certificateSerialNumber Строка Серийный номер сертификата
fileName Строка Наименование файла
docName Строка Наименование документа
docNumber Строка Номер документа
docDate Строка Дата генерации документа
sumAll Строка Общая сумма по документу
sumNds Строка Общая сумма НДС по документу
updPokupatelyaId Строка Идентификатор УПД покупателя
marking Логическое выражение (boolean) Признак наличия маркировки
mcDocState Строка Стейт отправки документа в ЦРПТ
actions Структура Служебная информация о возможных действиях с документом
forDocument Структура Информация о родительском документе
guid Строка Уникальный идентификатор
updated Строка Дата и время последнего обновления, формат ISO, с указанием часов и минут (без секунд, дата и время разделены пробелом)
nds Логическое выражение (boolean) Признак необходимости расчета НДС
signRequested Логическое выражение (boolean) Признак необходимости подписания документа
pageInfo Структура Информация о делении списка на страницы и о передаваемой странице списка
pageIndex Целое число Номер передаваемой страницы
pageRecords Целое число Количество строк списка на странице
pageCount Целое число Количество страниц в списке
sortKey Строка Имя поля ключа сортировки (аналогично запросу)
sortDirection Строка Направление сортировки (аналогично запросу)

4.1.2. Отправка документа

Для отправки формализованного документа заданному получателю используется запрос на основе метода POST.
Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/VERSION/documents/send

Здесь VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.
Параметры запроса располагаются в теле запроса и имеют вид следующей структуры:

{
  "to": "2PS-00631566061106315010010016107897",
  "docType": 7,
  "content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNv...",
  "signature": "MIIGGAYJKoZIhvcNAQcCoIIGCTCCBg...",
  "fileName": "my_file.txt",
  "parentDocId": "",
  "docAttrs": {
    "docName": "docName",
    "docNumber": "N-345",
    "docDate": "04.10.2018",
    "sumAll": "154.3",
    "sumNds": "12.3",
    "isNds": true,
    "isSignRequested": false
  }
}

Параметры запроса на отправку документа приведены в таблице 7.

Таблица 7. Параметры запроса на отправку документа

Параметр Вложенные поля Формат значения Описание Обязательно в запросе
to Строка Идентификатор получателя да
docType Целое число Тип документа да
content Строка Содержимое документа, закодированное с помощью алгоритма “Base 64” да
signature Строка Открепленная подпись в формате PKCS#7/CMS с публичной частью сертификата, закодированная с помощью алгоритма “Base 64” да
fileName Строка Имя файла документа да
parentDocId Строка Идентификатор документа, на основании которого был сгенерирован текущий документ нет
docAttrs Структура Содержит дополнительную информацию о документе нет
docName Строка Наименование документа нет
docNumber Строка Номер документа нет
docDate Строка Дата генерации документа нет
sumAll Строка Общая сумма по документу, указывется с использованием “.”, например “356.00” нет
sumNds Строка Общая сумма НДС по документу, указывется с использованием “.”, например “12.10” нет
isNds Логическое выражение (boolean) Признак необходимости расчета НДС нет
isSignRequested Логическое выражение (boolean) Признак необходимости подписания документа нет

Пример успешного ответа на запрос описан в разделе 1 , при этом параметр «message» имеет значение «OK», а «result» имеет значение «null».

4.1.3. Получение списка документов для подписания

Для получения клиентом списка документов для подписания используется HTTP-метод “GET”, в ответ на запрос возвращается список документов, в соответствии с переданным токеном.
Запрос на получение списка документов на подписание имеет вид:

GET https://lk.edo.ru/api/edo/VERSION/documents/for-signing?req-duplex-sign=REQ1

Параметры запроса приведены в таблице 8.

Таблица 8. Параметры запроса на получение списка документов для подписания

Параметр Заменяемая строка Описание Значение по умолчанию Обязательно в запросе
VERSION Версия системы v1 1) да
req-duplex-sign REQ1 Тип возвращаемых документов:
true — технологические (не требующие второй подписи) и прочие (требующие вторую подпись);
false — только технологические
false нет

Пример успешного ответа на запрос имеет следующий вид (приведены примеры значений):

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": [
    {
      "docId": 4483,
      "fromOrgId": "252",
      "fromOrgName": "ООО ПС-СТ",
      "toOrgId": "1",
      "toOrgName": "ОФД.РУ",
      "edoIdFrom": "2PS-00324502599803245010010096511518",
      "edoIdTo": "2PS",
      "docTypeId": 3,
      "docTypeName": "Извещение о получении электронного документа",
      "docStateId": 0,
      "docStateName": "Ожидается извещение о получении",
      "sfStateName": "Ожидается извещение о получении",
      "sfStateId": 2,
      "content": "PD94bWwgdmVyc2lvbiA9IjEuMCIgZW5jb2R...",
      "signature": null,
      "fileName": "DP_IZVPOL_2PS_2PS-0032450259980324...",
      "certFingerprint": null,
      "docName": null,
      "docNumber": null,
      "docDate": null,
      "sumAll": null,
      "sumNds": null,
      "updated": "17.10.2018 11:15:01",
      "nds": false
    }
  ]
}

Параметры ответа приведены в таблице 9.

Таблица 9. Параметры ответа на запрос списка документов на подписание

Параметр Вложенные поля Формат значения Описание
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос
result Структура Список документов на подписание
docId Целое число Идентификационный номер (индекс) документа
fromOrgId Строка Идентификатор документа, присвоенный организацией-отправителем
fromOrgName Строка Название документа, присвоенное организацией-отправителем
toOrgId Строка Идентификатор документа, присвоенный организацией-получателем
toOrgName Строка Название документа, присвоенное организацией-отправителем
edoIdFrom Строка Название системы ЭДО отправителя (в случае передачи документов между различными системами ЭДО)
edoIdTo Строка Название системы ЭДО получателя (в случае передачи документов между различными системами ЭДО)
docTypeId Целое число Идентификатор типа документа
docTypeName Строка Название типа документа
docStateId Целое число Идентификатор статуса (состояния) документа
docStateName Строка Статус документа
sfStateName Строка Статус подписи документа
sfStateId Целое число Идентификатор статуса подписи документа
content Строка Содержимое документа, закодированное с помощью алгоритма “Base 64”
signature Строка Открепленная подпись в формате PKCS#7/CMS с публичной частью сертификата, закодированная с помощью алгоритма “Base 64”
fileName Строка Имя файла документа
certFingerprint Строка Отпечаток сертификата
docName Строка Наименование документа
docNumber Строка Номер документа
docDate Строка, описывающая момент времени (дату и время в формате ISO) Дата формирования документа
sumAll Строка Общая сумма по документу
sumNds Строка Общая сумма НДС по документу
updated Строка, описывающая момент времени (дату и время в формате ISO) Дата последнего изменения документа
nds Логическое выражение (boolean) Признак необходимости расчета НДС

4.1.4. Получение предварительно заполненного шаблона документа

В некоторых случаях необходимо, чтобы «ЭДО.Поток» возвращал предварительно заполненные шаблоны XML-документов для УПД-покупателя, УКД покупателя, либо уточняющего документа.
Данные документы могут быть частично сформированы на стороне оператора ЭДО по данным родительского документа (СФ, УПД, УКД).
Недостающая часть информации вводится пользователем ИС «ЭДО.Поток» на веб-странице вручную.
Запросить предварительно заполненные шаблоны XML-документов можно с помощью запроса на основе метода POST.
Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/VERSION/documents/get-doc-template

Здесь VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.
Параметры запроса располагаются в теле запроса и имеют вид следующей структуры (приведены примеры значений):

{
  "docTypeId": 6,
  "parentDocId": 3972,
  "textRefinement": "Текстовый комментарий",
  "fingerprint": "4ff4214c64e8d8db2046defab0dAAAA"
}

Параметры запроса предварительно заполненной формы приведены в таблице 10.

Таблица 10. Параметры запроса предварительно заполненной формы

Параметр Формат значения Описание Обязательно в запросе
docTypeId Целое число Идентификатор типа документа для частично заполняемого бланка да
parentDocId Целое число Идентификатор документа, на основе которого производится частичное заполнение да
textRefinement Строка Текстовый комментарий да
fingerprint Строка Отпечаток сертификата да

Пример успешного ответа на запрос имеет следующий вид (приведены примеры значений):

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNv..."
}

Параметры ответа на запрос предварительно заполненной формы приведены в таблице 11.

Таблица 11. Параметры ответа на запрос предварительно заполненной формы

Параметр Вложенные поля Формат значения Описание
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос
result Строка Содержимое предварительно заполненной формы, закодированное с помощью алгоритма “Base 64”

4.1.5. Подписание документа

Для отправки формализованного документа заданному получателю используется запрос на основе метода POST.
Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/VERSION/documents/add-signature

Здесь VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.
Параметры запроса располагаются в теле запроса и имеют вид следующей структуры (приведены примеры значений):

{
  "docId": "2614",
  "signature": "MIIGGAYJKoZ…"
}

Параметры запроса на отправку документа приведены в таблице 12.

Таблица 12. Параметры запроса на отправку документа

Параметр Формат значения Описание Обязательно в запросе
docId Строка Идентификатор подписываемого документа да
signature Строка Открепленная подпись в формате PKCS#7/CMS с публичной частью сертификата, закодированная с помощью алгоритма “Base 64” да

Пример успешного ответа на запрос описан в разделе 1, при этом параметр «message» имеет значение «OK», а «result» имеет значение «null».

4.1.6. Удаление документа

Для удаления документа используется запрос на основе метода POST.
Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/VERSION/documents/remove-doc

Здесь VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.
Параметры запроса располагаются в теле запроса и имеют вид следующей структуры (приведены примеры значений):

{
  "docId": "2604"
}

Здесь docId — идентификатор удаляемого документа.
Пример успешного ответа на запрос описан в разделе 2, при этом параметр «message» имеет значение «OK», а «result» имеет значение «null».

4.1.7. Восстановление документа

Для восстановления удаленного документа используется запрос на основе метода POST.
Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/VERSION/documents/recover-doc

Здесь VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.
Параметры запроса располагаются в теле запроса и имеют вид следующей структуры (приведены примеры значений):

{
  "docId": "2604"
}

Здесь docId — идентификатор удаляемого документа.
Пример успешного ответа на запрос описан в разделе 1, при этом параметр «message» имеет значение «OK», а «result» имеет значение «null».

4.1.8. Добавление уточнения к документу

Для добавления к документу уточняющей информации (комментария) используется запрос на основе метода POST.
Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/VERSION/documents/request-clarification

Здесь VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.
Параметры запроса располагаются в теле запроса и имеют вид следующей структуры (приведены примеры значений):

{
  "docId": "4483",
  "comment": "test comment"
}

Здесь:

  • docId — идентификатор документа, для которого требуется уточнение;
  • comment — текст уточнения (комментария), добавляемый к документу, параметр обязателен в запросе.

Пример успешного ответа на запрос имеет следующий вид (приведены примеры значений):

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": {
    "docId": 4483,
    "fromOrgId": "252",
    "fromOrgName": "ООО ПС-СТ",
    "toOrgId": "1",
    "toOrgName": "ОФД.РУ",
    "docTypeId": 3,
    "docTypeName": "Извещение о получении электронного документа",
    "docStateId": 0,
    "docStateName": "Ожидается извещение о получении",
    "sfStateName": "Ожидается извещение о получении",
    "sfStateId": 2,
    "content": "PD94bWwgdmVyc2lvbj0iMTItLRIN...",
    "signature": null,
    "fileName": "DP_IZVPOL_2PS_2PS-0032450259980324...",
    "certFingerprint": null,
    "sumAll": null,
    "sumNds": null,
    "updated": "17.10.2018 11:15:01"
  }
}

Параметры ответа приведены в таблице 13.

Таблица 13. Параметры ответа на запрос внесения уточнения к документу

Параметр Вложенные поля Формат значения Описание
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос
result Структура Параметры документа
docId Целое число Идентификационный номер (индекс) документа
fromOrgId Строка Идентификатор документа, присвоенный организацией-отправителем
fromOrgName Строка Название документа, присвоенное организацией-отправителем
toOrgId Строка Идентификатор документа, присвоенный организацией-получателем
toOrgName Строка Название документа, присвоенное организацией-отправителем
docTypeId Целое число Идентификатор типа документа
docTypeName Строка Название типа документа
docStateId Целое число Идентификатор статуса (состояния) документа
docStateName Строка Название статуса документа
sfStateName Строка Статус подписи документа
sfStateId Целое число Идентификатор статуса подписи документа
content Строка Содержимое документа, закодированное с помощью алгоритма “Base 64”
signature Строка Открепленная подпись в формате PKCS#7/CMS с публичной частью сертификата, закодированная с помощью алгоритма “Base 64”
fileName Строка Имя файла документа
certFingerprint Строка Отпечаток сертификата
sumAll Строка Общая сумма по документу
sumNds Строка Общая сумма НДС по документу
Updated Строка, описывающая момент времени (дату и время в формате ISO) Дата последнего изменения документа

4.1.9. Получение детализированной информации о документе

Для получения детализированной информации о документе используется запрос на основе метода GET; запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/VERSION/documents/document?docId=ID1

Здесь:

  • VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим;
  • ID1 — идентификатор документа, информация о котором запрашивается.

Пример успешного ответа на запрос имеет следующий вид (приведены примеры значений):

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": {
    "docId": 4483,
    "fromOrgId": "252",
    "fromOrgName": "ООО ПС-СТ",
    "toOrgId": "1",
    "toOrgName": "ОФД.РУ",
    "edoIdFrom": "2PS-00324502599803245010010096511518",
    "edoIdTo": "2PS",
    "docTypeId": 3,
    "docTypeName": "Извещение о получении электронного документа",
    "docStateId": 0,
    "docStateName": "Ожидается извещение о получении",
    "sfStateName": "Ожидается извещение о получении",
    "sfStateId": 2,
    "content": "PD94bWwgdmVyc2lvbj0iMTItLRIN...",
    "signature": null,
    "fileName": "DP_IZVPOL_2PS_2PS-0032450259980324...",
    "certFingerprint": null,
    "sumAll": null,
    "sumNds": null,
    "updated": "17.10.2018 11:15:01"
  }
}

Структура данного ответа во многом напоминает структуру ответа на запрос о добавлении уточнения к документу.
Параметры ответа имеют то же самое назначение и описаны в таблице 9, п. 3.1.7; параметры edoIdFrom и edoIdTo аналогичны параметрам с теми же ключами (именами, идентификаторами), описанными в п. 3.1.3.

4.1.10. Получение комплекта документов

Запросить комплект связанных документов можно с помощью запроса на основе метода GET, при этом в ответе будут присутствовать все документы комплекта (СФ, ИСФ, КСФ, ИКСФ).
Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/VERSION/documents/doc-chain?docId=ID1

Здесь:

  • VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим;
  • ID1 — идентификатор одного из документов комплекта, параметр обязателен в запросе.

Успешный ответ на запрос имеет вид, аналогичный ответу, приведенному в п. 3.1.3.

4.1.11. Вывод справочника типов документов

Запросить справочник типов документов, определенных в системе, с указанием их названия, внутреннего идентификатора и признака формализованности можно с помощью запроса на основе метода GET.
Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/VERSION/dictionary/get-document-type

Здесь VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.

Успешный ответ на запрос имеет следующий вид (приведены примеры значений):

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": [
    {
      "id": 1,
      "name": "Счёт-фактура",
      "formalized": true
      "technical": false,
      "primary": true,
      "pokTitle": false
    }
  ]
}

Параметры ответа приведены в таблице 14.

Таблица 14. Параметры ответа на запрос справочника типов документов

Параметр Вложенные поля Формат значения Описание
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос
result Структура Список документов
id Целое число Внутренний идентификатор типа документа
name Строка Название типа документа
formalized Логическое выражение (boolean) Признак формализованности шаблона документа
technical Логическое выражение (boolean) Признак технического документа
primary Логическое выражение (boolean) Признак первичного документа
pokTitle Логическое выражение (boolean) Признак вторичного документа

4.1.12. Загрузка документа

Запросить содержимое документа можно с помощью запроса на основе метода GET, при этом в ответе будут присутствовать все документы комплекта (СФ, ИСФ, КСФ, ИКСФ).
Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/VERSION/documents/download-doc?docId=ID1&downloadType=TYPE1

Параметры запроса приведены в таблице 15.

Таблица 15. Параметры запроса загрузки документа

Параметр Заменяемая строка Описание Значение по умолчанию Обязательно в запросе
VERSION Версия системы v1 2) да
docId ID1 Идентификатор загружаемого документа да
downloadType TYPE1 Тип загрузки:
CURRENT — загрузка только текущего документа с заданным идентификатором;
WITH_SERVICE — загрузка документа с дополнительными служебными документами в архивном файле (.zip)
CURRENT нет

В ответ на данный запрос начинается загрузка файла в двоичном виде. В заголовках ответа (response headers) указывается имя загружаемого файла.

4.1.13. Получение извещения на подтверждение оператора (для отправителя)

После того как организация отправила документ, Оператор ЭДО создает подтверждение оператора о дате получение документа, подписывает его и направляет организации. Затем, когда организация получила подтверждение оператора, она должна отправить в ответ подписанное извещение о получении данного подтверждения.

Для получения извещения о подтверждении оператора о дате получения документа используется запрос на основе метода GET.
Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/VERSION/documents/for-sync-signing?docId=ID1

Где:
VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим;
ID1 — Id документа в ЭДО.Поток.

Пример запроса:

GET https://lk.edo.ru/api/edo/v1/documents/for-sync-signing?docId=6778895

Пример успешного ответа на запрос (приведены примеры значений, многоточие означает многократно повторяющуюся структуру):

{
	"status":{
		"code":0,
		"message":"OK"
	},
	"result":{
		"direction":null,
		"docId":631777,
		"fromOrgId":"11801",
		"fromOrgName":"ООО Ромашка Тест",
		"toOrgId":"1",
		"toOrgName":"ОФД.РУ",
		"docTypeId":3,
		"docTypeName":"Извещение о получении электронного документа",
		"docStateId":0,
		"docStateName":null,
		"sfStateName":null,
		"sfStateId":0,
		"innFrom":null,
		"innTo":null,
		"kppFrom":null,
		"kppTo":null,
		"content":"PDiDI7P8  Строка...",
		"signature":null,
		"certificateSerialNumber":null,
		"fileName":"DP_IZVPOL_2PS_2PS-00258532876001890440310032687548_20201112_e3b65627-fa62-41f7-b621-dd546625f8c4.xml",
		"docName":null,
		"docNumber":null,
		"docDate":null,
		"sumAll":null,
		"sumNds":null,
		"updPokupatelyaId":null,
		"marking":false,
		"fingerprint":null,
		"mcDocState":"MC_NONE",
		"actions":[],
		"forDocument":[null],
		"guid":"e3b65627-fa62-41f7-b621-dd546625f8c4",
		"updated":"12.11.2020 17:15:57",
		"signRequested":false,
		"nds":false
	}
}

Параметры структуры ответа приведены в таблице 6.

4.1.14. Получение извещений на документ (для получателя)

После того как организация отправила документ, Оператор ЭДО создает подтверждение оператора о дате получение документа, подписывает его и направляет организации. Затем, когда организация получила подтверждение оператора, она должна отправить в ответ подписанное извещение о получении данного подтверждения.

Для получения извещений для получателя используется запрос на основе метода GET.
Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/VERSION/documents/for-finished?docId=ID1

Где:
VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим;
ID1 — Id документа в ЭДО.Поток.

Пример запроса:

GET https://lk.edo.ru/api/edo/v1/documents/for-finished?docId=6778895

Пример успешного ответа на запрос, в случае отсутствия извещений:

{
	"status":{
		"code":0,
		"message":"OK"
	},
	"result":{
		"parentDocPossibleFinished":true,
		"techDocument":null
	}
}

Пример успешного ответа на запрос, в случае наличия извещений, требующих подписания со стороны получателя:

{
	"status":{
		"code":0,
		"message":"OK"
	},
	"result":{
		"parentDocPossibleFinished":false,
		"techDocument":{
			"direction":null,
			"docId":631775,
			"fromOrgId":"11818",
			"fromOrgName":"ИП Иванов Иван Иванович",
			"toOrgId":"1",
                        "edoIdFrom":null,
			"edoIdTo":null,
			"toOrgName":"ОФД.РУ",
			"docTypeId":3,
			"docTypeName":"Извещение о получении электронного документа",
			"docStateId":0,
			"docStateName":null,
			"sfStateName":null,
			"sfStateId":0,
			"innFrom":null,
			"innTo":null,
			"kppFrom":null,
			"kppTo":null,
			"content":"PD94bW  СТрока...",
			"signature":null,
			"certificateSerialNumber":null,
			"fileName":"DP_IZVPOL_2PS_2PS-64553144722100000000000054190308_20201112_636fe79f-f475-480d-a7a4-e87a650b9d05.xml",
			"docName":null,
			"docNumber":null,
			"docDate":null,
			"sumAll":null,
			"sumNds":null,
			"updPokupatelyaId":null,
			"marking":false,
			"fingerprint":null,
			"mcDocState":"MC_NONE",
			"actions":[],
			"forDocument":[null],
			"guid":"636fe79f-f475-480d-a7a4-e87a650b9d05",
			"updated":"12.11.2020 17:15:57",
			"signRequested":false,
                        "nds":false
		}
	}
}

Параметры структуры ответа приведены в таблице 15.1.

Таблица 15.1. Параметры структуры ответа на запрос

Параметр Вложенные поля Вложенные поля Формат значения Описание
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос
result Структура Содержащая список документов
parentDocPossibleFinished Логический тип Наличие извещений для подписания: false — есть извещения, true — нет извещений
techDocument Структура Данные списка документов
direction Строка Признак документа:
OUT — исходящий;
IN — входящий
docId Целое число Идентификационный номер (индекс) документа
fromOrgId Строка Идентификатор организации-отправителя
fromOrgName Строка Название организации-отправителя
edoIdFrom Строка Идентификатор в ЭДО организации-отправителя
edoIdTo Строка Идентификатор в ЭДО организации-получателя
toOrgId Строка Идентификатор организации-получателя
docTypeId Целое число Идентификатор типа документа
docTypeName Строка Название типа документа
docStateId Целое число Идентификатор статуса (состояния) документа
sfStateName Строка Статус подписи документа
sfStateId Целое число Идентификатор статуса подписи документа
innFrom Строка ИНН организации-отправителя
innTo Строка ИНН организации-получателя
kppFrom Строка КПП организации-отправителя
kppTo Строка КПП организации-получателя
content Строка Содержимое документа, закодированное с помощью алгоритма “Base 64”
signature Строка Открепленная подпись в формате PKCS#7/CMS с публичной частью сертификата, закодированная с помощью алгоритма “Base 64”
certificateSerialNumber Строка Серийный номер сертификата
fileName Строка Наименование файла
docName Строка Наименование документа
docNumber Строка Номер документа
docDate Строка Дата генерации документа
sumAll Строка Общая сумма по документу
sumNds Строка Общая сумма НДС по документу
updPokupatelyaId Строка Идентификатор УПД покупателя
marking Логическое выражение (boolean) Признак наличия маркировки
mcDocState Строка Стейт отправки документа в ЦРПТ
actions Структура Служебная информация о возможных действиях с документом
forDocument Структура Информация о родительском документе
guid Строка Уникальный идентификатор
updated Строка Дата и время последнего обновления, формат ISO, с указанием часов и минут (без секунд, дата и время разделены пробелом)
nds Логическое выражение (boolean) Признак необходимости расчета НДС
signRequested Логическое выражение (boolean) Признак необходимости подписания документа

4.1.15. Получение любых извещений на документы

После того как организация отправила документ, Оператор ЭДО создает подтверждение оператора о дате получение документа, подписывает его и направляет организации. Затем, когда организация получила подтверждение оператора, она должна отправить в ответ подписанное извещение о получении данного подтверждения.

Для получения извещений по всем документам используется запрос на основе метода GET.
Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/VERSION/documents/for-signing

Где:
VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.

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

{
	"status":{
		"code":0,
		"message":"OK"
	},
	"result":[
		{
			"direction":null,
			"docId":631758,
			"fromOrgId":"11818",
			"fromOrgName":"ИП Иванов Иван Иванович",
			"toOrgId":"1",
			"toOrgName":"ОФД.РУ",
			"edoIdFrom":null,
			"edoIdTo":null,
			"docTypeId":3,
			"docTypeName":"Извещение о получении электронного документа",
			"docStateId":0,
			"docStateName":null,
			"sfStateName":null,"sfStateId":0,
			"innFrom":null,
			"innTo":null,
			"kppFrom":null,
			"kppTo":null,
			"content":"PD94b  Строка...",
			"signature":null,
			"certificateSerialNumber":null,
			"fileName":"DP_IZVPOL_2PS_2PS-64553144722100000000000054190308_20201112_c518df7a-d0ae-41c3-9ddf-500689254d32.xml",
			"docName":null,
			"docNumber":null,
			"docDate":null,
			"sumAll":null,
			"sumNds":null,
			"updPokupatelyaId":null,
			"marking":false,
			"fingerprint":null,
			"mcDocState":"MC_NONE",
			"actions":[],
			"forDocument":[null],
			"guid":"c518df7a-d0ae-41c3-9ddf-500689254d32",
			"updated":"12.11.2020 12:06:43",
			"nds":false,
			"signRequested":false
		},
		...
	]
}

Параметры структуры ответа приведены в таблице 6.

Пример успешного ответа на запрос, в случае отсутствия извещений:

{
	"status":{
		"code":0,
		"message":"OK"
	},
	"result":[
	]
}

4.1.16. Получение PDF-представления формализованного документа

Документ в формате “Adobe PDF” удобен для просмотра и печати, возможность генерации такого документа присутствует в ИС «ЭДО.Поток», это действие возможно произвести с помощью запроса на основе HTTP-метода GET.
Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/VERSION/documents/show-doc-pdf?docId=ID1

Здесь:

  • VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим;
  • ID1 — идентификатор документа, на основе которого по запросу генерируется документ в формате “Adobe PDF”. Параметр обязателен.

В ответ на данный запрос начинается загрузка файла в двоичном виде. В заголовках ответа (response headers) указывается имя загружаемого файла.

4.2. Работа с контрагентами

Существует группа запросов к ИС «ЭДО.Поток», предназначенных для получения данных о взаимодействующих с клиентами контрагентах.

4.2.1. Поиск контрагентов

По данному запросу ИС «ЭДО.Поток» производит поиск информации о контрагентах, параметры которых соответствуют задаваемым в параметрах запроса поиска. Запрос построен на основе HTTP-метода GET и имеет следующий вид:

GET https://lk.edo.ru/api/edo/{version}/contractors/search-contractors?query={inf01}

Параметры запроса на поиск контрагента приведены в таблице 16.

Таблица 16. Параметры запроса на поиск контрагента

Параметр Заменяемая строка Описание
{version} Версия системы, текущая версия равна v1. В дальнейшем версия может измениться
query {inf01} ИНН клиента, КПП клиента или последовательность символов, искомая в полном названии контрагента 3)

Успешный ответ на запрос имеет следующий вид:

{
  "status": {
    "code": 0,
    "message": "OK"
  },
  "result": {
    "data": [
      {
        "clientId": "2PS-00278567668300483440610014472643",
        "fullName": "ООО \"Рога и копыта\"",
        "phone": "79103333412",
        "email": "RogaIKopyta@rk.ru",
        "mailAddress": null,
        "fullLegalAddress": "Брянск г Брянской Пролетарской Дивизии ул 9",
        "kpp": "048344061",
        "inn": "2785676683",
        "ogrn": "5097571958996",
        "ifns": null,
        "certificate": null,
        "stateName": null,
        "legalAddress": {
          "postalCode": null,
          "region": null,
          "area": null,
          "city": null,
          "settlement": null,
          "street": null,
          "houseNumber": null,
          "building": null,
          "office": null,
        }
      },
      "status": "NEW"
    ],
    "pageInfo": {
      "pageIndex": 1,
      "pageRecords": 1,
      "pageCount": 239,
      "sortKey": NULL,
      "sortDirection": "desc"
    }
  }
}

Параметры ответа на запрос на поиск контрагента приведены в таблице 17.

Таблица 17. Параметры ответа на запрос на поиск контрагента

Параметр Вложенные поля Вложенные поля Формат значения Описание
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос
result Структура Информацию по клиенту
data Структура Записи о контрагентах. Параметры элементов структуры data приведены в таблице 15.1
pageInfo Структура Информация о делении списка на страницы и о передаваемой странице списка
pageIndex Целое число Номер передаваемой страницы
pageRecords Целое число Количество строк списка на странице
pageCount Целое число Количество страниц в списке
sortKey Строка Имя поля ключа сортировки
sortDirection Строка Направление сортировки (см. п. 3.1.1, таблица 3)

Таблица 17.1. Параметры структуры «data»

Параметр Вложенные поля Формат значения Описание
clientId Строка Идентификатор клиента в ИС «ЭДО.Поток»
fullName Строка Полное название клиента
phone Строка Телефонный номер клиента
email Строка Адрес электронной почты клиента
mailAddress Строка Фактический почтовый адрес клиента одной строкой
fullLegalAddress Строка Юридический адрес клиента одной строкой
kpp Строка КПП клиента
inn Строка ИНН клиента
ogrn Строка ОГРН клиента
ifns Строка Идентификационный номер ФНС, за которой закреплен клиент
certificate Строка Открытая часть сертификата электронной подписи клиента
stateName Строка Название государства, к которому относится клиент
legalAddress Структура Информация о юридическом адресе клиента
postalCode Строка Почтовый индекс
region Строка Область
area Строка Район области (если используется)
city Строка Город
settlement Строка Населенный пункт
street Строка Улица
houseNumber Строка Номер дома
building Строка Номер корпуса или здания
office Строка Номер офиса
status Строка Состояние контрагента

4.2.2. Получение списка контрагентов с заданным статусом

Для получения списка контрагентов с фильтрацией по статусу применяется запрос, построенный на HTTP-методе GET и имеющий следующий вид:

GET https://lk.edo.ru/api/edo/{version}/contractors?status={status1}

Параметры запроса на поиск контрагента с заданным статусом приведены в таблице 18.

Таблица 18. Параметры запроса на поиск контрагента с заданным статусом

Параметр Заменяемая строка Описание
{version} Версия системы, текущая версия равна v1. В дальнейшем версия может измениться
status {status1} Состояние (статус) контрагента. Возможные значения:
NEW — запросы не были отправлены ни от контрагента, ни от клиента;
REQUEST_SENT — контрагенту направлен запрос от клиента для начала ЭДО;
REQUEST_RECEIVED — направленный запрос для начала ЭДО принят контрагентом;
CONFIRMED — контрагент и клиент обменялись запросами и ответами, документооборот возможен

Успешный ответ на запрос имеет вид, аналогичный ответу, приведенному в п. 4.2.1.

4.2.3. Получение списка контрагентов выбранного клиента

Для получения списка контрагентов выбранного клиента применяется запрос, построенный на HTTP-методе GET и имеющий следующий вид:

GET https://lk.edo.ru/api/edo/{version}/contractors?clientNamePart={str}&pageRecords={num}

Параметры запроса списка контрагентов выбранного клиента приведены в таблице 19.

Таблица 19. Параметры запроса списка контрагентов выбранного клиента

Параметр Заменяемая строка Описание Обязательно в запросе
{version} Версия системы, текущая версия равна v1. В дальнейшем версия может измениться да
clientNamePart {str} Последовательность символов, искомая в полном названии контрагента нет
pageRecords {num} Количество записей на странице, в виде десятичного целого числа нет

Результатом запроса является структура данных, подобная описанной в п. 4.2.1, назначение полей описано в таблице 14.

5. Маркировка

5.1. Авторизация для работы с маркировкой

Для работы с системой маркировки: отправки заказа на эмиссию кодов маркировки, документа ввода в оборот или для обновления статуса обработки этих документов в системе маркировки необходима авторизация со стороны клиента. Ключ сессии, полученный при авторизации действует в течение 10 часов.
Для авторизации потребуется:

  1. Методом «Запросить авторизацию при единой аутентификации» получить данные для авторизации.
  2. Сформировать прикрепленную подпись для данных, полученных на предыдущем методе.
  3. Передать подписанные данные с помощью метода «Получить ключ сессии при единой аутентификации».

Текущий статус авторизации можно получить с помощью метода «Получить состояние авторизации».

5.1.1 Запрос авторизации при единой аутентификации

Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/{version}/introduction/auth/data-for-sign

Здесь {version} — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.

Пример ответа на запрос:

{
  "contentsToSign": [
    {
      "contents": [
        {
          "content": "YmEtYTU1ZC1kNjIzMGM2NGIzMzIiCn0K",
          "id": "df08122e-30b5-11eb-adc1-02411c120123"
        }
      ],
      "providerId": "4f770978-abae-49dd-a2c7-9329b61556e9"
    }
  ]
}

Таблица 20. Параметры ответа на запрос

Параметр Формат значения Описание
Структура Содержащая контейнеры для подписания
content String Строка на подпись пользователю
id String Уникальный идентификатор запроса на аутентификацию
providerId String Идентификатор провайдера авторизации

5.1.2 Получение ключа сессии при единой аутентификации

Чтобы получить ключ сессии при единой аутентификации используется метод POST следующего вида:

POST https://lk.edo.ru/api/edo/{version}/introduction/auth/sign

Здесь {version} — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.

Пример запроса:

{
  "signedContents": [
    {
      "contents": [
        {
          "content": "YmEtYTU1ZC1kNjIzMGM2NGIzMzIiCn0K....",
          "id": "df08122e-30b5-11eb-adc1-02411c120123"
        }
      ],
      "providerId": "4f770978-abae-49dd-a2c7-9329b61556e9"
    }
  ]
}

Таблица 21. Параметры структуры ответа

Параметр Формат значения Описание
Структура Содержащая контейнеры для подписания
content String Сформированная прикрепленную подпись для контента, полученного ранее: параметр «content» из ответа за запрос метода «Запрос авторизации при единой аутентификации»
id String Уникальный идентификатор запроса на аутентификацию, полученный в методе «Запрос авторизации при единой аутентификации»
providerId String Идентификатор провайдера авторизации, полученный в методе «Запрос авторизации при единой аутентификации»

Пример ответа на запрос:


{
  "actualStates": [
    {
      "inn": "5250030906",
      "profiles": [
        {
          "providerId": "4f770978-abae-49dd-a2c7-9329b61556e9",
          "tokenTtl": "2018-01-01T12:13:14Z"
        }
      ]
    }
  ]
}

Таблица 22. Поля структуры ответа на запрос

Параметр Формат значения Описание
inn Строка ИНН клиента
legalAddress Массив данных Профили авторизации
providerId Строка Идентификатор провайдера авторизации
tokenTtl Строка Время инвалидации токена (UTC).

5.1.3 Получение состояния авторизации

Чтобы получить состояние авторизации используется метод GET следующего вида:

GET https://lk.edo.ru/api/edo/{version}/introduction/auth/state

Здесь {version} — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.

Пример ответа на запрос:

{
  "actualStates": [
    {
      "inn": "5250030906",
      "profiles": [
        {
          "providerId": "4f770978-abae-49dd-a2c7-9329b61556e9",
          "tokenTtl": "2018-01-01T12:13:14Z"
        }
      ]
    }
  ]
}

Таблица 23. Поля структуры состояния авторизации

Параметр Формат значения Описание
inn Строка ИНН пользователя
legalAddress Массив данных Профили авторизации
providerId Строка Идентификатор провайдера авторизации. Параметр будет отсутвовать, если токена авторизации нет или закончился срок его действия
tokenTtl Строка Время инвалидации токена (UTC). Параметр будет отсутвовать, если токена авторизации нет или закончился срок его действия

5.2. Заказ кодов маркировки

Порядок действий при заказе кодов маркировки:

  1. Методом "5.2.1 Создание заказа на коды маркировки" создать заказ на коды маркировки.
  2. Методом "5.2.2 Получить контенты заказа для подписания" получить один или несколько бинарных контентов заказа (Base64) и идентификаторов контента.
  3. Подписать полученные контенты. Для подписания контента требуется взять данные из параметра «content» запроса «5.2.2 Получить контенты заказа для подписания», перевести эти данные из формата base64 в бинарные данные и поместить в файл для подписания, после чего сформировать открепленную однострочную (без знаков переноса) подпись.
  4. Методом "5.2.3 Отправка подписанных контентов заказа" передать бинарный контент подписи (в Base64) и идентификатор контента, для которого сформирована подпись
  5. Проверять статус заказа с помощью метода "5.2.4 Получить статус заказа", пока статус не изменится на success или partialFailure
  6. Получить коды методом "5.2.6 Получение кодов маркировки"

Так же существует метод "5.2.5 Cписок заказов и их статусы" на получение списка заказов и краткой информации по ним; метод "5.2.7 Получение подробной информации о статусе каждого кода товара/GTIN в заказе" и "5.2.8 Получение информации об общих параметрах заказа"

5.2.1 Создание заказа на коды маркировки

Для создания заказа используется запрос на основе метода POST. Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/{version}/marking-codes/orders/create

Здесь {version} — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим.

Параметры запроса на создание заказа приведены в таблице 25.

Таблица 25. Параметры запроса на создание заказа

Параметр Вложенные поля Формат значения Описание Обязательно в запросе
orderName String Наименование заказа Да
number String Номер заказа (должен быть уникальным) Да
comment String Комментарий к заказу Нет
positions Структура Список товаров Да
gtin String (14) [0-9] {14} Код товара (GTIN) Да
name String Наименование товара Да
quantity Integer($int32) Количество КМ Да
serialNumberType String Способ генерации серийных номеров:
SELF_MADE — самостоятельно;
OPERATOR — оператором ГИС МТ.
Да
serialNumbers JSON Array of String Массив серийных номеров. Это
поле указывается в случае, если
значение «serialNumber = SELF_MADE»
Нет
Условно
обязательное
templateId Integer ($int32) Идентификатор шаблона товарной группы:
1 — обувные товары;
10— предметы одежды, белье
постельное, столовое, туалетное
и кухонное.
Да
stickerId String Идентификатор этикетки.
Заполняется только при создании заказа
в рамках процесса дистрибуции.
Нет
Условно
обязательное
cisType String Тип кода маркировки:
UNIT — единица товара;
BUNDLE — комплект;
SET — набор;
GROUP — групповая потребительская упаковка.
Используется только для ТГ «Одежда», обязательно для данной ТГ.
Нет
Условно
обязательное
exporterTaxpayerId String ИНН/УНБ (или аналог) экспортера.
Используется только для ТГ «Одежда» и «Обувь».
Становится обязательным для этих ТГ, только если в поле releaseMethod
(способ выпуска товара в оборот) было выбрано
значение «CROSSBORDER» (Ввезен в РФ из стран ЕАЭС)
Нет
Условно
обязательное
productGroup String Товарная группа:
lp — легкая промышленность;
shoes — обувные товары.
Да
clientToken String Да
omsId String Да
createMethodType String Способ изготовления:
SELF_MADE — Самостоятельно;
CEM — ЦЭМ;
CM — Контрактное производство;
CL — Логистический склад;
CA — Комиссионная площадка.
Используется только для ТГ «Одежда» и «Обувь», обязательно для данных ТГ.
Нет
Условно
обязательное
releaseMethodType String Способ выпуска товаров:
PRODUCTION — производство РФ;
IMPORT — ввезен в РФ (импорт);
REMAINS — маркировка остатков (доступно только для ТГ «Шины», «Альтернативный табак», «Духи и туалетная вода»);
COMMISSION — Принят на комиссию от физического лица (доступно для ТГ «Одежда», «Обувь»).
Используется только для ТГ «Одежда» и «Обувь», обязательно для данных ТГ.
Нет
Условно
обязательное
contactPerson String Контактное лицо.
Используется только для ТГ «Одежда» и «Обувь»
Нет
productionOrderId String Идентификатор производственного заказа.
Используется только для ТГ «Одежда» и «Обувь»
Нет
serviceProviderId String(36) UUID Идентификатор сервис-провайдера.
Используется только при наличии сервис-провайдера
в ЛК Честного знака.
Нет

Пример содержимого заказа кодов по товарной группе «Предметы одежды, белье постельное, столовое, туалетное и кухонное»

{
  "orderName": "Заказ Краснодар №41",
  "number": "NUMBER_1",
  "comment": "Comment",
  "positions": [
    {
      "gtin": "04636332455049",
      "name": "ПАЛЬТО ЗИМНЕЕ ЛЁГКОЕ КОРИЧНЕВОЕ .ВОРОТНИК-ПЕСЕЦ",
      "quantity": 125,
      "serialNumberType": "OPERATOR",
      "templateId": 10,
      "cisType": "BUNDLE"
    },
    {
      "gtin": "04636332455041",
      "name": "Наволочки белые 40х30х60 артикул 8786347879",
      "quantity": 125,
      "serialNumberType": "OPERATOR",
      "templateId": 10,
      "cisType": "UNIT
    },
  ],
  "productGroup": "lp",
  "clientToken": "d1d15b74-e56a-45d9-aaa9-9ad25f5108e8",
  "omsId": "79871fbf-c16d-4213-868a-462f5fcacc19",
  "createMethodType": "SELF_MADE",
  "releaseMethodType": "PRODUCTION",
  "contactPerson": "Иванов П.А."
}

Пример содержимого заказа кодов по товарной группе «Обувные товары»

{
  "orderName": "Заказ Уфа №41 от 01.02.2021",
  "number": "NUMBER_DRAFT_2",
  "comment": "Comment",
  "positions": [
    {
      "gtin": "04636332455067",
      "name": "Галоши резиновые мужские, 56 размер",
      "quantity": 100,
      "serialNumberType": "OPERATOR",
      "templateId": 1
    }
  ],
  "productGroup": "SHOES",
  "clientToken": "d1d15b74-e56a-45d9-aaa9-9ad25f5108e8",
  "omsId": "79871fbf-c16d-4213-868a-462f5fcacc19",
  "createMethodType": "SELF_MADE",
  "releaseMethodType": "IMPORT"
}

В случае успешной отправки возвращается идентификатор заказа (draftId). Пример успешного ответа на запрос:

  "df08122e-30b5-11eb-adc1-0242ac120016"


5.2.2 Получить контенты заказа для подписания

Для получения контентов заказа для подписания используется запрос на основе метода GET. Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/{version}/marking-codes/orders/{draftId}/contents

Здесь:

  • {version} — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим;
  • {draftId} — идентификатор заказа, полученный на предыдущем шаге (содержится в успешном ответе на запрос POST /marking-codes/orders/create).

Пример успешного ответа на запрос:

[
  {
    "content": "ewogICAgInByb2R1Y3...",
    "id": "6f9619ff-8b86-d011-b42d-00cf4fc964f2"
  },
  {
    "content": "CAgICAgICAgImAgImA...",
    "id": "6cbf8302-25f6-4139-834e-b857143cbd8f"
  }
]

Параметры ответа приведены в таблице 26.

Таблица 26. Параметры структуры ответа на запрос

Параметр Формат значения Описание
Структура Содержащая контейнеры для подписания
content String Контент документа в формате base64
id String Идентификатор контента документа

После получения контентов для подписания, нужно подписать их. Для этого требуется перевести данные из формата base64 в бинарные данные и поместить в файл для подписания, после чего создать открепленную однострочную (без знаков переноса) подпись и отправляем ее, используя метод «4.1.3 Отправка подписанных контентов заказа».

5.2.3 Отправка подписанных контентов заказа

Метод позволяет отправить заказ на обработку в «Честный ЗНАК». Используется после получения контентов из метода «4.1.2 Получить контенты заказа для подписания» и их подписания. Для подписания контента требуется перевести данные параметра «content» из формата base64 в бинарные данные и поместить в файл для подписания, после чего создать открепленную однострочную (без знаков переноса) подпись и отправить ее в параметре «content» запроса «4.1.3 Отправка подписанных контентов заказа».

Для отправки подписанных контентов заказа используется запрос на основе метода POST. Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/{version}/marking-codes/orders/{draftId}/contents/sign

Здесь:

  • {version} — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим;
  • {draftId} — идентификатор заказа, полученный в методе «4.1.1 Создание заказа на коды маркировки».

Параметры запроса на отправку заказа в «Честный ЗНАК» представлены в таблице 27.

Таблица 27. Параметры структуры запроса

Параметр Формат значения Описание
Структура Содержащая подписанные контейнеры
content String Подписанный контент заказа
id String Идентификатор контента заказа

Пример содержимого метода отправки заказа:

{
  "contents": [
    {
      "content": "MIIMuAYJKoInByb2R1Y3RzIjogWwogICA...",
      "id": "6f9619ff-8b86-d011-b42d-00cf4fc964f2"
    },
    {
      "content": "MIIMuAYJKoZIhvcNAQcCoIIMqTCCDKUCA...",
      "id": "6cbf8302-25f6-4139-834e-b857143cbd8f"
    }
  ]
}

В случае успешной отправки возвращается Response Messages: 201 ОК.

5.2.4 Получить статус заказа

Метод позволяет получить статус конкретного заказа, используется запрос на основе метода GET. Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/{version}/marking-codes/orders/{draftId}/status

Здесь:

  • {version} — обозначение версии системы, текущая версия равна v1 (но впоследствии номер версии может быть другим);
  • {draftId} — идентификатор заказа, полученный в методе «4.1.1 Создание заказа на коды маркировки».

Пример успешного ответа на запрос:

    IN_PROC

Параметры ответа представлены в таблице 28.

Таблица 28. Параметры структуры ответа на запрос

Формат значения Описание
String Статус заказа:
DRAFT — Черновик,
INPROC — Заказ в обработке,
SUCCESS — Заказа обработан без ошибок,
FAILURE — Заказ обработан: ошибка по всем позициям,
PARTIALFAILURE — Заказ обработан: часть позиций с ошибками.



5.2.5 Cписок заказов и их статусы

Для получения списка заказов и их статусов используется запрос на основе метода POST. Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/{version}/marking-codes/orders/list

Здесь {version} — обозначение версии системы, текущая версия равна v1 (но впоследствии номер версии может быть другим).

Параметры запроса приведены в таблице 29.

Таблица 29. Параметры запроса на получение списка заказа

Параметр Формат значения Описание Значение по умолчанию Обязательность в запросе
creationTimeFromIncl String Начальная дата периода поиска документов в формате (dd.mm.yyyy), где dd — день, mm — месяц, yyyy — год нет
creationTimeToExcl String Конечная дата периода поиска документов в формате (dd.mm.yyyy), где dd — день, mm — месяц, yyyy — год Текущая дата нет
orderName String Наименование заказа нет
draftId String Идентификатор заказа нет
pageSize NUM Количество записей на странице. В виде десятичного целого числа 1000 нет
pageIndex INDEX Номер запрашиваемой страницы списка документов; в виде десятичного целого числа 1 нет

Пример запроса:

{
  "creationTimeFromIncl": "01.01.2021",
  "creationTimeToExcl": "01.02.2021",
  "pageSize": 1000,
  "pageIndex": 1
}

Пример запроса без фильтров:

{

}

Пример успешного ответа на запрос:

{
  "result": {
    "data": [
      [
        {
          "draftId": "3cf0b5ce-447d-4fb9-86dd-c982362aa754",
          "productGroup": "lp",
          "creationTime": "2021-03-22T11:18:56.174Z",
          "status": "Success",
          "requestedQuantity": 9,
          "actualQuantity": 9,
          "gtinCount": 3,
          "orderName": "Тестирование 1 ",
          "number": "1616411464201",
          "releaseMethodType": "IMPORT"
        }
      ]
    ],
    "pageInfo": {
      "pageCount": 0,
      "pageIndex": 0,
      "pageRecords": 0,
      "sortDirection": "string",
      "sortKey": {
        "present": true
      }
    }
  },
  "status": {
    "code": 0,
    "message": "string"
  }
}

Параметры ответа представлены в таблице 30.

Таблица 30. Параметры структуры ответа на запрос

Параметр Вложенные поля Вложенные поля Формат значения Описание
result Структура Параметры авторизации
data Структура Данные списка заказов
creationtime Строка Дата создания заказа
draftId Строка Идентификатор заказа, полученный в ответе на метод «Создание заказа на коды маркировки»
orderName Строка Наименование заказа
number Строка Идентификатор заказа, полученный от пользователя
gtincount Строка Ваш идентификатор участника ЭДО
productgroup Строка Товарная группа:
lp — легкая промышленность;
shoes — обувные товары.
gtinCounty Целое число Количество кодов товара/GTIN в заказе
requestedQuantity Целое число Заказанное количество кодов маркировки
actualQuantity Целое число Фактически полученное количество кодов маркировки
status Строка Статус заказа:
DRAFT — Черновик,
INPROC — Заказ в обработке,
SUCCESS — Заказа обработан без ошибок,
FAILURE — Заказ обработан: ошибка по всем позициям,
PARTIALFAILURE — Заказ обработан: часть позиций с ошибками
pageInfo Структура Информация о делении списка на страницы и о передаваемой странице списка
pageCount Целое число Количество страниц в списке
pageIndex Целое число Номер передаваемой страницы
pageRecords Целое число Количество строк списка на странице
sortDirection Строка Порядок сортировки.
Возможные значения: asc — восходящая (прямой порядок);
desc — нисходящая (обратный порядок).
Значение по умолчанию — desc.
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос



5.2.6 Получение кодов маркировки

Метод используется для получения кодов маркировки по заказу. Заказ должен иметь статус Success или PartialFailure. Метод позволяет забрать все доступные коды по заказу или по конкретному коду товара (gtin).
Для получения кодов маркировки используется запрос на основе метода GET.
Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/{version}/marking-codes/orders/{draftId}/codes?gtin={gtin}

Все параметры в данном запросе приведены в таблице 31.

Таблица 31. Параметры запроса на получение списка документов

Параметр Заменяемая строка Описание Обязательно в запросе
{version} Обозначение версии системы, текущая версия равна v1 да
draftId {draftId}N Идентификатор заказа да
gtin {gtin} Код товара нет

Структура успешного ответа на запрос:

{
  "draftId": "string",
  "markingCodes": [
    "string"
  ]
}

Параметры ответа представлены в таблице 32.

Таблица 32. Параметры структуры ответа на запрос

Параметр Формат значения Описание
draftId String Идентификатор заказа
markingCodes Массив кодов маркировки

5.2.7 Получение подробной информации о статусе каждого кода товара/GTIN в заказе

Метод позволяет получить информацию о товарных позициях конкретного заказа кодов маркировки, используется запрос на основе метода GET. Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/{version}/marking-codes/orders/{orderId}/positions

Здесь:

  • {version} — обозначение версии системы, текущая версия равна v1 (но впоследствии номер версии может быть другим);
  • {orderId} — Id заказа

Пример успешного ответа на запрос:

{
  "result": {
    "data": [
      {
        "name": "04636332455032",
        "gtin": "04636332455032",
        "requestedCodesCnt": 2,
        "obtainedCodesCnt": 0,
        "status": "Failure",
        "details": "Проверка учетных данных УОТ не пройдена. Маркер безопасности b9b248ec-ea14-2f4f-7372-37e80892a1ae не найден"
      }
    ],
    "pageInfo": {
      "pageCount": 1,
      "pageIndex": 1,
      "pageRecords": 1,
      "sortDirection": "desc",
      "sortKey": "someKey"
    }
  },
  "status": {
    "code": 0,
    "message": "some message here"
  }
}

Параметры ответа представлены в таблице 33.

Таблица 33. Параметры структуры ответа на запрос

Параметр Вложенные поля Вложенные поля Формат значения Описание
result Структура Содержимое ответа
data Структура Данные контейнера
gtin Строка Номер gtin
name Строка Наименование
requestedCodesCnt Целое число Количество запрошенных кодов
obtainedCodesCnt Целое число Количество полученных кодов
status Целое число Статус заказа по конкретному коду товара/GTIN:
Success — коды получены,
PartialFailure,
Failure — отклонено,
InProс — в обработке,
AwaitingSign — заказ создан, ожидает подписания для отправки в «Честный ЗНАК»
details Строка Причина ошибки
pageInfo Структура Информация о делении списка на страницы и о передаваемой странице списка
pageCount Целое число Количество страниц в списке
pageIndex Целое число Номер передаваемой страницы
pageRecords Целое число Количество записей на странице.
sortDirection Целое число Направление сортировки
sortKey Строка Порядок сортировки.
Возможные значения:
asc — восходящая (прямой порядок);
desc — нисходящая (обратный порядок).
Значение по умолчанию — desc
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос



5.2.8 Получение информации об общих параметрах заказа

Метод позволяет получить параметры конкретного заказа, используется запрос на основе метода GET. Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/{version}/marking-codes/orders/{orderId}?include=mc-orig-req&include=mc&include=intro

Здесь:

  • {version} — обозначение версии системы, текущая версия равна v1 (но впоследствии номер версии может быть другим);
  • {orderId} — Id заказа

Пример успешного ответа на запрос:

{
    "result": {
        "originalRequest": {
            "number": "938a9a02-f203-4694-9165-8326a22f9f38",
            "comment": "комментарий",
            "omsId": "79871fbf-c16d-4213-868a-462f5fcacc14",
            "clientToken": "d1d15b74-e56a-45d9-aaa9-9ad25f5108e9",
            "positions": [
                {
                    "gtin": "04636332455094",
                    "name": "Куртка зеленая мужская, 54 размер",
                    "quantity": 98,
                    "serialNumberType": "OPERATOR",
                    "templateId": "10",
                    "cisType": "UNIT"
                }
            ],
            "releaseMethodType": "IMPORT",
            "productGroup": "lp",
            "contactPerson": "Иванов И.А.",
            "createMethodType": "SELF_MADE",
            "orderName": "531313"
        },
        "mcOrderInfo": {
            "comment": "комментарий к заказу",
            "creationTime": "2021-02-15T10:51:55.457Z",
            "finishedProcessingTime": "2021-02-15T10:51:55.457Z",
            "orderName": "Наименование заказа",
            "startProcessingTime": "2021-02-15T10:51:55.457Z",
            "status": "InProc",
            "totalObtainedCodesCnt": 8,
            "totalRequestedCodesCnt": 10
        }
  },
  "status": {
    "code": 0,
    "message": "ОК"
  }
}

Параметры ответа представлены в таблице 34.

Таблица 34. Параметры структуры ответа на запрос

Параметр Вложенные поля Вложенные поля Вложенные поля Формат значения Описание
result Структура Параметры авторизации
originalRequest Структура Параметры заказа, полученные при его формировании
number Строка Номер заказа, указанный клиентом в методе «Создание заказа на коды маркировки»
comment Строка Комментарий
omsId Строка Идентификатор клиента в ЧЗ, указанный при создании заказа
clientToken Строка Токен авторизации, указанный при создании заказа
positions Структура Список товаров
gtin String (14) [0-9] {14} Код товара (GTIN)
name String Наименование товара
quantity Integer($int32) Количество КМ
serialNumberType String Способ генерации серийных номеров:
SELF_MADE — самостоятельно;
OPERATOR — оператором ГИС МТ.
serialNumbers JSON Array of String Массив серийных номеров. Это
поле указывается в случае, если
значение «serialNumber = SELF_MADE»
templateId Integer ($int32) Идентификатор шаблона товарной группы:
1 — обувные товары;
10— предметы одежды, белье
постельное, столовое, туалетное
и кухонное.
stickerId String Идентификатор этикетки.
Заполняется только при создании заказа
в рамках процесса дистрибуции.
cisType String Тип кода маркировки:
UNIT — единица товара;
BUNDLE — комплект;
SET — набор;
GROUP — групповая потребительская упаковка.
Используется только для ТГ «Одежда», обязательно для данной ТГ.
exporterTaxpayerId String ИНН/УНБ (или аналог) экспортера.
Используется только для ТГ «Одежда» и «Обувь».
Становится обязательным для этих ТГ, только если в поле releaseMethod
(способ выпуска товара в оборот) было выбрано
значение «CROSSBORDER» (Ввезен в РФ из стран ЕАЭС)
productGroup String Товарная группа:
lp — легкая промышленность;
shoes — обувные товары.
clientToken String
omsId String
createMethodType String Способ изготовления:
SELF_MADE — Самостоятельно;
CEM — ЦЭМ;
CM — Контрактное производство;
CL — Логистический склад;
CA — Комиссионная площадка.
Используется только для ТГ «Одежда» и «Обувь», обязательно для данных ТГ.
releaseMethodType String Способ выпуска товаров:
PRODUCTION — производство РФ;
IMPORT — ввезен в РФ (импорт);
REMAINS — маркировка остатков (доступно только для ТГ «Шины», «Альтернативный табак», «Духи и туалетная вода»);
COMMISSION — Принят на комиссию от физического лица (доступно для ТГ «Одежда», «Обувь»).
Используется только для ТГ «Одежда» и «Обувь», обязательно для данных ТГ.
contactPerson String Контактное лицо.
Используется только для ТГ «Одежда» и «Обувь»
productionOrderId String Идентификатор производственного заказа.
Используется только для ТГ «Одежда» и «Обувь»
serviceProviderId String(36) UUID Идентификатор сервис-провайдера.
Используется только при наличии сервис-провайдера
в ЛК Честного знака.
orderName String Наименование заказа
mcOrderInfo Структура Информация об обработке заказа в ЧЗ
comment Строка Пользовательский комментарий
creationTime Строка Время создания заказа
finishedProcessingTime Строка Время получения итогового ответа от ЧЗ по каждому коду товара/GTIN в заказе
orderName Строка Наименование заказа
startProcessingTime Строка Время подписания заказа и отправки в ЧЗ
status Строка Статус заказа:
DRAFT — Черновик,
INPROC — Заказ в обработке,
SUCCESS — Заказа обработан без ошибок,
FAILURE — Заказ обработан: ошибка по всем позициям,
PARTIALFAILURE — Заказ обработан: часть позиций с ошибками
totalObtainedCodesCnt Целое число Общее количество полученных КМ для заказа
totalRequestedCodesCnt Целое число Общее количество заказанных КМ для заказа
status Структура Состояние запроса
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос



5.3. Ввод в оборот

Порядок действий при вводе в оборот:

5.3.1 Создать документ ввода в оборот (Импорт ФТС)

Данный метод позволяет создать документ «Ввод в оборот. Импорт ФТС». В случае успешной отправки возвращается идентификатор документа (documentId).

Для создания заказа используется запрос на основе метода POST. Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/{version}/marking-codes/introduction/import-fts

Здесь {version} — обозначение версии системы. Текущая версия равна v1, но впоследствии номер версии может быть другим.

Параметры запроса на создание заказа приведены в таблице 35.

Таблица 35. Параметры запроса на создание заказа

Параметр Вложенные поля Формат значения Описание Обязательно в запросе
documentnumber String Номер документа ввода в оборот (должно быть уникальным) Да
declarationdate String Дата декларации. Пример «2020-02-22» Да
declarationnumber String Номер декларации.
Пример номера декларации: «05100000/220220/0002233», где
«220220» — это дата декларации, которая должна совпадать с датой,
указанной в параметре declarationDate.
Да
comment String Комментарий к документу Нет
positions Структура Список товаров Да
cis String Код маркировки Да
packtype String Тип упаковки:
UNIT — КИ;
LEVEL1-99 — КИТУ.
Да
productgroup String Товарная группа:
lp — легкая промышленность;
shoes — обувные товары.
Да

Пример запроса

{
  "documentNumber": "6f9619ff-8b86-d011-b42d-00cf4fc964f2",
  "declarationnumber": "05100000/110121/0002233",
  "declarationdate": "11.01.2021",
  "comment": "комментарий к документу",
  "positions": [
    {
      "cis": "010463633245506321VKCCw)HEmmMog",
      "packType": "UNIT"
    }
  ],
  "productgroup": "lp"
}

В случае успешной отправки возвращается идентификатор документа (documentId).
Пример успешного ответа на запрос:


   df08122e-30b5-11eb-adc1-0242ac120016
   

5.3.2 Создать документ ввода в оборот (Полученных от физических лиц)

Данный метод позволяет создать документ «Ввод в оборот. Полученных от физических лиц». В случае успешной отправки возвращается идентификатор документа (documentId).

Для создания заказа используется запрос на основе метода POST. Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/{version}/marking-codes/introduction/individual

Здесь {version} — обозначение версии системы. Текущая версия равна v1, но впоследствии номер версии может быть другим.

Параметры запроса на создание заказа приведены в таблице 36.

Таблица 36. Параметры запроса на создание заказа

Параметр Вложенные поля Формат значения Описание Обязательно в запросе
documentnumber String Номер документа ввода в оборот (должно быть уникальным) Да
comment String Комментарий к документу Нет
positions Структура Список товаров Да
uit String Код маркировки. Обязательный, если не указан «uitu» Условно обязательное
uitu String Уникальный идентификатор транспортной упаковки.
Обязательный, если не указан «uit»
Условно обязательное
product_receiving_date date Дата получения товара. Параметр присутствует в запросе, если его
значение отличается от значения параметра «product_receiving_date».
Задается в формате yyyy-MMddTHH:mm:ss.SSS’Z
Нет
productgroup String Товарная группа:
lp — легкая промышленность;
shoes — обувные товары.
Да
productReceivingDate String (date-time) Дата получения товара. Задается в формате yyyy-MMddTHH:mm:ss.SSS’Z,
например, «2021-01-19T21:00:00.000Z»
Да

Пример запроса

{
  "documentNumber": "6f9619ff-8b86-d011-b42d-00cf4fc964f2",
  "comment": "комментарий к документу",
  "positions": [
    {
      "uit": "010463633245506321VKCCw)HEmmMog"
    }
  ],
  "productgroup": "lp",
  "productReceivingDate: "2021-01-19T21:00:00.000Z"
}

В случае успешной отправки возвращается идентификатор документа (documentId).
Пример успешного ответа на запрос:

   df08122e-30b5-11eb-adc1-0242ac120016

5.3.3 Создать документ ввода в оборот (Производство РФ)

Данный метод позволяет создать документ «Ввод в оборот. Производство РФ». В случае успешной отправки возвращается идентификатор документа (documentId).

Для создания заказа используется запрос на основе метода POST. Запрос имеет следующий вид:

POST https://lk.edo.ru/api/edo/{version}/marking-codes/introduction/production

Здесь {version} — обозначение версии системы. Текущая версия равна v1, но впоследствии номер версии может быть другим.

Параметры запроса на создание заказа приведены в таблице 37.

Таблица 37. Параметры запроса на создание заказа

Параметр Вложенные поля Формат значения Описание Обязательно в запросе
documentnumber String Номер документа ввода в оборот (должно быть уникальным) Да
comment String Комментарий к документу Нет
positions Структура Список товаров Да
productGroup String Товарная группа:
lp — легкая промышленность;
shoes — обувные товары.
Да
productionDate date Дата создания продукции. Задается в формате yyyy-MM-dd Да
uit String Код маркировки. Обязательный, если не указан «uitu» Условно обязательное
uitu String Уникальный идентификатор транспортной упаковки.
Обязательный, если не указан «uit»
Условно обязательное
tnved_code String Код товарной номенклатуры (10 знаков) Нет
certificate_document String Код вида документа обязательной сертификации \\Возможные значения:
CONFORMITY_CERTIFICATE — сертификат соответствия;
CONFORMITY_DECLARATION –декларация соответствия
Нет
certificate_document_number String Номер документа обязательной сертификации Нет
certificate_document_date String (date-time) Дата документа обязательной сертификации. Задается в формате yyyy-MM-dd. Диапазон даты, начиная с 2000-01-01 по дату создания документа Да
vsd_number string Номер ВСД, указывается для ТГ «Молочная продукция», обязательный, если в карточке НК «veterinaryControl» = true Да
{
  "comment": "Some comment",
  "documentNumber": "6f9619ff-8b86-d011-b42d-00cf4fc964f2",
  "positions": [
   {     "production_date": "2019-01-01",
         "uit_code": "0104630033880100211AREwAwLETM7g240ffd0",
         "uitu_code": 111111111111111111,
         "tnved_code": "6401921000",
          "certificate_document": "CONFORMITY_CERTIFICATE",
          "certificate_document_number": "123",
          "certificate_document_date": "2019-01-01",
           "vsd_number": "9DDA-5D57-FAEA-46DD-B94D-3DCC-AC70-1091" }
           ],
  "productGroup": "lp",
  "productionDate": "2019-01-01"
}

В случае успешной отправки возвращается идентификатор документа (documentId).
Пример успешного ответа на запрос:

   df08122e-30b5-11eb-adc1-0242ac120016

5.3.4 Получить данные документа ввода в оборот для подписания

Данный метод позволяет получить данные документа для подписания.

Используется запрос на основе метода GET. Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/{version}/marking-codes/introduction/{documentId}/contents

Здесь {version} — обозначение версии системы. Текущая версия равна v1, но впоследствии номер версии может быть другим; {documentId} — Id документа

Пример ответа

{
  "content": "ewogICAgInB...",
  "id": "6f9619ff-8b86-d011-b42d-00cf4fc964f2"
}

Таблица 38. Параметры ответа на запрос

Параметр Формат значения Описание
content string Идентификатор контента документа
id String Контент документа в формате base64

5.3.5 Отправить подписанный документ ввода в оборот в «Честный ЗНАК»

Метод позволяет отправить документ ввода в оборот в «Честный ЗНАК». Используется после получения контента из метода «Получение данных документа ввода в оборот для подписания» и их подписания. Для подписания контента требуется перевести данные параметра «content» из формата base64 в бинарные данные и поместить в файл для подписания, после чего создать прикрепленную однострочную (без знаков переноса) подпись и отправить ее в параметре «content» запроса «Отправка подписанного документа ввода в оборот в «Честный ЗНАК».

Для отправки документа используется запрос на основе метода POST. Запрос имеет следующий вид:

POST https://lk.edo.ru/POST/api/edo/{version}/marking-codes/introduction/{documentId}/send

Здесь {version} — обозначение версии системы. Текущая версия равна v1, но впоследствии номер версии может быть другим;
{documentId} — Id документа

Пример запроса

{
  "content": "ewogICAgInB..."
}

Таблица 39. Коды ответа на запрос

Статус кода HTTP Причина ответа
200 Запрос выполнен успешно
401 Ошибка аутентификации/авторизации

5.3.6 Получить статус документа ввода в оборот

Данный метод позволяет получить статус документа ввода в оборот.

Используется запрос на основе метода GET. Запрос имеет следующий вид:

GET https://lk.edo.ru/api/edo/{version}/marking-codes/introduction/{documentId}/status

Здесь {version} — обозначение версии системы. Текущая версия равна v1, но впоследствии номер версии может быть другим; {documentId} — Id документа

Пример ответа

{
  "codesIntroductionType": "LP_FTS_INTRODUCE",
  "comment": "some comment",
  "documentId": "cf9619ff-8b76-d211-b42d-00cf4fc964f5",
  "documentNumber": "6f9619ff-8b86-d011-b42d-00cf4fc964f2",
  "documentStatus": "Created",
  "errors": "\"errors\":\"{\"errors\": [\"parse_error\", \"parse_error_2\"]\"}\"",
  "productGroup": "lp"
}

Таблица 40. Параметры ответа на запрос на создание заказа

Параметр Формат значения Описание Обязательно в запросе
codesIntroductionType string Тип документа на ввод в оборот:
LP_FTS_INTRODUCE — Ввод в оборот. Импорт с ФТС;
LP_INTRODUCE_GOODS — Ввод в оборот. Производство;
LK_INDI_COMMISSIONING — Ввод в оборот. Полученных от физических лиц.
Да
comment String Комментарий к документу Нет
documentId String Уникальный идентификатор документа в ГИС МТ. Да
documentNumber String Уникальный идентификатор запроса пользователя, задается пользователем Да
documentStatus string Статус документа:
Created — «Требуется подпись», документ ввода создан, требуется подписать документ для отправки его в Честный ЗНАК»;
Sending — «Отправляется»
SentForIntroduction — «Отправлен в ЧЗ»
IntroductionFailed — «Ошибка ввода»
SendingError — «Ошибка отправки документа»
Introduced — «Введено в оборот».
Да
errors string Ошибки документа по вводу в оборот КМ Нет
productgroup String Товарная группа:
lp — легкая промышленность;
shoes — обувные товары.
Да

История изменений

Версия 2.0
Выпущена 11 января 2019 г.
Первая регистрируемая версия документа.

Версия 2.1
Выпущена 10 апреля 2019 г.
Исправлены ошибки в тексте и в ответах получаемые при выполнении запросов.

Версия 2.2
Выпущена 24 апреля 2020 г.
Изменен адрес сервера, на который необходимо отправлять API-запросы.

Версия 2.3
Выпущена 11 сентября 2020 г.
Исправлена ошибка в методе авторизации в ИС «ЭДО.Поток».

Версия 2.4
Выпущена 25 сентября 2020 г.

  • Исправлена нумерация таблиц;
  • Устранены мелкие недочеты по всему объему документа.

Версия 2.5
Выпущена 09 октября 2020 г.

  • Переработаны таблицы для большей наглядности информации о вложенных полях в структурах;
  • Исправлены названия таблиц по всему объему документа;
  • Исправлены ошибки в тексте и в ответах получаемые при выполнении запросов;
  • Добавлены параметры в таблицу 4;
  • Исправлена ошибка в методе авторизации через AuthToken.

Версия 2.6
Выпущена 12 октября 2020 г.

  • Исправлена ошибка в методе 3.1.10 Вывод справочника типов документов;
  • Исправлены ошибка в методе 3.3.1 Поиск контрагентов;
  • Добавлен метод 3.3.2. Получение списка контрагентов по статусу.

Версия 2.7
Выпущена 15 октября 2020 г.
Убран блок информации 3.2. Запросы, связанные с клиентами.

Версия 2.8
Выпущена 18 ноября 2020 г.

  • Изменен адрес запросов с edmapi.ofd.ru на lk.edo.ru;
  • Временно убран раздел «Авторизация с помощью имени пользователя (логина) и пароля»;
  • Добавлен раздел 3.1.13. Получение извещения на подтверждение оператора (для отправителя);
  • Добавлен раздел 3.1.14. Получение извещений на документ (для получателя);
  • Добавлен раздел 3.1.15. Получение любых извещений на документы.

Версия 2.9
Выпущена 23 декабря 2020 г.

  • Добавлен раздел 3.1 Отправка заказа кодов маркировки в «Честный ЗНАК»
  • Добавлен раздел 3.2 Получение статуса заказа и кодов маркировки

Версия 3.0
Выпущена 03 марта 2021 г.
Добавлен раздел 4. Маркировка

Версия 3.1
Выпущена 04 марта 2021 г.

  • Добавлен раздел 4.2.3 Создание документа ввода в оборот (Производство РФ)
  • Добавлен раздел 4.2.4 Получение данных документа для подписания
  • Добавлен раздел 4.2.5 Сохранение подписанных данных заказа на ввод кодов в оборот для последующей отправки в ГИС МТ
  • Добавлен раздел 4.2.6 Получение статуса документа ввода в оборот КМ

Версия 3.2
Выпущена 10 марта 2021 г.
Добавлен раздел 2 — Метод регистрации в ИС «ЭДО.Поток»

Версия 3.3
Выпущена 23 марта 2021 г.
Добавлены методы получение информации о товарных позициях заказа КМ, получение информации о параметрах заказа КМ

1) Зависит от текущей или используемой версии системы, может изменяться.
2) Зависит от текущей или используемой версии системы, может изменяться
3) Задается по правилам написания адресов URL и URI: недопустимые символы заменяются служебными последовательностями в соответствии с RFC 3986, см. https://ru.wikipedia.org/wiki/URL, https://www.ietf.org/rfc/rfc3986.txt и http://www.protocols.ru/WP/rfc3986/.