Standard Business Document Header (SBDH)

Основні поняття

Стандартний заголовок для бізнес-документів (SBDH) дозволяє вказати усю необхідну інформацію для конкретного повідомлення при обміні EDI. Цей заголовок є обов’язковим елементом для кожного повідомлення у форматі GS1 XML.

Дана документація описує найважливіші елементи для SBDH, які необхідно або варто використовувати в роботі.

Повністю переглянути стандарт XSD для SBDH можна на офіційному сайті: https://www.gs1.org/standards/edi/gs1-xml

Приклад мінімально достатнього заголовка

<sh:StandardBusinessDocumentHeader>
    <sh:HeaderVersion>1.0</sh:HeaderVersion>
    <sh:Sender>
        <sh:Identifier Authority="GS1">123456789</sh:Identifier>
    </sh:Sender>
    <sh:Receiver>
        <sh:Identifier Authority="GS1">987654321</sh:Identifier>
    </sh:Receiver>

    <sh:DocumentIdentification>
        <sh:Standard>GS1</sh:Standard>
        <sh:TypeVersion>3.6.0</sh:TypeVersion>
        <sh:InstanceIdentifier>MSG-100002</sh:InstanceIdentifier>
        <sh:Type/>
        <sh:CreationDateAndTime>2006-01-10T12:00:01.000-05:00</sh:CreationDateAndTime>
    </sh:DocumentIdentification>
</sh:StandardBusinessDocumentHeader>

Основні елементи для заповнення

Елемент Режим Формат Опис

Елемент	Режим	Формат	Опис
`StandardBusinessDocumentHeader`	1..1		Стандартний заголовок бізнес-документа
`HeaderVersion`	1..1	xs:string	Версія використаного SBDH стандарту. Згідно з правилами GS1 SBDH: завжди повинен мати значення 1.0
`Sender`	1..*	sh:Partner	Відправник повідомлення. Повинен бути зареєстрований в Edibox
`Receiver`	1..*	sh:Partner	Отримувач повідомлення. Повинен бути зареєстрований в Edibox. Не може бути таким самим що й відправник.
`DocumentIdentification`	1..1	sh:DocumentIdentification	Ідентифікаційна інформація повідомлення, яка дозволяє однозначно визначити його серед повідомлень відправника.

StandardBusinessDocumentHeader

1..1

Стандартний заголовок бізнес-документа

HeaderVersion

1..1

xs:string

Версія використаного SBDH стандарту. Згідно з правилами GS1 SBDH: завжди повинен мати значення 1.0

Sender

1..*

sh:Partner

Відправник повідомлення. Повинен бути зареєстрований в Edibox

Receiver

1..*

sh:Partner

Отримувач повідомлення. Повинен бути зареєстрований в Edibox. Не може бути таким самим що й відправник.

DocumentIdentification

1..1

sh:DocumentIdentification

Ідентифікаційна інформація повідомлення, яка дозволяє однозначно визначити його серед повідомлень відправника.

    <sh:HeaderVersion>1.0</sh:HeaderVersion>

Відправник/отримувач

Відправник (Sender) та отримувач (Receiver) - повинні бути зареєстровані у сервісі Edibox - інакше повідомлення буде відхилене з помилкою.

Опис відправника

<sh:Sender>
    <sh:Identifier Authority="GS1">123456789</sh:Identifier>
</sh:Sender>

Елемент Identifier містить GLN код відправника або отримувача.

За стандартом GS1 XML атрибут Authority повинен завжди містити значення GS1.

Контактна інформація

За необхідності дані про відправника/отримувача можна доповнити контактною інформацією ContactInformation, що полегшить обмін повідомленнями. Лише елемент Contact у контактній інформації є обов’язковим - решта може не використовуватися.

Для кожної зі сторін може міститися декілька елементів контактної інформації ContactInformation, наприклад, для бухгалтерії та технічного відділу.

Контактна інформація відправника: бухгалтерія та тех відділ

<sh:Sender>
    <sh:Identifier Authority="GS1">123456789</sh:Identifier>

    <sh:ContactInformation>
        <sh:Contact>Ольга Володимирівна</sh:Contact>
        <sh:EmailAddress>olga_sales@ukr.net</sh:EmailAddress>
        <sh:TelephoneNumber>+38-067-555-2233</sh:TelephoneNumber>
        <sh:ContactTypeIdentifier>Бухгалтерія</sh:ContactTypeIdentifier>
    </sh:ContactInformation>

    <sh:ContactInformation>
        <sh:Contact>Сергій Петрович</sh:Contact>
        <sh:EmailAddress>it_team@salescompany.com.ua</sh:EmailAddress>
        <sh:TelephoneNumber>+38-050-555-2122</sh:TelephoneNumber>
        <sh:ContactTypeIdentifier>Тех. підтримка</sh:ContactTypeIdentifier>
    </sh:ContactInformation>

</sh:Sender>

Елемент Режим Формат Опис

Елемент	Режим	Формат	Опис
`ContactInformation`	0..*		Контактна інформація
`Contact`	1..1	xs:string	Ім’я контактної особи
`EmailAddress`	0..1	xs:string	Адреса електронної пошти
`TelephoneNumber`	0..1	xs:string	Номер телефону. Рекомендується використовувати стандарт RFC-3966, щоб полегшити обробку телефонів.
`ContactTypeIdentifier`	0..1	xs:string	Посада або обов’язки контактної особи

ContactInformation

0..*

Контактна інформація

Contact

1..1

xs:string

Ім’я контактної особи

EmailAddress

0..1

xs:string

Адреса електронної пошти

TelephoneNumber

0..1

xs:string

Номер телефону. Рекомендується використовувати стандарт RFC-3966, щоб полегшити обробку телефонів.

ContactTypeIdentifier

0..1

xs:string

Посада або обов’язки контактної особи

Ідентифікація повідомлення

DocumentIdentification - це обов’язковий елемент для SBDH, який дозволяє вказати дані для ідентифікації повідомлення в сервісі обміну документами.

Мінімально достатня ідентифікація

<sh:DocumentIdentification>
    <sh:Standard>GS1</sh:Standard>
    <sh:TypeVersion>3.6.0</sh:TypeVersion>
    <sh:InstanceIdentifier>100002</sh:InstanceIdentifier>
    <sh:Type/>
    <sh:MultipleType>false</sh:MultipleType>
    <sh:CreationDateAndTime>2023-06-10T12:15:44+03:00</sh:CreationDateAndTime>
</sh:DocumentIdentification>

Елемент Режим Формат Опис

Елемент	Режим	Формат	Опис
`DocumentIdentification`	1..1		Інформація щодо ідентифікації повідомлення
`Standard`	1..1	xs:string	Згідно правил GS1 SBDH: завжди дорівнює GS1
`TypeVersion`	1..1	xs:string	Згідно з правилами GS1 SBDH: версія використаного стандарту GS1 XML. Наразі підтримується єдина версія: 3.6.0
`InstanceIdentifier`	1..1	xs:string	Унікальний ідентифікатор цього повідомлення згенерований відправником/
`Type`	1..1	xs:string	Вказує на тип документа, який передається в повідомленні: замовляння, відповідь на замовлення, рахунок тощо. Рекомендуємо лишати пустим. Також згідно з правилами GS1 SBDH можна заповняти назвою кореневого вузла документа XML, наприклад, orderMessage для документа замовлень.
`MultipleType`	0..1	xs:boolean	Чи передаються в повідомлення документи різних типів. Згідно з правилами GS1 SBDH: повинно бути встановлено значення false, оскільки стандарт GS1 XML дозволяє в одному повідомлення передавати документи тільки одного типу.
`CreationDateAndTime`	1..1	xs:dateTime	Дата та час створення повідомлення у системі відправника. Рекомендується слідувати формату дати та часу ISO 8601. Якщо використати формат `2023-07-13T18:00:00`, то цей час сприйматиметься у часовому поясі України, тобто `2023-07-13T18:00:00+03:00` Також важливо розуміти, що це не дата документа, який передається всередині повідомлення. Наприклад, цілком реальна ситуація, коли дата повідомлення буде на день пізніше, ніж дата документа замовлення, який передається всередині повідомлення.

DocumentIdentification

1..1

Інформація щодо ідентифікації повідомлення

Standard

1..1

xs:string

Згідно правил GS1 SBDH: завжди дорівнює GS1

TypeVersion

1..1

xs:string

Згідно з правилами GS1 SBDH: версія використаного стандарту GS1 XML. Наразі підтримується єдина версія: 3.6.0

InstanceIdentifier

1..1

xs:string

Унікальний ідентифікатор цього повідомлення згенерований відправником/

Type

1..1

xs:string

Вказує на тип документа, який передається в повідомленні: замовляння, відповідь на замовлення, рахунок тощо. Рекомендуємо лишати пустим. Також згідно з правилами GS1 SBDH можна заповняти назвою кореневого вузла документа XML, наприклад, orderMessage для документа замовлень.

MultipleType

0..1

xs:boolean

Чи передаються в повідомлення документи різних типів. Згідно з правилами GS1 SBDH: повинно бути встановлено значення false, оскільки стандарт GS1 XML дозволяє в одному повідомлення передавати документи тільки одного типу.

CreationDateAndTime

1..1

xs:dateTime

Дата та час створення повідомлення у системі відправника. Рекомендується слідувати формату дати та часу ISO 8601.

Якщо використати формат 2023-07-13T18:00:00, то цей час сприйматиметься у часовому поясі України, тобто 2023-07-13T18:00:00+03:00

Також важливо розуміти, що це не дата документа, який передається всередині повідомлення.

Наприклад, цілком реальна ситуація, коли дата повідомлення буде на день пізніше, ніж дата документа замовлення, який передається всередині повідомлення.

Унікальний ідентифікатор

Ідентифікатор повідомлення InstanceIdentifier повинен бути унікальним в межах відправника. Тобто один відправник не може мати два повідомлення з однаковим ідентифікатором MSG-001, а от два різних відправники цілком можуть мати однакові номери - це не призведе до проблем.

Якщо відправник спробує присвоїти новому повідомленню ідентифікатор, який вже існує в системі, тоді сервіс видасть помилку і повідомлення не буде збережено.

Зазвичай для ідентифікатора використовують зрозумілу для людини послідовність чисел та символів, наприклад, MSG-00000234.

Не слід плутати ідентифікатор повідомлення з номером документа, який передається всередині цього повідомлення.

Тобто повідомлення MSG-00000234 в собі може містити документ безпосередньо замовлення товарів, який буде мати свій окремий номер, наприклад, ЗАМ-000456, який ідентифікує саме документ замовлення в системі відправника.

Номер документа вказується в окремому елементі ідентифікації кожного окремого типу документа. Наприклад, для замовлень - це елемент orderIdentification. Ця інформація подана на відповідних сторінках довідки для документів.

Приклад заголовка

В даному прикладі наведено заголовок, як він може виглядати в більшості повідомлень.

Типовий вигляд заголовка бізнес документа

<sh:StandardBusinessDocumentHeader>
    <sh:HeaderVersion>1.0</sh:HeaderVersion>
    <sh:Sender>
        <sh:Identifier Authority="GS1">123456789</sh:Identifier>
        <sh:ContactInformation>
            <sh:Contact>Євген</sh:Contact>
            <sh:EmailAddress>zheka234@ukr.net</sh:EmailAddress>
            <sh:TelephoneNumber>+38-093-555-2123</sh:TelephoneNumber>
            <sh:ContactTypeIdentifier>Менеджер</sh:ContactTypeIdentifier>
        </sh:ContactInformation>
    </sh:Sender>
    <sh:Receiver>
        <sh:Identifier Authority="GS1">987654321</sh:Identifier>
        <sh:ContactInformation>
            <sh:Contact>Лілія</sh:Contact>
            <sh:TelephoneNumber>+38-050-333-2125</sh:TelephoneNumber>
            <sh:ContactTypeIdentifier>Бухгалтер</sh:ContactTypeIdentifier>
        </sh:ContactInformation>
    </sh:Receiver>
    <sh:DocumentIdentification>
        <sh:Standard>GS1</sh:Standard>
        <sh:TypeVersion>3.6.0</sh:TypeVersion>
        <sh:InstanceIdentifier>100002</sh:InstanceIdentifier>
        <sh:Type/>
        <sh:MultipleType>false</sh:MultipleType>
        <sh:CreationDateAndTime>2023-06-10T12:00:01+03:00</sh:CreationDateAndTime>
    </sh:DocumentIdentification>
</sh:StandardBusinessDocumentHeader>

В наступному прикладі наведено мінімальний заголовок, де заповнені тільки обов’язкові поля і немає ніякої додаткової інформації.

Типовий вигляд заголовка бізнес документа

<sh:StandardBusinessDocumentHeader>
    <sh:HeaderVersion>1.0</sh:HeaderVersion>

    <sh:Sender>
        <sh:Identifier Authority="GS1">123456789</sh:Identifier>
    </sh:Sender>

    <sh:Receiver>
        <sh:Identifier Authority="GS1">987654321</sh:Identifier>
    </sh:Receiver>

    <sh:DocumentIdentification>
        <sh:Standard>GS1</sh:Standard>
        <sh:TypeVersion>3.6.0</sh:TypeVersion>
        <sh:InstanceIdentifier>100002</sh:InstanceIdentifier>
        <sh:Type/>
        <sh:CreationDateAndTime>2023-06-10T12:00:01+03:00</sh:CreationDateAndTime>
    </sh:DocumentIdentification>
</sh:StandardBusinessDocumentHeader>