Помогаем продавать
Войти в ЛК

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

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

Введение

Описывается программный интерфейс приложений (API), предоставляющий возможность сторонним приложениям использовать данные из информационной системы (ИС) ЭДО.ПОТОК для обмена юридически значимыми электронными документами.

Взаимодействие клиентского приложения и API производится путем отправки приложением HTTP-запросов к серверу и получением ответов на них. Для отправки запросов и получения ответов используется протокол HTTPS.

Проблемы использования ЭДО.ПОТОК, которые не удалось решить самостоятельно, читая техническую и пользовательскую документацию, скорее всего, получится решить, позвонив в службу технической поддержки по телефону 8 (800) 550-99-11.

Ниже описаны запросы HTTP, которыми реализуются функции API по работе с онлайн-кассами.

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

Кодировка, используемая в запросах и ответах – Windows-1251. Запросы выполняются методом POST, параметры запроса располагаются в структуре формата JSON, передаваемой в блоке данных запроса.

Ответы выдаются сервером в формате JSON и, в случае успешности ответа согласно его заголовку (код ответа по протоколу HTTP равен 200), данные имеют следующий обобщенный вид:

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

Здесь ключу "result" соответствует произвольный тип данных (часто – структура данных, вид которой определяется видом запроса); "status" – структура, описывающая состояние обработки запроса; состав и назначение полей в данной структуре см. в таблице 1 (п. 2.1).

2. Методы авторизации в ИС «ЭДО.ПОТОК»

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

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

&token=TOKEN1

Здесь TOKEN1 — токен, возвращенный в результате авторизации (см. пп. 2.1 и 2.2). В дальнейшем токен, как дополнительный параметр, при описании запросов упоминаться не будет.

Использование токена в заголовках запросов (HTTP-headers) предполагает при формировании запроса добавление заголовка следующего вида:

Authorisation: Token TOKEN1

Здесь TOKEN1 — также, токен, возвращенный в результате авторизации.

2.1. Авторизация с помощью имени пользователя (логина)и пароля; сквозная аутентификация

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

POST /api/edo/VERSION/clients/auth

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

{
"clientId": "2PS-0078414651",
"password": "PASSWORD"
}

Здесь clientId — уникальный идентификатор клиента в ИС «ЭДО.ПОТОК», password — пароль клиента в ИС «ЭДО.ПОТОК». Оба поля являются обязательными для заполнения. В ответ на запрос сервер возвращает структуру данных (приведены примеры значений):

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

Назначение полей ответа приведено в таблице 1.

Таблица 1. Поля структуры данных ответа

Ключ поля Тип значения поля Описание
status Структура Структура данных ответа (состояния запроса)
code Целое число Код ответа на запрос (0 - OK)
message Строка Сообщение в ответе на запрос
result Строка Токен, далее используемый клиентом в качестве дополнительного параметра в последующих запросах к API. Действителен в течение суток с момента получения

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

Вторым доступным пользователю механизмом авторизации в ИС «ЭДО.ПОТОК» является авторизация посредством механизма AuthToken, которая здесь предполагает использованием квалифицированной электронной подписи (КЭП). Для авторизации необходимо проделать следующую последовательность действий.

  1. Со стороны клиента должен быть направлен запрос следующего вида:
GET /api/edo/VERSION/clients/auth-with-ds?fingerprint=FPRINT1,

Здесь VERSION — обозначение текущей версии системы, по умолчанию равное v1, но впоследствии номер версии может быть другим, FPRINT1 — отпечаток сертификата. В ответ на данный запрос возвращается структура данных вида, описанного в разд. 1 и таблице 1 в пп. 2.1. Поле с ключом "result" имеет тип данных «Строка», и в нем возвращается строка для подписания, которая будет использована в следующих шагах.

  1. Клиент подписывает строку для подписания с помощью КЭП, а затем отправляет ее вместе с подписью (CMS detached container), закодированную по алгоритму “Base64”, на тот же адрес URL с помощью запроса следующего вида:
POST /api/edo/VERSION/clients/auth-with-ds

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

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

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

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

Ключ поля Тип значения поля Описание
cmsDetached Строка Электронная подпись, CMS detached container
content Строка Подписанная строка для подписания в закодированная с помощью “Base64”
  1. Сервер производит проверку переданной строки, и в случае успешной проверки возвращает ответ, структура которого описана в разд. 1 и таблице 1 в пп. 2.1.; поле "result" имеет тип «Строка», и его значением является токен, далее использующийся в запросах к API в качестве обязательного дополнительного параметра.

3. Запросы ИС «ЭДО.ПОТОК»

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

Большинство запросов и ответов имеет вид, описанный в разд. 1, если входные и выходные данные будут другого вида, это будет описываться дополнительно. Данные документов при передаче кодируются алгоритмом “Base64”.

Запросы API ИС «ЭДО.ПОТОК» можно разделить на три группы: запросы, связанные с документами, запросы связанные с клиентами и запросы, связанные с контрагентами. К запросам, связанным с клиентами относится также и авторизация пользователя в системе, описанная в разд.

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

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

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

Запрос на получение списка документов клиента имеет вид:

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

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

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

Название параметра Заменяемая строка Описание параметра Значение по умолчанию Обязательно
в запросе
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 — дата получения документа,
RECEIVED_DATE нет

Далее здесь во всех запросах будет указана первая версия API (“v1”). Пример запроса с использованием аутентификации в заголовках запросов (HTTP-headers):

GET/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

или с использованием аутентификации в параметрах запросов:

GET/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&token=c698a3c9-d22f-4a93-9a8d-d8310cac326a

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

{
"status": {
"code": 0,
"message": "OK"
},
"result": {
"data": [
{
"docId": 2610,
"fromOrgId": "2PS-003245025998032",
"fromOrgName": PS ST,
"toOrgId": "2PS-00440111648005445",
"toOrgName": "ИП Иванов",
"docTypeId": 1,
"docTypeName": "Счёт-фактура",
"docStateId": 0,
"docStateName": "Создан",
"sfStateName": "Подписано отправителем",
"sfStateId": 3,
"xmlBody": "PD94bWwgdmVyc2...",
"imgBody": null,
"signature": "MIIGGAYJKoZIhvcNAQcCoII Строка...",
"fileName": "ON_SCHFDOPPR_2PS-0069110332410689418822_2PS-007841465194609667_20180820_80aa0ec5-d512-48a1-b504-7d84872d5dcf",
"certFingerprint": "4ff4214c64e8d8db2046defab0dAAAA",
"updated": "2018-08-31 13:17"
}
],
"pageInfo": {
"pageIndex": 1,
"pageRecords": 1000,
"pageCount": 1,
"sortKey": doc_id",
"sortDirection": "desc"
}
}
}

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

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

Ключ Формат значения Описание
status Структура Структура данных ответа (состояния запроса)
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос
result Структура Структура, содержащая список документов
data Массив структур Данные списка документов
docId Целое число Идентификационный номер (индекс) документа
fromOrgId Строка Идентификатор организации-отправителя
fromOrgName Строка Название организации-отправителя
toOrgId Строка Идентификатор организации-получателя
docTypeId Целое число Идентификатор типа документа
docTypeName Строка Название типа документа
docStateId Целое число Идентификатор статуса (состояния) документа
sfStateName Строка Статус подписи документа
sfStateId Целое число Идентификатор статуса подписи документа
xmlBody Строка Строка, содержащая тело документа в виде двоичного массива, закодированного с помощью алгоритма "Base 64”
imgBody Строка Строка, содержащая тело документа в виде двоичного массива, закодированного с помощью алгоритма "Base 64”
signature Строка CMS-контейнер с сертификатом и открепленной подписью, закодированный с помощью алгоритма “Base 64”
fileName Строка Имя файла
certFingerprint Строка Отпечаток сертификата
updated Строка Дата и время последнего обновления, формат ISO, с указанием часов и минут (без секунд, дата и время разделены пробелом)
pageInfo Структура Информация о делении списка на страницы и о передаваемой странице списка
pageIndex Целое число Номер передаваемой страницы
pageRecords Целое число Количество строк списка на странице
pageCount Целое число Количество страниц в списке
sortKey Строка Имя поля ключа сортировки (аналогично запросу)
sortDirection Строка Направление сортировки (аналогично запросу)

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

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

POST /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"
}
}

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

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

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

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

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

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

GET /api/edo/VERSION/documents/for-signing?req-duplex-sign=REQ1

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

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

Название параметра Заменяемая строка Описание параметра Значение по умолчанию Обязательно
в запросе
VERSION Версия системы v1 да
req-duplex-sign REQ1 Тип возвращаемых документов: true — технологические (не требующие второй подписи) и прочие (требующие вторую подпись), 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
}
]
}

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

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

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

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

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

POST /api/edo/VERSION/documents/add-signature

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

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

Все параметры (поля) для запроса приведены в таблице 8.

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

Название параметра (поля) Описание параметра Тип значения Обязательно
в запросе
docId Идентификатор подписываемого документа Строка да
signature Тип документа Строка да

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

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

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

POST /api/edo/VERSION/documents/remove-doc

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

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

{

"docId": "2604"

}

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

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

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

POST /api/edo/VERSION/documents/recover-doc

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

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

{
"docId": "2604"
}

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

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

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

POST /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",
}
}

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

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

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

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

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

GET /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.8; параметры edoIdFrom и edoIdTo аналогичны параметрам с теми же ключами (именами, идентификаторами), описанными в п. 3.1.3.

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

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

GET /api/edo/VERSION/documents/doc-chain?docId=ID1

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

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

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

GET /api/edo/VERSION/documents/doc-type-dictionary

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

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

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

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

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

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

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

GET /api/edo/VERSION/documents/download-doc?docId=ID1&downloadType=TYPE1

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

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

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

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

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

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

Запросить предварительно заполненные шаблоны XML-документов можно с помощью запроса на основе метода POST; запрос имеет следующий вид:

POST /api/edo/VERSION/documents/get-doc-template

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

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

Все параметры (поля) для запроса приведены в таблице 12.

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

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

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

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

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

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

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

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

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

GET /api/edo/VERSION/documents/show-doc-pdf?docId=ID1

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

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

3.2. Запросы, связанные с клиентами

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

3.2.1. Получение информации по клиенту по его ИНН и КПП

Для получения информации о клиенте по его ИНН и КПП можно использовать запрос ИС «ЭДО.ПОТОК», действующий на основе HTTP-метода GET; запрос имеет следующий вид:

GET /api/edo/VERSION/clients?inn=INN&kpp=KPP

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

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

Название параметра Заменяемая строка Описание параметра Значение по умолчанию Обязательно
в запросе
VERSION Версия системы v1 да
inn INN ИНН клиента да
kpp KPP КПП клиента да

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

{
"status": {
"code": 0,
"message": "OK"
},
" result ": {
"clientId": "2PS-00325504956903257010010014472643",
"fullName": "ООО \"Ай Ти Сервис\"",
"phone": "79103333412",
"email": "itmail@bk.ru",
"mailAddress": null,
"fullLegalAddress": "Брянск г Брянской Пролетарской Дивизии ул 9",
"kpp": "325701001",
"inn": "3255049569",
"ogrn": "1063255002579",
"ifns": null,
"certificate": null,
"stateName": null,
"legalAddress": {
"building": null,
"houseNumber": null,
"office": null,
"postalCode": null,
"region": null,
"settlement": null,
"street": null
}
}
}

Параметры (поля) ответа приведены в таблице 15.

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

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

3.2.2. Получение информации по клиенту по его уникальному идентификатору

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

GET /api/edo/VERSION/clients?clientId=ID1

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

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

3.3. Запросы связанные с контрагентами

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

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

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

GET /api/edo/VERSION/contractors/search-contractors?
status=STATUS1&clientNamePart=NAME1&inn=INN&kpp=KPP

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

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

Название параметра Заменяемая строка Описание параметра Значение по умолчанию Обязательно
в запросе
VERSION Версия системы v1 да
status STATUS1 Состояние (статус) контрагента. Возможные значения: нет
clientNamePart NAME1 Последовательность символов, искомая в полном названии контрагента нет
Inn INN ИНН клиента нет
Kpp KPP КПП клиента нет

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

{
"status": {
"code": 0,
"message": "OK"
},
"result": {
"data": [
{
"clientId": "2PS-00325504956903257010010014472643",
"fullName": "ООО \"Ай Ти Сервис\"",
"phone": "79103333412",
"email": "itmail@bk.ru",
"mailAddress": null,
"fullLegalAddress": "Брянск г Ленина просп 9",
"kpp": "325701001",
"inn": "3255049569",
"ogrn": "1063255002579",
"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"
}
}
}

Параметры (поля) ответа приведены в таблице 16.

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

Ключ Формат значения Описание
status Структура Структура данных ответа (состояния запроса)
code Целое число Код ответа на запрос (0 — OK)
message Строка Сообщение в ответе на запрос
result Структура Структура, содержащая информацию по клиенту
data Массив структур Массив записей о контрагентах
clientId Строка Идентификатор клиента в ИС «ЭДО.ПОТОК»
fullName Строка Полное название клиента
phone Строка Телефонный номер клиента
email Строка Адрес электронной почты клиента
mailAddress Строка Фактический почтовый адрес клиента одной строкой
fullLegalAddress Строка Юридический адрес клиента одной строкой
kpp Строка КПП клиента
inn Строка ИНН клиента
ogrn Строка ОГРН клиента
ifns Строка Идентификационный номер ФНС, за которой закреплен клиент
certificate Строка Открытая часть сертификата электронной подписи клиента
stateName Строка Название государства, к которому относится клиент
legalAddress Строка Структура, содержащая юридический адрес клиента, разбитый на компоненты
postalCode Строка Почтовый индекс
region Строка Область
area Строка Район области (если используется)
city Строка Город
settlement Строка Населенный пункт
street Строка Улица
houseNumber Строка Номер дома
building Строка Номер корпуса или здания
office Строка Номер офиса
status Строка Состояние контрагента
pageInfo Структура Информация о делении списка на страницы и о передаваемой странице списка
pageIndex Целое число Номер передаваемой страницы
pageRecords Целое число Количество строк списка на странице
pageCount Целое число Количество страниц в списке
sortKey Строка Имя поля ключа сортировки
sortDirection Строка Направление сортировки (см. п. 3.1.1, таблица 3)

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

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

GET /api/edo/VERSION/contractors?clientNamePart=STR&pageRecords=NUM

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

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

Название параметра Заменяемая строка Описание параметра Значение по умолчанию Обязательно
в запросе
VERSION Версия системы v1 да
clientNamePart STR Последовательность символов, искомая в полном названии контрагента нет
pageRecords NUM Количество записей на странице; в виде десятичного целого числа 1000 нет

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

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

Версия 2.0

Выпущена 11 января 2019 г.

Первая регистрируемая версия документа.