| EDI web-сервис для XML-документовCпецификация и протокол работы |
CISLink Limited1. Назначение
Web-сервис предназначен для организации электронного обмена данными (Electronic Data Interchange, EDI) с сервером CISLink посредством передачи электронных документов в формате XML:
- Прием электронных документов в формате XML с сервера CISLink
- Передача электронных документов в формате XML на сервер CISLink
Структура электронных документов XML описана ниже в этом документе.
2. Описание
Веб-сервис предоставляет функции для организации документооборота – функции приема, передачи информации, вспомогательные функции отправки подтверждений получения-прочтения документа. Спецификация методов веб-сервиса приведена ниже.
Примеры получаемых (с сервера CISLink) электронных документов
- Заявка (Заказ) (ORDERS)
- Корректировка / подтверждение заказа (ORDCHG)
- Акт приемки (RECADV)
- Синхронизация справочника товаров (PRICAT / PRODAT)
* в скобках указаны канонические названия EDI - сообщений по стандарту EDIFACT.
Примеры передаваемых на сервер CISLink электронных документов
- Ответ на заказ (ORDRSP)
- Накладная (DESADV)
Служебные электронные сообщения
- Подтверждение о доставке / целостности сообщения (CONTRL)
- Подтверждение об обработке сообщения (импорте) (APERAK)
Служебные уведомления отсылаются по каждому переданному/полученному электронному документу последовательно по факту изменения статуса документа, сначала CONTRL, после APERAK.
3. Доступ к веб-сервису
Веб-сервис доступен по URL:
http://edi. /FileClient/WebService1/service. asmx
http://edi. /FileClient/WebService2/service. asmx
WSDL-определение доступно по URL:
http://edi. /FileClient/WebService1/service. asmx? wsdl
http://edi. /FileClient/WebService2/service. asmx? wsdl
Для авторизации и возможности работы с веб-сервисом необходимо получить логин и пароль. Эти данные можно запросить по адресу *****@***com.
4. Спецификация методов веб-сервиса
IsWebServiceAvailable()проверка доступности веб-сервиса. Возвращает true, если сервис доступен, false – если нет.
Login3(userName, data, isEncrypt)создает сессию соединения, возвращает GUID сессии. В противном случае пустую строку.
Параметр data – пароль для аутентификации для данного имени пользователя.
isEncrypt – параметр типа Boolean, содержащий указание на то, что пароль зашифрован. Шифрование пароля пользователя происходит по ассиметричной схеме – пароль шифруется открытым ключом, а на сервере пароль расшифровывается при помощи закрытого ключа.
Logout(SessionGUID)удаляет SessionGUID. Возвращает true, если успешно удалено, false – если нет.
GetXMLDocument(SessionGUID, DocumentType)получает EDI-документ(ы) с сервера в формате 5.4
DocumentType – параметр содержит название типа документа по терминологии стандарта EANCOM:
ORDERS – заказ
ORDRSP – ответ на заказ
DESADV – уведомление об отгрузке
RECADV – уведомление о приемке
(подробнее см. http://*****/?page_id=4 )
Будет возвращен один (наиболее давний) недоставленный (по статусам CONTRL) документ указанного типа.
Для того, чтобы полученный документ более не возвращался, необходимо подтвердить доставку вызовом метода PostAckMessage.
Дополнительно для совместимости существует возможность запросить конкретный документ, указав в параметре DocumentType непосредственно уникальный номер документа, присваиваемый CISLink. Номер возвращается как результат вызова метода CheckNewMessages / CheckNewMessagesEx или виден на веб-портале CISLink как часть URL документа.
Документ будет возвращен только при успешной проверке прав доступа для данного пользователя на запрос документа. В противном случае будет возвращена xml-структура вида 5.4.1
PostXMLDocument(SessionGUID, DocumentContentXml)отсылает EDI-документ на сервер в формате 5.4
CheckNewMessages (SessionGUID)проверяет наличие новых исходящих со стороны сервера edi-сообщений на сервере. Возвращает XML в формате 5.1
Сообщение остается в статусе «новое» и будет возвращаться методом до тех пор, пока не будет получено подтверждение о доставке (CONTRL) через вызов метода PostAckMessage (п.8).
CheckNewMessagesEx (SessionGUID)проверяет наличие новых входящих edi-сообщений на сервере. Возвращает XML в формате 5.1.1
Дополнительно указываются тип документа, дата и его номер.
GetAckMessage(SessionGUID)Возвращает подтверждение от получателя с сервера по ранее отправленным сообщениям. Возвращает XML в формате 5.2
PostAckMessage(SessionGUID, AckXml)отправляет подтверждение о доставке/ об обработке (APERAK) сообщения на сервер. Тип уведомления (CONTRL/APERAK) определяется в XML-элементе параметра AckXml. Формат AckXml приведен в 5.2
Уведомления необходимо отправлять на сервер только по исходящим с сервера edi-сообщениям.
GetEDILinks(SessionGUID)получает данные о настроенных EDI-связях с сервера. Возвращает XML в формате 5.3.
Далее перечислены функции, предназначенные для работы с web-сервисом из EDI-модуля для 1С:
IsUpdateAvailable3 (SessionGUID, clientVersionNumber)проверяет наличие на сервере обновления модуля. Обновляет текущий номер версии клиента в БД CISLink. Возвращает номер текущей версии.
GetUpdateList (SessionGUID)получение списка файлов обновления (для Windows Installer варианта приложения).
GetUpdate(SessionGUID, Filename)получает обновление файла Filename из списка файлов обновления модуля, полученных GetUpdateList() с сервера.
5. Форматы XML-данных
5.1. Сообщение о новых документах
Пример
<Result>
<NewMessagesOnServer>3</ NewMessagesOnServer >
<DocID>101</DocID>
<DocID>102</DocID>
<DocID>103</DocID>
</Result>
5.1.1. Расширенное сообщение о новых документах
В разработке
Пример
<Result>
</Result>
5.2. Уведомление
<Acknowledgement>
<AckType> varchar(10) Тип уведомления
<AckDateTime varchar(19) Дата-время создания уведомления
(yyyy-MM-dd HH:mm:ss)
<AckSender> varchar(13) Отправитель уведомления
<AckReceiver> varchar(13) Получатель уведомления
<SourceDocument>
<DocNumber> varchar(19) Номер исходного документа
<DocDate> varchar(20) Дата исходного документа
(yyyy-MM-dd)
<DocID> varchar(10) ID исходного документа
<Status> varchar(500) Статус документа
</SourceDocument>
</Acknowledgement>
Если вы передаете DocID, то некоторые элементы можно не передавать, в этом случае уведомление будет выглядеть так:
<Acknowledgement>
<AckType> varchar(10) Тип уведомления
<AckDateTime varchar(19) Дата-время создания уведомления
(yyyy-MM-dd HH:mm:ss)
<SourceDocument>
<DocID> varchar(10) ID исходного документа
<Status> varchar(500) Статус документа
</SourceDocument>
</Acknowledgement>
Комментарии и указания
Уведомления отсылаются в явном виде для подтверждения следующего:
- CONTRL - по факту получения сообщения с сервера,
- APERAK - по факту прочтения (загрузки в учетную систему
получателя).
Если для партнера указан тип взаимодействия через web-cервис, статусы доставки-прочтения исходного документа на сайте изменить будет нельзя.
AckSender/AckReceiver - это дополнительный способ идентификации участников при обработке служебных уведомлений. Это идентификаторы участников (отправителя и получателя) в системе CISLink.
В случае со служебными уведомлениями процесс идентификации упрощен и ни GLN, ни локальные коды участников не используются для идентификации, поскольку участники в большинстве случаев будут определяться по исходному документу - по элементу <SourceDocument> и его потомкам.
Если в уведомлении указано значение элемента DocID, значения, указанные в паре элементов AckSender/AckReceiver, игнорируются при обработке.
Указывайте 1 и 2, как в примере.
Status не должен содержать каких-либо обрамляющих кавычек и их эквивалентов &lt / &gt.
Пример
<Acknowledgement>
<AckType>CONTRL</AckType>
<AckDateTime> 12:20</AckDateTime>
<AckSender>2</AckSender>
<AckReceiver >1</AckReceiver>
<SourceDocument>
<DocNumber >A1234</DocNumber>
<DocDate> </ DocDate>
<DocID>1234</DocID>
<Status>OK или текст ошибки обработки</Status>
</SourceDocument>
</Acknowledgement>
5.3. EDI-Связи с типами документов
<Partners>
<EDILink>
<PartnerID>2</ PartnerID >
<PartnerIdentType>GLN</PartnerIdentType>
<PartnerName>Заказчик ООО</ PartnerName>
<GLN></GLN>
<LocalCode/>
<Document>
<Type>ORDERS</Type>
<Direction>Incoming</Direction>
</Document>
<Document>
<Type>DESADV</Type>
<Direction>Outgoing</Direction>
</Document>
<Location>
<LocationID>
<LocationName>Магазин1</LocationName Name>
<LocationAddress>г. Кукуев, ул. </ LocationAddress>
<LocationGLN></LocationGLN >
<LocationCode/></LocationCode>
</Location>
<Location>
<LocationID>
<LocationName>Магазин2</LocationName Name>
<LocationAddress>г. Кукуев, ул. </ LocationAddress>
<LocationGLN></LocationGLN >
<LocationCode/></LocationCode>
</Location>
</EDILink>
</Partners>
5.4. Документ
Элемент XML | Тип данных | Обязательность | Описание |
<Document> | Корневой элемент | ||
<DocumentType> | varchar(13) | Да | название документа EANCOM |
<DocID> | numeric(13) | Нет | Уникальный идентификатор документа в системе CISLink (только для GetXMLDocument) |
<BuyerID> | numeric(13) | Правило 1 | ID Заказчика в системе CISLink |
<BuyerEAN> | numeric(13) | Правило 1 | ГЛН Покупателя (Заказчика) |
<BuyerName> | varchar(50) | Нет | Название Заказчика |
<BuyerAddr> | varchar(200) | Нет | Адрес Заказчика |
<SupplierID> | numeric(13) | Правило 1 | ID Поставщика в системе CISLink |
<SupplierGLN> | numeric(13) | Правило 1 | ГЛН Поставщика |
<DeliveryPointID> | numeric(10) | Правило 1 | ID точки доставки в системе CISLink |
<DeliveryPointGLN> | numeric(13) | Правило 1 | ГЛН точки доставки Заказчика (магазина) |
<ConsigneeName> | varchar(50) | Нет | Название грузополучателя |
<ConsigneeAddr> | varchar(200) | Нет | Адрес грузополучателя |
<SenderCode> | varchar(30) | Правило 1 | Код отправителя по его учетной системе |
<ReceiverCode> | varchar(30) | Правило 1 | Код получателя в ИС отправителя |
<DeliveryCode> | varchar(30) | Правило 1 | Код точки доставки в ИС отправителя |
<Format> | varchar(25) | Нет | Формат исходного файла заказа (в рамках данного ТЗ не используется) |
<DocumentNumber> | varchar(20) | Да | Номер документа |
<OrderId> | numeric(20) | Правило 2 | ID заказа в системе CISLink (для типов документа не “заказ”) |
<OrderNumber> | varchar(20) | Правило 2 | Номер заказа (для типов документа не “заказ”) |
<OrderDate> | varchar(20) | Правило 2 | Дата заказа (для типов документа не “заказ”) (yyyymmdd) |
<DesadvNumber> | varchar(20) | Нет | Номер накладной (для типов документа RECADV/INVOIC) |
<DocumentDate> | varchar(20) | Да | Дата документа(yyyymmdd) |
<DeliveryDate> | varchar(20) | Да | Дата доставки (yyyymmdd) |
<OptionalText> | varchar(200) | Нет | Комментарий |
<DispatchDate> | varchar(20) | Нет | Дата отгрузки (yyyymmdd) |
<Currency> | varchar(3) | Нет | код денежной единицы документа по ISO 4217 http://www. iso. org/iso/currency_codes_list-1 |
<DocDetail> | Далее указаны дочерние элементы для DocDetail | ||
<EAN> | numeric(14) | Правило 3 | EAN товара |
<SenderPrdCode> | varchar(50) | Правило 3 | Код товара в ИС отправителя |
<ReceiverPrdCode> | varchar(100) | Правило 3 | Код товара в ИС получателя |
<OptionalPrdCode> | varchar(100) | Нет | Код товара дополнительный |
<ProductName> | varchar(200) | Нет | Название товара |
<UOM> | varchar(20) | Нет | Название или код единицы измерения По возможности необходимо использовать коды по рекомендации UNECE http://www. unece. org/cefact/codesfortrade/rec20.xml |
<ItemsPerUnit> | numeric(10,4) | Нет | Штук в упаковке |
<QTYtype> | numeric(10) | Нет | Код типа количества. По умолчанию для заказов – заказанное количество |
<QTY> | numeric(10,4) | Да | Количество (без разделителей тысяч и с разделителем дробной части – точка) |
<Pricetype> | varchar(255) | Нет | Тип цены для Price1. По умолчанию – закупочная цена с НДС |
<Price1> | varchar(15) | Нет | Цена (без разделителя тысяч и с разделителем дробной части - точка) |
<Price2> | varchar(15) | Нет | Дополнительная цена или стоимость |
<VAT> | numeric(2) | Нет | Ставка НДС, % (без символа ‘%’) |
<OriginCountry> | varchar(50) | Правило 4 | Страна происхождения по ISO 3166-1-alpha-2 (http://www. iso. org/iso/country_codes/iso_3166_code_lists. htm)) |
<CustDeclNumber> | varchar(40) | Правило 4 | Номер ГТД. ГТД - государственная таможенная декларация |
<MinimalExpirationDate> | varchar(8) | Правило 4 | Срок годности как произвольный текст |
Комментарии
GLN – Global Location Number.
Международный код, присваиваемый компании и ее подразделениям.
Регистрирующая организация – GS1, http://www. *****/about/
GLN является основным кодом идентификации участников в задачах электронного обмена данными (EDI).
GLN участников можно уточнить у партнера по EDI, у EDI-провайдера или по реестру www. gepir. org .
Правила
1. Основной способ идентификации участников - по GLN в элементах
<BuyerEAN>
<SupplierGLN>
<DeliveryPointGLN>
(соответственно покупатель, поставщик, точка доставки)
Элемент для GLN покупателя должен называться <BuyerEAN> (но <SupplierGLN>).
SenderCode / ReceiverCode / DeliveryCode - это альтернативный способ идентификации партнеров по кодам отправителя.
Он используется, когда партнер не имеет своего GLN или нет возможности
их указывать.
Если идентификация происходит по GLN, коды SenderCode / ReceiverCode можно не указывать для целей идентификации. Иногда они используются для передачи сопроводительной информации, например номера контракта заказчика с поставщиком.
Если вы выбираете этот способ идентификации, пожалуйста, предоставьте список ваших кодов всех точек доставки, а также коды отправителя и получателя, которые будут использоваться в элементах SenderCode и ReceiverCode, для настройки таблицы трансляции кодов.
BuyerID / SupplierID / DeliveryPointID - это альтернативный способ идентификации партнеров, если известны их идентификаторы в системе CISLink.
2. Для идентификации участников и исходного заказа в edi-документах, формируемых на основании заказа (накладная, счет, ответ на заказ), наиболее простым и быстрым способом рекомендуется указывать элемент OrderID со значением атрибута DocID из заголовка заказа. В этом случае приоритет отдается идентификации по OrderID по сравнению с правилом 1.
Если OrderID не используется, для идентификации исходного заказа обязательно использование OrderNumber и OrderDate.
3. <EAN>
<SenderPrdCode>
<ReceiverPrdCode>
<OptionalPrdCode>
Участники предварительно самостоятельно синхронизируют справочники кодов номенклатурных позиций и используют для идентификации любой из указанных элементов. Остальные элементы этой группы являются необязательными.
4. Поля OriginCountry и CustDeclNumber подчиняются следующим правилам:
a. Если в поле «Страна» определено значение «Россия», то значение поля «ГТД» должно быть пустое
b. Если в поле «Страна» определено значение, отличное от «Россия», значение в поле «ГТД» обязательно
c. Возможно дублирование позиции, если для товара определены несколько ГТД (поставка из разных партий)
5.4.1. Ошибки по документу
<Document>
<DocType>ERROR</DocType>
<OptionalText>No documents found or you are not authorised to request this document</OptionalText>
</Document>
6. Протокол работы с web-сервисом
6.1. Передача документа
UML диаграмма последовательности обращения к web-сервису показана на рис.6.1
После установления соединения передается XML документ, сформированный в формате 5.4, после чего осуществляется получение с сервера статусов ранее отправленных документов – доставлен получателю, обработан получателем или ошибка.
GetAckMessage() возвращает одно уведомление за раз. Сначала отдаются уведомления о доставке, после – уведомления об обработке. Уведомления упорядочены по возрастанию времени их создания.
Необходимо вызывать GetAckMessage() несколько раз, пока не вернется пустая строка.
В конце работы вызывается метод Logout().
Рисунок 6.1
6.2. Получение документа
UML диаграмма последовательности обращения к web-сервису показана на рис.6.2
После установления соединения осуществляется проверка наличия новых сообщений на сервере. после чего осуществляется получение с сервера поступивших документов – один документ за раз.
Сразу после получения каждого документа необходимо сформировать и отправить на сервер уведомление о доставке сообщения.
После получения всех документов вызывается метод Logout().
По факту обработки полученных документов в учетной системе получателя необходимо отправить уведомление об обработке. Устанавливается соединение и вызывается метод PostAckMessage() с типом уведомления APERAK.
В конце работы вызывается метод Logout().
Рисунок 6.2
