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

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

Введение

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

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

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

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

Здесь:

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

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

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

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

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

Authorization: Token TOKEN1

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

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

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

2.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"
}

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

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

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

Поле с ключом «result» имеет тип данных «Строка», и в нем возвращается строка для подписания, которая будет использована в следующих шагах.

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

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

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

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

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

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

Параметр Формат значения Описание
cmsDetached Строка Подписанная строка для подписания, закодированная с помощью “Base64”
content Строка Строка для подписания, полученная на прошлом шаге

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

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

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

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

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

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

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

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

3.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

Все параметры в данном запросе приведены в таблице 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 — дата получения документа;
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"
    }
  }
}

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

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

Параметр Вложенные поля Вложенные поля Формат значения Описание
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 Строка 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 Строка Направление сортировки (аналогично запросу)

3.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
  }
}

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

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

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

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

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

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

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

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

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

Параметр Заменяемая строка Описание Значение по умолчанию Обязательно в запросе
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
    }
  ]
}

Параметры ответа приведены в таблице 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. Получение предварительно заполненного шаблона документа

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

POST https://lk.edo.ru/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.5. Подписание документа

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

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

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

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

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

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

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

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

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

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

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

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

{
  "docId": "2604"
}

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

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

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

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

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

{
  "docId": "2604"
}

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

3.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"
  }
}

Параметры ответа приведены в таблице 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.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.

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

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

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

Здесь:

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

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

3.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
    }
  ]
}

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

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

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

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

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

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

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

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

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

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

3.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
	}
}

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

3.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
		}
	}
}

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

Таблица 11.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 Строка CMS-контейнер с сертификатом и открепленной подписью, закодированный с помощью алгоритма “Base 64”
certificateSerialNumber Строка Серийный номер сертификата
fileName Строка Наименование файла
docName Строка Наименование документа
docNumber Строка Номер документа
docDate Строка Дата генерации документа
sumAll Строка Общая сумма по документу
sumNds Строка Общая сумма НДС по документу
updPokupatelyaId Строка Идентификатор УПД покупателя
marking Логическое выражение (boolean) Признак наличия маркировки
mcDocState Строка Стейт отправки документа в ЦРПТ
actions Структура Служебная информация о возможных действиях с документом
forDocument Структура Информация о родительском документе
guid Строка Уникальный идентификатор
updated Строка Дата и время последнего обновления, формат ISO, с указанием часов и минут (без секунд, дата и время разделены пробелом)
nds Логическое выражение (boolean) Признак необходимости расчета НДС
signRequested Логическое выражение (boolean) Признак необходимости подписания документа

3.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
		},
		...
	]
}

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

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

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

3.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) указывается имя загружаемого файла.

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

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

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

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

GET https://lk.edo.ru/api/edo/VERSION/contractors/search-contractors?query=INFO1

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

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

Параметр Заменяемая строка Описание Значение по умолчанию
VERSION Версия системы v1 3)
query INFO1 ИНН клиента, КПП клиента или последовательность символов, искомая в полном названии контрагента 4)

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

{
  "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"
    }
  }
}

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

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

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

Таблица 15.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 Строка Состояние контрагента

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

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

GET https://lk.edo.ru/api/edo/VERSION/contractors?status=STATUS1

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

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

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

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

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

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

GET https://lk.edo.ru/api/edo/VERSION/contractors?clientNamePart=STR&pageRecords=NUM

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

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

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

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

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

Версия 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. Получение любых извещений на документы.
1)
Зависит от текущей или используемой версии системы, может изменяться.
2) , 3) , 5)
Зависит от текущей или используемой версии системы, может изменяться
4)
Задается по правилам написания адресов URL и URI: недопустимые символы заменяются служебными последовательностями в соответствии с RFC 3986, см. https://ru.wikipedia.org/wiki/URL, https://www.ietf.org/rfc/rfc3986.txt и http://www.protocols.ru/WP/rfc3986/.