Messages from KonaKart to ERP

Messages from KonaKart to ERP
Prev	Chapter 21. KonaKart ERP Integration	Next

Export Customer to ERP

KonaKart to ERP.

This message is sent by KonaKart whenever a customer registers using the online store. It contains a unique numeric customer id generated by KonaKart (kkCustomerId). It is also sent whenever a customer modifies any information such as his primary address.


<exportCustomer>
    <storeId>store1</storeId>
    <time>16:50:07 26022015</time>
    <version>1.0</version>
    <body>
        <kkCustomerId>44</kkCustomerId>
        <customerId>ERP007</customerId>
        <kkCustomerGroupId>34</kkCustomerGroupId>
        <type>INSERT</type>
        <gender>m</gender>
        <firstName>Peter</firstName>
        <lastName>Smith</lastName>
        <company>ACME Inc</company>
        <address1>Rose Cottage</address1>
        <address2>32 High Street</address2>
        <address3>MayBank</address3>
        <city>Newcastle</city>
        <state>Staffordshire</state>
        <postcode>ST5 ORT</postcode>
        <ISO3CountryCode>GBR</ISO3CountryCode>
        <ISONumericCountryCode>123</ISONumericCountryCode>
        <telephone1>01782765334</telephone1>
        <telephone2>335624599</telephone2>
        <email>peter.smith@acme.com</email>
        <locale>en_GB</locale>
        <dateOfBirth>03032015</dateOfBirth>
        <fax>01782765335</fax>
        <taxEntity>taxEntity</taxEntity>
        <taxExemption>taxExemption</taxExemption>
        <taxIdentifier>taxIdentifier</taxIdentifier>
        <custom1>custom1</custom1>
        <custom2>custom2</custom2>
        <custom3>custom3</custom3>
        <custom4>custom4</custom4>
        <custom5>custom5</custom5>
    </body>
</exportCustomer>

Mandatory Attributes

kkCustomerId	This attribute should contains a unique numeric identifier for the customer. It is generated by KonaKart when the customer registers.
type	Valid values are INSERT and UPDATE depending on whether it is a new customer or an existing customer with modified information such as an updated address.
firstName	The customer's first name.
lastName	The customer's last name.
address1	The first line of the street address.
city	The customer's city
state	The customer's state. If a list of valid states exists in the KonaKart database for the customer's country then this attribute must contain either the numeric KonaKart id of one of the states or the state code (e.g. ZH) or the state name (e.g. Zürich). If a list of states is not present in the database then it may take any value.
postcode	The customer's postcode.
ISO3countryCode or ISONumericCountryCode	Either the 3 letter ISO country code or the ISO numeric country code should be present.
email	The email address of the customer.

Optional Attributes

time	Time message was created in format HH:mm:ss ddMMyyyy
version	The version of the interface being used
storeId	The id of the KonaKart virtual store
customerId	This attribute should contain the unique identifier used by the ERP system to identify the customer. Once the customer has been registered, KonaKart will send a message back to the ERP which will contain the customer details, the KKCustomerId and this customerId. In this way, the ERP system will be able to associate the KKCustomerId with its internal customerId.
kkCustomerGroupId	If the customer should belong to a KonaKart group, this should contain the numeric KonaKart group id.
gender	This should contain "M", "F" or "X" which stand for male, female and other.
company	The customer's company.
address2	The second line of the street address.
address3	The third line of the street address.
telephone1	The customer's primary telephone number.
telephone2	The customer's other telephone number.
locale	The customer's locale in the format en_GB.
dateOfBirth	The customer's date of birth in the format ddMMyyyy.
fax	The customer's fax number.
taxEntity	Tax entity information for the customer.
taxExemption	Tax exemption information for the customer.
taxIdentifier	Tax identifier for the customer.
custom1-custom5	Custom attributes that may contain any custom data to be saved in the KonaKart database with the customer.

Match Customer to ERP

KonaKart to ERP.

The purpose of this message is for KonaKart to inform the ERP system of the KonaKart customer identifier generated when a customer is exported from the ERP system and registered in KonaKart.


<matchCustomer>
    <storeId>store1</storeId>
    <time>16:50:07 26022015</time>
    <version>1.0</version>
    <body>
        <customerId>ERP007</customerId>
        <kkCustomerId>44</kkCustomerId>
    </body>
</matchCustomer>

Mandatory Attributes

customerId	This attribute should contain the unique identifier used by the ERP system to identify the customer.
kkCustomerId	This attribute should contains a unique numeric identifier for the customer. It is generated by KonaKart when the customer registers.

Optional Attributes

time	Time message was created in format HH:mm:ss ddMMyyyy
version	The version of the interface being used
storeId	The id of the KonaKart virtual store

Order Export to ERP

KonaKart to ERP.

This message is sent by KonaKart whenever an order is placed on on the online store.

This is a large message so in the following pages it is split up for readability with comments on the Mandatory and Optional fields inserted at appropriate points. Each of the following message parts can be combined to form one single orderExport message.


<orderExport>
    <time>15:27:53 03032015</time>
    <version>1.0</version>
    <storeId>store1</storeId>
    <body>
        <kkOrderId>55</kkOrderId>
        <orderNumber>32634/2015</orderNumber>
        <kkLifecycleId>c53a3c97-b3b4-443d-9dcc-cdcfc9d06214</kkLifecycleId>
        <orderState>7</orderState>
        <creationDate>16:19:46 03032015</creationDate>
        <kkCustomerId>67</kkCustomerId>
        <customerId>W0000067</customerId>
        <customerLocale>en_GB</customerLocale>
        <currencyCode>GBP</currencyCode>
        <currencyValue>1.36</currencyValue>
        <paymentMethod>Credit Card</paymentMethod>
        <paymentModuleCode>authorizenet</paymentModuleCode>
        <paymentModuleSubCode>paymentModuleSubCode</paymentModuleSubCode>
        <pointsAwarded>150</pointsAwarded>
        <pointsUsed>20</pointsUsed>
        <couponIds>23</couponIds>
        <promotionIds>12</promotionIds>
        <affiliateId>affiliateId</affiliateId>
        <invoiceFileName>32634-2015.pdf</invoiceFileName>
        <shippingModuleCode>fedex</shippingModuleCode>
        <shippingServiceCode>overnight</shippingServiceCode>
        <orderCreator>21</orderCreator>
        <storeName>multi-vendor store name</storeName>
        <kkParentOrderId>66</kkParentOrderId>
        <custom1>custom1</custom1>
        <custom2>custom2</custom2>
        <custom3>custom3</custom3>
        <custom4>custom4</custom4>
        <custom5>custom5</custom5>
        <custom6>custom6</custom6>
        <custom7>custom7</custom7>
        <custom8>custom8</custom8>
        <custom9>custom9</custom9>
        <custom10>custom10</custom10>
        <custom11>custom11</custom11>
        <custom12>custom12</custom12>
        <custom13>custom13</custom13>
        <custom14>custom14</custom14>
        <custom15>custom15</custom15>
        <custom16>custom16</custom16>

Simple Mandatory Attributes

kkOrderId	A unique numeric id for the order assigned by KonaKart when the order is saved in the KonaKart database.
orderState	An integer identifying the state of the order. The order states may be defined in the KonaKart database using the KonaKart Admin App.
creationDate	The date the order was created in the format HH:mm:ss ddMMyyyy.
customerLocale	The customer's locale in the format en_GB.
currencyCode	The ISO 4217 Currency Code (e.g. USD, EUR, GBP).
paymentMethod	The method used for payment. The value of this attribute is defined by the KonaKart payment module written to support the chosen payment gateway.
paymentModuleCode	The code of the KonaKart payment module. A store may have more than one payment modules. e.g. There could be a credit card payment module, a cash on delivery payment module, a pick up in store payment module etc.
shippingModuleCode	The code of the KonaKart shipping module. A store may have more than one shipping module. e.g. There could be a database table driven module with fixed costs based on order weight for domestic orders and an interface to a web service like FedEx for international orders.
orderCreator	The numeric KonaKart id of the customer making the order.

Simple Optional Attributes

time	Time message was created in format HH:mm:ss ddMMyyyy
version	The version of the interface being used
orderId	The id of the KonaKart virtual store
storeNumber	A unique order number identifying the order. Depending on how this number is assigned, it may not be present when KonaKart exports the order because it may be assigned by the ERP.
kkLifecycleId	This is a unique UUID assigned to the order by KonaKart. It is present even before the order is saved in the KonaKart database.
customerId	This attribute may be present if the customer has been assigned an id by the ERP or if there is an algorithm that KonaKart can use to create the ID. e.g. create an ID of W0000067 from the KonaKart id of 67.
currencyValue	Only present if this has been set on the KonaKart currency. It is used to translate currencies.
paymentModuleSubCode	Only present for certain payment gateways that support multiple payment methods, each of which has a code.
pointsAwarded	Only present if reward points is enabled in the storefront and the customer was awarded points for the order.
pointsUsed	Only present if reward points is enabled in the storefront and the customer used points to pay or partially pay for the order.
couponIds	If one or more coupon codes were used, this attribute contains the KonaKart numeric coupon ids separated by commas.
promotionIds	If one or more promotions were used, this attribute contains the KonaKart numeric promotion ids separated by commas.
affiliateId	Can be used to contain the id of an affiliate partner.
invoiceFileName	Can be used to contain the file name of the invoice for the order.
shippingServiceCode	Some shipping modules (especially the service based ones) may return multiple options such as overnight shipping, or 2-day shipping etc.
storeName	Only used in multi vendor mode where the order is a vendor order containing only the products which the vendor needs to ship. It has a parent which is the main order containing all of the order items.
kkParentOrderId	Only used in multi vendor mode where the order is a vendor order containing only the products which the vendor needs to ship. It has a parent which is the main order containing all of the order items. The attribute contains the KonaKart order id of the parent order.
custom1-custom16	Custom attributes that may contain any custom data saved in the KonaKart database with the order.


        <customerAddress>
            <kkAddressId>23</kkAddressId>
            <name>Peter Smith</name>
            <company>ACME Inc</company>
            <address1>Rose Cottage</address1>
            <address2>32 High Street</address2>
            <address3>MayBank</address3>
            <city>Newcastle</city>
            <state>Staffordshire</state>
            <postcode>ST5 ORT</postcode>
            <ISO3CountryCode>GBR</ISO3CountryCode>
            <ISONumericCountryCode>123</ISONumericCountryCode>
            <telephone1>01782765334</telephone1>
            <telephone2>335624599</telephone2>
            <email>peter.smith@acme.com</email>
        </customerAddress>
        <billingAddress>
            <kkAddressId>23</kkAddressId>
            <name>Peter Smith</name>
            <company>ACME Inc</company>
            <address1>Rose Cottage</address1>
            <address2>32 High Street</address2>
            <address3>MayBank</address3>
            <city>Newcastle</city>
            <state>Staffordshire</state>
            <postcode>ST5 ORT</postcode>
            <ISO3CountryCode>GBR</ISO3CountryCode>
            <ISONumericCountryCode>123</ISONumericCountryCode>
            <telephone1>01782765334</telephone1>
            <telephone2>335624599</telephone2>
            <email>peter.smith@acme.com</email>
        </billingAddress>
        <deliveryAddress>
            <kkAddressId>23</kkAddressId>
            <name>Peter Smith</name>
            <company>ACME Inc</company>
            <address1>Rose Cottage</address1>
            <address2>32 High Street</address2>
            <address3>MayBank</address3>
            <city>Newcastle</city>
            <state>Staffordshire</state>
            <postcode>ST5 ORT</postcode>
            <ISO3CountryCode>GBR</ISO3CountryCode>
            <ISONumericCountryCode>123</ISONumericCountryCode>
            <telephone1>01782765334</telephone1>
            <telephone2>335624599</telephone2>
            <email>peter.smith@acme.com</email>
        </deliveryAddress>

Complex Mandatory Attributes - Addresses

Each order contains three address sections which may all contain different addresses for Customer, Billing and Delivery Addresses.

Mandatory Attributes - Addresses

name	The person's name.
address1	The first line of the street address.
city	The person's city
state	The person's state.
postcode	The person's postcode.
ISO3countryCode or ISONumericCountryCode	Either the 3 letter ISO country code or the ISO numeric country code should be present.
email	The email address of the person (only mandatory for the Customer address, not the Billing address or Delivery address).

Optional Attributes - Addresses

kkAddressId	The numeric id of the KonaKart address. Only useful for immediate use since the registered customer may remove the address from his address book.
company	The person's company.
address2	The second line of the street address.
address3	The third line of the street address.
telephone1	The person's primary telephone number.
telephone2	The person's other telephone number.


        <lineItems>
            <lineItem>
                <kkProductId>45</kkProductId>
                <productSKU>DLI-4567</productSKU>
                <productName>De'Longhi BCO 410</productName>
                <productModel>DLBCO410</productModel>
                <singleProductWeight>15.6</singleProductWeight>
                <quantity>2</quantity>
                <discountPercent>20.00</discountPercent>
                <totalPriceExTax>20.00</totalPriceExTax>
                <totalPriceIncTax>24.00</totalPriceIncTax>
                <totalTax>4.00</totalTax>
                <taxCode>taxCode</taxCode>
                <refundValue>19.20</refundValue>
                <refundPoints>100</refundPoints>
                <custom1>custom1</custom1>
                <custom2>custom2</custom2>
                <custom3>custom3</custom3>
                <custom4>custom4</custom4>
                <custom5>custom5</custom5>
                <custom6>custom6</custom6>
                <custom7>custom7</custom7>
                <custom8>custom8</custom8>
                <custom9>custom9</custom9>
                <custom10>custom10</custom10>
            </lineItem>
        </lineItems>

Complex Mandatory Attributes - Line Items

Each order contains a line item for each product type ordered. There must be at least one line item.

Mandatory Attributes - Line Items

kkProductId	The KonaKart numeric product id.
productSKU	The product SKU which is understood by the ERP system.
productName	The name of the product.
productModel	The model of the product.
quantity	The quantity bought.
totalPriceExTax	The total price of the line item (unit price x qty) excluding tax.
totalPriceIncTax	The total price of the line item (unit price x qty) including tax.
totalTax	The total tax for the line item.

Optional Attributes - Line Items

singleProductWeight	The weight of a single product.
discountPercent	Used for tier pricing.
taxCode	The tax code used for the product.
refundValue	The final unit price of a product having taken into account all discounts. May be used to calculate refunds.
refundPoints	The number of points allocated for a single product. May be used to calculate refunds. Default value is -1 (not set).
custom1-custom10	Custom attributes that may contain any custom data saved in the KonaKart database with the line item.


        <orderTotals>
            <orderTotal>
                <title>Sub-Total</title>
                <text>£24.00</text>
                <value>24.00</value>
                <className>ot_subtotal</className>
                <custom1>custom1</custom1>
                <custom2>custom2</custom2>
                <custom3>custom3</custom3>
                <custom4>custom4</custom4>
                <custom5>custom5</custom5>
            </orderTotal>
            <orderTotal>
                <title>Flat Rate Shipping</title>
                <text>£5.00</text>
                <value>5.00</value>
                <className>ot_shipping</className>
                <custom1>custom1</custom1>
                <custom2>custom2</custom2>
                <custom3>custom3</custom3>
            </orderTotal>
            <orderTotal>
                <title>Total</title>
                <text>£29.00</text>
                <value>29.00</value>
                <className>ot_total</className>
                <custom1>custom1</custom1>
                <custom2>custom2</custom2>
                <custom3>custom3</custom3>
                <custom4>custom4</custom4>
                <custom5>custom5</custom5>
            </orderTotal>
        </orderTotals>

Complex Mandatory Attributes - Order Totals

Each order normally contains a number of order totals for things like sub total, shipping, promotion discount, total etc.

Mandatory Attributes - Order Totals

title	Typically displayed on the order. Contains text like Total, Shipping, Sub Total etc.
text	A formatted representation of the amount. e.g €23.45 or £34.56
value	A numeric representation of the amountt e.g. 23.45 or 34.56
className	This identifies the order total module used to generate the order total.

Optional Attributes - Order Totals

promotionId	When the Order Total contains the result of a promotion, it holds the promotion id.
discountAmount	The discount amount defined by the promotion. Only present when the order total contains the results of a promotion and the promotion defines a discount amount rather than a discount percentage.
discountPercent	The discount percentage defined by the promotion. Only present when the order total contains the results of a promotion and the promotion defines a discount percentage rather than a discount amount.
custom1-custom5	Custom attributes that may contain any custom data saved in the KonaKart database with the order total.


        <statusHistory>
            <status>
                <kkOrderStatusId>1</kkOrderStatusId>
                <updatedBy>5</updatedBy>
                <date>18:54:00 03032015</date>
                <customerNotified>false</customerNotified>
                <comments/>
            </status>
            <status>
                <kkOrderStatusId>5</kkOrderStatusId>
                <updatedBy>5</updatedBy>
                <date>18:54:00 03032015</date>
                <customerNotified>true</customerNotified>
                <comments>
                    Authorize.net payment successful.
                    Authorize.net TransactionId = 27364
                </comments>
            </status>
        </statusHistory>

Complex Mandatory Attributes - Status History

A status record is added to the order every time the status changes. When the order is exported it will already have a minimum of one status record associated with it.

Mandatory Attributes - Status History

kkOrderStatusId	An integer identifying the state of the order. The order states may be defined in the KonaKart database using the KonaKart Admin App.
date	The date / time the state was changed in format HH:mm:ss ddMMyyyy
customerNotified	True if an email was sent to the customer for the state change.

Optional Attributes - Status History

updatedBy	The id of the KonaKart user that caused the state change.
comments	Any comments can be added to accompany the state change.


        <paymentHistory>
            <payment>
                <transactionDate>16:19:46 03032015</transactionDate>
                <transactionAmount>99.99</transactionAmount>
                <kkResult>0</kkResult>
                <kkResultDescription>Transaction OK</kkResultDescription>
                <gatewayResult>1 - This transaction has been approved.</gatewayResult>
                <gatewayFullResponse>gatewayFullResponse</gatewayFullResponse>
                <gatewayTransactionId>0</gatewayTransactionId>
                <gatewayCaptureId>2207759569</gatewayCaptureId>
                <gatewayCreditId>2207759568</gatewayCreditId>
                <moduleCode>authorizenet</moduleCode>
                <custom1>custom1</custom1>
                <custom2>custom2</custom2>
                <custom3>custom3</custom3>
                <custom4>custom4</custom4>
                <custom5>custom5</custom5>
            </payment>
        </paymentHistory>
    </body>
</orderExport>

Complex Mandatory Attributes - Payment History

If the customer has paid by credit card through a payment gateway, KonaKart will have captured payment details returned by the payment gateway. The Payment History section may consist of more than one payment object because the customer may make multiple attempts to pay (e.g. using different credit cards) until payment was successful.

transactionDate	The date / time of the transaction in format HH:mm:ss ddMMyyyy
transactionAmount	The amount of the transaction.
kkResult	The KonaKart result. The value is 0 if the transaction was successful regardless of the outcome. e.g. A KonaKart value of 0 means that the communication with the gateway was successful even if the credit card wasn't accepted by the gateway.
kkResultDescription	A description of the KonaKart result.
gatewayResult	The result from the gateway which determines whether the credit card was accepted or not. The value will depend on the actual gateway.
gatewayFullResponse	The full response received from the payment gateway. Useful for auditing purposes.
gatewayTransactionId	The payment gateway transaction id.
moduleCode	The code of the KonaKart module used to communicate with the payment gateway.

Optional Attributes - Payment History

gatewayCaptureId	May contain a value if the gateway was used to reserve the funds on the credit card. The captureId is transmitted to the payment gateway in another transaction (typically when the goods are shipped) in order to actually deduct the funds from the credit card.
gatewayCreditId	May contain a value that can be used to refund an amount to the customer if the products are returned.
custom1-custom3	Custom attributes that may contain any custom data saved in the KonaKart database by the payment module.

Update Object

KonaKart to ERP.

The purpose of this message is to inform the ERP system that a KonaKart object has been modified, inserted or deleted. It allows the ERP system to use the KonaKart APIs to read the updated objects.

For Customers, a message is sent when the following events occur:

When a customer registers using the Storefront Engine.
When a customer updates his personal information using the Storefront Engine.
When a customer updates his primary address using the Storefront Engine.
When a customer updates, inserts or deletes any non primary address using the Storefront Engine.
When an administrator registers a customer using the Admin Engine.
When an administrator updates customer information using the Admin Engine.
When an administrator updates a customer’s primary address using the Admin Engine.
When an administrator deletes a customer using the Admin Engine.

For Orders, a message is sent when the following events occur:

When an order is saved using the Storefront Engine.
When the state of an order is changed using the Storefront Engine.
When the state of an order is changed using the Admin Engine.

Note that for orders, the code that sends the message is in the Order Integration Managers, and by default, the message is only sent when the order is in the Payment Received state.

For Products, a message is sent when the following events occur:

A product is inserted, edited or deleted.
The product quantity is changed using setProductQuantity() or setProductQuantityWithOptions().


<updateObject>
	<storeId>store1</storeId>
	<time>16:50:07 26022015</time>
	<version>1.0</version>
	<body>
		<objectType>1</objectType>
		<operationType>2</operationType>
		<kkObjectId>88</kkObjectId>
		<objectId1>ABC</objectId1>
		<objectId2>XYZ</objectId2>
		<value1>32</value1>
		<value2></value2>
	</body>
</updateObject>

Mandatory Attributes

objectType	Integer used to identify the object: Order Customer including primary address Product Non primary address
operationType	Integer used to identify the type of CRUD operation: Create Update Delete
kkObjectId	The numeric id of the KonaKart object

Optional Attributes

objectId1	Additional identifier that can be used by the ERP to identify the object. For object type 3, it contains the product SKU if available. For object type 4, it contains the address id.
objectId2	Additional identifier that can be used by the ERP to identify the object. For object type 3, it contains the catalog id if available.
value1	Optional value to simplify the processing of the message. For object type 3, it contains the new quantity of the product if the API call setProductQuantity() or setProductQuantityWithOptions() was called. For object type 1, it contains the numeric state of the order.
value2	Optional value to simplify the processing of the message.

Prev	Up	Next
Messages from ERP to KonaKart	Home	Installation and Configuration