Поиск документов (с фильтрацией), выбор списка документов

Для работы с этим методом пользователь должен быть авторизированным .

С помощью метода api/eds/docs/search можно быстро совершить поиск по заданым критериям, например, получить список документов с определенным статусом, или за промежуток времени.

Метод запроса HTTP POST
Content-Type application/json (тело запроса/ответа в json формате в теле HTTP запроса
URL запроса https://edo-v2.edi-n.com/api/eds/docs/search?gln=9864065702429
Параметры, передаваемые в URL (вместе с адресом метода)

В строке заголовка (Header) «Set-Cookie» обязательно передается SID - токен полученный при авторизации

Обязательные url-параметры:

gln - строка(13); номер GLN организации, которая связана с авторизированным пользователем платформы EDIN 2.0 на уровне аккаунта

{«…»} - тело http запроса - json с критериями поиска (Таблица_2)

Внимание: В запросе в теле json присутствуют обязательные (должны передаваться) и опциональные параметры (колонка Тип).

Подсказка

Также возможно выполнить запрос в виде curl-строки:

curl -X POST „https://edo-v2.edi-n.com/api/eds/docs/search?gln=9864065702429“ -d {json с критериями поиска(Таблица_2)} -b „SID=458a0d38-5b56-4b8e-8998-009a1edd31eb“

Спецификация для расшифровки ключей curl запроса: https://curl.haxx.se/docs/manpage.html

JSON-параметры в теле HTTP запроса/ответа

REQUEST

Таблица 2 - Описание json-параметров (фильтр) запроса метода API

Параметр Тип Формат Описание
  Объект StorageQuery  
extraParams   List<ExtraQueryParameters> массив объектов;
multiExtraParams   List<ExtraQueryParameters> массив объектов;
type M List<XDocType> массив объектов; список типов документов: 0 - все типы, 1 / 2 / 3 … и более - конкретный тип документа
statuses M List<Integer> массив; список статусов (состояний) документов, по которым будет происходить отбор: 0 - все 1 - open 2 - sent 3 - delivered 4 - inbox 5 - read 6 - error 7 - deleted
tags   List<Long> массив; тег
exchangeStatus O List<Integer> массив; статус документооборота
docs   List<Long> массив; документы
direction M Direction объект; направление документооборота; указываются отправитель, получатель и связь между ними в критериях отбора документов
limit O Limitation объект; фильтр отбора (настройки вывода данных)
number O String номер документа
family O int семейство (EDI / UZD); возможные значения: 1 - edi
partnerId   Long id розничной сети
chainHash   String хэш-значение, полученное в результате обработки цепочки
docHash   String хэш-значение, полученное в результате обработки документа
docDate O DateTimeRange объект; дата указанная в документе (в формате UNIX-timestamp) с / по
docCreate O DateTimeRange объект; дата создания документа (в формате UNIX-timestamp) с / по
docRead O DateTimeRange объект; дата прочтения документа (в формате UNIX-timestamp) с / по
docChanged O DateTimeRange объект; дата последнего изменения документа (в формате UNIX-timestamp) с / по
archive   Boolean флаг наличия архивного признака документа
important   boolean флаг наличия отметки «важный» документ
visible   boolean флаг видимости
loadBody   boolean флаг наличия тела документа
loadComments   boolean флаг наличия комментариев к документу
loadStatuses   boolean флаг наличия статусов документа
loadTags   boolean флаг наличия тегов документа
loadChain   boolean флаг наличия цепочки документов
       

Таблица 3 - Описание параметров объекта ExtraQueryParameters

Параметр Тип Формат Описание
  Объект ExtraQueryParameters  
operator   enum (AND, OR)  
type M enum (EQUALS, EQUALS_UUID, EQUALS_MD5, LIKE, MORE, MORE_EQ, LESS, LESS_EQ, IN)  
fieldName   String наименование параметра
value   String id параметра

Таблица 4 - Описание параметров объекта Direction

Параметр Тип Формат Описание
  Объект Direction  
type   enum (EQ, OR, IN) тип выборки; возможные значения: «EQ» / «OR» / «IN» * EQ - отбираются только документы в которых совпадают указанные И sender, И receiver; * OR - отбираются документы в которых совпадают ИЛИ sender, ИЛИ receiver; * IN - отбираются документы в которых sender или receiver один из тех, которые указаны в массивах sender и receiver
sender M/O List<String> массив; отправители; GLN отправителей, может быть пустым (если указан массив GLN получателей)
receiver M/O List<String> массив; получатели; GLN получателей - обязательный, но может быть пустым если указан массив GLN отправителей (sender)

Таблица 5 - Описание параметров объекта Limitation

Параметр Тип Формат Описание
  Объект Limitation  
offset O int смещение первого элемента списка относительно верхней границы выборки (по умолчанию 0)
count O int лимит выборки (количество)

Таблица 6 - Описание параметров объекта DateTimeRange

Параметр Тип Формат Описание
  Объект DateTimeRange  
startTimestamp   long начало временного диапазона
finishTimestamp   long окончание временного диапазона

Таблица 7 - Описание параметров объекта XDocType

Параметр Тип Формат Описание
  Объект XDocType описание_параметров
type   int id типа документа/квитанции
title   String название документа/квитанции
description   String описание документа/квитанции (наименование на русском)

Таблица 8 - Описание fieldName параметров (объект ExtraQueryParameters)

id параметра Наименование параметра Тип Формат Описание параметра
1 created_from   UUID идентификатор документа или цепочки
2 is_signed   TINYINT отметка о подписании
3 encrypted   TINYINT отметка о шифровании
4 comdoc_reestr_id   INT id факторингового Реестра на основании коммерческого документа
5 comdoc_reestr_is_active   TINYINT отметка об активности факторингового договора
6 ftpex_file_name   VARCHAR
наименование файла, отправленного по FTP
7 ftpex_file_date   INT дата/время отправки документа по FTP
8 inv_date   INT дата документа invrpt (Отчет об инвентаризации)
9 inv_num   VARCHAR номер документа invrpt (Отчет об инвентаризации)
11 sub_doc_type_id   INT id подтипа документа
12 sub_status_id   INT id статуса документа (состояние цепочки документов)
13 action   VARCHAR статус документа по осуществленным действиям пользователя
14 buyer_uuid   VARCHAR отправитель документа
15 consignee_uuid   VARCHAR грузопполучатель
16 consignor_uuid   VARCHAR грузоотправитель
17 customer_uuid   VARCHAR покупатель
18 performer_uuid   VARCHAR исполнитель
19 supplier_uuid   VARCHAR поставщик
20 delivery_place_uuid   VARCHAR место доставки
21 contract_date   VARCHAR дата договора
22 contract_number   VARCHAR номер договора
23 delivery_date M INT дата доставки
24 order_number M VARCHAR номер заказа
25 order_date   INT дата заказа
26 return_date   INT дата возврата
27 summ   VARCHAR сумма с НДС
28 parent_chain_hash   MD5 хэш цепочки
29 period   VARCHAR крайняя дата подписи документа
31 trans_id   VARCHAR id транзакции
32 ttn   VARCHAR номер накладной
33 doc_start_date   VARCHAR начало срока подписания документа
34 doc_end_date   VARCHAR окончание срока подписания документа
35 delivery_note_number   VARCHAR номер накладной
42 contract_gln   VARCHAR GLN место доставки при товарном согласовании (Agreem->Comdoc)
43 doc_date   INT дата из документа
44 delivery_agreement_number   VARCHAR количество согласований
45 delivery_agreement_date   INT дата согласования
46 varn   VARCHAR юзд id документа
47 other_info   TEXT дополнительные данные
48 sub_doc_date   INT дата подтипа документа
49 sub_doc_number   VARCHAR номер подтипа документа
50 doc_error   TEXT шибка при работе с документом
51 doc_info   TEXT комментарий к документу
52 old_doc_id   INT id документа
53 sub_status_date   INT дата статуса документа (состояние цепочки документов)
54 from_doc_id   INT порядковый номер документа в цепочке
56 doc_num   VARCHAR номер документа
57 sender   VARCHAR GLN отправителя
58 recipient   VARCHAR GLN получателя
59 file_name   VARCHAR наименование прикладываемого (вложение) файла
60 xml_hash   VARCHAR хеш содержания документа
61 answer_doc_id   INT id ответного COMDOC документа
80 identifier   VARCHAR идентификатор документа в системе клиента
82 compound_number   VARCHAR составной номер
85 doc_process   TINYINT  
87 users   VARCHAR  

Таблица 9 - Описание DocType параметров (объект XDocType)

Тип Название Описание (наименование кириллицей)
0 all all
1 invoice Счет
2 orders Заказ
3 recadv Уведомление о приеме
4 desadv Уведомление об отгрузке
5 ordrsp Подтверждение заказа
6 pricat Прайс-лист
10 declar Налоговая накладная
11 insdes Инструкция по доставке
13 slsrpt Отчет о продажах
14 invrpt Отчет об инвентаризации
15 coacsu Акт сверки взаиморасчетов
16 actset Акт взаимозачета
17 iftmin Инструкция о транспортировке
18 retann Уведомление о возврате
19 iftmbf Заказ транспортировки
21 mscons Отчет о предоставленых услугах
25 retins Инструкция о возврате
28 comdoc Коммерческий документ
29 declarj12 Корректировка к налоговой накладной
30 condra Не структурированный документ
42 iftmbc Подтверждение заказа транспортировки
59 documentinvoice Товарная накладная
67 doccorinvoice doccorinvoice
75 waybill ТТН
79 addbill addbill
98 quotes Приложение к ув.об отгрузке

*Тип* поля: M - mandatory (обязательное к заполнению), O - optional (опциональное)

RESPONSE

Таблица 10 - Описание json-параметров, которые могут передаваться в ответ на метод API

Параметр Формат Описание
items List<XDoc> массив объектов; список документов
totalCount int количество документов

Таблица 11 - Описание параметров объекта XDocStatus

Параметр Формат Описание
Объект XDocStatus подробнее
state int id статуса
title String статус

Таблица 12 - Описание параметров объекта XDoc

Параметр Формат Описание
Объект XDoc  
body XDocBodyForms объект; тела документов
attachments List<XDocAttachment> массив объектов; вложение (может не использоваться)
comments XDocCommentsList объект (в котором массив объектов); список комментариев
doc_id long id документа
doc_uuid UUID уникальный идентификатор документа/квитанции
uuidSender String уникальный идентификатор отправителя
uuidReceiver String уникальный идентификатор получателя
docNumber String номер документа
dateCreated long дата создания документа (unix timestamp)
dateChanged long дата последнего изменения документа (unix timestamp)
dateRead long дата прочтения документа (unix timestamp)
docDate long дата документа, указанная в документе
chain_id long id цепочки документов
chain_uuid UUID уникальный идентификатор цепочки документов
family int семейство (EDI / UZD)
hash String хэш-значение, полученное в результате обработки
type XDocType объект; тип документа
status XDocStatus объект; статус пары документов у отправителя и получателя
exchange_status String сабстатус документа
is_archive boolean флаг; «архивный» документ или нет
signInfo XDocSignInfo объект; данные о подписях
chain XChain объект; данные связанных цепочек
extraFields Map<String, String> массив объектов; набор индексов (аналог индексных таблиц)
tags List<XTag> массив объектов; прикрепленные теги
statuses List<XStatus> массив объектов; статусы об обработке отправленных документов
multiExtraFields Map<String, List<String>>
массив объектов; мультииндекс. Пример: {„key1“: [„val1“, „val2“], „key2“: [„val1“, „val2“]}. Используется, например для обработки передаваемой строки => разбивка строки по условию => индексирование каждого куска

Таблица 13 - Описание параметров объекта XTag

Параметр Формат Описание
Объект XTag  
id long id тега
name String содержание тега
shortName String краткое наименование тега

Таблица 14 - Описание параметров объекта XStatus

Параметр Формат Описание
Объект XStatus  
docId long id документа/квитанции
date long дата статуса; формат unix timestamp
type int тип статуса
text String содержание статуса

Таблица 15 - Описание параметров объекта XDocSignInfo

Параметр Формат Описание
Объект XDocSignInfo  
doc_id long id документа/квитанции
date long дата подписания; формат unix timestamp
count short количество подписей
info String дополнительная информация
hash String хэш-значение, полученное в результате обработки

Таблица 16 - Описание параметров объекта XDocCommentsList

Параметр Формат Описание
Объект XDocCommentsList  
XDocCommentsList List<XDocComment> массив объектов; комментарии к документу

Таблица 17 - Описание параметров объекта XDocComment

Параметр Формат Описание
Объект XDocComment  
id long id комментария
docUUID UUID уникальный идентификатор документа
createTimestamp long дата создания комментария в формате timestamp
authorLogin String автор комментария
comment String содержание комментария

Таблица 18 - Описание параметров объекта XDocAttachment

Параметр Формат Описание
Объект XDocAttachment  
id long id вложения
docUUID UUID уникальный идентификатор документа
fileName String наименование файла
createDate long дата создания вложения; формат unix timestamp
type String тип вложения
base64content String содержание вложения в BASE64
content byte[] содержание вложения в целочисленном виде

Таблица 19 - Описание параметров объекта XDocBodyForms

Параметр Формат Описание
Объект XDocBodyForms  
forms HashMap<String, XDocBody> массив объектов; тело документа

Таблица 20 - Описание параметров объекта XDocBody

Параметр Формат Описание
Объект XDocBody  
type XDocBodyType объект; тип тела документа: CONTENT = 1 - содержание в байтах; JSON = 2 - содержание в json формате; SIGN = 3 - содержание подписи; STAMP = 4; CRYPTED = 5 - содержание в зашифрованном виде; UZDRESPONSE = 6
base64content String содержание тела документа в BASE64

Таблица 21 - Описание параметров объекта XDocBodyType

Параметр Формат Описание
Объект XDocBodyType  
id int id типа тела документа
name String наименование типа тела документа

Таблица 22 - Описание DocStatus параметров (объект XDocStatus)

id статуса статус
0 ALL - любой статус
1 OPEN - черновик(отправитель)
2 SENT - отправлен(отправитель)
3 DELIVERED - прочитан(отправитель)
4 INBOX - доставлен/входящий(получатель)
5 READ - прочитан(получатель)
6 ERROR - ошибка
7 DELETED - удален

Примеры (json)

Получить все входящие (полученные) документы на определенный GLN без черновиков (массив statuses не содержит «1»)

{
    "direction": {
        "sender": [],
        "receiver": [
            "9864232304302"
        ],
        "type": "IN"
    },
    "exchangeStatus": [],
    "family": "1",
    "statuses": [
        "2",
        "3",
        "4",
        "5",
        "6",
        "7"
    ],
    "type": [
        {
            "type": "0"
        }
    ]
}

Получить все исходящие (отправленные) документы по GLN без черновиков (массив statuses не содержит «1»)

{
    "direction": {
        "sender": [
            "9864232304302"
        ],
        "receiver": [],
        "type": "IN"
    },
    "exchangeStatus": [],
    "family": "1",
    "statuses": [
        "2",
        "3",
        "4",
        "5",
        "6",
        "7"
    ],
    "type": [
        {
            "type": "0"
        }
    ]
}

Получить все входящие (полученные) документы на определенный GLN без черновиков (массив statuses не содержит «1»), у которых номер содержит подстроку «1001»

{
    "direction": {
        "sender": [],
        "receiver": [
            "9864232304302"
        ],
        "type": "IN"
    },
    "exchangeStatus": [],
    "family": "1",
    "statuses": [
        "2",
        "3",
        "4",
        "5",
        "6",
        "7"
    ],
    "number": "1001",
    "type": [
        {
            "type": "0"
        }
    ]
}

Получить все исходящие (отправленные) документы по GLN без черновиков (массив statuses не содержит «1»), которые созданы в мае 2019 (startTimestamp и finishTimestamp даты в формате UNIX-timestamp)

{
    "direction": {
        "sender": [
            "9864232304302"
        ],
        "receiver": [],
        "type": "IN"
    },
    "exchangeStatus": [],
    "family": "1",
    "statuses": [
        "2",
        "3",
        "4",
        "5",
        "6",
        "7"
    ],
    "type": [
        {
            "type": "0"
        }
    ],
    "docDate": {
        "startTimestamp": "1556668800",
        "finishTimestamp": "1559347199"
    }
}

Пример тела ответа (json):

{
    "items": [
        {
            "body": {
                "forms": {}
            },
            "attachments": [],
            "comments": [],
            "doc_id": 1017,
            "doc_uuid": "e18a05d5-983b-4ebc-95f3-c35eccc7d611",
            "uuidSender": "4820128010004",
            "uuidReceiver": "9864065702429",
            "docNumber": "8663c3f48bea4f96a281238e847b1639",
            "dateCreated": 1549961913,
            "dateChanged": 1549961913,
            "dateRead": 0,
            "docDate": 1547503200,
            "chain_id": 1006,
            "chain_uuid": "60e487d3-871f-4b3a-9254-1d3f0e7a032f",
            "family": 1,
            "hash": "30745386780343D0C2F4C65C7F06D60F",
            "type": {
                "type": 1,
                "title": "invoice",
                "description": "Счет"
            },
            "status": {
                "status": 4,
                "title": "inbox"
            },
            "exchange_status": "000000000000000000000000",
            "is_archive": false,
            "extraFields": {
                "order_date": "1551477600",
                "delivery_date": "1547503200",
                "ftpex_file_name": "highload_invoice_test.xml",
                "sender": "4820128010004",
                "buyer_uuid": "4820128010004",
                "doc_num": "8663c3f48bea4f96a281238e847b1639",
                "order_number": "747401",
                "doc_date": "1547503200",
                "recipient": "9864065702429",
                "ftpex_file_date": "1549961913",
                "supplier_uuid": "9864065702429",
                "delivery_place_uuid": "4820128019007"
            },
            "tags": [],
            "statuses": [],
            "multiExtraFields": {}
        }
    ],
    "totalCount": 0
}