WEBAPI Nop Commerce
WEBAPI Nop Commerce
List of Content
About the plugin .............................................................................................................................................. 3
Installation and configuration ......................................................................................................................... 3
Web API - description ...................................................................................................................................... 3
Examples.......................................................................................................................................................... 5
Example for CATEGORIES ............................................................................................................................ 6
1. GET all categories ............................................................................................................................ 6
2. GET category by id ({id=1}) .............................................................................................................. 6
3. GET Product list from category id ({id=2}) ....................................................................................... 6
4. POST (update) new category ........................................................................................................... 6
5. PATCH (partial update - the client specifies just the properties to update) ................................... 7
6. PUT (update category)..................................................................................................................... 7
7. DELETE category .............................................................................................................................. 8
Examples for CUSTOMERS........................................................................................................................... 8
1. GET customer (with expand options) .............................................................................................. 8
2. PUT (add) address for customer (which exists in table Addresses) ................................................ 8
3. DELETE address for customer (reference) ....................................................................................... 9
4. PUT (add) role to customer ............................................................................................................. 9
5. DELETE role for customer (existing role) ......................................................................................... 9
Examples for PRODUCTS ........................................................................................................................... 10
1. PUT (add) tag for product (existing tag) ........................................................................................ 10
Example for ORDERS ................................................................................................................................. 10
1. GET OrderDate .............................................................................................................................. 10
Example for IMAGE ................................................................................................................................... 11
1. Prepare Picture model................................................................................................................... 11
2. Prepare ProductPicture model ...................................................................................................... 11
Clear Cache (version 3.70) ......................................................................................................................... 12
Enabling Cross-Origin (version 3.70) ......................................................................................................... 12
Cross-Origin Example ................................................................................................................................ 12
Show data without value (count option) .................................................................................................. 15
Show all methods used ............................................................................................................................. 15
Order example ........................................................................................................................................... 16
List of supported tables ............................................................................................................................. 17
2
nop4you.com
About the plugin
Plugin Web API for nopCommerce (version 3.60) gives an access to business data stored in nopCommerce database.
It has been built in ASP.NET Web API and the OData provider.
More info about Web API can be found on http://www.asp.net/web-api.
Note: User should be familiar with nopCommerce database structure.
First of all, the Web API plugin has to be installed on the nopCommerce.
Only registered customers (in nopCommerce) with both keys (public and secret key) have got an access to the API. Web
API plugin uses customer roles and rights to authorize client (for getting/updating data) -> based on ACL in
nopCommerce.
Register customer for Web API (user should exist in nopCommerce as a registered user). Go to Plugin List -> (on
WebAPI plugin) Configure.
3
nop4you.com
Data model (metadata - i.e. structure and organization of all the resources) can be found under following link:
http://yourstore.com/odata/$metadata (Request Header is required).
Web API client can use OData options (like $filter, $top, $select etc.) and Web API specific options. More can be found
on http://www.asp.net/web-api.
Paging is required for querying multiple records. It can be done with OData $skip and $top.
Example 1:
How to prepare signature:
private string Signature()
{
string publicKey = YourPublicKey;
string secretKey = YourSecretKey;
if (String.IsNullOrWhiteSpace(secretKey) ||
String.IsNullOrWhiteSpace(publicKey))
return "";
string signature;
var secretBytes = Encoding.UTF8.GetBytes(secretKey);
var valueBytes = Encoding.UTF8.GetBytes(publicKey);
Result: authInfo =
YWRtaW5AeW91cnN0b3JlLmNvbTpjUGZzeC9GaWRCbE9TRzZGUVAvei9pVGt2RnNhMWNJaTY5ZDBKekMxWVh
JPQ==
4
nop4you.com
Examples
Examples (based on sample application) show how to build JSON client app.
It can be downloaded from http://nop4you.com/WebApi.zip
This is a sample application with source code to get/put/post/patch and delete request to your store using format
JSON.
Methods:
URL example for calories (client want to get information about category with Id=1): odata/Category or
odata/Category(1) (full address is: http://yourstore.com/odata/Category(1))
5
nop4you.com
Client can get columns, for example:
http://yourstore.com/odata/Category(1)?$select=*
http://yourstore.com/odata/Category(1)?$select=Id,Name
Client can use select extensions (to get additional data joined with ‘main’ data), for example you client call customer
with Id=1 and its addresses:
http://yourstore.com/odata/Customer(1)?$expand=Addresses
URL: http://yourstore.com/odata/Category
REQUEST HEADER:
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ== <- it should be generated for client (see example: link) - for all examples
PublicKey: 0c31c4ce25114e728504682d9aee5ca1 <- it should be generated for client
User-Agent: WebApiFornopCommerce
Accept: application/json
Accept-Charset: UTF-8
URL: http://yourstore.com/odata/Category(1)
REQUEST HEADERS:
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ==
PublicKey: 0c31c4ce25114e728504682d9aee5ca1
User-Agent: WebApiFornopCommerce
Accept: application/json
Accept-Charset: UTF-8
URL: http://yourstore.com/odata/
ProductCategory?$filter=CategoryId+eq+2&$expand=Category,Product
URL: http://yourstore.com/odata/Category
REQUEST HEADERS:
6
nop4you.com
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ==
PublicKey: 0c31c4ce25114e728504682d9aee5ca1
Content-Type: application/json; charset=utf-8
User-Agent: WebApiFornopCommerce
BODY:
{"Name":"Books55","Description":"test","CategoryTemplateId":1,"MetaKeywords":"Books, Dictionary,
Textbooks","MetaDescription":"Books category
description","MetaTitle":null,"ParentCategoryId":0,"PictureId":1,"PageSize":4,"AllowCustomersToSelec
tPageSize":true,"PageSizeOptions":"8, 4, 12","PriceRanges":"-25;25-50;50-
;","ShowOnHomePage":false,"IncludeInTopMenu":true,"HasDiscountsApplied":false,"SubjectToAcl":fal
se,"LimitedToStores":false,"Published":true,"Deleted":false,"DisplayOrder":1,"CreatedOnUtc":"2014-
04-05T08:46:31.007","UpdatedOnUtc":"2014-04-05T08:46:31.007","Id":16}
5. PATCH (partial update - the client specifies just the properties to update)
URL: http://yourstore.com/odata/Category(16)
REQUEST HEADERS:
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ==
PublicKey: 0c31c4ce25114e728504682d9aee5ca1
Content-Type: application/json; charset=utf-8
BODY:
{"Name":"Books3","Description":"test"}
URL: http://yourstore.com/odata/Category(16)
REQUEST HEADERS:
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ==
PublicKey: 0c31c4ce25114e728504682d9aee5ca1
Content-Type: application/json; charset=utf-8
BODY:
{"Name":"Books33","Description":"test","CategoryTemplateId":1,"MetaKeywords":"Books, Dictionary,
Textbooks","MetaDescription":"Books category
description","MetaTitle":null,"ParentCategoryId":0,"PictureId":1,"PageSize":4,"AllowCustomersToSelec
tPageSize":true,"PageSizeOptions":"8, 4, 12","PriceRanges":"-25;25-50;50-
;","ShowOnHomePage":false,"IncludeInTopMenu":true,"HasDiscountsApplied":false,"SubjectToAcl":fal
se,"LimitedToStores":false,"Published":true,"Deleted":false,"DisplayOrder":1}
7
nop4you.com
7. DELETE category
URL: http://yourstore.com/odata/Category(17)
REQUEST HEADERS:
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ==
PublicKey: 0c31c4ce25114e728504682d9aee5ca1
User-Agent: WebApiFornopCommerce
Description: Method will create reference between Customer and Address tables in nopCommerce database.
URL: http://yourstore.com/odata/Customer(1)/Addresses/$ref
REQUEST HEADERS:
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ==
PublicKey: 0c31c4ce25114e728504682d9aee5ca1
User-Agent: WebApiFornopCommerce
Accept: application/json
Accept-Charset: UTF-8
Content-Type: application/json
BODY:
{"@odata.id":"http://yourstore.com/odata/Address(7)"}
8
nop4you.com
3. DELETE address for customer (reference)
Decription: Methods deletes address for customer (existing address) – deletes reference between Customer
and Address tables in nopCommerce database.
URL:
http://yourstore.com/odata/Customer(1)/Addresses/$ref?$id=http://yourstore.com/odata/Address(7)
REQUEST HEADERS:
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ==
PublicKey: 0c31c4ce25114e728504682d9aee5ca1
User-Agent: WebApiFornopCommerce
Accept: application/json
Accept-Charset: UTF-8
Content-Type: application/json
Description: Adds role to customer (existing role) – creates reference between Customer and Roles tables in
nopCommerce database.
URL: http://yourstore.com/odata/Customer(1)/CustomerRoles/$ref
REQUEST HEADERS:
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ==
PublicKey: 0c31c4ce25114e728504682d9aee5ca1
User-Agent: WebApiFornopCommerce
Accept: application/json
Accept-Charset: UTF-8
Content-Type: application/json
BODY:
{"@odata.id":"http://yourstore.com/odata/CustomerRole(5)"}
Description: Deletes role for customer (existing role) – deletes reference between Customer and Role tables in
nopCommerce database.
URL:
http://yourstore.com/odata/Customer(1)/CustomerRoles/$ref?$id=http://yourstore.com/odata/Custo
merRole(5)
REQUEST HEADERS:
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ==
9
nop4you.com
PublicKey: 0c31c4ce25114e728504682d9aee5ca1
User-Agent: WebApiFornopCommerce
Accept: application/json
Accept-Charset: UTF-8
Content-Type: application/json
Description: Adds tag for product (existing tag) – creates reference between Product and Tag tables in
nopCommerce database.
URL: http://yourstore.com/odata/Product(1)/ProductTags/$ref
REQUEST HEADER:
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ==
PublicKey: 0c31c4ce25114e728504682d9aee5ca1
User-Agent: WebApiFornopCommerce
Content-Type: application/json
BODY:
{"@odata.id":"http://yourstore.com/odata/ProductTag(3)"}
1. GET OrderDate
URL: http://yourstore.com/odata/Order/GetCreateDate(Id=1)
REQUEST HEADER:
Authorization: Basic
YWRtaW5AeW91cnN0b3JlLmNvbTozMVlQOGNleDJwNEZORlNxOXlSUm80NWp2N2V2SlIyZVFEYlRJS2R
hT0VNPQ==
PublicKey: 0c31c4ce25114e728504682d9aee5ca1
User-Agent: WebApiFornopCommerce
Accept: application/json
Accept-Charset: UTF-8
10
nop4you.com
Example for IMAGE
Sample code:
Sample:
{
"ProductId":1,
"PictureId": 81,
"DisplayOrder":1
}
11
nop4you.com
Method type: POST
URL: http://localhost:15536/odata/ProductPicture
User-Agent: WebApiFornopCommerce
Accept: application/json
Accept-Charset: UTF-8
To enable cross-origin you need to modify your main Web.config file, by adding:
<appSettings>
Cross-Origin Example
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/rollups/hmac-sha256.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/components/enc-base64.js"></script>
<script>
CryptoJS.enc.u8array = {
// Shortcuts
// Convert
12
nop4you.com
var u8 = new Uint8Array(sigBytes);
u8[i]=byte;
return u8;
},
// Shortcut
// Convert
};
function getByte(str){
bytes.push(str.charCodeAt(i));
return bytes;
};
function getHmacSHA256Key(publicKey,secretKey,userEmail) {
13
nop4you.com
secretBytes = CryptoJS.enc.u8array.parse(secretBytes);
valueBytes = CryptoJS.enc.u8array.parse(valueBytes);
return result;
};
$(document).ready(function(e) {
$.ajax({
type : 'GET',
url : 'http://localhost:15536/odata/Category',
dataType : 'json',
xhr.setRequestHeader('PublicKey', publicKey);
xhr.setRequestHeader('Access-Control-Allow-Origin', '*');
},
crossDomain : true,
success : function(data){
console.log(data);
},
14
nop4you.com
console.log("error"+' '+JSON.stringify(data) + textStatus + errorThrown);}
});
});
</script>
15
nop4you.com
Order example
You may make order, but this option require two steps. First need to call Order by POST method:
"OrderGuid":"6ae2c5c9-beb9-4e94-a0c5-f6d7d6327b58",
"StoreId":2,
"CustomerId":1,
"BillingAddressId":21,
"ShippingAddressId":22,
"PickUpInStore":false,
"OrderStatusId":10,
"ShippingStatusId":20,
"PaymentStatusId":10,
"PaymentMethodSystemName":"Payments.CheckMoneyOrder",
"CustomerCurrencyCode":"USD",
"CurrencyRate":1,
"CustomerTaxDisplayTypeId":10,
"CustomerLanguageId":1,
"OrderSubtotalInclTax":0.0000,
"OrderSubtotalExclTax":0.0000,
"OrderSubTotalDiscountInclTax":0.0000,
"OrderSubTotalDiscountExclTax":0.0000,
"OrderShippingInclTax":0.0000,
"OrderShippingExclTax":0.0000,
"PaymentMethodAdditionalFeeInclTax":0.0000,
"PaymentMethodAdditionalFeeExclTax":0.0000,
"OrderTax":0.0000,
"OrderDiscount":0.0000,
"OrderTotal":245.0000,
"RefundedAmount":0.0000,
"AffiliateId":0,
"AllowStoringCreditCardNumber":false,
"Deleted":false,
"CreatedOnUtc":"2017-05-26T09:01:16.197Z",
"CustomOrderNumber":"26/5/2017"
16
nop4you.com
Second need to add items to that order, by calling OrderItem:
"OrderItemGuid":"713d9686-ee2e-4368-82c0-7e700745ff42",
"OrderId":26,
"ProductId":17,
"Quantity":1,
"UnitPriceInclTax":1300.0000,
"UnitPriceExclTax":1300.0000,
"PriceInclTax":1300.0000,
"PriceExclTax":1300.0000,
"DiscountAmountInclTax":0.0000,
"DiscountAmountExclTax":0.0000,
"OriginalProductCost":0.0000,
"DownloadCount":0,
"IsDownloadActivated":false
Category
Manufacturer
Product
Customer
CategoryTemplate
CheckoutAttribute
CheckoutAttributeValue
Country
CrossSellProduct
Currency
CustomerRole
CustomerAttribute
CustomerAttributeValue
DeliveryDate
Discount
DiscountRequirement
EmailAccount
ExternalAuthenticationRecord
GenericAttribute
GiftCard
GiftCardUsageHistory
Language
LocaleStringResource
LocalizedProperty
ManufacturerTemplate
MeasureDimension
MeasureWeight
17
nop4you.com
Order
OrderItem
OrderNote
Picture
ProductCategory
ProductManufacturer
ProductPicture
ProductAttributeMapping
ProductTag
ProductSpecificationAttribute
ProductAttribute
ProductReviewHelpfulness
ProductTemplate
ProductAttributeCombination
ProductAttributeValue
QueuedEmail
RelatedProduct
ReturnRequest
Setting
Shipment
ShipmentItem
ShippingMethod
ShoppingCartItem
ShoppingCartItem
SpecificationAttribute
SpecificationAttributeOption
StateProvince
Store
StoreMapping
TaxCategory
TierPrice
UrlRecord
Vendor
Warehouse
RewardPointsHistory
Address
PermissionRecord
AclRecord
NewsItem
Topic
TopicTemplate
MessageTemplate
Download
18
nop4you.com