DropShipping API Manual

Version 2.1

PROVISIONAL

2

Content Introduction .................................................................................................................................. 4

Process ...................................................................................................................................... 4

The API (REST) ............................................................................................................................... 5

Login .......................................................................................................................................... 5

Logout........................................................................................................................................ 6

Products List .............................................................................................................................. 6

Brand Products List ................................................................................................................... 7

Paging Product List .................................................................................................................... 8

Product Image ........................................................................................................................... 9

Stock .......................................................................................................................................... 9

Orders Between Dates ............................................................................................................ 10

Send Orders ............................................................................................................................. 11

Get Tracking ............................................................................................................................ 16

The Data ...................................................................................................................................... 16

LoginModel.............................................................................................................................. 16

ProductModel ......................................................................................................................... 17

StockProductModel ................................................................................................................. 17

ClientOrderModel ................................................................................................................... 18

ClientOrderLineModel ............................................................................................................. 19

OrderModel ............................................................................................................................. 19

OrderLineModel ...................................................................................................................... 20

OrdersInfoModel ..................................................................................................................... 21

TrackingModel ......................................................................................................................... 21

PHP Examples .............................................................................................................................. 22

Introduction ............................................................................................................................ 22

PostLogin ................................................................................................................................. 22

GetProducts ............................................................................................................................. 23

GetBrandProducts ................................................................................................................... 24

GetPagingProducts .................................................................................................................. 25

3

GetImageProduct .................................................................................................................... 26

Download Image ................................................................................................................. 26

GetStock .................................................................................................................................. 27

GetOrdersBetweenDates ........................................................................................................ 28

PostSendOrders ....................................................................................................................... 29

GetOrdersTrakings .................................................................................................................. 30

Observations ........................................................................................................................... 31

Tests .................................................................................................................................... 31

Principal changes respect the API 1.9 ................................................................................. 31

Functioning (Web) ....................................................................................................................... 32

Create an order ....................................................................................................................... 32

Internal structure of the order ............................................................................................ 32

Order example......................................................................................................................... 33

Create an order with the “.txt” extension using Microsoft Excel 2007 .................................. 33

Create an order with the “.csv” extension using Microsoft Excel 2007 .................................. 33

Send more than one order in the same file ............................................................................ 36

Send Order (Web) ....................................................................................................................... 37

4

Introduction

Nova Engel’s DropShipping System offers to its clients the possibility to make sales for their

final customers without worrying about having a self-stock of products. Nova Engel is

responsible for sending the requested products to the final customer with a serious and

effective carrier.

Nova Engel offers this new API System with three different methods to receive and send

information to its clients: An API that uses web services (ideal for an important volume of

data), an auxiliary API as a complement of the first step through http and a website of support.

Process

The process can be summarized in the following figure:

1. Login: Identifies the clients in the system. Every client has a username and a password

that allows them to access the website and the API services.

2. Download Products: Allows updating the information about the products offered by

Nova Engel to its clients. We recommend you to download frequently all the managed

products to be informed about the novelties and to know the available stock at any

time.

3. Send Orders: This option allows sending to Nova Engel all the orders we want to be

delivered to the final customer. Each order must be identified by the client in a unique

way. By limitations of the carrier the order numbers must be NUMERIC.

4. Logout: Disconnection of the system.

5

The API (REST)

The clients will work through standard HTTP operations (post and get methods). It is an easy

way to work that allows JSON format and XML format. The methods available in the web

service are explained below, the connexion is http://drop.novaengel.com . The exact syntax of

a call depends entirely on the platform from which they are called.

Login

This call identifies us in the system. It accepts a username and a password. If it all works

properly, you will receive a string with a token that will be used to call the next methods. If for

some reason fails, you will receive a null value.

Method: Post Call: http://drop.novaengel.com/api/login Parameters from body: {user: "prueba", password: "prueba"} Returned Value: LoginModel

6

Logout

This call overrides the token we are using. It is not essential, but it is advisable for security

reasons.

Method: Post Call: http://drop.novaengel.com/api/logout/token Parameters from URI: token Returned Value: No value returned

Products List

This call gives us all of the available products for Nova Engel’s DropShipping. For a correct

functioning, it is necessary to provide the token previously provided by the Login. Now you the

chance to choose the language (es, en, fr…) (product description, set content and categories).

In case of not specifying the language, the program will show you one by default. If for some

reason fails, you will receive an empty list of ProductModel.

Method: Get Call: http://drop.novaengel.com/api/products/availables/token/languaje Parameters from URI: token, languaje Returned Value: List<ProductModel>

7

Brand Products List

This call gives us all the products of a brand available for Nova Engel’s DropShipping. For a

correct functioning, it is necessary to provide the token previously provided by the Login and

the brand Id to see the products, now you the chance to choose the language (es, en, fr…)

(product description, set content and categories).

In case of not specifying the language, the program will show you one by default if for some

reason fails, you will receive an empty list of ProductModel.

Method: Get Call: http://drop.novaengel.com/api/products/brand/token/brandId/languaje

Parameters from URI: token, brandId, languaje Returned value: List<ProductModel>

8

Paging Product List

This call gives us a page with the available products for Nova Engel’s DropShipping. For a

correct functioning, it is necessary to provide the token previously provided by the login, the

page number that we want to download (beginning by 0) and the number of products for

every page. If the number of the returned products is less than the requested orders, it means

that we have downloaded all the data. Now you the chance to choose the language (es, en,

fr…) (product description, set content and categories). In case of not specifying the language,

the program will show you one by default

If for some reason fails, you will receive an empty list of ProductModel.

If for example we want to download 50 elements every time, the call will be:

products = GetPagingProducts(token, 0, 50)

products = GetPagingProducts (token, 1, 50)

…….

Until the number of products is below 50.

Method: Get Call: http://drop.novaengel.com/api/products/paging/token/pages/elements/languaje Parameters from URI: token, pages, elements, languaje Returned value: List<ProductModel>

9

Product Image

This call provides us the product URL of the image. For a correct functioning, it is necessary to

provide the token previously provided by the Login and the product Id of image we desire. If

for some reason fails, you will receive an empty string.

Method: Get Call: http://drop.novaengel.com/api/products/image/token/productId Parameters from URI: token, productId Returned value: string

Stock

This call gives us all the products available and if they are in stock for DropShipping. The information is minimal, but this is an ideal method to maintain the stock and Id of the products updated, if for some reason fails, you will receive an empty list of StockProductModel. Method: Get Call: http://drop.novaengel.com/api/stock/update/token Parameters from URI: token Returned value: List<StockProductModel>

10

Orders Between Dates

With this call we can know the exact number of orders between dates and their general status.

Will need the token, start and end date. If for some reason fails, you will receive an empty list

of OrderModel.

Method: Get Call: http://drop.novaengel.com/api/orders/betweendates/token/initiation/final Parameters from URI: token, initiation (date), final (date). Returned value: List<OrderModel>

11

Send Orders

It allows us to notify to Nova Engel the orders that we want to be delivered to the final

customer. It accepts as parameters the Token provided by the Login and a list with the orders

to be delivered. It provides a list with the information of every order. It is possible to send

orders in json or xml format. We will see both ways.

12

JSON format, from Body: [ { "OrderNumber": "568746", "Valoration": 0, "CarrierNotes": "cerrado lunes", "Lines": [ { "ProductId": 2977, "Units": 5 }, { "ProductId": 15162, "Units": 5 } ], "Name": "Cristian", "SecondName": "Alvarez Muñoz", "Telephone": "968446850", "Mobile": "699854712", "Street": "Pelayo nº 5 5A", "City": "Palma", "County": "Baleares", "PostalCode": "96632", "Country": "ES", } ]

The information provided will contain a message with the possible mistakes found in

some orders and the orders sent correctly.

Method: Post Call: http://drop.novaengel.com/api/orders/send/token Parameters from URI: token Parameters from Body: orderList (json format) Returned value: List<OrdersInfoModel>

13

14

XML format, from Body: <ArrayOfClientOrderModel xmlns:i=http://www.w3.org/2001/XMLSchema-instance xmlns="http://schemas.datacontract.org/2004/07/eCommerce.DropShipping.Servicios.V2"> <ClientOrderModel> <CarrierNotes>cerrado lunes</CarrierNotes> <City>Palma</City> <Country>ES</Country> <County>Baleares</County> <Lines> <ClientOrderLineModel> <ProductId>2977</ProductId> <Units>5</Units> </ClientOrderLineModel> <ClientOrderLineModel> <ProductId>15162</ProductId> <Units>5</Units> </ClientOrderLineModel> </Lines> <Mobile>634897477</Mobile> <Name>Cristian</Name> <OrderNumber>568746</OrderNumber> <PostalCode>07600</PostalCode> <SecondName>Álvarez Muñoz</SecondName> <Street>Pelayo nº 5 5A</Street> <Telephone>871469870</Telephone> <Valoration>0</Valoration> </ClientOrderModel> </ArrayOfClientOrderModel>

The information provided will contain a message with the possible mistakes found in

some orders and the orders sent correctly.

Method: Post Call: http://drop.novaengel.com/api/orders/send/token Parameters from URI: token Parameters from Body: orderList (xml format) Returned value: List<OrdersInfoModel>

15

16

Get Tracking

This method allows us to get all related available information with the location of our orders. If

for some reason fails, you will receive an empty list of TrackingModel.

Method: Get Call: http://drop.novaengel.com/api/trackings/orders/token/orders Parameters from URI: token, orders Parameters from Body: orderList (xml format) Returned value: List<TrackingModel>

The Data Below are explained the structure of the objects used in the API previously mentioned.

LoginModel

It assigns us a token that we will need to do the other petitions.

public class LoginModel { public string Token { get; set; } }

17

ProductModel

Contains the information about the products with which Nova Engel is working. The format is:

public class ProductModel { public int Id { get; set; } public List<string> EANs { get; set; } public string Description { get; set; } public string SetContent { get; set; } public decimal Price { get; set; } public decimal PVR { get; set; } public int Stock { get; set; } public string BrandId { get; set; } public string BrandName { get; set; } public string Gender { get; set; } public List<string> Families { get; set; } }

Id: Unique identifier of the product.

EANs: EANs list of product.

Description: Product description, including its content.

SetContent: Content of the Set.

Price: Nova Engel’s sale price.

PVR: Recommended retail price for this product. It’s the price the manufacturer

indicates.

Stock: Current stock of Nova Engel.

BrandId: Brand Identifier of the product.

BrandName: Name of Brand

Gender: Product targeted for a Gender. It can be Unisex, for Woman or for Man.

Families: List that contains the products of the same family.

StockProductModel

It contains the updated information about the stock of the products with which Nova Engel is

working. The format is:

public class StockProductModel { public int Id { get; set; } public int Stock { get; set; } public int Price { get; set; } }

18

Id: Unique identifier product.

Stock: Current stock of Nova Engel.

Price: Actual price of the product.

ClientOrderModel

It contains the order for sending to Nova Engel. Its structure is:

public class ClientOrderModel { public string OrderNumber { get; set; } public decimal Valoration { get; set; } public string CarrierNotes { get; set; } public IList<ClientOrderLineModel> Lines { get; set; } public string Name { get; set; } public string SecondName { get; set; } public string Telephone { get; set; } public string Mobile { get; set; } public string Street { get; set; } public string City { get; set; } public string County { get; set; } public string PostalCode { get; set; } public string Country { get; set; } }

OrderNumber: Order number assigned by the client. Can have a max. Length of 15

characters. By limitations of the carrier to scan the bar codes the order numbers must

be a numeric code.

Valoration: Optional parameter with the valoration.

CarrierNotes: Notes for the carrier.

Lines: List of products and quantity to be delivered.

Name: Name of recipient.

SecondName: Recipient’s second name.

Telephone: Telephone number so the carrier can communicate with the person that

will receive the shipment. It is optional.

Mobile: Mobile number so the carrier can communicate with the person that will

receive the shipment. It is optional.

Street: Shipment address.

City: City of delivery.

County: County of delivery.

PostalCode: Post code.

Country: Country of delivery.

19

ClientOrderLineModel

Details of every order. It indicates the product ID and quantity. Its format is:

public class ClientOrderLineModel { public int ProductId { get; set; } public int Units { get; set; }

}

ProductId: Id of the product.

Units: Number of products.

OrderModel

It contains the order after being sent by Nova Engel. Its structure is:

public class OrderModel { public string OrderNumber { get; set; } public string Invoice { get; set; } public DateTime Date { get; set; } public decimal Discount { get; set; } public decimal Charge1 { get; set; } public decimal Charge2 { get; set; } public decimal Total { get; set; } public decimal Valoration { get; set; } public int ClientId { get; set; } public EstadoPedido Status { get; set; } public string CarrierNotes { get; set; } public TrackingModel SendInfo { get; set; } public IList<OrderLineModel> Lines { get; set; } public string Name { get; set; } public string SecondName { get; set; } public string Telephone { get; set; } public string Mobile { get; set; } public string Street { get; set; } public string City { get; set; } public string County { get; set; } public string PostalCode { get; set; } public string Country { get; set; } }

OrderNumber: Order number assigned by the customer. It must have a max. length of

15. By limitations of the carrier to scan the bar codes the order numbers must be a

numeric code.

Invoice: Order invoice.

20

Date: Order date.

Discount: Order discount.

Charge1: First charge.

Charge2: Second Charge.

Total: Total amount of the order.

Valoration: Optional parameter with the valoration.

ClientId: Id of the client.

Status: Status of the order.

CarrierNotes: Notes for the carrier.

SendInfo: Tracking information of the order.

Lines: List of products and quantity to be delivered.

Name: Name of recipient.

SecondName: Receipient’s second name.

Telephone: Telephone number so the carrier can communicate with the person that

will receive the shipment. It is optional.

Mobile: Mobile number so the carrier can communicate with the person that will

receive the shipment. It is optional.

Street: Shipment address.

City: City of delivery.

County: County of delivery.

PostalCode: Post code.

Country: Country of delivery.

Status can take the following values: { ShippingSlope= 1, Invoiced = 2, Sent = 3, StockError = 4, CarrierError = 5, Canceled = 6, Received = 7}

OrderLineModel

Wide information obtained in ClientOrderLineModel. It includes the discount and the associated price. public class OrderLineModel { public int ProductId { get; set; } public int Units { get; set; } public decimal Price { get; set; } public decimal Discount { get; set; } }

21

OrdersInfoModel

It shows the information about the mistakes produced doing the importation of the orders.

The structure is:

public class OrdersInfoModel { public string Message { get; set; } public string OrderNumber { get; set; }

}

Message: Message that explains the incidence.

OrderNumbre: Number of Order.

TrackingModel

Indicates the information related to the shipping tracking of the order.

public class TrackingModel { public string ClientDocument { get; set; } public string Tracking { get; set; } public string Expedition { get; set; } public string Carrier { get; set; }

}

ClientDocument: Order number assigned by the client. It can have a max length of 15.

By limitations of the carrier to scan the bar codes the order numbers must be a

numeric code.

Tracking: Tracking number that the carrier assigns to the package.

Expedition: Expedition number of the package in our system.

Carrier: Carrier that delivers the order.

22

PHP Examples

Introduction

For make it easy, we have created examples of every function call, in this case for PHP language. All of these processes have been tested creating the php code to run it in a local host with a WAMP (Windows, Apache, MySQL, and PHP).

PostLogin

Code:

Result:

23

GetProducts

Code:

Result:

24

GetBrandProducts

Code:

Result:

25

GetPagingProducts

Code:

Result:

26

GetImageProduct

Code:

Result:

Download Image

We use the API method to obtain the url of the image by sending the token and the product id

of the image we want.

Once we have the url, we will remove the quotation marks at the beginning and the end of the

string.

For this example, we will save the image obtained in the Temp folder located in the Windows

folder.

As shown in the sample code, it was used the CURL_INIT() method

The code of the example is as follows:

27

GetStock

Code:

28

Result:

GetOrdersBetweenDates

Code:

29

Result:

PostSendOrders

Code (json);

30

Result:

GetOrdersTrakings

Code:

Result:

31

Observations

All the methods previously mentioned have been tested with Google Chrome that you can get

by clicking here.

Also has been used an extension for Google Chrome called POSTMAN.

Tests

First, we have to add 2 headers: Content-Type application/json Accept application/json

Principal changes respect the API 1.9

- The ID product field has been added.

- A list of families where a product belongs has been added.

- To identify a product we won't use the EAN code, now we will use the ID.

- The orders that are going to be sent must have a JSON or XML format.

- Functions related with the incidences have been removed.

- New API is based in REST architecture (HTTP standard)

Principal changes respect the API 2.0

- It has been added the possibility for getting the description, set content and category

of the products in one of the available languages by inserting the language in the

requests from GetProducts, GetBrandProducs, PaginProducts. (see the examples).

- Available Languages (es, en, de, fr, it, nl, pl, pt).

- We have the posibility to add more information in the future.

32

Functioning (Web)

The website can be found on the following URL: http://drop.novaengel.com/

First of all, we will create an order to be sent through the website.

Create an order

The orders can be created manually or using a program created by your IT service provider. In

any case the final result will be a file with the extension ".csv" or ".txt".

Internal structure of the order

The structure of an order is fixed, meets certain standards already set and should be

maintained at all times. If you don't want to write anything on a required field, leave it empty.

Each field will be separated by semicolons and will written in quotation marks, extra quotation

marks mustn’t be used.

An order consists of:

One line of orders with four fields:

1. Order ID: identifies an order, fixed value "P".

2. Order number: number (Maximum 15 digits) that identifies the order.

3. Order notes: allows you to write a short message to the carrier.

4. Valoration: optional parameter with the assessment.

One or several lines of products with four fields:

1. Order ID: identifies an order, fixed value "A".

2. Order number: number (Maximum 15 digits) that identifies the order.

3. EAN-13: reference code supplied in the product list..

4. Quantity: number that indicates the number of units requested.

One Address line with twelve fields:

1. Address ID: identifies an address, fixed value "D".

2. Order number: number (Maximum 15 digits) that identifies your order.

3. Full name.

4. Address.

5. Post code.

6. City.

7. County.

8. Country (ISO code)

9. Telephone (landline)

10. Telephone (mobile)

11. Fax

12. Email

33

Order example

We have a fragrance company where we use a system that organizes my orders using 10 digits.

A customer named Ramon who has a small shop has bought me three articles. I don't have his

landline or fax and he doesn't use ratings. We will create a new order:

Order line:

"P";"0000001240";" Deliver before 15:30. Monday closed."

Product line:

"A";"0000001240";"3351500980400";"2"

"A";"0000001240";"3574896512004";"1"

"A";"0000001240";"3000145972106";"5"

Address line:

"D";"0000001240";"Ramón Delgado Gual";"St/ Repozuelo Nº2";"07008";"Palma de

Mallorca";"Baleares";"ES";"";"646756842";"";"ramon@company.co.uk"

Create an order with the “.txt” extension using Microsoft Excel 2007

Create a file with the .txt extension. We will use for this case “Demonstration.txt”.

We will enter the text of the example line by line. The result is as follows:

IMPORTANT: Is necessary save the document with UTF-8 codification

34

Create an order with the “.csv” extension using Microsoft Excel 2007

We will open a spreadsheet to create the file that we will call for this case:

“Demonstration.csv”. Press F12 and save the file as shown in Figure2.

Figure2

If a warning message appears after you save the file, click "OK".

If another message appears again, press "Yes".

35

Enter each field in a cell as reflected in Figure3.

Figure3

As you can see, it is not necessary to quote the data in Microsoft Excel 2007, since it records

the correct format after being saved, but remember that empty fields necessarily must include

"" so the format is correct.

We recommend using the format "Text" to enter data (marked in red in the Figure3).

36

Send more than one order in the same file

In case you want to make two or more orders simply continue completing the file line by line.

Object lesson:

My company sells in one day to three different customers. My system is prepared so it can

save me the orders and at the end of the day allows me to create a .csv file to process all the

orders.

So if I enter the information manually I will do it line by line. If my IT service provider has

created me a program that automates the task, then it will be ready. As a result we obtain the

Figure4.

37

Send Order (Web)

Once the order has been created following the steps previously explained, we will proceed to

send it, so we will connect to the website http://drop.novaengel.com and we will login with

our username and password.

Once inside we will press: Send Orders -> Browse -> (once the order has been selected) ->

Upload.

If the order has the right structure and there hasn't been any type of mistake we will see a

message that tells us that the order has been successfully uploaded.