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

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

С помощью метода 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) «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; 6 - Документы АТС
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
88	basis_doc_subtype		INT	подтип документа-основания
89	basis_doc_number		INT	номер документа-основания
90	basis_doc_date		INT	дата документа-основания

Таблица 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
}