Messages from ERP to KonaKart

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

Update Product

ERP to KonaKart.

The purpose of this message is to allow the ERP system to update the price and / or quantity of a product in the KonaKart database.


<updateProduct>
    <storeId>store1</storeId>
    <time>16:50:07 26022015</time>
    <version>1.0</version>
    <body>
        <sku>ABC-123</sku>
        <catalogId>store6</catalogId>
        <quantity>88</quantity>
        <price0>33.56</price0>
        <price1>30.34</price1>
        <price2>26.99</price2>
        <price3>11.52</price3>
        <stockType>1</stockType>
        <disable>false</disable>
    </body>
</updateProduct>

Mandatory Attributes

sku	Used to identify the product
quantity	Quantity in stock (only mandatory if message is used to set the stock level)
price0	The price of the product (only mandatory if message is used to set the price)
disable	can be set to "true" or "false" to disable or enable a product. When disabled, the product is not displayed in the storefront.
stockType	The product can be given a stockType which conditions the behaviour of the storefront application for the case of low stock (see table below)

Note that only one of quantity, price0, disable or stockType is mandatory. They aren't all mandatory.

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
catalogId	Only used when using KonaKart catalogs which allow you to set price and stock information for a specific catalog.
price1-price3	Each KonaKart product has 4 price fields. Only price0 is mandatory.

stockType attribute

Quantity	Stock Type	Behaviour
>0	Not Set	Allow purchase
<=0	Not Set	Don't allow purchase and hide Add To Cart button but still display product
>0	1	Allow purchase
<=0	1	Allow purchase but show a warning
>0	2	Allow purchase
<=0	2	Don't allow purchase and hide Add To Cart button but still display product

Update Product Prices

ERP to KonaKart.

The purpose of this message is to allow the ERP system to update the prices of one or more products in the KonaKart database. Within the <product> tag of a message you can set the prices of a product and all of its variants. The variant is identified by the SKU. Since a variant may be determined by the combination of multiple options such as size and color, this message will only work for products that have variants using a single option because the final product price is determined by the delta prices of the options.


<updateProductPrices>
    <storeId>store1</storeId>
    <time>16:50:07 07022017</time>
    <version>1.0</version>
    <body>
        <product>
            <prices>
                <catalogId>store6</catalogId>
                <price>
                    <sku>SKU-1</sku>
                    <price0>10.99</price0>
                    <price1>11.99</price1>
                    <price2>12.99</price2>
                    <price3>13.99</price3>
                    <priceOperation>0</priceOperation>
                </price>
                <price>
                    <sku>SKU-1</sku>
                    <price0>0.00</price0>
                    <priceOperation>1</priceOperation>
                </price>
                <price>
                    <sku>SKU-2</sku>
                    <price0>2.00</price0>
                <priceOperation>1</priceOperation>
                </price>
           </prices>
       </product>
    </body>
</updateProductPrices>

Mandatory Attributes

sku

Used to identify the base product or the product variant.

price0

The price of the base product or the delta price of the product variant.

priceOperation

It can be set to 0 or 1.

0 : If the SKU identifies the base product or any product variant, the base product price is set with the price passed in the message.

1 : If the SKU identifies a product variant, the variant delta price is set with the price passed in the message. If the SKU identifies the base product, the base product price is set with the price passed in the message.

In the above example, the product has two variants, SKU-1 at €10.99 and SKU-2 at €12.99. SKU-1 is the default variant for when the product price is displayed and the base product has not been assigned an SKU.

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
catalogId	Only used when using KonaKart catalogs which allow you to set price and stock information for a specific catalog.
price1-price3	Each KonaKart product has 4 price fields. Only price0 is mandatory.

Update Order

ERP to KonaKart.

The purpose of this message is to allow the ERP system to update the state of an order in the KonaKart database so that it is visible to the customer.


<updateOrder>
    <storeId>store1</storeId>
    <time>16:50:07 26022015</time>
    <version>1.0</version>
    <body>
        <orderNumber>ABC123456</orderNumber>
        <kkOrderId>2345</kkOrderId>
        <kkOrderStatusId>7</kkOrderStatusId>
        <updatedById>34</updatedById>
        <notifyCustomer>true</notifyCustomer>
        <comments>Order has been partially shipped</comments>
        <shipment>
            <kkShipperId>3</kkShipperId>
            <shipperName>FedEx</shipperName>
            <trackingNumber>64564564</trackingNumber>
            <trackingURL>http://www.fedex.com/Tracking?tracknumbers=64564564</trackingURL>
            <shipmentNotes>First floor of block of apartments</shipmentNotes>
            <custom1>custom1</custom1>
            <custom2>custom2</custom2>
            <custom3>custom3</custom3>
            <shippedProducts>
                <shippedProduct>
                    <sku>XDS-456</sku>
                    <quantity>1</quantity>
                </shippedProduct>
                <shippedProduct>
                    <sku>KLJ-897</sku>
                    <quantity>2</quantity>
                </shippedProduct>
            </shippedProducts>
        </shipment>
    </body>
</updateOrder>

Mandatory Attributes

orderNumber or kkOrderId	Either the orderNumber or the numeric kkOrderId may be used to identify the order. Only one of the two should be used. If the order number is generated by the ERP after KonaKart exports the order, then KonaKart won't be aware of it so the kkOrderId must be used.
kkOrderStatusId	The numeric id of the order state. In KonaKart you can configure a set of order states that cover the complete life cycle of the order and each state has a unique id. Typical states are "Payment Received", "Partially Shipped" etc.

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
updatedById	The numeric id of a KonaKart administrator responsible for updating the order.
notifyCustomer	KonaKart can be configured to automatically send a template based email to a customer whenever an order moves into a certain state. If the automatic mechanism is not used, the decision to send an email may be controlled by setting this attribute to "true" or "false".
comments	Any comment that should be made visible to the customer.
shipment	The order state change may regard a shipment of some or all of the products in the order.

Mandatory Shipment Attributes

shippedProduct

The shipment section must contain at least one shipped Product with a valid sku and integer quantity.

Optional Shipment Attributes

kkShipperId	Numeric id of the Shipper that exists in the KonaKart database. If this id is stored, when viewing the shipment in the KonaKart Admin App the correct Shipper will be displayed on the UI.
shipperName	The name of the shipper to display on the storefront application to the customer. e.g. FedEx, UPS, DHL
trackingNumber	The number used to track the shipment.
trackingURL	The URL used to track the shipment.
shipmentNotes	Any notes connected with the shipment.
custom1-custom3	Custom attributes that may contain any custom data to be saved in the KonaKart database with the shipment.

Export Invoice

ERP to KonaKart.

The purpose of this message is to allow the ERP system to associate an invoice file (typically in PDF format) with a KonaKart order with the option of having the invoice sent out to a customer in an email by KonaKart. The invoice may be downloaded by a customer from the storefront after logging in.

The message is not used for actually transporting the invoice file to the servers hosting KonaKart. The mechanism for achieving this is still under investigation.


<exportInvoice>
    <storeId>store1</storeId>
    <time>16:50:07 26022015</time>
    <version>1.0</version>
    <body>
        <orderNumber>ABC123456</orderNumber>
        <kkOrderId>2345</kkOrderId>
        <invoiceFilename>inv_165007.pdf</invoiceFilename>
        <attachmentName>Invoice.pdf</attachmentName>
        <invoicePath>/store1/invoices</invoicePath>
        <sendEmail>true</sendEmail>
        <emailTemplate>OrderInvoice_fr.vm</emailTemplate>
    </body>
</exportInvoice>

Mandatory Attributes

orderNumber or kkOrderId	Either the orderNumber or the numeric kkOrderId may be used to identify the order. Only one of the two should be used. If the order number is generated by the ERP after KonaKart exports the order, then KonaKart won't be aware of it so the kkOrderId must be used.
invoiceFilename	The name of the invoice file which must be present on the servers hosting KonaKart so that KonaKart can read it from the file system.

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
sendEmail	If present, it must be set to true. KonaKart will send out a template based email with the invoice as an attachment.
emailTemplate	If sendEmail is set to true, this attribute must contain the name of the email template that will be used by KonaKart for the email. The template name may or may not contain the country code. It should not contain an extension. e.g. 1. ERPIntegrationOrderInvoice_fr - KonaKart will look for ERPIntegrationOrderInvoice_fr.vm 2. ERPIntegrationOrderInvoice - KonaKart will use the customer's locale on the order (if present) to attempt to determine the language code.
attachmentName	This attribute may be used to give the email attachment a friendly name such as Invoice .
invoicePath	The directory where invoices are stored. If not specified the value that is configured in KonaKart will be used.

Export Customer to KonaKart

ERP to KonaKart.

The purpose of this message is to allow the ERP system to register a customer in KonaKart. A mechanism to allow the customer to login needs to be present. One alternative is to provide a link similar to the Forgot Password link so that the new customer is sent a password to his email address when logging in for the first time.


<exportCustomer>
    <storeId>store1</storeId>
    <time>16:50:07 26022015</time>
    <version>1.0</version>
    <body>
        <customerId>ERP007</customerId>
        <kkCustomerGroupId>34</kkCustomerGroupId>
        <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

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.
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
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 KonaKart

ERP to KonaKart.

The purpose of this message is to allow the ERP system to send an ERP customer id to KonaKart so that any future customer exports from KonaKart to the ERP system will contain both the KonaKart and the ERP customer identifiers. This message would typically be sent by the ERP after it has received an INSERT export customer message from KonaKart since in this case the ERP system may create a new ERP customer and so a new customer identifier.

The message may not be necessary if the ERP system can use the KonaKart customer ID.


<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

Payment Capture

ERP to KonaKart.

In many cases when the customer confirms an order using his credit card, the funds are reserved and not captured until the products are actually shipped. This message, sent by the ERP, instructs KonaKart to initiate a credit card capture transaction with the payment gateway for the amount specified.


<paymentCapture>
    <storeId>store2</storeId>
    <time>16:50:07 26022015</time>
    <version>1.0</version>
    <body>
        <orderNumber>ABC123456</orderNumber>
        <kkOrderId>55</kkOrderId>
        <captureAmount>44.36</captureAmount>
        <gatewayCaptureId>2207759569</gatewayCaptureId>
    </body>
</paymentCapture>

Mandatory Attributes

orderNumber or kkOrderId	Either the orderNumber or the numeric kkOrderId may be used to identify the order. Only one of the two should be used. If the order number is generated by the ERP after KonaKart exports the order, then KonaKart won't be aware of it so the kkOrderId must be used.
captureAmount	The amount KonaKart should capture on the credit card used for confirming the order.

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
gatewayCaptureId	If the gatewayCaptureId isn't provided in the message, then KonaKart will look it up from the database using the kkOrderId. If it is provided then it will be used.

Prev	Up	Next
XML Message Structure	Home	Messages from KonaKart to ERP