Authorization


Registration   Forgot password?

EXTERNAL INTERFACES

Here the matter will concern additional possibilities for the most advanced web-masters. These worth successors of my business :) will be able when wiling to leave even the most competent and meticulous user-checker in ignorance concerning the fact that their shop is the client of our system, that is to move all interfaces to its own site whether it is just a simple shopping cart gathering or payment process.

ATTENTION!!! All files necessary for this interface will be stored here:
http(s)://shopxml.com/EXTERNAL/
Referring to some of them (it will be stated to which specifically) you should use the protected https protocol. To the others - the usual http one (though the protected one is also not prohibited).
Below when describing the protocols only the file name itself will be specified. You should remember where these files are stored right now :)

General provisions and principles

Referring to interfaces (that is per se the corresponding files' request) it is required to submit some parameters to them. You can submit these parameters at your discretion both using the GET-method (via the address line) and using the POST-method.

Every time when you refer to interfaces you'll receive a certain result from them. The format of this result can be of two types:
1. Any line (on default)
This line can contain different data:
- HTML-code for direct inclusion into your page (to facilitate your work) when you simply request any data like the shopping-card content or the list of delivery ways. At that they are not demanding from the server to perform any actions like placing the order to the shopping cart, payment processing and so on.
- The line (or several lines) containing the list of fields divided with the | sign in case of server query to perform some actions like placing the order to the shopping cart, payment processing and so on. For every special case there will be given the list of fields and their values.
Attention: However in all cases (both in the 1-st and the 2-nd ones) when the error occurs this will be the very line containing the list of fields characterizing the error (info on error processing see below).

2. XML-structure (at request to receive XML) - for that when making a query the GET_XML=1 parameter should be stated
(in some interfaces - it will be specified - this parameter isn't valid because of the absence of any sense)
XML - is always XML. The external tags will always be the <answer></answer> tag (even in case of error). Internal structure in every case will be different (will be below described for every specific case).
Attention: However in all cases when the error occurs this structure will be the same and will describe the error (info on error processing see below).
Attention: The default coding for XML is windows-1251. If your parser doesn't understand this coding and requires only UTF-8 then you can among other parameters submit the GET_UTF8=1 parameter in a query to any interface (has sense only at GET_XML=1). Then you'll receive XML in the UTF-8 coding.

Up

Error processing


When an error occurs when referring to any system interface the answer format will be always the same:
1. In case of a simple query the structure will be as follows:
error|ID|description|additional_description
Here:
error - first field - will always be just the error line - that is when making a query to any system interface if the obtained result starts from error - then the
ID error occured - unique error number
description - error description
additional_description - additional error description (created on the fly)

2. In case of the XML-structure query (GET_XML=1 parameter) the XML structure will be as follows (inside the external <answer> tags):
<error>
ID - unique error number
<description> - error description
<additional_description>* - additional error description
Clarifications concerning the format of XML structure description see at the beginning of the page where the objects for export were described.

Up

Error ID (ID) Description (description) Explanation
1 Session opening error Session opening error
10 Session identification error Session identification error
15 HTTPS must be used You can use this interface only using HTTPS
20 Incorrect product code Incorrect product code or the product ID is not specified
21 Product is not available now Product is not available now
22 Product was not found in the database Product was not found in the database
23 Product is not available for a while Product is not available for a while. Will be available later.
24 Product is out of stock now Product is out of stock now.
25 Product is already in your shopping cart Product is already in your shopping cart. Products with attributes however can be selected multiple times - as every time new attributes can be specified
26 This product is not available This product is not available
27 Too big quantity Not enough in stock (when the specified quantity is greater than there is available)
28 Options are not transferred Options are not transferred
29 Some of required attributes are not chosen Some of required attributes are not chosen
50 Invalid item index Invalid item index in the shopping cart for the product with attributes
51 Incorrect quantity Incorrect value for the product quantity (when editing the position in the shopping cart)
52 Incorrect attribute values Incorrect attribute options' values (when editing the position in the shopping cart)
69 No logged customer No logged customer (when trying to logout without the preliminary login)
70 Customer already logged Customer already logged (when trying to repeatedly use interfaces for login)
71 Email incorrect Email of the customer is not specified or has the incorrect format
72 Password is required You forgot to submit the password
73 Account deactivated Account deactivated
74 Invalid password Invalid password
75 No user found No user found with this E-Mail
76 Entered E-Mail already exists in our customers' database Entered E-Mail already exists in our customers' database
77 Password is not confirmed Repeated password doesn't correspond to the main one (at registration)
78 New password is required You forgot to submit new password (when changing password)
79 New password is not confirmed Repeated new password doesn't correspond to the main one (when changing password)
81 Shopping cart is empty Shopping cart is empty (when trying to use interfaces requiring that the shopping cart contain some products)
82 Customer is not logged in Customer is not logged in (when trying to use interfaces requiring that the customers be logged in)
83 Shipping address is not defined Shipping address is not defined (when trying to use interfaces requiring that the address be defined)
84 Shipping method is not defined Shipping method is not defined (when trying to use interfaces requiring that the method be defined)
100 Incorrect input data Incorrect input data (for example the unexisting country is specified, unknown shipping ID and so on)
101 Incorrect Ship-to State/Province When entering the address it is required to specify the province, but it is not specified or specified incorrectly.
102 Ship-to First Name is empty Ship-to First Name is not specified
103 Ship-to Last Name is empty Ship-to Last Name is not specified
104 Ship-to Address is empty Ship-to Address is not specified
105 Too short Ship-to Address Too short Ship-to Address
106 Ship-to City is empty Ship-to City is not specified
107 Too short Ship-to City Too short Ship-to City
108 Ship-to Zip/Postal Code is empty Ship-to Zip/Postal Code is not specified
109 Too short Ship-to Zip/Postal Code Too short Ship-to Zip/Postal Code
110 Ship-to Telephone is empty Ship-to Telephone is not specified
111 Too short Ship-to Telephone Too short Ship-to Telephone
121 Incorrect Bill-to State/Province When entering the address it is required to specify the province, but it is not specified or specified incorrectly
122 Bill-to First Name is empty Bill-to First Name is not specified
123 Bill-to Last Name is empty Bill-to Last Name is not specified
124 Bill-to Address is empty Bill-to Address is not specified
125 Too short Bill-to Address Too short Bill-to Address
126 Bill-to City is empty Bill-to City is not specified
127 Too short Bill-to City Too short Bill-to City
128 Bill-to Zip/Postal Code is empty Bill-to Zip/Postal Code is not specified
129 Too short Bill-to Zip/Postal Code Too short Bill-to Zip/Postal Code
130 Bill-to Telephone is empty Bill-to Telephone is not specified
131 Too short Bill-to Telephone Too short Bill-to Telephone
201 Credit card owner is empty Credit card owner is not specified (authorized payment)
202 Too short credit card owner's name Too short credit card owner's name (authorized payment)
203 Credit card number is empty Credit card number is not specified (authorized payment)
204 Too short ñredit card number Too short ñredit card number (authorized payment)
205 The credit card number is invalid The credit card number is invalid - should contain only numbers without spaces, dashes and so on (authorized payment)
206 CVV Code is empty CVV Code is empty (authorized payment)
207 Too short CVV Code Too short CVV Code (authorized payment)
208 The CVV Code is invalid The CVV Code is invalid - should contain only numbers (authorized payment)
209 Credit Card expire year is invalid Credit Card expire year is invalid - should contain 4 numbers (authorized payment)
210 Credit Card is expired Credit Card is expired - that is the current data is higher than the specified one (authorized payment)
211 Problem with connection to payment system Problem with connection to credit cards' processing system (authorized payment)
212 Your IP is banned Customer IP is banned
213 Too much attempts of credit card processing. Are you a carder? Suspicion of cardering
215 Credit Card processing error Credit Card processing error. Additional error description (additional_description) will contain the line with payment system clarifications
300 Quantity of some products is over our limit When the person has made an order and somebody managed to make it earlier and to take some quantity of products, so that now some products are not available. Additional error description (additional_description) will contain the line with payment system clarifications
350 Discount is already applied One discount coupon has been applied earlier (when trying to repeatedly apply the same of another discount coupon)
351 Incorrect discount coupon code Incorrect discount coupon code
352 This discount coupon has been deactivated This discount coupon has been deactivated
353 This discount coupon is not active now This discount coupon is not active now or yet
354 Limit of using this discount coupon is excessed Limit of using this discount coupon is excessed
400 Incorrrect order ID Incorrrect order ID
1000 Unknown error Unknown error

Up

Interfaces description

0. Session creation (session_start.php).

This item purposely has number 0. You should carefully read it and remember all that it says. Many moments in the further interface description won't be repeated - it is presupposed that you do remember all such moments.
To use interface data you should ALMOST ALWAYS (except specifically mentioned cases) first of all open the session (for every unique customer). The session - is practically the analog to PHP session. It is opened by creating the query to the file:
session_start.php

Request parameters:
shop - Your shop ID in the system (required parameter)

Return:
In the answer you'll receive the identifier-line of the opened session which you have to save to your computer to use it for further referring to external interfaces.
1. In case of a simple query that will be just the session code:
session
2. In case of XML-structure query it will look like this:
<session> - session code

ATTENTION1 (this is important!!!): The session should not be opened at once for every user. It should be opened only when the user decided to become the customer namely when he's put the product to the shopping cart OR when he decided to register in the system.
ATTENTION2: You DON'T have the right to open the session more than once for one customer. Repeated referring to this file will lead to the loss of the previous session identifier for this user and as a result all data on the previous session will be lost, too.

Up

Here is a good PHP code for session opening (this code should be included into the script where the product is put to the shopping cart):
<?
session_start();
if (!$_SESSION['SHOPXML_SESSION']) {
$tmp=file("http://shopxml.com/EXTERNAL/session_start.php?shop=$MyShopID");
if (strpos($tmp[0],'error|')===0) my_process_error($tmp);
else {
$SHOPXML_SESSION=$tmp[0];
session_register('SHOPXML_SESSION');
}
}
else $SHOPXML_SESSION=$_SESSION['SHOPXML_SESSION'];
?>
Up

As a result of this code performance in the $SHOPXML_SESSION valuable you'll have the current session identifier.
The my_process_error() function in the example - is your error processing function.

Here is the code that should be used in all other scripts:
<?
session_start();
$SHOPXML_SESSION=$_SESSION['SHOPXML_SESSION'];
?>
 By the way, the SHOPXML_SESSION name for the given valuable is used not accidentally! When making inquiries to the system (referring to interfaces) you should use the very name for session identifier submission. For example:
http://shopxml.com/EXTERNAL/filename.php?SHOPXML_SESSION=$SHOPXML_SESSION

Up

So, we sum it all a little bit up.
Here are several things you should make clear to yourself and which won't be repeated below:

1. All files for external interface use are here:
http(s)://shopxml.com/EXTERNAL/
2. To use any (except the separately mentioned ones) interfaces you should preliminary open the session one time (!) for every unique customer (and not any user) with the help of the 0 interface.
3. When referring to any interface (except the 0 one and those where it will be personally stated that it is not required) it is necessary to submit the unique identifier of the preliminary opened session for the current customer SHOPXML_SESSION session
4. To receive as an answer from any XML-structure the interface when making a query submit the GET_XML=1 parameter (again except the separately specified cases where this parameter doesn't play any part.
At that if you want to receive XML in UTF-8 coding (and not in windows-1251 one which is used on default) then you should submit the GET_UTF8=1 parameter.
The answer as XML will always (even in case of an error) have external tags - further on these tags won't be mentioned.
5. When referring to any interface as an answer you may receive the error - don't forget to process it.
Up

1. Putting the product to the shopping cart (add_to_cart.php).


To put the prduct to the shopping-cart you should request the file:
add_to_cart.php

Request parameters:
product - product ID (required parameter)
quantity - quantity (optional parameter) - default value is 1
new_name - redefined name for the given product in your shop (optional parameter)
attributes_by_code - flag (=1), indicate that you use a new format for indication product's options (required from Dec 20, 2008). In this case in the option's names and values, specified below, you need use attrCode and optCode instead attrID and optID
Besides these three parameters you must also submit the selected options for the product attributes if there are any. The options are submitted according to the rules described above (for the options' selection form). I'll repeat them here:
attr[attrID] - for attributes of 0 and 1 types (obligatory and optional choice). The optID value should be submitted.
attr[attrID][optID] - for attributes of type 2 (multiple choice). The value 1 should be submitted if the option is selected.
quest[attrID][optID] - user answers to additional questions to selected options.
get_quantity - submit 1 if you want to receive the total value of products in the shopping cart as an answer.

Return:
In the answer (if no error occured that you don't forget to process as far as I know) the shopping cart product index (integer value from -1) will be Returned to you. You should remember - further (if required) you will use this index for operations with the shopping cart (delete the product, change the quantity). Important only for products having attributes as it is not possible to unambiguously identify them in the shopping cart only by ID (as there can be several positions of this product in the shopping cart with different attribute options selected). In this case the index will equal 0-... In case of the simple product the index always equals index=-1. Also if you have set get_quantity=1 in the query then the total product quantity in the customer shopping cart will be the second Returned value.
1. In case of a simple query this will be only the code line:
index or index|quantity - if get_quantity=1 was set
2. In case of XML-structure query it will look like this:
<index> - code
<quantity>* - if get_quantity=1 was set

Attention: As it is quite difficult to form the options' selection form by yourself according to all rules don't forget about the existing possibility to export this form using the following query (that should be certainly made only when the product has attributes):
http://shopxml.com/EXPORT/product.php?shop=shopID&product=prodID&template=FORM&quantity=Quantity&new_order_url=YourActionURL
Here template and quantity are still optional parameters.
But pay attention (!) on the new (not mentioned before) new_order_url parameter introduced specifically for this case. Using this parameter you can submit the url-address which is necessary to be set into Action of the options' selection form - your script-processor address. Thus in this script you will be able just to submit add_to_cart.php all data obtained from this form.
Up

Here is an example of good PHP function which Returns the line of adding to url by submitting all the parameters required by the page into it (but not further than to the second-level massives):
<?
function translate_to_url() {
$P=array_merge($_GET,$_POST);
$str='';
foreach ($P as $k=>$v) {
if (!is_array($v)) { $str.="&$k=".urlencode($v); continue; }
foreach ($v as $k1=>$v1) {
if (!is_array($v1)) { $str.="&{$k}[$k1]=".urlencode($v1); continue; }
foreach ($v1 as $k2=>$v2)
if (!is_array($v2)) $str.="&{$k}[$k1][$k2]=".urlencode($v2);
}
}
Return $str;
}
?>

Example of use:
<?
$URL="http://shopxml.com/EXTERNAL/add_to_cart.php?SHOPXML_SESSION=$SHOPXML_SESSION".translate_to_url();
$res=implode('',file($URL));
?>
Up

2. Export of the shopping card content as well as of some other useful information (cart.php).


To find out what there is in the user's shopping card as well as some information on the order price (though ideally you have to dublicate this information on your computer) you should request the following file: cart.php
Attention: you should request this file if there already exists the opened session (which you have to open only when moving the product to the shopping cart)! If there is no shopping cart then it is obvious that the shopping cart is empty.
Request parameters:
new_update_url - only in case of a simple (without GET_XML=1) query. The url-address which is required to be set into the Action of the shopping cart refresh form.
new_edit_item_url - only in case of a simple (áåç GET_XML=1) query. The url-address which is required to be set into the selected options editing link for the products with attributes in the shopping cart.
Attention: The index parameter in the new_edit_item_url will be added automatically.
new_cancel_discount_url - only in case of a simple (without GET_XML=1) query. The url-address which is required to be set into the link to cancel the applied discout coupon. If it is not specified then the corresponding link won't exist

Return:
In the answer the complete information on the shopping card content will be Returned.
1. In case of a simple query this will be the shopping card HTML code:
HTML-code
2. In case of the XML-structure query it will look like this:
<products> - products list
quantity - product quantity in the shopping cart
weight - total weight of products in the shopping cart
price - total price of products in the shopping cart
tax* - total tax sum (if the customer has already entered the billing address and if the tax doesn't equal 0)
ship* - delivery costs (if the customer has already entered the shipping address and the delivery sum doesn't equal 0)
price_full - full price (products+taxes+delivery)
discount* - sum of the received discount (if it is applied)
discount_products* - product discount part
discount_tax* - tax discount part
discount_shipping* - delivery discount part
<product>* - product (for every position in the shopping cart)

ID - product ID (remeber that the products with attributes will be repeated if put several times)
index* - position index in the shopping cart for products with attributes
Required as such a product can be put several times and in this case the sole ID number is not enough for identification. Besides it serves as an identifier when editing this position in the shopping cart.
<name> - name
quantity - quantity for this position in the shopping cart
weight - total weight of this position in the shopping cart (that is taking into account the quantity)
price_one_wo_attr* - price of one product in this position not taking into account the attributes' price (if the product has some attributes)
price_one - price of one product in this position
price - position price (that is taking into account the quantity)
tax* - tax sum for this position (if it doesn't equal 0)
price_full - total position price (taking into account taxes)
<attributes> - line with enumeration of the selected attribute options

Up

3. Shopping cart content change (cart_update.php).


To change the shopping cart content (change the product quantity, delete product) you should request the following file: cart_update.php

Request parameters:
prod[prodID] - products' quantity in the order position. Obligatory for simple products that is for products that do not have attributes
fprod[index] - products quantity in the order position. Obligatory for products with attributes.
Pay attention that in this case not only the product ID is specified in brackets, but also the position index in the shopping cart. This is the very index that is Returned when adding the product to the shopping cart. You can also find it out by requesting the shopping cart content in XML format (interface 2).
Attention (!!!) The sum of these parameters should be present for every position in the shopping cart. That is for every simple product - the 1st parameter, for every product with attributes - the 2nd one. In case you accidentally skip the parameter for any position it will be counted as 0 - and the product will be deleted from the shopping cart.
The two below mentioned parameters are optional. They could be successfully substituted correspondingly by the first 2 ones with the 0 value
del_prod[prodID] - submit 1 if it is necessary to delete the position. Only for simple products that is for products without attributes .
del_fprod[index] - submit 1 if it is necessary to delete the position. Only for products with attributes.
get_quantity - submit 1 if you want to receive information on the total products' quantity in the shopping cart as an answer.

Pay attention that the Request parameters of this interface are just the same as the fields in the form when using interface 2 in HTML export mode - that is per se you can (and so it was thought over) just make the export of his form to your page changing it for Action-à (new_update_url) to your script address. In your script you should just insert all the data received from the form into your query to this interface (see the function example above). And, of course, don't forget about the other necessary parameters.
Return :
In the answer (if no errors occured) you will be Returned 1 or quantity - total products' quantity in the shopping cart (can also equal 0) if you haven't set get_quantity=1
1. In case of a simple query:
1 or quantity
2. In case of XML-structure query it will look like this:
<code> - 1 or quantity
Attention: When updating the shopping cart using this interface no error occurs if the quantity of any product is higher than there is available. In this case the maximum possible quantity value will be set.

Up

4. Receive the options' selection change form in the shopping cart (item_edit.php).


Additional interface (to facilitate the use of the next 5th interface). Using this interface you can receive the ready form to change the selected product options in the shopping cart (for products with attributes). You should request the following file:
item_edit.php

Request parameters:
index - position ID in the shopping cart for editing (its location was mentioned above)
new_item_update_url - url-address which is required to be set as Action in the form of editing the selected options of the products with attributes in the shopping cart.
template - template that should be used for the product at options' editing (the default value is FORM - that is an empty form

Return:
In the answer the HTML-code of the options' selection form will be always Returned to you. The GET_XML=1 parameter is not valid here as it has no sense (even when an error occurs it will always be in another format than XML)
Attention: Basically the same result can be achieved using the extended method of form export):
http://shopxml.com/EXPORT/product.php?shop=shopID&product=prodID&template=FORM&quantity=Quantity&new_item_update_url=YourActionURL&index=IndexInCart
Also except the specified parameters you can submit those attribute values that have been already set according to the already known rules:
attr[attrCode] - for attributes of type 0 and 1 (obligatory and optional choice). The optCode value should be submitted
attr[attrCode][optCode] - for the attributes of type 2 (multiple choice). The 1 value should be submitted if the option is selected.
quest[attrCode][optCode] - user answers to additional questions to the selected options.

Here template and quantity are still optional parameters.
index - position index in the shopping cart
new_item_update_url - this the url-address that is required to be set into Action of the options' selection form - address of your script-processor. Thus you will be able just to submit all data received from this form in the query to item_update.php (the next interface - 5) in your own script.

Up

5. Change of product options in the shopping cart (item_update.php).


To change the selected product options in the shopping cart (for products with attributes) you should request the following file:
item_update.php
Request parameters:
index - position index in the editing shopping cart (required parameter)
product - ID of the given product. Optional parameter, but it is recommended to specify it :)
quantity - new quantity for this position in the shopping cart (required parameter)
attributes_by_code - flag (=1), indicate that you use a new format for indication product's options (required from Dec 20, 2008). In this case in the option's names and values, specified below, you need use attrCode and optCode instead attrID and optID
Besides these parameters you also must submit the selected options for product attributes. Options are submitted according to the rules which have been described above (for the options' selection form, as well as for the interface 1 - add_to_cart.php). I'll repeat them here:
attr[attrID] - for attributes of type 0 and 1 (obligatory and optional choice). The optID value should be submitted
attr[attrID][optID] - for attributes of type 2 (multiple choice). The 1 value should be submitted if the option is selected.
quest[attrID][optID] - user answers to additional questions to the selected options.
get_quantity - submit 1 if you want to receive the total product quantity in the shopping cart as an answer.

Return: The 1 or quantity will be returned to you (if no errors occured) - total product quantity in the shopping cart (may also equal 0) if you have set get_quantity=1
1. In case of a simple query:
1 or quantity
2. In case of the XML-structure query it will look like this:
<code> - 1 or quantity

Up

6. Get the login form for the user (login_form.php) - only https.


Additional interface (to facilitate the use of the following interface 7 as well as the cases if you want to make your customer "personal cabinet" in your shop where he could, for example, view the history of his purchases and so on). Using this interface you can receive the ready customer's login form. You should request the following file:
login_form.php
Attention: This interface DOESN'T require the submission of the SHOPXML_SESSION parameter, but it will be better if you still continue submitting it as the request of this interface has no sense . If the customer is already logged in (you'd better save this information somewhere in your own session and if he is already logged in doesn't request this interface at all). Summing up:
- If you don't submit SHOPXML_SESSION then you'll always receive the result (HTML form code)
- if you submit it then the interface will give back either the result or the corresponding error if the session is incorrect or the customer is already logged in and so on.

Request parameters: email - Customer E-Mail address (it is also the login) (optional parameter)
password - customer password (optional parameter)
new_login_url - url-address that is required to be set as Action in the login form (optional parameter)
Attention: If the new_login_url is not specified then the user will be automatically redirected from this page to continue the purchase form filling in to the main system site.

Return: The HTML login form code will be always returned to you. The GET_XML=1 parameter is here not valid as it makes no sense (even in case when an error occurs it will always be in ANOTHER format than XML)
Up

7. Customer system login (login.php) - only https.


To login the customer to the system (to register the purchase) you should request the following file:
login.php
This interface serves not only in order the customer could enter the system, but also it can be of use to organize the password reminding and reset to the system (that is automatical generation of new password).

Request parameters :
email - Customer E-Mail address (it is also the login) (required parameter)
password - customer password (required parameter when making the login)
dologin - 1 - login indicator (required parameter when making the login)
doreset - 1 - password reset indicator (required parameter to reset the password)

get_customer_id - if you don't set this parameter in 1 then this customer ID will return to you in the login_status field in the answer

Return : The login_status will be just returned to you (if no errors occured) in the answer - 1 or customer ID (integer positive value) if you have set get_customer_id=1, - if the login is correct, 0 - if the either reminder was made or the password reset.
password - old password if the password reminder was made or the newly password was generated if the password wasn't reset.
Attention: Password (both the reminded and the generated one) can be only sent to the user's E-Mail! It is prohibited to be shown right on the page in security purposes!
These data will be displayed as:
1. In case of a simple query:
login_status|password
2. In case of the XML-structure query it will look like this:
<login_status>* - if the login was made (dologin=1)
<password>* - if the password reminder was made (without the parameter) or it was reset (doreset=1)

Up

8. Receive information on entering the shipping and billing addresses or the form for their entry (addresses.php) by the customer - only https.


Using this interface you can receive the possible list of ñîuntries and regions (states/provinces) for every of these lands in XML format or the ready form to enter this information by the customer. You should request the following file:
addresses.php
Attention: If obtained from the server this form will include the customer registration fields in the system except the enter address fields if this is a new (that is unlogged) customer. If you are a brave person and will build this form yourself don't forget about these fields as it will be required to use them in the next 9th interface (it will be specified below which namely).

Request parameters :
All parameters are optinal and are used only at requesting the HTML-form, that is at GET_XML=1 they are all idle. Besides, all these parameters except the new_addresses_url one are valid only when the user is unlogged (only in the registration process) or this interface hasn't been used successfully in this session yet - that is the user makes the first purchase when "coming" to the shop. Otherwise these parameters will be set automatically.
email - Customer E-Mail address (it is also the login) (only when he is not logged in)
password - customer password that he has to select (only if he is not logged in)
password1 - customer password in the password confirmation field (only if he is not logged in)
new_addresses_url - url-address that is required to be set as Action in this form
Attention: If the new_addresses_url is not specified the user will be automatically redirected then from this page to the main system site to continue the puchase registration.
sel_addr2 - customer shipping address ID from his address list
If the customer makes the purchase for the first time then all entered addresses are saved and when next purchases are made he may not enter them again and just select them from the given list.
Values:
0 - enter new address
more than 0 - address ID from the list
sel_addr1 - customer billing address ID from his address list
Values:
0 - enter new address
-1 - the same as the shipping address
more than 0 - address ID from the list

first_name2 - shipping first name
last_name2 - shipping last name
company2 - shipping company name
address21 - shipping address line 1
address22 - shipping address line 2
city2 - shipping city
state2 - shipping state/province (province ID for particular country)
zip2 - shipping zip/postal code
country2 - shipping country (country province ID)
tel2 - shipping telephone

first_name1 - billing first name
last_name1 - billing last name
company1 - billing company name
address11 - billing address line 1
address12 - billing address line 2
city1 - billing city
state1 - billing state/province (province ID for particular country)
zip1 - billing zip/postal code
country1 - billing country (country province ID)
tel1 - billing telephone

comment - customer comment

Return: 1. In case of a simple query the HTML-code form will be returned to you.
2. In case of the XML-structure query it will look like this:
<addresses>* - address list for the given customer
<address> - address (repeated for every address)
ID - address ID
<name> - name
<countries> - countries' list
<country> - country (repeated for every country)
ID - country ID
<name> - name
<zones>* - provinces' list for particular country (if there are such)
<zone> - province (repeated for every province)
ID - province ID
<name> - province name

Up

9. Customer shipping and billing addresses entering + registration of the customer in the system if he is not already logged in (addresses_process.php) - only https.

Using this interface you should provide saving of the customer shipping and billing addresses entered into the system as well as simultaneously his registration if he is new here (that is not already logged in). You should request the following file :
addresses_process.php

Request parameters :
email - E-mail address (it is also the login) of the customer being registered (required parameter if the customer is not already logged in)
password - password selected by the customer being registered (required parameter if the customer is not already logged in)
password1 - password entered by the customer being registered into the password confirmation field (required parameter if the customer is not already logged in)
sel_addr2 - Customer shipping address ID from his address list if the logged-in customer has selected it
Values:
0 - new address
more than 0 - address ID from the list
sel_addr1 - customer billing address ID from his address list if the logged-in customer has selected it
Values:
0 - new address
-1 - the same as the shipping address
more than 0 - address ID from the list

The following parameters (even marked as required) are valid only when either the sel_addr2=0 or is not specified at all (that is when the customer enters the new shipping address). Otherwise the parameters marked as required can (should) not be specified.
first_name2 - shipping first name (required)
last_name2 - shipping last name (required)
company2 - shipping company name
address21 - shipping address line 1 (required)
address22 - shipping address line 2
city2 - shipping city (required)
state2 - shipping state/province (province ID for particular country) (required only if the selected country has states. Otherwise it can either equal 0 or be absent at all)
zip2 - shipping zip/postal code (required)
country2 - shipping country (country province ID) (required)
tel2 - shipping telephone (required)

The following parameters (even marked as required) are valid only when either the sel_addr1=0 or isn't specified at all (that is when the customer enters the new billing address). Otherwise the parameters marked as required can (should) not be specified.
first_name1 - billing first name (required)
last_name1 - billing last name (required)
company1 - billing company name
address11 - billing address line 1 (required)
address12 - billing address line 2
city1 - billing city (required)
state1 - billing state/province (province ID for particular country) (required only if the selected country has states. Otherwise it can either equal 0 or be absent at all)
zip1 - billing zip/postal code (required)
country1 - billing country (country province ID) (required)
tel1 - billing telephone (required)

comment - user comment

get_customer_id - if you set this parameter in 1 the current customer ID will be returned to you in the answer

Return : In the answer (if no error occured) simply 1 and the current customer ID (integer positive value) will be returned to you if you haven't set get_customer_id=1
1. In case of a simple query:
1 or ID
2. In case of the XML-structure query it will look like this:
<code> - 1 or ID

Up

10. Get information on possible order delivery variants (shipping) or the shipping selection form (shipping.php)

Using this interface you can receive either the list of available delivery methods' price for the specified customer shipping address in XML format or the ready form to enter new customer information. You should request the following file :
shipping.php

If you receive the HTML form then as usual you can use the data obtained from it directly in the next 11th interface.

Request parameters :
new_shipping_url - url-address required to be set as Action in this form

Return :
1. In case of a simple query the HTML form code will be returned to you.
2. In case of the XML-structure query it will look like this:
<shippings> - delivery methods list
<shipping> - delivery method (repeated for every way)
ID - delivery method ID (line!!!)
price - delivery method price
<name> - delivery method name

Up

11. Delivery method selection (shipping_process.php).

Using this interface you should specify the delivery method selected by the customer. You should request the following file:
shipping_process.php

Request parameters :
ship - delivery method ID - line (in XML figured as ID) (required parameter)

Return :
In the answer simply 1 will be returned to you (if no error occured)
1. In case of a simple query:
2. In case of the XML-structure query it will look like this:
<code> - 1
Up

12. Receive the information on possible payment methods or the payment method form (payment.php) - only https

. Using this interface you can receive the information on possible payment methods in XML format or the ready form to enter the customer information.
In case of a simple query you receive the form containing also the discount coupon code enter field if no discount coupon has already been applied by the customer in earlier stages (the extended interfaces for that will be described below)
You should request the following file:
payment.php

If you receive the HTML form then as usual you can use the data obtained from it directly in the next 13th interface.

Request parameters :
new_payment_url - url-address required to be set as Action in this form
new_cvv_url - url-address required to be set in the link to credit card CVV-code instruction
discount_code - discount coupon ID that should be set into the corresponding form field (if the discounts haven't been applied before)
no_discount - submit 1 if you do not want that the field to enter the discount coupon be present in the payment form (if the discount has already been applied it will be absent in any case)
The below mentioned parameters will be taken from the already known data if you specify them or the old data will be automatically taken if the customer has already made successful purchases in this session:
cc_name - credit card owner name
m_cc_type - credit card type (for payment method 2) - see below
cc_number - credit card number
cc_month - credit card expire month 1-12
cc_year - credit card expire year - 4-digit
cc_id - credit card CVV-ID SHOULD NOT BE SUBMITTED - it won't be interpreted (for security purposes).
Possible credit card types (for payment method 2):
0 - Visa
1 - Master Card

Return :
1. In case of a simple query the HTML form code will be returned to you.
2. In case of the XML-structure query it will look like this:
<payments> - payment methods' list
payment method
<payment> - payment method (repeated for every method)
ID - method ID (this is a line)
<name> - method name
<discount_code>* - the earlier applied discount coupon ID will be displayed if it has been applied (that is you are not able to apply them again until you cancel the old one - see extended interfaces below)

Up

13. Payment process (payment_process.php) - only https.

Using this interface you should speicify the payment method selected by the customer. This interface makes payment at once - this is the final ordering process stage. You should request the following file:
payment_process.php

Request parameters :
system - payment method ID - line (in XML figured as ID) (required parameter)
customer_ip - customer IP-address. As you may understand we ourselves cannot define the IP address of your customer if you use external interfaces. That's why if you want additional customer control by this parameter you should submit it, moreover, it is not so difficult. To define the IP-address in PHP there is the $_SERVER['REMOTE_ADDR'] valuable (when submitting don't forget to url-code it as well)
discount_code - discount coupon ID that should be applied to this purchase (if no discounts have been applied before. If the discounts have been applied and you submit this parameter not empty then you'll receive an error)
get_detailed_info - submit 1 if in the answer you want to receive the detailed information on order registration

You should also submit the following data depending on the selected payment method:

Method 1: ID=authorize - credit card payment
cc_name - credit card owner name (required parameter)
cc_number - credit card number (required parameter)
cc_month - credit card expire month from 1-12 (required parameter )
cc_year - credit card expire year - 4-digit (required parameter)
cc_id - credit card CVV-code (required parameter)

Method 2: ID=manual - credit card payment (for some products used instead of method 1)
cc_name - credit card owner name (required parameter)
m_cc_type - credit card type (required parameter)
cc_number - Credit card number (required parameter)
cc_month - Credit card expire month from 1-12 (required parameter)
cc_year - Credit card expire year - 4-digit (required parameter)
cc_id - (required parameter)
cc_id - Credit card CVV-code ()

Method 3: ID=hsbc - credit card payment (processing HSBC)
cc_name - credit card owner name (required parameter)
cc_number - credit card number (required parameter)
cc_month - credit card expire month from 1-12 (required parameter )
cc_year - credit card expire year - 4-digit (required parameter)
cc_id - credit card CVV-code (required parameter)

Return : In the answer if no error occured the order ID will be returned to you if you haven't requested the detailed information. Or the following fields if you have requested it (get_detailed_info=1):
ID - order ID product_num - quantity of subjects in the order
price - order price (the customer paid that is taking into account discounts if there were any)
price_products - products price in the order (taking into account discounts if there were any)
price_tax - tax sum in the order (taking into account discounts if there were any)
price_shipping - delivery price (taking into account discounts if there were any)
discount - received discount sum (if there were any)
discount_products - products discount
discount_tax - tax discount
discount_shipping - delivery discount
Note that futher on this list can be extended, but the fields will be always added "to the end of the list"

1. In case of a simple query:
ID
- if the detailed information is requested
ID|product_num|price|price_products|price_tax|price_shipping|discount|discount_products|discount_tax|discount_shipping
- if the detailed information was requested (get_detailed_info=1)
2. In case of the XML-structure it will look like this:
<ID> - order ID - always
<product_num> - see the value above (if the detailed information was requested)
<price> - see the value above (if the detailed information was requested)
<price_products> - see the value above (if the detailed information was requested)
<price_tax> - see the value above (if the detailed information was requested)
<price_shipping> - see the value above (if the detailed information was requested)
<discount> - see the value above (if the detailed information was requested)
<discount_products> - see the value above (if the detailed information was requested)
<discount_tax> - see the value above (if the detailed information was requested)
<discount_shipping> - see the value above (if the detailed information was requested)

Necessary note:
If the customer makes the second order that is he has made one order and then gathered another shopping cart and makes the order then the shipping options are not saved as the shipping methods and price depend on what is in the shipping cart and how much does it cost. The same is when the customer selected the shipping methods during the first order and then has either added something to the shopping cart or deleted something from it, or changed the quantity then he should go through all the stages starting from addresses_process.php (that you can perform without participation of the user) again - it is necessary as the very interface calculates the delivery methods and price depending on the shopping cart content and shipping address.
As far as you can see having studied the provided interfaces they are designed not only to ensure the necessary functionality, but also maximally facilitate the system build on their background to the web-master if he wants it. For that he should just export all forms in HTML directly to his pages not involving into building them by himself. The data received from these forms should be just "transmitted" from the action-scripts into the corresponding server interfaces. At that you can quite organically write all these forms into your pages colouring them using styles (HTML-code contains the written-in styles for many elements - see right in the code). The person familiar with CSS can significantly succeed in this. And the very demanding ones can transform the received HTML-code using inline functions, regular expressions and so on. If you won't be even satisfied with this the only thing that remains to work with XML and build your own forms.
To end up with the system familiarization and the consequence of work with external interfaces if something remained unclear you may study the following scheme:

Additional external interfaces
The above described interfaces as you could note (including those from the depicted scheme) are required and there is enough basis for working with the system. Moreover, it is even a little bit abundant in features as, for example, you could create the login form yourself without using the corresponding interface and the same is about the shopping card. Because to know its content you don't necessarily need to request the system - you can concurrently store its content on your computer. But nevertheless these interfaces are able to facilitate your life. Below you'll find the additional interfaces created to complications and specific features enumeration. For example, to create the cursomer's personal cabinet where he can view the status of his orders or change his password...
Attention: The above provided scheme of external interfaces use is correct only if you use the main interfaces. If you use additional interfaces then there will appear additional blocks and branches. For example when starting the product purchase registration you won't need that the page with the login form be shown if the customer has already logged into the system before. It will be redirected to the enter address page at once. There will be no new scheme that would take into account all new interfaces built. If you have already managed to create the shop using basic interfaces then you should now be clear in your mind about all specificity and the subject matter. That is you should gain the understanding where and how to use additional interfaces yourself and what corrections would their use introduce into the user site movement scheme.
Up

14. Get the new customer registration form (register_form.php) - only https.

Additional interface (to facilitate the use of the following 15th interface. You should request the following file:
register_form.php

Attention: This interface DOESN'T require the SHOPXML_SESSION parameter submission, but it would be better if you continue submitting it, as the request of this interface has no sense , if the customer is already logged into the system (you'd better save this information somewhere in your own session and if already logged in don't request this interface at all). Summing up:
- If you don't submit SHOPXML_SESSION then you'll always give back the result (HTML form code)
- if you won't submit it then the interface will give back either the result or the corresponding error if the session is wrong or the customer is already logged into the system and so on.

Request parameters :
first_name - customer first name (optional parameter)
last_name - customer last name (optional parameter)
email - customer E-Mail address (it is also the login) (optional parameter)
password - customer password (optional parameter)
password1 - confirmed customer password (optional parameter)
new_register_url - url-address required to be set as Action in the registration form (optional parameter)

Attention: If new_register_url is not specified then the user will be automatically redirected from this page to the main system site.

Return :
In the answer the HTML registration form code will always be returned to you. The GET_XML=1 parameter is not valid here as there is no sense (even when the error occurs it will always be in another than XML format)

Up

15. Customer registration to the system (register.php) - only https.

To register the customer to the system you should request the following file:
register.php

Request parameters: first_name - customer first name (optional parameter)
last_name - customer last name (optional parameter)
email - customer E-Mail address (it is also the login) (required parameter)
password - customer password (required parameter)
password1 - confirmed customer password (required parameter)
get_customer_id - if you set this parameter in 1, then the ID conferred to this user will returned to you in the answer in the register_status field

Return:
In the answer the
register_status (if no error occured) - 1 or customer ID (integer positive value) will be Returned to you if you set get_customer_id=1
1. In case of a simple query:
register_status
2. In case of the XML-structure query it will look like:
<register_status>
Up

16. Customer logout from the system (logout.php).

To log the customer out you should request the following file:
logout.php

Request parameters :
absent (certainly except the obligatory SHOPXML_SESSION)
Return:
In the answer the logout_status - 1 will be Returned to you (if no error occured)
1. In case of a simple query:
logout_status
2. In case of the XML-structure query it will look like:
<logout_status>

Up

17. Get the customer password change form (password_form.php) - only https.

Additional interface (to facilitate the use of the next 18th interface. You should request the following file:
password_form.php

Request parameters :
password - current customer password (optional parameter)
new_password - new customer password (optional parameter)
new_password1 - confirmed new customer password (optional parameter)
new_password_url - url-address required to be set as Action in the password change form (optional parameter)
Attention: If the new_password_url is not specified then the user will be automatically redirected from this page to the main system site.

Return :
In the answer you'll always get back the HTML change password form code. The GET_XML=1 parameter is not valid here as there is no sense (even when the error occurs it will always be in another than XML format)
Up

18. Password change by the customer (password.php) - only https.

To change the customer password in the system you should request the following file:
password.php

Request parameters :
password - current customer password (required parameter)
new_password - new customer password (required parameter)
new_password1 - confirmed new customer password (required parameter)

Return :
In the answer just the
password_status - 1 will be Returned to you (if no error occured)
1. In case of a simple query:
password_status
2. In case of the XML-structure query it will look like this:
<password_status>

Up

19. Get information on the quantity of products in the customer shopping cart (quantity.php).

To find out about the quantity of products in the customer shopping cart you should request the following file:
quantity.php
However it is not recommended to use this interface (it is created just to be on the safe side) as you can find out about the quantity of products in the shopping cart directly using the interfaces which may involve this quantity by submitting the get_quantity=1 parameter (described above in the corresponding interfaces).

Request parameters :
absent (certainly except the obligatory SHOPXML_SESSION)
Return :
In the answer the
quantity - product quantity will be Returned to you
1. In case of a simple query:
quantity
2. In case of the XML-structure query it will look like this:
<quantity>

Up

20. Get the discount coupon form (discount_form.php).

Additional interface (to facilitate the use of the next 21st interface. You should request the following file:
discount_form.php

Request parameters :
discount_code - discount coupon code (to be shown in the corresponding field)
new_discount_url - url-address required to be set as Action in the form
Attention: If new_discount_url is not specified then the user will be automatically redirected from this page to the main system site.

Return :
As an answer you'll always receive the HTML discount coupon enter form code. The GET_XML=1 parameter is not valid here as there is no sense (even when the error occurs it will always be in another than XML format).
If the discount has already been applied then the corresponding error will be returned.
Up

21. Application or cancellation of the discount coupon (discount.php).

Using this interface you can apply the discount to the customer order. You can apply it absolutely in any stage - both in the shopping card and directly before the payment - only when the session is opened. You should request the following file:
discount.php

Request parameters :
discount_code - discount couponcode that should be applied to the current purchase (if the discounts haven't been applied before. If there were some you'll get an error)
delete - submit 1, if you want to cancel the discount applied before (you surely shouldn't submit the code in this case)

Return :
In the answer you'll see the following fields if there were no errors:
price - current order price (taking into account discounts if applied)
price_products - price for products in the order (taking into account discounts if applied)
price_tax - tax sum in the order (taking into account discounts if applied)
price_shipping - shipping price (taking into account discounts if applied)
discount - sum of the received discount (if applied)
discount_products - products discount part
discount_tax - tax discount part
discount_shipping - shipping discount part

1. In case of a simple query:
price|price_products|price_tax|price_shipping|discount|discount_products|discount_tax|discount_shipping

2. In case of the XML-structure query it will look like this:
<price> - see the value above (if the detailed information was requested))
<price_products> - see the value above (if the detailed information was requested)
<price_tax> - see the value above (if the detailed information was requested)
<price_shipping> - see the value above (if the detailed information was requested)
<discount> - see the value above (if the detailed information was requested)
<discount_products> - see the value above (if the detailed information was requested)
<discount_tax> - see the value above (if the detailed information was requested)
<discount_shipping> - see the value above (if the detailed information was requested)

Up

22. Get the table with the information on the current order (cart_info.php)

Additional interface. This table contains information on the discount if it was applied as well as it can contain the discount coupon apllication form if the discount wasn't applied yet. You should request the following file:
cart_info.php
Request parameters :
discount_code - discount coupon code (to be shown in the corresponding field in the form if the discount wasn't applied)
new_discount_url - url-address required to be set as Action in the discount coupon application form
no_discount - submit 1 if you don't want that the discount coupon enter form be present in the table with order information (if the discount was already applied there will be no discounts in any case)
new_cancel_discount_url - url-address required to be set in the link to cancel the applied discount coupon. If not specified then there will be no corresponding link
Attention: If new_discount_url is not specified the user will be automatically redirected from this page to the main system site.

Return :
In the answer you'll always receive the HTML-code with the table. The GET_XML=1 parameter is not valid here as there is no sense (even when the error occured it will always be in another than XML format).
Up

23. Customer orders' history export (orders.php)

To get information on the orders' history of the current customer (should be logged in for now) you should request the following file:
orders.php

Request parameters:
new_order_view_url - only in case of a simple (áåç GET_XML=1) query. Url-address required to be set in the link to receive the detailed information on the specific order. If this parameter is not specified this link will be absent.
Attention: the ID parameter in new_order_view_url will be added automatically.

Return:
As an answer you'll receive the information on the customer orders' history.
1. In case of a simple query it will be the table HTML-code with the list of orders:
HTML-code
2. In case of the XML-structure query it will look like:
<orders> - orders list
<order>* - order (for every order)
ID - order ID
time - order time in UNIX_TIMESTAMP
time_str - order time clear line
price - total order price (includes products, taxes, shipping), paid by the customer (that is taking into account the discounts)
price_prd - price only for products in the order
price_tax - taxes
price_ship - order shipping price
discount - total discount received by the customer
discount_prd - product discount part
discount_tax - taxes discount part
discount_ship - order shipping price part
status - order status - number (see below)
status_str - order status - clear definition (see below)

Possible order statuses:

Up

24. Export of the detailed information about the customer order (order_details.php)

. To get the detailed information on the specific order of the current customer (should be logged in for now) you dhould request the following file:
order_details.php

Request parameters :
ID - order ID (obligatory parameter)

Return :
As an answer you will receive the complete information on the order.
1. In case of a simple query you will get the HTML-code of the table containing information about the order:
HTML-code
2. In the XML-structure query it will look like this:
<order> - order
ID - order ID
time - order time in UNIX_TIMESTAMP
time_str - order time in clear line
price - total order price (includes products, taxes, shipping), paid by the customer (that is taking into account the discounts)
price_prd - price only for the products in the order
price_tax - taxes
price_ship - order shipping price
discount - total discount received by the customer
discount_prd - product discount part
discount_tax - taxes discount part
discount_ship - order shipping price discount part
status - order status - number
status_str - order status - clear definition
boxes - number of boxes the order was sent in (should be a very large order that the number of boxes exceeded 1)

<products> - products list
quantity - quantity of products in the order
weight - total products' weight in the shopping cart
<product>* - product (for any position in the order)
ID - product ID (products with attributes if they were put several times then they will be repeated)
<name> - name
quantity - quantity for te given position in the order
weight - total weight of this position in the order (that is taking into account the quantity)
price_one_wo_attr* - price of one product in this position without taking into account the attributes (if the product has some)
price_one - price of one product in this position
price - position price (that is taking into account the quantity)
tax* - tax sum for this position (if not 0)
price_full - total position price (taking into account the taxes)
<attributes> - line with enumeration of the selected options for attributes

<model> - product's model
<email> - customer E-Mail
<comment> - user order comment
<shipping_details> - selected shipping method (clearly written line)
<payment_details> - payment details (clearly written line)

<shipping_address> - shipping address - first name
<last_name> - last name
<company> - company name
<address1> - address line 1
<address2> - address line 2
<city> - city
<state> - state/province (full name)
<zip> - zip/postal code
<country> - country (full name)
<tel> - telephone
<fax> - fax

<billing_address> - customer billing address (payer)
<first_name> - first name
<last_name> - last name
<company> - company name
<address1> - address line 1
<address2> - address line 2
<city> - city
<state> - state/province (full name)
<zip> - zip/postal code
<country> - country (full name)
<tel> - telephone
<fax> - fax


Up

Contact Us Legal and Policies Sitemap
© XMLShop.com 2004 – 2013