Приемане на XML документи – Техническо описание
Съдържание
Съдържание………………………………………………………………………………………. 1
1. Въведение……………………………………………………………………………............. 2
2. Общи положения………………………………………………………………………… 2
3. Изисквания за приемане на XML документ…………………………............. 2
4. Описание на XML елементите в GovDoc………………………………............. 3
5. Електронно подписване в GovDoc………………………………………………. 5
6. Прикачване на файлове в GovDoc……………………………………………….. 6
7. Използване на уеб услугата за зареждане на документи…………... 6
Приложения……………………………………………………………………………………… 9
Приложение 1. XML схема на GovDoc…………………………………………………………. 9
Приложение 2. Примерен GovDoc документ…………………………………………………..11
Въведение
Министерството на транспорта и съобщенията предоставя публично достъпна услуга под формата на XML Web Service, чрез която частни лица, фирми и държавни организации имат възможност да изпращат електронно подписани документи, на базата на отворения стандарт XML. Услугата е интегрирана със съществуващата системата за управление на документо-оборота в МТС.
Този документ съдържа техническа информация за структурата на приеманите документи (XML схема), принципите, по които се формират, както и условията, на които трябва да отговарят, за да могат да бъдат обработени.
Тази информация е предназначена за разработчици на софтуер, които биха искали да създадат приложения, които да обменят електронно подписани документи директно с информационната система на МТС.
Общи положения
Общите положения свързани с приемането на XML документи са следните:
-
МТС въвежда XML формат за обмен на електронно подписани документи с външни контрагенти.
-
XML документите които постъпват в МТС трябва да отговарят на определена XML схема наречена GovDoc. Схемата може да се намери в Приложение 1 на този документ.
-
MTC предоставя публично достъпна услуга под формата на XML Web Service, чрез която външни контрагенти могат да изпращат документи в GovDoc формат.
-
GovDoc документите се подписват електронно съгласно стандарта на W3C - XML Signature. Повече информация за правилата за електронно подписване може да се намери в раздела „Електронно подписване в GovDoc”.
-
GovDoc позволява прикачването на документи от различен тип – doc, pdf, xls, rtf и txt, наричани по-нататък „полезен товар”.
-
GovDoc съдържа реквизити на полезния товар – регистрационен номер, адресат, подател и т.н.
-
Подателят може да получи обратна разписка в GovDoc формат съдържаща входящ номер, при положение, че е посочил електронен адрес за обратна връзка (атрибут @URI на елемента ).
-
-
Документът се приема на адрес https://online.mtc.government.bg/GovDoc/ посредством SOAP заявка.
-
Документът трябва да отговаря на XML схемата в приложение 1.
-
Документът трябва да е електронно подписан съгласно правилата в т5.
-
Документът трябва да е с размер по-малък от 2MB.
-
Полезният товар може да бъде един от следните типове документи – DOC (Microsoft Word Document), PDF (Adobe Portable Document Format), XLS (Microsoft Excel Spreadsheet), RTF (Rich Text Format), TXT (clear text).
Описание на XML елементите в GovDoc
XML елемент/атрибут
|
Описание
|
GovDoc
|
Основен (root) елемент на XML документа. Задължително трябва да съдържа декларация за XML namespace –
xmlns=”http://www.mtc.government.bg/GovDoc”
|
DocID
|
Уникален идентификационен номер, който се генерира от приложението създаващо документа. При постъпване на документ, съдържащ валиден електронен адрес за обратна връзка, на подателя се изпраща отговор, съдържащ входящ регистрационен номер и DocID на иницииращия документ. По този начин се дава възможност на автоматизираните информационни системи да направят връзка (корелация) между иницииращия документ и отговора.
|
DocHeader
|
Съдържа метаданни за документа.
|
DocType
|
Вид на документа – писмо, молба, покана и т.н.
|
RegNum
|
Регистрационен номер на документа. Когато документът се изпраща от юридическо лице RegNum съдържа изходящ номер. При връщане на отговор този елемент съдържа входящ номер, под който документът е регистриран от адресата.
|
RegDate
|
Дата на генериране на регистрационен номер във формат dd.MM.yyyy или dd.MM.yyyy hh:mm:ss.
|
Subject
|
За какво се отнася документа.
|
Category
|
Категория на документа.
|
Priority
|
Приоритет – нормален, висок, спешен.
|
Addressee
|
Данни за адресата.
|
Correspondent
|
Съдържа данни за кореспондент – адресат или подател в зависимост от родителския елемент.
|
Name
| -
Когато се отнася за адресат (Addressee), съдържа име на лицето (на български) за което е предназначен документа. Този елемент задължително съдържа стойност, когато адресатът е физическо лице.
-
Когато се отнася за подател (Sender), съдържа име на лицето, което е титуляр на документа. Този елемент задължително съдържа стойност, когато подателят е физическо лице.
|
Organization
| -
Когато се отнася за адресат съдържа име на организацията, за която е предназначен документа. Този елемент задължително съдържа стойност, когато адресатът е юридическо лице.
-
Когато се отнася за подател (Sender), съдържа име на организацията, която изпраща документа. Този елемент задължително съдържа стойност, когато подателят е юридическо лице.
|
Code
|
Код на организацията. Това е незадължителен атрибут на елемента , който евентуално може да се използва при обмен между организации поддържащи обща кодировка на контрагентите.
|
OrgUnit
|
Отдел/Дирекция/Агенция в рамките на организацията.
|
Position
|
Длъжност на кореспондента.
|
Telephone
|
Телефон
|
Email
|
Адрес на електронна поща.
|
PostalAddress
|
Съдържа пощенски адрес на кореспондента – адресат или подател.
|
Country
|
Държава
|
Region
|
Област
|
Municipality
|
Община
|
City
|
Град/село, задължителен елемент на пощенския адрес.
|
PostalCode
|
Пощенски код, задължителен елемент на пощенския адрес.
|
District
|
Квартал
|
Street
|
Улица
|
StreetNum
|
Номер на улица.
|
Block
|
Номер на жилищен блок.
|
Entrance
|
Вход
|
Floor
|
Етаж
|
Apartment
|
Апартамент
|
Sender
|
Данни за подателя.
|
ResponseDetails
|
Съдържа данни за обратния отговор – краен срок, електронен адрес и алтернативен начин на доставяне.
|
DueBy
|
Краен срок (дата), до който подателя би желал да получи отговор от адресата.
|
ResponseAddress
|
Съдържа електронен адрес (атрибут URI) на който се изпраща евентуален отговор. При наличие на валиден e-mail адрес, на подателя се изпраща разписка (в GovDoc формат) съдържаща входящ номер.
|
URI
|
Адрес, на който се изпраща разписката с входящ номер. За момента се допуска само валиден е-mail адрес (с префикс mailto:).
|
CustomDeliveryMethod
|
Посочва се алтернативен начин за изпращане на отговор. Подателят може да заяви своите предпочитания – например хартиен документ по пощата, електронен документ върху дискета и т.н.
|
Comments
|
Място за допълнителни коментари и пояснения
|
DocAnnotation
|
Кратка анотация за съдържанието на документа
|
AdditionalAttributes
|
Дава възможност за добавяне на допълнителни атрибути на принципа „име на атрибута” и „стойност”.
|
Attribute
|
Елемент съдържащ Name, Value.
|
Name
|
Име на атрибута.
|
Value
|
Стойност на атрибута.
|
Signatures
|
Съдържа W3CDSIG елементи – електронни подписи на документа (или части от него).
|
DocBody
|
Съдържа тялото на документа
|
DocContent
|
Base64 кодирано съдържание на прикачения документ.
|
OrigFileName
|
Име на прикачения документ. Името задължително трябва да включва едно от следните разширения - doc, xls, pdf, rtf, txt.
|
Encoding
|
Трябва да има стойност „Base64”
|
Електронно подписване в GovDoc
-
Правила за електронно подписване.
GovDoc документите които постъпват в МТС трябва да отговарят на следните правила за електронно подписване:
-
Електронното подписване отговаря на стандарта W3C XML Signature
-
XML документът е подписан с универсален електронен подпис. По-долу са изброени поддържаните сертификати (към дата 1/1/2005):
-
Персонален сертификат (физическо лице) - StampIT Doc, B-Trust Personal Certificate Class 2
-
Професионален сертификат (юридическо лице) - StampIT DocPro, B-Trust Professional Certificate for Employee Class 2, B-Trust Professional Certificate for Self-Employed Class 2, B-Trust Professional Certificate for Manager Class 2
-
Допускат се един или повече подписа (co-sign) на полезния товар (елемент ).
-
Задължително GovDoc трябва да съдържа един електронен подпис върху целия документ (включително подписите на полезния товар, ако има такива). Сертификатите могат да бъдат персонални или професионални, като се въвеждат следните правила:
-
ако полезния товар е подписан с персонален сертификат, то целият документ също трябва да е подписан с персонален сертификат.
-
ако полезния товар е подписан с професионален сертификат, то целият документ също трябва да е подписан с професионален сертификат.
-
Технически детайли
Електронният подпис върху GovDoc документите се извършва по стандарта дефиниран в http://www.w3.org/2000/09/xmldsig#. Всеки документ може да съдържа един или няколко подписа. Елементите от тип “Signature” както е описано в стандарта се съдържат в елемента “Signatures” в GovDoc схемата.
Поддържат се два вида подписи - подпис на полезния товар (елемент ) и подпис на целия XML документ. Двата подписа се различават по трансформациите, които се дефинират във всеки “Signature” елемент. Разликата е, че подписа върху полезния товар съдържа една допълнителна XSLT трансформация, която избира елемента .
По-долу е даден пример за трансформациите в двата случая.
“Transforms” елемент за подпис на полезния товар:
“Transforms” елемент за пълен подпис:
При проверка на подписите трансформациите се сравняват дословно (след нормализация), за да се гарантира, че няма неизвестна трансформация, която би могла да ограничи елементите, които се подписват.
Прикачване на файлове в GovDoc
Полезният товар в GovDoc представлява Base64 кодиран файл. Този подход позволява прикачване на файлове от произволен тип и тяхното електронно подписване съгласно стандарта XML Signature.
Типът на файла – Microsoft Word Document, Adobe Acrobat Document и т.н., се определя от разширението в името на прикачения файл, което се намира в атрибута @OrigFileName на елемента .
Използване на уеб услугата за зареждане на документи
На адрес https://online.mtc.government.bg/GovDoc/ сe намира уеб услуга, която предоставя възможност за изпращане на цифрово подписани GovDoc документи към Министерството на транспорта и съобщенията. Услугата има само един метод – GovDocSubmit, който приема един параметър от тип текст. Параметърът трябва да съдържа цифрово подписан XML документ отговарящ на XML схемата в приложение 1.
Услугата извършва проверки на документа и ако някоя от проверките пропадне, връща SoapException, в детайлите на който има описание на грешката и нейния код.
По-долу е даден пример за един детайлен елемент от възможна грешка:
Certificate types are not the same or no full signature found.
Атрибутът errorCode съдържа кода на грешката, а текстът в errorInfo елемента е нейното описание. Схемата на този елемент е следната:
В таблицата по-долу са дадени възможните кодове за грешка.
Код на грешка
|
Грешка
|
Описание
|
2001
|
The system cannot accept your request now, please try later.
|
Клиентът се опитва да изпрати повече от една заявка в рамките на една минута.
|
2002
|
The file extension is not valid or file name contains invalid characters.
|
Името на прикачения документ се проверява за невалидни символи и дали разширението е в списъка на позволени разширения.
|
2003
|
Error validating signature. Error is : ...
|
Тази грешка се връща, когато има проблем с валидацията на цифровите подписи или сертификати. Съдържа допълнително пояснение за причината за грешката.
|
2004
|
Certificate types are not the same or no full signature found.
|
Тази грешка се връща, ако документът има само частични подписи или има подписи със сертификати от различен вид (персонални и фирмени).
|
2005
|
Internal error.
|
Ако се върне тази грешка, това означава, че има непредвиден проблем в обработката на документа. Най-добре се обърнете към администратора на услугата.
|
2006
|
The document does not contain attached file
|
Тази грешка се връща, ако се изпрати GovDoc документ, който не съдържа приложен документ. Макар, че това е позволено от гледна точка на схемата, тази услуга изисква винаги да има приложен документ.
|
Приложения
Приложение 1. XML схема на GovDoc
attributeFormDefault="unqualified" elementFormDefault="qualified" targetNamespace="http://www.mtc.government.bg/GovDoc" xmlns:xs="http://www.w3.org/2001/XMLSchema">
По-долу е даден примерен GovDoc документ. Стойностите на елементите , и са заменени с „XXX…” и зависят от конкретното съдържание на документа, използвания частен ключ и сертификат за подпис.
Писмо
Примерен GovDoc документ
Нормален
Министерство на транспорта и съобщенията
Име и фамилия на подателя
Град
1234
Улица
X
Документът съдържа два подписа - един пълен и един върху полезния товар
Полезният товар е base 64 кодиран TXT документ съдържащ текста: "Това е примерен TXT документ"
XXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXX
0u7i4CDlIO/w6Ozl8OXtIFRYVCDk7urz7OXt8g0K
Страница
Сподели с приятели: |
