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:
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 }, {...}, ... ] }
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" }, {...}, ... ] }
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" }, {...}, ... ] }
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" }, {...}, ... ] }
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" }, {...}, ... ] }
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 }, {...}, ... ] }