Master Data

Suppliers
Brands
Product Types
Ports
Made In
Delivery Terms
Tags

Quickstart

The PickTOUR API Web Service is a service that returns information about your collected data using HTTP POST requests.

Thanks to API you can easily integrate all the collected data to your company ERP or PLM.

The following requests are available:

API	API NAME	LINK
Trips API returns list of trip based on filter	trips_V1	View
Products API returns list of product based on a trip or supplier	products_V1	View
Single product API returns a product detail	single_product_V1	View
Images API returns a temporaly link for download images	image_V1	View
Suppliers API returns supllier based on optional filter	suppliers_V1	View
Brand API returns list of brands	brands_V1	View
Product Types API returns list of Product Types values	product_types_V1	View
Made In API returns list of Made In values	made_in_V1	View
Port API returns list of ports	ports_V1	View
Delivery Terms API returns list of Delivery Terms values	delivery_terms_V1	View
Tags API returns list of Tags values	tags_V1	View

Each of the services is accessed as an HTTP POST request and returns an JSON response. All requests must use the https:// protocol and include an API key in the POST payload.

curl https://manage.yourpicktour.com/platform/api?cmd=API_NAME&FILTER_PARAMS=VALUE --data 'authToken=SECRET_KEY'

Authentication

The PickTOUR API Web Service uses a key to identify your organization. You’ll need your own secret key before you can begin using the API.

Follow these steps to create or modify your secret key.

Go to the PickTOUR backend and login with your administration account.
Select the Administration Tab. Next, in the sidebar on the left click Dashboard.
In that page you can find your own secret key. Use the “Reset Key” button for create a new key.

Advice: Do not use this key outside of your server code. For example, do not embed it in a web page or in a mobile application.

Usage Limits and Requirements

The PickTOUR API Web Service enforces a limit of 10’000 requests multiplied by the active active license in a 24 hour period. If your app exceeds the limit, the web service requests start failing.

Make a request

Please make a note of the following:

All API calls should be made with HTTP POST.
You can consider any non-200 HTTP response code an error – the returned data will contain more detailed information.

To use the API you must make a request as follows:

URL	https://manage.yourpicktour.com/platform/api?cmd=API_NAME&PARAM_1=VALUE_1&PARAM_2=VALUE_2
Request-type	POST
Content-type	application/x-www-form-urlencoded
Data	authToken=YOUR_SECRET_KEY

___________________
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
____________________

URL url = new URL("https://manage.yourpicktour.com/platform/api?cmd=API_NAME"); 

HttpURLConnection connection = (HttpURLConnection) url .openConnection(); 
connection.setDoOutput(true); 
connection.setRequestMethod("POST"); 
connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded"); 
connection.setRequestProperty("charset", "UTF-8"); 
connection.setUseCaches(false);  
DataOutputStream wr = new DataOutputStream(connection.getOutputStream()); 
wr.writeBytes("authToken=" + SECRET_KEY); 
wr.flush(); 
wr.close();   

int responseCode = connection.getResponseCode();   

if(responseCode == 200){

  BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
  String inputLine;
  StringBuffer response = new StringBuffer();
  while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
  }
  in.close();

  System.out.println("Response: " + response.toString());
}else{
  System.out.println("ERROR");
}

function CallAPI()
{
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_POST, 1);
    curl_setopt($curl, CURLOPT_POSTFIELDS, “authToke=SECRET_KEY”);
    curl_setopt($curl, CURLOPT_URL, ‘https://manage.yourpicktour.com/platform/api?cmd=API_NAME’);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

    $result = curl_exec($curl);

    curl_close($curl);

    return $result;
}

import requests
payload = {'authToken': 'SECRET_KEY'}
r = requests.post(“https://manage.yourpicktour.com/platform/api?cmd=API_NAME”, params=payload)

Response

A JSON response contains these root elements:
“success” : this is the request outcom, it’s a boolean (true/false).
“errorCode” : this field contains metadata on the request.

OK indicates that no errors occurred; the place was successfully detected and at least one result was returned.
MAX_NR_OF_REQUESTS_REACHEDrequest limit exceeded daily
INVALID_CREDENTIALS the secret key is not valid
BAD_REQUEST generally indicates that the some request params is missing
ERROR indicates a generic error
INTERNAL_SERVER_ERROR indicates a server error

“message” : this field contains the error message.
“next” : If not included, this is the last page of data. Otherwise it is the parameter to be use to retrive the next elements. See Pagination for more detail.
“result” : contains the detailed information about the requested.

Generic JSON Example

{
"success": true,
"code": "OK",
"message": "",
"next": "&start=2",
"result": [
   {your_object_data},
   {your_object_data}
]}

Pagination

The responses contain at most 25 elements, in case the results exceed this limit, it will be necessary to make another request to obtain the next elements.
If your JSON response includes the “next” key, in order to get the next page, just add these parameters to the request URL and make a POST request with your secret key.

For example if JSON response is like this:

JSON

{
"success": true,
"code": "OK",
"message": "",
"next": "&start=25",
"result": [
   {your_object_data},
   {your_object_data}
]}

you must add the value of the “next” key to the URL.

curl https://manage.yourpicktour.com/platform/api?cmd=API_NAME&FILTER_PARAMS=VALUE&start=25 --data 'authToken=SECRET_KEY'

Trips API

API_NAME

trips_V1

The Trips API Web Service returns a list of the Trips.
The request is an HTTP POST following this format:

Required parameters

None

Optional parameters

tripDate : The trip creation date. Restricts results to only those trips create after this date
user: The user that create the trip. Returns only those trip created by this user
desTrip: Results will be restricted to those containing the passed description. The filter is caseinsensitive
brandId: Trips’s Brand. Returns only those trip with this Brand. Use the Brand API Web Serivce to get the available Brands
productTypeId: Trips’s Product type. Returns only those trip with this Product Type. Use the Brand API Web Serivce to get the available brands
desTag: Tag description. Results will be restricted to those containing the passed tag. The filter is caseinsensitive

Response

The response is a paginated list of trips.

JSON Example

 {"success": true,
  "errrorCode": "",
  "message": "",
  "next": "&start=10",
  "result": [{"id": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1432199370",
              "desTrip": "Trip 2015-05-21",
              "idBrand": 1,
              "idProductType": 1,
              "createUser": "USER",
              "createDate": "2015-05-21 09:10:58",
              "updateDate": "2015-05-21 10:04:32"},
              {...},...]
 }

Products API

API_NAME

products_V1

The Products API Web Service returns a list of the Products.
The request is an HTTP POST following this format:

Required parameters

The web service requires at least one of the following parameters, otherwise you’ll get a BAD_REQUEST response.

tripId: the trip id. Returns only those products contained in this trip. You can get the trip id from the Trips API, Tags API or Products API web services response.
supplierId: the supplier id. Returns only those products associated to this supplier. You can get the supplier id from the Suppliers API web service response.

Optional parameters

desProduct: Results will be restricted to those containing the passed description. The filter is caseinsensitive.
desTag: Results will be restricted to those containing the passed tag. The filter is caseinsensitive.

Response

The response is a paginated list of products.

JSON Example

 {
  "success": true,
  "errorCode": "OK",
  "message": "",
  "next":"&start=10",
  "result": [
   {
      "id": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1432199370",
      "tripId": "34030A94-A886-4C83-9E6F-5B909AE5BA65|143213231",
      "desProduct": "Red T-Shirt",
      "note":  "Red",
      "sendingDate": "2015-06-18 00:00:00",
      "idProductType": 1,
      "descrProductType": "Generic",
      "brandId": 1,
      "descrBrand": "NONE",
      "price": 10.2,
      "quantity": 20,
      "minQuantity": 10,
      "colorMinQuantity": 5,
      "codCurrency": "EUR",
      "desComposition":  "Coton",
      "desMaintenance":  "Machine wash",
      "desNoteQf": "Style Developer note",
      "portId": 12,
      "descrPort": “VENICE”,
      "madeinId": 12,
      "descrMadein": "Italy",
      "deliveryTermsId": 0,
      "descrDeliveryTerms": "EXW",,
      "tagId": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1432199370",
      "desTag": "T-Shirt",
      "flgProductOrigin": "Y",
      "supplierId": "83707731-ACFE-4C3B-883E-6D1FF25BD100|9898121",
      "qtaBulkDays": 0,
      "createUser": "USER",
      "createDate": "2015-05-21 09:40:06",
      "updateDate": "2015-05-21 09:45:09"
    },
    {...}
  ]
}

Single Product API

API_NAME

single_product_V1

The Product API Web Service returns a specified product.

The request is an HTTP POST following this format:

Required parameters

The web service requires at least one of the following parameters, otherwise you’ll get a BAD_REQUEST response.

productId: the product Id. You can get the trip id from the Products API web service response.

Optional parameters

None

Response

In the response you can find all the product data, included quotation, labels and images.

quotations: it’s an array that contain alwasy 3 element. Each element corresponds to a row in the quotation table, present in the Style developer form. Use the position field for recognize the row (1 is the first row).
labels: Each element corresponds to a label in the Style Designer form.
Images: Each element corresponds to an image and you can differentiate the images for form and position using the fields:
- formType: “S” is Style Developer form, “P” is Style Developer and “D” is Pattern Designer.
- Position: is the image position in the card (1 is the first image)

JSON Example

 {
  "success": true,
  "errorCode": "OK",
  "message": "",
  "next":"&start=10",
  "result": [
   {
      "id": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1432199370",
      "tripId": "34030A94-A886-4C83-9E6F-5B909AE5BA65|143213231",
      "desProduct": "Red T-Shirt",
      "note":  "Style Designer Note",
      "sendingDate": "2015-06-18 00:00:00",
      "idProductType": 1,
      "descrProductType": "Generic",
      "brandId": 1,
      "descrBrand": "NONE",
      "price": 10.2,
      "quantity": 20,
      "minQuantity": 10,
      "colorMinQuantity": 5,
      "codCurrency": "EUR",
      "desComposition":  "Coton",
      "desMaintenance":  "Machine wash",
      "desNoteQf": "Style Dveloper note",
      "portId": 12,
      "descrPort": “VENICE”,
      "madeinId": 12,
      "descrMadein": "Italy",
      "deliveryTermsId": 0,
      "descrDeliveryTerms": "EXW",,
      "tagId": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1432199370",
      "desTag": "T-Shirt",
      "flgProductOrigin": "Y",
      "supplierId": "83707731-ACFE-4C3B-883E-6D1FF25BD100|9898121",
      "qtaBulkDays": 0,
      "createUser": "USER",
      "createDate": "2015-05-21 09:40:06",
      "updateDate": "2015-05-21 09:45:09"
      "quotation": [ { 
          "id": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1432199373",
          "idProduct": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1432199371",
          "position": 1,
          "minVolume": 1,
          "unitCost": 1110,
          "flgSelected": "N",
          "createUser": "USER",
          "createDate": "2015-05-21 09:11:52",
          "updateDate": "2015-05-21 09:40:55"
        }, { … }],
      "labels": [ {
          "id": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1", 
          "idProduct": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1432199371",
          "name": "Size Range",
          "value": "123",
          "position": 0,
          "createUser": "USER",
          "createDate": "2015-05-21 09:11:52",
          "updateDate": "2015-05-21 09:40:55"
        }, { … }],
      "images": [{
          "id":"34030A94-A886-4C83-9E6F-5B909AE5BA65|092312",
          "idProduct": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1432199371",
          "title": "QUOTATION",
          "description":”Photo”,
          "formType": "P",
          "position": 1
        }, { … }]
    },
    {...}
  ]
}

Image API

API_NAME

image_V1

The Image API Web Service returns a specified image.

Note: every company can download up to 3000 images per day.

The request is an HTTP POST following this format:

Required parameters

The web service requires at least one of the following parameters, otherwise you’ll get a BAD_REQUEST response.

imageId: the image Id. You can get the trip id from the Product API web service response.

Optional parameters

None

Response

The response contains 3 image links:

image: the original image.
imageThumb: an image thumb with a max side of 200px.
imageSquareThumb: an center crop square thumb with sited of 100px.

Note: To protect your privacy every link is valid for 4 hours. We recommend you to download them by this time.

JSON Example

 {
  "success": true,
  "errorCode": "OK",
  "message": "",
  "next":"&start=10",
  "result": [
   {
     "image": “link”,
     "imageThumb": “link”,
     "imageSquareThumb": “link”
    }
  ]
}

Suppliers API

API_NAME

suppliers_V1

The Suppliers API Web Service returns a list of the Suppliers.

The request is an HTTP POST following this format:

Required parameters

None

Optional parameters

tripId: the trip id. Returns only those suppliers contained in this trip. You can get the trip id from the Trips API, Tags API or Products API web services response.
supplierId: the supplier id. Returns only the supplier with this id.

Response

The response is a paginated list of suppliers.

JSON Example

 {
  "success": true,
  "errorCode": "OK",
  "message": "",
  "next":"&start=10",
  "result": [
   {
      "id": "SERVER|11",
      "codSupplier": "BS2",
      "desSupplier": "Backend Supplier",
      "desCompany": "Supplier Test",
      "address": "Piazza San Marco, Venice, ITALY",
      "mail": "mail@mail.it",
      "cell": "+39 340 12123456",
      "phone": "+39 042 123456",
      "fax": "+39 042 123457",
      "idProductType": 2,
      "createUser": "ADMIN",
      "createDate": "2015-05-25 14:44:33",
      "updateDate": null
    },
    {...},
    ...
  ]
}

Brands API

API_NAME

brands_V1

The Brand API Web Service returns a list of the Brands define in the backend.
The request is an HTTP POST following this format:

Required parameters

None

Optional parameters

None

Response

The response is a paginated list of brands.

JSON Example

 {
  "success": true,
  "errorCode": "OK",
  "message": "",
  "next":"&start=10",
  "result": [
   {
      "id": 582,
      "brand": "My Brand",
      "description": "Brand Description",
      "createUser":  "USER",
      "createDate": "2015-05-04 11:32:52",
      "updateDate": "2015-07-29 12:32:52"
    },
    {...},
    ...
  ]
}

Product Types API

API_NAME

product_types_V1

The Product Types API Web Service returns a list of the Product Types define in the backend.

The request is an HTTP POST following this format:

Required parameters

None

Optional parameters

None

Response

The response is a paginated list of product types.

JSON Example

 {
  "success": true,
  "errorCode": "OK",
  "message": "",
  "next":"&start=10",
  "result": [
   {
      "id": 12,
      "description": "T-SHIRT",
      "createUser": "USER",
      "createDate": "2015-05-04 11:32:52",
      "updateDate": "2015-07-29 12:32:52"
    },
    {...},
    ...
  ]
}

Ports API

API_NAME

ports_V1

The Port API Web Service returns a list of the Port define in the backend.

The request is an HTTP POST following this format:

Required parameters

None

Optional parameters

None

Response

The response is a paginated list of ports.

JSON Example

 {
  "success": true,
  "errorCode": "OK",
  "message": "",
  "next":"&start=10",
  "result": [
   {
      "id": 10,
      "itemPort": "BU",
      "description": "BUCAREST",
      "createUser":  "USER",
      "createDate": "2015-05-04 11:32:52",
      "updateDate": "2015-07-29 12:32:52"
    },
    {...},
    ...
  ]
}

Made In API

API_NAME

made_in_V1

The Made In API Web Service returns a list of the Made In define in the backend.

The request is an HTTP POST following this format:

Required parameters

None

Optional parameters

None

Response

The response is a paginated list of made in.

JSON Example

 {
  "success": true,
  "errorCode": "OK",
  "message": "",
  "next":"&start=10",
  "result": [
   {
      "id": 1,
      "madeIn": "AE",
      "description": "UNITED ARAB EMIRATES",
      "createUser":"USER",
      "createDate": "2015-05-04 11:32:52",
      "updateDate": "2015-07-29 12:32:52"
    },
    {...},
    ...
  ]
}

Delivery Terms API

API_NAME

delivery_terms_V1

The Port API Web Service returns a list of the Delivery Terms define in the backend.

The request is an HTTP POST following this format:

Required parameters

None

Optional parameters

None

Response

The response is a paginated list of delivery terms.

JSON Example

 {
  "success": true,
  "errorCode": "OK",
  "message": "",
  "next":"&start=10",
  "result": [
   {
      "id": 1,
      "itemDeliveryTerm": "EXW",
      "description": "EXW",
      "createUser": "USER",
      "createDate": "2015-05-04 11:32:52",
      "updateDate": "2015-07-29 12:32:52"
    },
    {...},
    ...
  ]
}

Tags API

API_NAME

tags_V1

The Tags API Web Service returns a list of the Tags define in the backend.

Note: a tag is always associated to a trip.

The request is an HTTP POST following this format:

Required parameters

None

Optional parameters

tripId: the trip id. Results will be restricted to those associating to the passed trip. You can get the trip id from the Trips API web service response.

Response

The response is a paginated list of tags.

JSON Example

 {
  "success": true,
  "errorCode": "OK",
  "message": "",
  "next":"&start=10",
  "result": [
   {
      "id": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1432304728",
      "tripId": "34030A94-A886-4C83-9E6F-5B909AE5BA65|1432304728",
      "desTag": "Bag",
      "createUser": "USER",
      "createDate": "2015-05-27 12:48:32",
      "updateDate": null
    },
    {...},
    ...
  ]
}

Master Data

Quickstart

Authentication

Usage Limits and Requirements

Make a request

Response

Generic JSON Example

JSON

Trips API

Required parameters

Optional parameters

Response

JSON Example

Products API

Required parameters

Optional parameters

Response

JSON Example

Single Product API

Required parameters

Optional parameters

Response

JSON Example

Image API

Required parameters

Optional parameters

Response

JSON Example

Suppliers API

Required parameters

Optional parameters

Response

JSON Example

Brands API

Required parameters

Optional parameters

Response

JSON Example

Product Types API

Required parameters

Optional parameters

Response

JSON Example

Ports API

Required parameters

Optional parameters

Response

JSON Example

Made In API

Required parameters

Optional parameters

Response

JSON Example

Delivery Terms API

Required parameters

Optional parameters

Response

JSON Example

Tags API

Required parameters

Optional parameters

Response

JSON Example

API Documentation