Customer Import

Short description

This interface describes which customer information is sent from the ERP system to Vendisto.

Customer information includes:

• Shop Specific Debit Number

• Billing address details

• Name1

• Name2 (e.g. Attn.)

• Address

• Postal code

• City

• Country

• Standard shipping address information

• Name1

• Name2 (e.g. Attn.)

• Address

• Postal code

• Town

• Country

• Additional information (e.g. port number, exit number, etc.)

• Delivery instruction (e.g. "Leave behind in a box...")

• Name contact person

• E-mail address contact person

• Payment method (on account, cash, etc.)

• Payment condition

• DeliverySchedule

• DivisionCode

• ApplyEqualizationTax

How to submit

Update Frequency: Batch at least 1x per day

Incremental or Full Set: Incremental

File Type: Zipped XML

Bestandsbenaming: [SHOPNAME]_customers_[INDEXNUMBER].xml Transport: over FTPS, FTPS Vendisto server is hosted by INTEGRACE, file is put on FTPS server by ERP party.

Location within FTP root: \Vendisto\Integration\

Customer XML Structure

This XML structure can be used for batch import of Customer data. All optional elements can be omitted from the import. Omitted elements that represent customer information will not update existing information. E.G. if <FirstName> is not present in the XML but is in the database, the field will not be updated. If <FirstName /> is present as an empty XML element, the FirstName in the database will be made empty. If <CustomerAddresses> is not present, the CustomerAddresses will not be updated. If <CustomerAddresses /> is present as empty XML element, all existing customer’s addresses will be removed from the database.

The ImportSettings element can be used to set the default behavior of import.

Changes from Customer XML 2.0 to 2.1

• The ImportSettings node is now required as well as the 'Importer' setting.

• The PartialUserImport setting is no longer available.

• StreetAddressType is a new import setting with values: Combined and Separated

• StreetAddres1 and StreetAddress2 are renamed to AddressLine1 and AddressLine2

• AddressLine1 contains Street and housenumber when StreetAddressType is set to Combined

• The new fields Street, HouseNumber and HouseNumberAddition are to be used when StreetAddressType is set to Separated

• AddressLine2: May contain an additional address line

• UserType and UserRights are new elements on the User level

• ExternalId can be filled with the address id of the ERP system

Changes from Customer XML 2.1 to 2.2

• The PriceGroup element was removed from the XML definition

• A new PriceList element was added to the definition

• An optional Currency element was added. This element can be used by the shop to predefine the users currency in the shop.

• An optional Incoterm element was added. The incoterm is used to show to the user in the account section of the user portal.

• An optional ShippingCostType element was added. The ShippingCostType is used for the shipment API. With this information the api can calculate the correct shipment costs.

• An optional InvoiceTo element was added. If this field is filled, the shop will show the invoice addresses of the invoice debtor in the user portal and in the checkout process.

• An optional DivisionCode element was added. We are able to configure the WebService to pass this field along with requests to a Shoxl rest implementation.

• An optional attribute "ignoreElements" was added to the "Validation" element. It can be used to ignore certain XML elements in the validation process. Currently only supports "PostalCode" Usage:

  <?xml version="1.0" encoding="utf-8"?>
  <ImportSettings>
      <Validation ignoreElements="PostalCode,...">...</Validation>
      ...
  </ImportSettings>

• An optional ApplyEqualizationTax element was added. If this field contains the value “true”, it means that this customer is eligible for an equalization tax. The shop can use this information to show a detailed breakdown of how a price is made up.

• An optional CreateUnknownAuthorizationProfiles element was added to the import settings. If this field is true, non-existing authorization profiles are automatically created in Vendisto. This is useful when exporting pricelists as authorization profiles.

• An optional PaymentCondition element was added. This element contains a debtor's payment condition code and -description.

<?xml version="1.0" encoding="utf-8"?>
<Import>
    <ImportSettings>
        <Importer>CustomerData</Importer>
        <Version>2.2</Version>
        <PartialImport></PartialImport>
        <Validation></Validation>
        <CreateUnknownAuthorizationProfiles></CreateUnknownAuthorizationProfiles>
        <StreetAddressType></StreetAddressType>
    </ImportSettings>
    <Customers>
        <Customer>
            <DebtorNumber></DebtorNumber>
            <Company></Company>
            <CompanyVatNumber></CompanyVatNumber>
            <Gln></Gln>
            <Gender></Gender>
            <FirstName></FirstName>
            <MiddleName></MiddleName>
            <LastName></LastName>
            <Email></Email>
            <PhoneNumber></PhoneNumber>
            <MobilePhoneNumber></MobilePhoneNumber>
            <DefaultReference></DefaultReference>
            <DateOfBirth></DateOfBirth>
            <Iban></Iban>
            <BuyOnCredit></BuyOnCredit>
            <PriceList></PriceList>
            <State></State>
            <PreferredBranche></PreferredBranche>
            <Currency></Currency>
            <Incoterm></Incoterm>
            <ShippingCostType></ShippingCostType>
            <InvoiceTo></InvoiceTo>
            <DeliverySchedule></DeliverySchedule>
            <DivisionCode></DivisionCode>
            <EqualizationTax></EqualizationTax>
            <PaymentCondition>
                <Code></Code>
                <Description></Description>
            </PaymentCondition>
            <Authorization>
                <Profile></Profile>
                <Profile></Profile>
            </Authorization>
            <CustomerAddresses>
                <CustomerAddress>
                    <AddressType></AddressType>
                    <Company></Company>
                    <Gender></Gender>
                    <FirstName></FirstName>
                    <MiddleName></MiddleName>
                    <LastName></LastName>
                    <AddressLine1></AddressLine1>
                    <Street></Street>
                    <HouseNumber></HouseNumber>
                    <HouseNumberAddition></HouseNumberAddition>
                    <AddressLine2></AddressLine2>
                    <PostalCode></PostalCode>
                    <City></City>
                    <Country></Country>
                    <ExternalId></ExternalId>
                    <IsDefaultAddress></IsDefaultAddress>
                </CustomerAddress>
            </CustomerAddresses>
            <Users>
                <User>
                    <Username></Username>
                    <FirstName></FirstName>
                    <MiddleName></MiddleName>
                    <LastName></LastName>
                    <Email></Email>
                    <PreferredLanguage></PreferredLanguage>
                    <BuyOnCredit></BuyOnCredit>
                    <State></State>
                    <Authorization>
                        <Profile></Profile>
                        <Profile></Profile>
                    </Authorization>
                    <UserType></UserType>
                    <UserRights>
                        <Right></Right>
                        <Right></Right>
                    </UserRights>
                </User>
            </Users>
        </Customer>
    </Customers>
</Import >

Velden customer XML

Import element:

Name	Description	Type	Required/Optional
ImportSettings	Container element for importsettings	Element	Required
Customers	Container element for Customer data	Element	Required

ImportSettings element:

Name	Description	Type	Required/Optional
Importer	Name of the importer. Should be CustomerData.	Text, default CustomerData	Required
Version	Version of the import xml. Value must be set to 2.2	Text	Required
PartialImport	Defines if import is full or partial import.	Boolean, default Y	Optional
Validation	Defines the validation type. Strict validation requires FirstName and LastName fields of Customer Address. Loose validation doesn’t. Also contains attribute "ignoreElements" which holds comma seperated element names which are ignored during the validation process.	Validation, default Loose	Optional
CreateUnknownAuthorizationProfiles	If this field is true, non-existing authorization profiles are automatically created in Vendisto	default N	Optional
StreetAddressType	Setting to make the distinction between 'Combined' and 'Separated' address lines. ERP systems that store the housenumber in a separate field should set the type to 'Separated'. Those that don't to 'Combined'.	StreetAddressType, default Separated	Optional

Customer element:

Name	Description	Type	Required/Optional
DebtorNumber	Debtor number	Text	Required if Vendisto setting ‘Customer identification type’ is set to ‘Debtor number’, else Optional.
Company	Name of the company	Text	Optional
CompanyVatNumber	Vat number	Text	Optional
Gln	Global location number	GLN	Optional
Gender	Gender of the customer contact person	Gender	Optional
FirstName	of the contact person	Text	Optional
MiddleName	of the contact person	Text	Optional
LastName	of the contact person	Text	Optional
Email	of the contact person	Text, must be a valid email address	Required
PhoneNumber	of the contact person	Text	Optional
MobilePhoneNumber	of the contact person	Text	Optional
DateOfBirth	of the contact person	Date	Optional
DefaultReference	Depricated	Text	Optional
Iban	For future use	Text	Optional
BuyOnCredit	Enables the BuyOnCredit payment method, if this is available in the shop	Boolean, default N	Optional
PriceList	Vendisto pricelist name	PriceList	Optional
State	State of the customer: Active or Blocked	CustomerState, default Active	Optional
PreferredBranche	A preferred location or branche where the order will be handled	Text	Optional
Currency	Must contain the ISO 4217 three-letter currency code	Char[3]	Optional
Incoterm	Trade term	Text	Optional
ShippingCostType	The shipment cost type	ENUM: ShippingCostApplied, ShippingCostFree, ShippingCostPostCalculation	Optional
InvoiceTo	Account Number of the Invoice debtor. If this field is filled, the shop will show the invoice addresses of the invoice debtor in the user portal and in the checkout process	Text	Optional
DeliverySchedule	The name of the DeliverySchedule that the customer needs to be set to	Text	Optional
DivisionCode	Indicates the division a customer belongs to	Text	Optional
EqualizationTax	Indicates a customer is eligible for equalization tax	Boolean, default N	Optional
Authorization	Container for list of Profiles	Authorization element	Optional
CustomerAddresses	List of addresses of the customer (Invoice or Delivery)	CustomerAddress elements	Optional
Users	List of users for the customer	User elements	Optional
PaymentCondition	A debtor's payment condition	CustomerPaymentConditionElement	Optional

Authorization element:

Name	Description	Type	Required/Optional
Profile	Code of authorization profile	Char[3]	Optional

CustomerAddress element:

Name	Description	Type	Required/Optional
AddressType	Defines the type of the address: Invoicing or Delivery	AddressType	Required
CompanyName	Name of the company	Text	Optional
Gender	Gender of the customer address contact person	Gender, default Undefined	Optional
FirstName	of the address contact person	Text	Required if Validation is Strict
MiddleName	of the address contact person	Text	Optional
LastName	of the address contact person	Text	Required if Validation is Strict
AddressLine1	of the address contact person	Text	Only imported if StreetAddressType is Combined and in that case Required
Street	of the address contact person	Text	Only imported if StreetAddressType is Separated and in that case Required
HouseNumber	of the address contact person	Text	Only imported if StreetAddressType is Separated and in that case Required
HouseNumberAddition	of the address contact person	Text	Only imported if StreetAddressType is Separated and in that case Optional
AddressLine2	of the address contact person	Text	Optional
PostalCode	of the address contact person	Text	Required
City	of the address contact person	Text	Required
Country	of the address contact person	Text	Required
ExternalId	Address ID of the external (ERP) system	Text	Optional
IsDefaultAddress	In case of multiple addresses of the given Type this property indicates the default	Boolean, default N	Optional

User element:

Name	Description	Type	Required/Optional
Username	User’s username	Text	Required
FirstName	User's firstname	Text	Optional
MiddleName	User's middlename	Text	Optional
LastName	User's lastname	Text	Optional
Email	User’s email address	Text, must be a valid email address	Optional
PreferredLanguage	Indicates preferred language on website	LCID	Optional
BuyOnCredit	Enables the BuyOnCredit payment method, if this is available in the shop	Boolean, overrides customer’s BuyOnCredit setting	Optional
State	State of the user: Inactive, Active or Blocked	UserState, default Active	Optional
Authorization	Container for list of Profiles, overrides customer authorization profiles	Authorization element	Optional
UserType	The type of the user. Can be used to indicate the superuser who is able to manage the Rights per user.	UserType, default User	Optional
UserRights	Container for a list of Rights	UserRights element	Optional

UserRights element:

Name	Description	Type	Required/Optional
Right	Specifies a right that the user has	Right	Required

CustomerPaymentConditionElement:

Name	Description	Type	Required
Code	Identifier of a Payment Condition	string
Description	Description of a Payment Condition	string

Types:

Type	Values
AddressType	Invoicing, Delivery
Boolean	Y, N
Date	yyyy-MM-dd
CustomerIdentification	DebtorNumber, Email
CustomerState	Active, Blocked
Gender	Undefined, Male, Female
GLN	Must be a valid GLN number
LCID	Windows decimal LCID
PriceList	Name of in Vendisto existing PriceList
Right	OrderHistory, InvoiceHistory, BackOrderOverview, RestrictedOrderList, FavoritesList, UserManagement
StreetAddressType	Combined, Separated
UserState	Inactive, Active, Blocked
UserType	User, SuperUser
Validation	Strict, Loose

Structuur Customer XML (Legacy)

De informatie in deze sectie beschrijft het legacy formaat voor de Customer XML import. Dit formaat wordt nog ondersteund maar zal worden uitgefaseerd. Nieuwe implementaties dienen hier geen gebruik meer van te maken.

<?xml version="1.0" encoding="utf-8"?>
<customers>
        <customer>
                <accountNumber></accountNumber>
                <defaultBillingAddress>
                        <name1></name1>
                        <name2></name2>
                        <address1></address1>
                        <address2></address2>
                        <postalCode></postalCode>
                        <city></city>
                        <country></country>
                </defaultBillingAddress>
                <defaultShipmentAddress>
                        <name1></name1>
                        <name2></name2>
                        <address1></address1>
                        <address2></address2>
                        <postalCode></postalCode>
                        <city></city>
                        <country></country>
                        <transportInstructionText></transportInstructionText>
                </defaultShipmentAddress>
                <projects>
                        <project>
                                <projectAccountNumber></projectAccountNumber>
                                <name></name>
                                <description></description>
                                <defaultShipmentAddress>
                                        <name1></name1>
                                        <name2></name2>
                                        <address1></address1>
                                        <address2></address2>
                                        <postalCode></postalCode>
                                        <city></city>
                                        <country></country>
                                        <transportInstructionText></transportInstructionText>
                                </defaultShipmentAddress>
                        </project>
                </projects>
                <ContactName></ContactName>
                <ContactEmailAddress></ContactEmailAddress>
                <CompanyVatNumber></CompanyVatNumber>
                <FirstName></FirstName>
                <MiddleName></MiddleName >
                <LastName></LastName >
                <GLN></GLN>
                <priceListNumber></priceListNumber>
                <paymentOnAccountAllowed></paymentOnAccountAllowed>
                <showPrices></showPrices>
                <showStock></showStock>
        </customer>
</customers>

Velden customer XML (Legacy)

Name	Description	Type	Required / Optional
accountNumber	The identifier of a customer.	Text	Required
defaultBillingAddress / name1	Name of the billing address (department).	Text	Required
defaultBillingAddress / name2	A second name row of the billing address (attn)	Text	Optional
defaultBillingAddress / address1	Street and house number of the billing address	Text	Required
defaultBillingAddress / address2	An extra address row for the billing address	Text	Optional
defaultBillingAddress / postalcode	The postal code of the billing address	Text	Required
defaultBillingAddress /city	The city of the billing address	Text	Required
defaultBillingAddress /country	The country of the billing address	Text	Required
defaultShippingAddress / name1	Name of the shipping address (department).	Text	Required
defaultShippingAddress / name2	A second name row of the shipping address (attn)	Text	Optional
defaultShippingAddress / address1	Street and house number of the shipping address	Text	Required
defaultShippingAddress / address2	An extra address row for the shipping address	Text	Optional
defaultShippingAddress / postalcode	The postal code of the shipping address	Text	Required
defaultShippingAddress /city	The city of the Shipping address	Text	Required
defaultShippingAddress /country	The country of the Shipping address	Text	Required
defaultShippingAddress /transportInstructionText	Transport and delivery instruction for the shipping address	Text	Optional
project / projectAccountNumber	The identifier of a project	Text	Required
project / name	The name of the project	Text	Required
project / description	A description of the project	Text	Optional
project / defaultShippingAddress / name1	Name of the shipping address (department).	Text	Required
project / defaultShippingAddress / name2	A second name row of the shipping address (attn)	Text	Optional
project / defaultShippingAddress / address1	Street and house number of the shipping address	Text	Required
project / defaultShippingAddress / address2	An extra address row for the shipping address	Text	Optional
project / defaultShippingAddress / postalcode	The postal code of the shipping address	Text	Required
project / defaultShippingAddress /city	The city of the Shipping address	Text	Required
project / defaultShippingAddress /country	The country of the Shipping address	Text	Required
project /defaultShippingAddress /transportInstructionText	Transport and delivery instruction for the shipping address	Text	Optional
ContactName	The name of the contact. Can be replaced by FirstName, MiddleName and LastName	Text	Optional
ContactEmailAddress	The contacts emailaddress	Text	Required
FirstName	First name of the contact person	Text	Optional
MiddleName	Middle name of the contact person	Text	Optional
LastName	Last name of the contact person	Text	Optional
CompanyVatNumber	Vat number	Text	Optional
GLN	Global location number	GLN	Optional
priceListNumber	The pricelist reference	Text	Required
paymentOnAccountAllowed	Is the customer allowed to pay on account? (yes = true, no = false)	Boolean	Required
showPrices	Can the customer see price information? (yes = true, no = false)	Boolean	Required
showStock	Can the customer see stock information? (yes = true, no = false)	Boolean	Required

Types:

Name	Values
Boolean	yes, no
GLN	Must be a valid GLN number