Master Data

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:

APIAPI NAMELINK
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.

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

Schermata-2015-07-21-alle-14.27.41

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:

URLhttps://manage.yourpicktour.com/platform/api?cmd=API_NAME&PARAM_1=VALUE_1&PARAM_2=VALUE_2
Request-typePOST
Content-typeapplication/x-www-form-urlencoded
DataauthToken=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_NAMEtrips_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_NAMEproducts_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_NAMEsingle_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_NAMEimage_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_NAMEsuppliers_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_NAMEbrands_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_NAMEproduct_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_NAMEports_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_NAMEmade_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_NAMEdelivery_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_NAMEtags_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
    },
    {...},
    ...
  ]
}

API Documentation

Sinesy s.r.l. – Privacy Policy & Cookie Policy – Copyright © All Right Reserved