Типи елементів GS1 XML

На цій сторінці наведено перелік найпоширеніших та важливих типів для елементів GS1 XML, які використовуються майже у всіх документах.

Для кожного типу відображені тільки важливі або рекомендовані елементи.

Для розуміння типів потрібно переглянути повну специфікацію XSD, вер. 3.6.0

Поширені типи даних

EntityIdentificationType

GS1 XML тип: ecom_common:Ecom_EntityIdentificationType

Елементи з цим типом дозволяють вказати інформацію для ідентифікації документів в переданих повідомленнях.

Таб. 1. Перелік основних елементів для типу EntityIdentification
Елемент Режим Формат Опис

entityIdentification

1..1

xsd:string (80)

Унікальний ідентифікатор для переданого документа. Зазвичай це номер в системі відправника. Наприклад, УО-00001345.
Приклад ідентифікації рахунка на оплату
<invoiceIdentification>
    <entityIdentification>IN11-548</entityIdentification>
</invoiceIdentification>

DocumentReferenceType

GS1 XML тип: ecom_common:Ecom_DocumentReferenceType

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

Таб. 2. Перелік основних елементів для типу DocumentReferenceType
Елемент Режим Формат Опис

entityIdentification

1..1

xsd:string (80)

Унікальний ідентифікатор для переданого документа. Зазвичай це номер в системі відправника. Наприклад, УО-00001345.

creationDateTime

0..1

xs:dateTime

Дата та час, коли документ замовлення було створено в системі відправника. Бажано слідувати формату: ISO 8601
Посилання на документ замовлення
<originalOrder>
    <entityIdentification>PO3352</entityIdentification>
</originalOrder>
Посилання на документ відповіді на замовлення
<orderResponse>
    <entityIdentification>PO3352</entityIdentification>
    <creationDateTime>2011-03-11T11:00:00.000-05:00</creationDateTime>
</orderResponse>

TransactionalParty

GS1 XML тип: ecom_common:TransactionalPartyType

Тип TransactionalPartyType використовується для ідентифікації компаній, юридичних осіб тощо, які фігурують в документах.

Також цей тип дозволяє задати будь-яку додаткову інформацію щодо компанії:

  • Банківські рахунки

  • Контактні особи

  • Адреси

  • Дані про юридичну організацію

Нижче наведено таблицю з елементами вартими уваги. Для повного розуміння специфікації для типу ecom_common:TransactionalPartyType необхідно вивчити схему XSD.

Таб. 3. Перелік основних елементів для типу TransactionalPartyType
Елемент Режим Формат Опис

gln

0..1

\d{13}

GLN код компанії

additionalPartyIdentification

0..*

xsd:string (80)

Будь-які додаткові коди для додаткової ідентифікації компанії: ЄДРПОУ, ІПН, код з системи продавця тощо. Обов’язкове використання атрибута: additionalPartyIdentificationTypeCode для зазначення типу використаного коду.

address

0..1

AddressType

Адреса

contact

0..*

ContactType

Контактны особи

organisationDetails

0..1

OrganisationType

Додаткові дані, щодо юридичної особи компанії, яка фігурує в документі

financialInstitutionInformation

0..*

OrganisationType

Інформація щодо банківської установи, де розміщений рахунок компанії

  financialAccount

0..1

FinancialAccountType

Інформація безпосередньо про рахунок компанії

Ідентифікація сторін

Зазвичай для ідентифікації компанії достатньо використання <gln>.

<seller>
    <gln>3662214000145</gln>
</seller>

Якщо компанія не має GLN кода, тоді можна скористатися елементом <additionalPartyIdentification>, який дозволяє вказати довільний код, попередньо узгоджений сторонами, та його значення.

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

<buyer>
    <additionalPartyIdentification additionalPartyIdentificationTypeCode="SELLER_ASSIGNED_IDENTIFIER_FOR_A_PARTY">
        0000023456
    </additionalPartyIdentification>
</buyer>

Перелік можливих GS1 XML кодів для додаткової ідентифікації: AdditionalPartyIdentificationTypeCode

Варто звернути увагу на наступні коди:

  • BUYER_ASSIGNED_IDENTIFIER_FOR_A_PARTY - ідентифікатори, що надані покупцем

  • SELLER_ASSIGNED_IDENTIFIER_FOR_A_PARTY - ідентифікатори, що надані постачальником

  • FOR_INTERNAL_USE_1 - може мати різні значення за домовленістю сторін. Цей код має 20 варіантів: від 1 до 20. Зазвичай його використовують, коли решта варіантів ідентифікації вичерпано.

Наприклад, за домовленістю сторін FOR_INTERNAL_USE_1 може означати ЄДРПОУ, а FOR_INTERNAL_USE_2 - ІПН.

Ідентифікація за допомогою ЄДРПОУ
<buyer>
    <additionalPartyIdentification additionalPartyIdentificationTypeCode="FOR_INTERNAL_USE_1">
        12345678
    </additionalPartyIdentification>
</buyer>

Інформація про рахунки

В елементах з типом ecom_common:TransactionalPartyType можна додати інформацію про рахунки компанії та банк.

Продавець з GLN та його рахунок
<seller>
    <gln>3662214000145</gln>

    <financialInstitutionInformation>
        <financialInstitutionName>Приватбанк</financialInstitutionName>
        <financialAccount>
            <financialAccountNumber>
                UA 11 222222 00000 12345678901234
            </financialAccountNumber>

            <financialAccountNumberTypeCode>
                IBAN_IDENTIFICATION
            </financialAccountNumberTypeCode>

        </financialAccount>
    </financialInstitutionInformation>
</seller>

DescriptionN

GS1 XML тип: shared_common:Description1000Type, shared_common:Description500Type, де число вказує на обмеження по кількості символів

Елементи з цим типом містять опис, тобто текстову інформацію.

Таб. 4. Атрибути для типу
Атрибут Режим Формат Опис

languageCode

1..1

xsd:string (80)

Код мови, яка використовується в описі, у форматі ISO 639-1. Для української: uk

codeListVersion

0..1

xsd:string (35)

Версія списку кодів. Зазвичай не використовується.
Приклад елемента з типом shared_common:Description1000Type
    <additionalOrderInstruction languageCode="uk">
        Кожен товар повинен бути запакований окремо.
    </additionalOrderInstruction>
Приклад елемента з типом shared_common:Description500Type
<note languageCode="en">
    Test message
</note>

TransactionalTradeItemType

GS1 XML тип: ecom_common:TransactionalTradeItemType

В документах GS1 описує товар та будь-які його додаткові властивості. В цьому елементи можна задати фізичні параметри товара, його вагу, дані щодо термінів придатності тощо.

Зазвичай товар ідентифікується з використанням штрихкоду GTIN через елемент <gtin>.

Таб. 5. Перелік основних елементів для типу TransactionalTradeItemType
Елемент Режим Формат Опис

gtin

0..1

GTINType

Штрихкод товара, 14 символів.

additionalTradeItemIdentification

0..*

AdditionalItemIdentification

Додаткова ідентифікація товару

tradeItemDescription

0..1

Description200

Назва/опис товару.

transactionalItemData

0..1

TransactionalItemDataType

Додаткові відомості про товар.

  - bestBeforeDate

0..1

xs:date

Дата придатності для цього товара

  - transactionalItemWeight

0..*

UnitMeasurementType

Вагова інформація по цьому товару

    - - measurementType

1..1

MeasurementTypeCodeType

Вказує на тип вагового показника. Поширені типи:
DECLARED_NET_WEIGHT - маса товара нетто;
TARE_WEIGHT - вага тари;
TOTAL_GROSS_WEIGHT - загальна маса товара з врахуванням пакування, ящика.
Повний перелік показників можна побачити на відповідній сторінці каталогу

    - - measurementValue

1..1

MeasurementType

Безпосереднє значення ваги та одиниці вимірювання. Наприклад, вагу можна задати в кілограмах, грамах тощо.
Таб. 6. Атрибути типу AdditionalTradeItemIdentificationType
Атрибут Режим Формат Опис

additionalTradeItemIdentificationTypeCode

1..1

xsd:string (80)

Код додаткової ідентифікації товару. Перелік кодів можна переглянути на офіційному сайті GS1 XML.

codeListVersion

0..1

xsd:string (35)

Версія списку типів додаткової ідентифікації товарів. Зазвичай не використовується

Ідентифікація товару

Інколи товари не мають штрихкоду або ж цей штрихкод не відповідає формату GTIN. У такому випадку використовують елемент additionalTradeItemIdentification, який дозволяє задати необмежену кількість додаткових ідентифікацій для будь-якого товара.

Варто звернути увагу на такі коди додаткової ідентифікації товарів:

  • BUYER_ASSIGNED - ідентифікатор, який назначений покупцем.

  • SUPPLIER_ASSIGNED - ідентифікатор, який назначений постачальником.

  • FOR_INTERNAL_USE_1 - цей код має 20 варіантів: від 1 до 20. За домовленістю сторін кожен з них може характеризувати будь-який ідентифікатор, наприклад, артикул.

  • GTIN_8 - GS1 штрихкод з 8 символів.

  • GTIN_12 - GS1 штрихкод з 12 символів.

  • GTIN_13 - GS1 штрихкод з 13 символів.

  • GTIN_14 - GS1 штрихкод з 14 символів.

  • DISTRIBUTOR_ASSIGNED - ідентифікатор, який присвоєний дистриб’ютором.

  • MANUFACTURER_PART_NUMBER - парт-номер, що присвоєно виробником

  • MODEL_NUMBER - номер моделі. Зазвичай використовується як додаткова ідентифікація, що позначає варіацію товару.

Код назначений постачальником
<additionalTradeItemIdentification
    additionalTradeItemIdentificationTypeCode="SUPPLIER_ASSIGNED">
    00123456
</additionalTradeItemIdentification>
За домовленістю сторін сприймається, як Артикул
<additionalTradeItemIdentification
    additionalTradeItemIdentificationTypeCode="FOR_INTERNAL_USE_1">
    АФК-2345
</additionalTradeItemIdentification>

Приклади опису товару

Приклад для елемента transactionalTradeItem з вказанням ваги товару
<transactionalTradeItem>
    <gtin>04820000538169</gtin>
    <tradeItemDescription languageCode="uk">Дриль-шурупокрут акумуляторний RZTK RD 1220Li</tradeItemDescription>
    <transactionalItemData>
        <transactionalItemWeight>
            <!-- Вага товару без упаковки -->
            <measurementType>DECLARED_NET_WEIGHT</measurementType>
            <measurementValue measurementUnitCode="KGM">1.5</measurementValue>
        </transactionalItemWeight>
    </transactionalItemData>
</transactionalTradeItem>

AmountType

GS1 XML тип: shared_common:AmountType

Цей тип використовується для опису сумм в грошових одиницях. Елементи XML з цим типом повинні містити значення xsd:float. Для десяткового розділювача використовується крапка.

Таб. 7. Атрибути для AmountType
Атрибут Режим Формат Опис

currencyCode

1..1

xsd:string (80)

Назва/код валюти. Повинен слідувати формату для кодів валют ISO 4217

codeListVersion

0..1

xsd:string (35)

Версія списку кодів валют для вказаної валюти. Зазвичай не використовується.

Зверніть увагу, що даний тип обов’язково вимагає вказати валюту.

Сума в гривнях
<netAmount currencyCode="UAH">400</netAmount>

QuantityType

GS1 XML тип: shared_common:QuantityType

Використовується для опису кількості товарів або інших елементів.

Елементи XML, які мають це тип, повинні містити xsd:decimal значення. При потребі для десяткового розділювача використовується крапка.

Таб. 8. Атрибути для QuantityType
Атрибут Режим Формат Опис

measurementUnitCode

0..1

xsd:string (80)

Назва/код одиниці вимірювання.

codeListVersion

0..1

xsd:string (35)

Версія списку кодів одиниці вимірювання для вказаного значення одиниці. Зазвичай не використовується.

Зазвичай вказання одиниць не є обов’язковим - в такому випадку використовується стандартна одиниця закріплена за товаром.

Вказання кількості
<tradeItemQuantity>30</tradeItemQuantity>

Також цей тип дозволяє вказати одиницю вимірювання через використання атрибута measurementUnitCode - однак сторони повинні про це домовитися заздалегідь.

Вказання кількості та одиниці вимірювання
<confirmedQuantity measurementUnitCode="KGM">1.5</confirmedQuantity>

У Європі діє UN/ECE стандарт #20 щодо використання назв одиниць вимірювання, які повністю підтримуються GS1 стандартом.

Детально з переліком доступних пакувань можна ознайомитися на сторінці документації Типи пакування GS1. Ось найпоширеніші з них:

  • EA - одиниця товару; все то, що в торгівлі зазвичай позначається, як шт; зазвичай це запакований товар.

  • NE - не запаковано, окрема одиниця товару: яблуко, окуляри, кастрюля тощо. Може розглядатися як шт, взаємозамінне з EA.

  • BO - пляшка: вино, горілка, пиво, йогурт, шампунь

  • BX - коробка, упаковка; може містити великогабаритні вантажі > 300 кг

  • CR - ящик (з верхом або без); зазвичай для будь-чого

  • LTR - літр

  • GRM - грам

  • KGM - кілограм

  • MTR - метр

  • MTQ - кубічний метр

Хоча стандарт GS1 дозволяє дуже точно вказувати будь-які варіанти пакувань, проте це може суттєво ускладнювати обмін на парсинг повідомлень.

Зазвичай компанії домовляються використовувати лише базові одиниці, щоб спростити роботу з повідомленнями: EA, KGM тощо.

DateOptionalTime

GS1 XML тип: shared_common:DateOptionalTimeType

Вказує дату та час. Час не є обов’язковим.

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

date

1..1

xs:date

Дата. Приклад: 2022-06-15

time

0..1

xs:time

Час протягом доби. Приклад: 11:00:00

 
<latestDeliveryDate>
    <date>2023-05-11</date>
</latestDeliveryDate>

GTINType

GS1 XML тип: shared_common:GTINType

Визначає штрихкод, який складається з 14 символів: 40987650000223.

AttributeValuePairListType

GS1 XML тип: ecom_common:Ecom_AttributeValuePairListType

Використовується для передачі не стандартизованої інформації та властивостей у повідомленнях. За допомогою цього типу відправник може передати будь-які додаткові дані, які вважає за необхідне, гарантуючи валідність XML.

Таб. 9. Елементи для типу Ecom_AttributeValuePairListType
Елемент Режим Формат Опис

eComStringAttributeValuePairList

0..*

EcomStringAttributeValuePairListType

Дозволяє вказати довільне значення у вигляді КЛЮЧ=ЗНАЧЕННЯ
Таб. 10. Атрибути для елемента eComStringAttributeValuePairList
Атрибут Режим Формат Опис

attributeName

1..1

xsd:string (70)

Назва властивості для передачі довільної інформації.
Ця назва виступає ключем, а безпосереднє значення елемента буде вважатися значенням, цього ключа.
Тобто таким чином можна передати дані типу: КЛЮЧ=ЗНАЧЕННЯ, де значення цього атрибута виступає у ролі КЛЮЧ.

qualifierCodeList

0..1

xsd:string (70)

Вказує на назву/тип списка довільних властивостей, які можуть додатково зазначатися для переданих даних. Див. приклади використання.

qualifierCodeName

0..1

xsd:string (70)

Зазвичай використовується в комбінації з атрибутом qualifierCodeList і задає безпосереднє значення з вказаного там списку.

Дозволяє вказувати довільні властивості для додаткових не стандартизованих даних. Див. приклади використання.

Відправник та Отримувач попередньо повинні узгодити інтерпретацію ключів та значення даних, які будуть передаватися таким чином.

Передача простих даних у вигляді ключ=значення

Наприклад, постачальник у відповіді на замовлення бажає вказати відповідальну особу, яка створювала це замовлення та її ідентифікатор у базі постачальника. Ось так це може виглядати:

У прикладах avpList має тип Ecom_AttributeValuePairListType

<avpList>
    <eComStringAttributeValuePairList attributeName="EMP_NAME">
        Петренко І.П.
    </eComStringAttributeValuePairList>
    <eComStringAttributeValuePairList attributeName="EMP_ID">
        00000234
    </eComStringAttributeValuePairList>
</avpList>

Попередньо відправник і постачальник узгоджують найменування атрибутів EMP_NAME та EMP_ID.

Передача даних з додатковими характеристиками

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

Для реалізації такого сценарію можна використати комбінацію qualifierCodeList та qualifierCodeName, де можна зазначити валюту:

  • qualifierCodeList - вказує на тип списка CurrencyCode. Назва списка може бути будь-якою з тих, що використовуються у стандарті GS1, GDSN. Зазвичай використання цих списків узгоджується між відправником та отримувачем.

  • qualifierCodeName - вказує на значення з цього списка: UAH, USD, EUR тощо.

В результаті отримуємо наступний блок:

<avpList>
    <eComStringAttributeValuePairList attributeName="BONUS" qualifierCodeList="CurrencyCode" qualifierCodeName="UAH">
        100.0
    </eComStringAttributeValuePairList>
    <eComStringAttributeValuePairList attributeName="BONUS" qualifierCodeList="CurrencyCode" qualifierCodeName="EUR">
        5.0
    </eComStringAttributeValuePairList>
</avpList>

Тут зазначається, що передається інформація BONUS, і для кожного з бонусів передано додаткові дані щодо валюти.

Також відправник і отримувач можуть узгодити між собою використання нестандартних списків, якщо в цьому є потреба.

Зверніть увагу, що цю інформацію по бонусах можна передати іншим способом: з використанням змінених назв атрибутів - BONUS_UAH, BONUS_EUR.

<avpList>
    <eComStringAttributeValuePairList attributeName="BONUS_UAH">
        100.0
    </eComStringAttributeValuePairList>
    <eComStringAttributeValuePairList attributeName="BONUS_EUR">
        5.0
    </eComStringAttributeValuePairList>
</avpList>

Однак цей спосіб призводить до того, що потрібно буде постійно збільшувати кількість найменувань атрибутів при додаванні нових валют, а при імпорті "різати" ці значення, щоб визначити валюту.

Ще один приклад використання qualifierCodeList - це відображення літражу NET_CONTENT товара. Для певних товарів зручно показати у літрах, а для інших - у мілілітрах.

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

Приклад використання для літрів та мілілітрів
<avpList>
    <!--  Містить 6 літрів  -->
    <eComStringAttributeValuePairList attributeName="NET_CONTENT" qualifierCodeList="MeasurementUnitCode" qualifierCodeName="LTR">
        6
    </eComStringAttributeValuePairList>

    <!--  Містить 350 мілілітрів  -->
    <eComStringAttributeValuePairList attributeName="NET_CONTENT" qualifierCodeList="MeasurementUnitCode" qualifierCodeName="MLT">
        350
    </eComStringAttributeValuePairList>
</avpList>