Data Structure

JSON is used as the data structure for the exchange. A JSON object represents a product.

The order contains:

  • transaction data

  • the address (delivery address, billing address and premium address)

  • order data for the order

  • payment information

  • order items for books/articles or subscriptions with premiums

Field definition

object: order

Name

Description

Article / Title

Subscription

transaction

REQUIRED

OBJECT

Object transaction

x

x

order_number

REQUIRED

STRING [1..11]

Unique ID for avoiding duplicates in webshop (order number for the client confirmation and invoice)

x

x

order_id_unique

REQUIRED

STRING [1..32]

Unique system ID of request, in Magento internal order_id (i.c. NOT the order number)

x

x

order_date

REQUIRED

STRING

Date of order

x

x

order_country_code

STRING

Country code order as ISO2 code

x

x

total_amount

REQUIRED

NUMBER {0.01..}

Total amount of order in gross rate

x

x

currency

REQUIRED

STRING {0..3} 

Currency code

x

x

gift_card_code

STRING {0..40} 

Gift card code

x

-

gift_card_value

NUMBER {0.01..}

Amount of gift card

x

-

shipping_code_ext

STRING {0..20} 

Ext. code of shipping surgery, for mapping in COVER

x

-

shipping_amount

NUMBER {0.01..} 

Amount of shipping. If total_amount_net > 0: net value, else gross value

x

-

addresses

REQUIRED

OBJECT ADDRESSES

Object with adresses for billing. shipping, gift

x

x

orderpositions

REQUIRED

ARRAY ORDERPOSITION

Array of order positions for order a book/aticle or order a subscription

x

x

payment

REQUIRED

OBJECT PAYMENT

Payment information

x

x

object: transaction

Name

Description

Article / Title

Subscription

timestamp

REQUIRED

STRING

Current timestamp on creation of JSON file

x

x

transaction_id

REQUIRED

STRING (1..20)

The same Unique transaction-ID of registration by calling system

x

x

ext_system_type

REQUIRED

STRING ENUM {WEBSHOP, COVER, ERP)

Type external system

x

x

ext_system_id

REQUIRED

STRING

Unique ID from external system

x

x

ext_system_name

REQUIRED

STRING

Name from external system

x

x

webshop_id
REQUIRED

STRING [1..12]

ID of webshop

x

x

webshop_name

STRING

Name of webshop

x

x

erp_owner

REQUIRED

STRING [1..20]

Owner of COVER-Transfer

x

x

erp_system_id

REQUIRED

STRING [1..12]

ID of COVER-Transfer

x

x

 object: adresses

Name

Description

Article / Title

Subscription

billing

REQUIRED

OBJECT ADDRESS

Billing address

x

x

shipping

OBJECT ADDRESS

Shipping address

x

x

gift

OBJECT ADDRESS

Gift address

x

object: address

Name

Description

Article / Title

Subscription

timestamp

REQUIRED

STRING

Current timestamp on creation of JSON file

x

x

ext_system_id

REQUIRED

STRING

Unique ID from external system

x

x

ext_customer_nr

REQUIRED

STRING

Unique customer ID in the external system

x

x

ext_customer_sub_nr

STRING

Unique key for sub-address number in external system

x

x

erp_system_id

REQUIRED

STRING (12)

ID of COVER-Transfer

x

x

erp_customer_nr

STRING (9)

ERP/COVER address number

x

x

erp_customer_sub_nr

STRING (3)

ERP address number / COVER person_nr

x

x

salutation_code

STRING (..40)

Salutation-Code

x

x

title_code

STRING (..40)

Title-Code

x

x

firstname

REQUIRED

STRING (..20)

Firstname

x

x

lastname

REQUIRED

STRING (..30)

Lastname

x

x

company

STRING (..135)

Company

x

x

street

STRING (..46)

Street and housenumber

x

x

street2

STRING (..46)

Address suffix such as Stiege, Stock, Tür no.

x

x

postcode

STRING (1..3)

Postcode

x

x

city

REQUIRED

STRING (1..40)

City

x

x

country_code

STRING (1..3)

Country code as ISO2 code

x

x

vat_number

STRING (..15)

Sales tax number

x

x

email

REQUIRED

STRING (1..100)

E-Mail

x

x

phone

STRING (..60)

Phone

x

x

mobile

STRING (..60)

Mobile

x

x

optin_general

STRING

Advertising permission / optin general. Apply T (true) only.

x

x

address_change_status

STRING ENUM {clean,in_process)

Processing status of the address in the transfer

x

x

object: orderposition

Case 1: Ordering a article / title

Name

Description

Article / Title

type

REQUIRED

STRING {string="B"}

Type of order item:

  • B - Book

  • A - Abonnement (subscription)

x

quantity

REQUIRED

NUMBER {1..9999}

Count of items

x

price

REQUIRED

NUMBER {0.00..}

Price of one item (including tax)

x

discount_percent

NUMBER {0.00..100}

Discount percent

x

discount_type

STRING {0..6}

Discount type

x

sku

REQUIRED

STRING 

Sku in webshop

x

erp_sku

REQUIRED

NUMBER

Issue ID

x

erp_subsku

REQUIRED

NUMBER

Edition number

x

erp_sku_series

NUMBER

Issue ID

x

start_date 

STRING {dd.MM.yyyy}

Startdate for startarticle Standing Order

x

is_reserved

BOOLEAN 

Reservation for this orderposition/itim

x

custom_text

STRING 

Personalized text

x

Case 2: Ordering a Subscription (Abonnement)

Name

Description

Subscription

type

REQUIRED

STRING {string="A"}

Type of order item:

  • B - Book

  • A - Abonnement (subscription)

x

quantity

REQUIRED

NUMBER {1..9999}

Count of items

x

campaign_code

REQUIRED

STRING {..12}

Cover campaign ID

x

campaign_subcode

REQUIRED

STRING {..4}

Cover subcampaign ID

x

campaign_offer_number

REQUIRED

NUMBER {1..9999}

Current number ID

x

abo_typ

REQUIRED

STRING ENUM  {EA, GA, LWL}

Typ of subscription: EA (Subscription  for billing person), GA (Subscription as gift), LWL (Subscription  for billing person and promotion for promoting person)

x

promotions

OPTIONAL

OBJECT PROMOTION

Promotion Articles

x

free_magazines

OPTIONAL

OBJECT FREE_MAGAZIN

Free magazin

x

edition_id 

REQUIRED

STRING {..2}

Edition ID, such as regional edition

x

object_id 

REQUIRED

STRING {..3}

Object ID. ID of the magazin

x

send_first_magazine_to_billing 

OPTIONAL

BOOLEAN {true, false}

Send first magazine to billing address. Available with abo_typ=GA only.

x

price

REQUIRED

NUMBER {0.00..}

Price of one item (including tax)

x

start_date 

REQUIRED

STRING {dd.MM.yyyy}

Date of order

x

subscription_ext_id

OPTIONAL

STRING {..12}

External Subscription ID (unique subcription ID)

x

object: promotion

Name

Description

Article / Title

Subscription

sku
REQUIRED

STRING

Sku of the choosen promotion object

-

x

bonus_erp_sku

REQUIRED

STRING {..20}

COVER edition/variant to the selected premium

-

x

bonus_erp_subsku

REQUIRED

STRING {..9}

COVER article no. of the 1st premium

-

x

add_payment

NUMBER

Additional payment. In use with promotions

-

x

is_paid

BOOLEAN

True if the price of the subscription includes the additional payment of promotion

-

x

custom_text

STRING 

Personalized text

-

x

object: free magazin

Name

Description

Article / Title

Subscription

sku

REQUIRED

STRING

Sku of the choosen free magazin.

-

x

campaign_code

REQUIRED

STRING 

Marketing campaign code which represent the campaign

-

x

campaign_subcode

REQUIRED

STRING

2nd part of campaign code if campaign is multidimensional

-

x

campaign_offer_number

REQUIRED

STRING 

Key field of subscription template of erp system

-

x

object: payment

Case 1: PAYONE Paypal

Name

Description

Article / Title

Subscription

payment_provider

REQUIRED

STRING ENUM {PAYONE} 

Name of payment provider

x

x

payment_type_ext

REQUIRED

STRING ENUM { "PAYONE_P"} 

Payment type

x

x

transaction_code

REQUIRED

STRING [1..50]

Payment external code for transaction

x

x

transaction_date

STRING {dd.MM.yyyy}  

Invoice date

x

x

currency

REQUIRED

STRING {0..3} 

Currency code

x

x

user_id

REQUIRED

STRING {..20}

User_id of Paypal provided by Payone

x

x

Case 2: PAYONE Credit Card

Name

Description

Article / Title

Subscription

payment_provider

REQUIRED

STRING ENUM {PAYONE} 

x

x

payment_type_ext

REQUIRED

STRING ENUM {"PAYONE_K", ...} 

Payment type

x

x

transaction_code

REQUIRED

STRING [1..50]

Payment external code for transaction

x

x

transaction_date

STRING {dd.MM.yyyy}  

Invoice date

x

x

currency

REQUIRED

STRING {0..3} 

Currency code

x

x

cc_number

STRING {..20}

Pseudo Credit card number

x

x

cc_month

STRING {1..12}

Credit card expired month

x

x

cc_year

STRING {2000..9999}

Credit card expired year

x

x

user_id

STRING {..20}

User_id of Paypal

?

?

Case 3: Direct debit

Name

Description

Article / Title

Subscription

payment_provider

REQUIRED

STRING ENUM {ERP} 

Name of payment provider

x

x

payment_type_ext

REQUIRED

STRING ENUM {"C"}

Payment types

C=Direct debit

x

x

currency

REQUIRED

STRING {1..3} 

Currency code

x

x

account_owner

REQUIRED

STRING {1..27}

Name of account holder

x

x

iban

REQUIRED

STRING {1..40}

IBAN

x

x

bic

STRING  {1..20} 

Bank Identifier Code

x

x

transaction_date

STRING {dd.MM.yyyy}  

Invoice date

x

x

sepa_mandate_granted

BOOLEAN  {true, false}

SEPA mandate granted

x

x

Case 4: invoice

Name

Description

Article / Title

Subscription

payment_provider

REQUIRED

STRING ENUM {ERP} 

Empty, no payment provider exists

x

x

payment_type_ext

REQUIRED

STRING ENUM {"F"} 

Payment types

  • F=Bill

x

x

currency

REQUIRED

STRING {1..3} 

Currency code

x

x

transaction_date

STRING {dd.MM.yyyy}

Invoice date

x

x

Request

Request syntax

POST /cover/wrd/ecorder
Host: cover-url

Body
CODE


For example:

POST https://covernet.de:8081/cover/wrd/ecorder
CODE

Request header

Field definition

Name

Description

Tomcat  user
OPTIONAL

STRING

Depends from the server configuration

Tomcat password
OPTIONAL

STRING

Depends from the server configuration

C_BENUTZER_ID
REQUIRED

STRING

User Name for Webservice

C_PASSWORT
REQUIRED

STRING

User Password for Webservice

C_TRANSFER_ID
REQUIRED

STRING

Transfer ID in cover to be used for transfer (this must be unique in cover)

C_MANDANT
REQUIRED

STRING

Cover client from which the data should be retrieved

C_ANW
REQUIRED

STRING

Cover application (address range) from which the data should be retrieved

C_KUNDE
REQUIRED

STRING

Client code of the cover client

Request Body

JSON-Object

{
	"order": {
		"transaction": {
			"timestamp": "20180303091235",
			"transaction_id": "PUBL00000555011",
			"ext_system_type": "WEBSHOP",
			"ext_system_id": "magento2.prod.cover-ecom.de",
			"ext_system_name": "Magento-2-COVER-Web-Shop.de",
			"webshop_id": "main_bas",
			"webshop_name": "main-base-site",
			"erp_owner": "IMS",
			"erp_system_id": "COVERNET2"
		},
		"order_number": "1400004617",
		"order_id_unique": "589783",
		"order_date": "16.03.2017",
		"total_amount": 34.98,
		"currency": "EUR",
		"gift_card_code": "097z36gfte643",
		"gift_card_value": 10.00,
		"shipping_code_ext": "VERS_KOST",
		"shipping_amount": "3.50",
		"addresses": {
			"billing": {
				"timestamp": "20180303091235",
				"ext_system_id": "magento2.prod.cover-ecom.de",
				"ext_customer_nr": "ADR1234",
				"ext_customer_sub_nr": "AB12",
				"erp_system_id": "COVERNET2",
				"erp_customer_nr": "123456789",
				"erp_customer_sub_nr": "002",
				"salutation_code": "Herr",
				"title_code": "Dr.",
				"firstname": "Thomas",
				"lastname": "Müller",
				"company": "COVER",
				"country_code": "DE",
				"street": "Calwer Str. 1",
				"street2": "Stiege 5",
				"postcode": "71034",
				"city": "Böblingen",
				"vat_number": "DE1234987552957",
				"email": "thms.mueller@gmail.com",
				"phone": "+4917537656789"
			},
			"shipping": {
				"salutation_code": "Frau",
				"firstname": "Sabine",
				"lastname": "Müller",
				"country_code": "DE",
				"street": "Calwer Str. 1",
				"postcode": "71034",
				"city": "Böblingen"
			}
		},
		"orderpositions": [{
				"type": "B",
				"quantity": 1,
				"sku": "BU-45693-0-01-IMS"
				"erp_sku": 45693,
				"erp_subsku": 0,
				"price": 15.99
			}, {
				"type": "B",
				"quantity": 3,
				"sku": "BU-47773-0-01-IMS"
				"erp_sku": 47773,
				"erp_subsku": 0,
				"price": 18.99
			}, {
				"type": "A",
				"quantity": 1,
				"campaign_code": "WEBSHOP",
				"campaign_subcode": 11,
				"campaign_offer_number": 23,
				"abo_typ": "EA",
				"promotions": [
				{
					"sku": "BU-1234213-0-01-IMS",
					"bonus_erp_sku": 12345,
					"bonus_erp_subsku": 0,
					"add_payment": 20.00,
					"is_paid": true
				}
				],
				"free_magazin": [
				{
					"sku": "VZ-WEBSHOP-01-3-01-IMS",
					"campaign_code": "WEBSHOP",
					"campaign_subcode": 01,
					"campaign_offer_number": 3,
				}
				],
				"object_id ": "PC",
				"edition_id ": "-",
				"send_first_magazine_to_billing ": false,
				"price": 18.99,
				"start_date ": "22.03.2019",
				"subscription_ext_id": "ADER4325",
			}
		],
		"payment": {
			"payment_provider": "PAYONE",
			"payment_type_ext": "PAYONE_P",
			"transaction_code": "AF78C561DF67FA12",
			"transaction_date": "27.03.2017",
			"currency": "EUR",
			"user_id": "ABC2345723bged",
			"cc_number": "123456fmdurt345",
			"cc_month": "12",
			"cc_year": "2023",
			"iban": "DE04641500000345030299",
			"bic": "SOLADES1TUB",
			"user_id": "ABC2345723bged",
		}
	}
}
JSON

Examples

Subscription EA + Promotion + free Magazine

{
	"order": {
		"transaction": {
			"timestamp": "20180303091235",
			"transaction_id": "PUBL00000555011",
			"ext_system_type": "WEBSHOP",
			"ext_system_id": "magento2.prod.cover-ecom.de",
			"ext_system_name": "Magento-2-COVER-Web-Shop.de",
			"webshop_id": "main_bas",
			"webshop_name": "main-base-site",
			"erp_owner": "IMS",
			"erp_system_id": "COVERNET2"
		},
		"order_number": "1400004617",
		"order_id_unique": "589783",
		"order_date": "16.03.2017",
		"total_amount": 34.98,
		"currency": "EUR",
		"addresses": {
			"billing": {
				"timestamp": "20180303091235",
				"ext_system_id": "magento2.prod.cover-ecom.de",
				"ext_customer_nr": "ADR1234",
				"ext_customer_sub_nr": "AB12",
				"erp_system_id": "COVERNET2",
				"erp_customer_nr": "123456789",
				"erp_customer_sub_nr": "002",
				"salutation_code": "Herr",
				"title_code": "Dr.",
				"firstname": "Thomas",
				"lastname": "Müller",
				"company": "COVER",
				"country_code": "DE",
				"street": "Calwer Str. 1",
				"street2": "Stiege 5",
				"postcode": "71034",
				"city": "Böblingen",
				"vat_number": "DE1234987552957",
				"email": "thms.mueller@gmail.com",
				"phone": "+4917537656789"
			},
		"orderpositions": [{
				"type": "A",
				"quantity": 1,
				"campaign_code": "WEBSHOP",
				"campaign_subcode": 11,
				"campaign_offer_number": 23,
				"abo_typ": "EA",
				"promotions": [
				{
					"sku": "BU-1234213-0-01-IMS",
					"bonus_erp_sku": 12345,
					"bonus_erp_subsku": 0,
					"add_payment": 0.00
				}
				],
				"free_magazin": [
				{
					"sku": "VZ-WEBSHOP-01-3-01-IMS",
					"campaign_code": "WEBSHOP",
					"campaign_subcode": 01,
					"campaign_offer_number": 3,
				}
				],
				"object_id ": "PC",
				"edition_id ": "-",
				"price": 18.99,
				"start_date ": "22.03.2019",
				"subscription_ext_id": "ADER4325",
			}
		],
		"payment": {
			"payment_provider": "PAYONE",
			"payment_type_ext": "PAYONE_P",
			"transaction_code": "AF78C561DF67FA12",
			"transaction_date": "27.03.2017",
			"currency": "EUR",
			"user_id": "ABC2345723bged",
			"cc_number": "123456fmdurt345",
			"cc_month": "12",
			"cc_year": "2023",
			"iban": "DE04641500000345030299",
			"bic": "SOLADES1TUB",
			"user_id": "ABC2345723bged",
		}
	}
}
CODE

Subscription LWL

{
	"order": {
		"transaction": {
			"timestamp": "20180303091235",
			"transaction_id": "PUBL00000555011",
			"ext_system_type": "WEBSHOP",
			"ext_system_id": "magento2.prod.cover-ecom.de",
			"ext_system_name": "Magento-2-COVER-Web-Shop.de",
			"webshop_id": "main_bas",
			"webshop_name": "main-base-site",
			"erp_owner": "IMS",
			"erp_system_id": "COVERNET2"
		},
		"order_number": "1400004617",
		"order_id_unique": "589783",
		"order_date": "16.03.2017",
		"total_amount": 34.98,
		"currency": "EUR",
		"addresses": {
			"billing": {
				"timestamp": "20180303091235",
				"ext_system_id": "magento2.prod.cover-ecom.de",
				"ext_customer_nr": "ADR1234",
				"ext_customer_sub_nr": "AB12",
				"erp_system_id": "COVERNET2",
				"erp_customer_nr": "123456789",
				"erp_customer_sub_nr": "002",
				"salutation_code": "Herr",
				"title_code": "Dr.",
				"firstname": "Thomas",
				"lastname": "Müller",
				"company": "COVER",
				"country_code": "DE",
				"street": "Calwer Str. 1",
				"street2": "Stiege 5",
				"postcode": "71034",
				"city": "Böblingen",
				"vat_number": "DE1234987552957",
				"email": "thms.mueller@gmail.com",
				"phone": "+4917537656789"
			},
		"orderpositions": [{
				"type": "A",
				"quantity": 1,
				"campaign_code": "WEBSHOP",
				"campaign_subcode": 11,
				"campaign_offer_number": 23,
				"abo_typ": "EA",
				"promotions": [
				{
					"sku": "BU-1234213-0-01-IMS",
					"bonus_erp_sku": 12345,
					"bonus_erp_subsku": 0,
					"add_payment": 0.00
				}
				],
				"free_magazin": [
				{
					"sku": "VZ-WEBSHOP-01-3-01-IMS",
					"campaign_code": "WEBSHOP",
					"campaign_subcode": 01,
					"campaign_offer_number": 3,
				}
				],
				"object_id ": "PC",
				"edition_id ": "-",
				"price": 18.99,
				"start_date ": "22.03.2019",
				"subscription_ext_id": "ADER4325",
			}
		],
		"payment": {
			"payment_provider": "PAYONE",
			"payment_type_ext": "PAYONE_P",
			"transaction_code": "AF78C561DF67FA12",
			"transaction_date": "27.03.2017",
			"currency": "EUR",
			"user_id": "ABC2345723bged",
			"cc_number": "123456fmdurt345",
			"cc_month": "12",
			"cc_year": "2023",
			"iban": "DE04641500000345030299",
			"bic": "SOLADES1TUB",
			"user_id": "ABC2345723bged",
		}
	}
}
CODE

Mixed Shopping Card

{                     
	"order": {
		"transaction": {
			"timestamp": "20180303091235",
			"transaction_id": "PUBL00000555011",
			"ext_system_type": "WEBSHOP",
			"ext_system_id": "magento2.prod.cover-ecom.de",
			"ext_system_name": "Magento-2-COVER-Web-Shop.de",
			"webshop_id": "main_bas",
			"webshop_name": "main-base-site",
			"erp_owner": "IMS",
			"erp_system_id": "COVERNET2"
		},
		"order_number": "1400004617",
		"order_id_unique": "589783",
		"order_date": "16.03.2017",
		"total_amount": 34.98,
		"currency": "EUR",
		"addresses": {
			"billing": {
				"timestamp": "20180303091235",
				"ext_system_id": "magento2.prod.cover-ecom.de",
				"ext_customer_nr": "ADR1234",
				"ext_customer_sub_nr": "AB12",
				"erp_system_id": "COVERNET2",
				"erp_customer_nr": "123456789",
				"erp_customer_sub_nr": "002",
				"salutation_code": "Herr",
				"title_code": "Dr.",
				"firstname": "Thomas",
				"lastname": "Müller",
				"company": "COVER",
				"country_code": "DE",
				"street": "Calwer Str. 1",
				"street2": "Stiege 5",
				"postcode": "71034",
				"city": "Böblingen",
				"vat_number": "DE1234987552957",
				"email": "thms.mueller@gmail.com",
				"phone": "+4917537656789"
			},
			"gift": {
				"salutation_code": "Frau",
				"firstname": "Sabine",
				"lastname": "Müller",
				"country_code": "DE",
				"street": "Calwer Str. 1",
				"postcode": "71034",
				"city": "Böblingen"
			}
		},
		"orderpositions": [{
				"type": "A",
				"quantity": 1,
				"campaign_code": "WEBSHOP",
				"campaign_subcode": 11,
				"campaign_offer_number": 23,
				"abo_typ": "LWL",
				"object_id ": "PC",
				"edition_id ": "-",
				"price": 18.99,
				"start_date ": "22.03.2019",
				"subscription_ext_id": "ADER4325",
			}
		],
		"payment": {
			"payment_provider": "PAYONE",
			"payment_type_ext": "PAYONE_P",
			"transaction_code": "AF78C561DF67FA12",
			"transaction_date": "27.03.2017",
			"currency": "EUR",
			"user_id": "ABC2345723bged",
			"cc_number": "123456fmdurt345",
			"cc_month": "12",
			"cc_year": "2023",
			"iban": "DE04641500000345030299",
			"bic": "SOLADES1TUB",
			"user_id": "ABC2345723bged",
		}
	}
}
CODE