API Dokumentace

Contents #

1. Introduction #

VSP API is provided by HTTP REST interface.

API is available on domain https://api.vspdata.cz.

Communication is secured by HTTPS protocol, connection is encrypted (TLSDHERSAWITH AES128CBCSHA, 128 bit key, TLS 1.0)

Certification authority: GeoTrust Inc.

1.1. Interface #

Response:

Every response that contains body will send data in JSON format. This means that the Content-type header will contain application/json.

After success the server returns 200 OK or 201 Created HTTP status code. Otherwise some of 4xx or 5xx HTTP codes are returned.

When the request was successful and there is no data to be returned according to the nature of the request, the success message will be available in "message" property.

When requesting a list due to certain conditions and no data met the conditions, the 204 No Content response with no body is returned.

The body of unsuccessful response will contain error message in "error" property.

I/O data types

  • Base types bool, int, string.
  • float: Decimal number with a dot as a decimal mark.
  • date: Format "YYYY-MM-DD".
  • datetime: Format "YYYY-DD-MM HH:MM".
  • <type>[]: That means the array of inputs of the declared type. Eg. string[] means array of strings ([ "first string", "second", "third" ]).
  • object: Object followed by its properties description in deeper level.

Ranges

When requesting a range of items based on date range, there will be two input parameters: <dateSince> and <dateTo>. Use the date or datetime format. When <dateTo> is only in date format, it will be considered as is at time 23:59:59.

The result JSON will contain properties "totalCount", "pageLimit" and "pagesCount". If the "pagesCount" is bigger than 1, you may need include argument <page> into your request if you want to list older units, and/or include argument <pageLimit> to customize units per page limit (default is 30, maximal number allowed is 200).

1.2. Legend of doc #

In whole API documentation there are certain marks in URL and headers examples that has special meaning. They are the following:

  • < and > encapsulates custom parameters, e.g.: <unit_number>
  • [ and ] encapsulates parts that are optional to be present, e.g.: [since=2014-05-15]

If the request contains body, there will be JSON properties description list in this doc. Additionally there will be JSON Schema file for download, that describes required structure of the JSON body. The description list is structured as follows:

  • (data_type) "property_name": [required] description

That is for example:

  • (string) "partNumber": Material number.

The [required] label means that property must be present in JSON request. Otherwise the property is optional and must not be necessarily present or it may have a value of null. If the object have no label [required] it is optional even though its properties does have the label.

1.3. Compatibility #

The API keeps the backward compatibility, but request or response body can be extended with new properties in future. Be aware of this.

1.4. Test usage #

For testing and development usage, append header X-Connect-To: dev and the request will be send to testing database that contains testing data. So that is the sandbox where you can try everything without worry.

2. Authorization #

2.1. Acquire session token #

Every request must be authorized by user's login and password that the user uses to sign in Business zone on VSP Data Services web site.

Because sending the real password with every request is dangerous, there is a section that lets you to acquire an authorization token to be used with consequent requests. Let make a request:

Request:

  • URL: /authorization
  • METHOD: POST
  • Header: Authorization: Basic <credentials>

<credentials> is base64 encoded string in format login:password. In PHP with cURL it can be written as:

// fill $login and $password variables
curl_setopt( $ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC );
curl_setopt( $ch, CURLOPT_USERPWD, "$login:$password" );

For more information see RFC 2616 chapter 14.8.

Token lifetime is 25 minutes. If there is no request using this token received during last 25 minutes, token will expire. After that, new session must be opened.

Note that token is granted for and only for the requester IP address.

Example response:

{
    "token": "75b4e474279f60aa81cbcb3609148eed1662173d",
    "dev": false
}

The "dev" property says whether request was sent to testing database according to X-Connect-To header (for your check).

2.2. Send requests using token #

After you have got a fresh token, lets call custom requests and add following header into each one:

  • Header: Authorization: Basic <credentials>

Where <credentials> means base64 encoded string auth:<token>. As before, in PHP:

// $token contains freshly acquired token
curl_setopt( $ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC );
curl_setopt( $ch, CURLOPT_USERPWD, "auth:$token" );

2.3. Close connection #

After your work has been done, it is recommended to close the connection. It will make your token useless anymore, so it cannot be used again.

Request:

  • URL: /authorization
  • METHOD: DELETE

You must normally authorize as described in section 2.2.

2.4. Prolong token lifetime #

If you need to use connection longer then 25 minutes but you know that there will be longer deaf interval, you may refresh token lifetime by something like "ping" or "heartbeat". Use following request:

Request:

  • URL: /authorization
  • METHOD: PUT

2.5. Get user's privileges #

To get to know what privileges the authenticated user has, you can ask by following request:

Request:

  • URL: /authorization
  • METHOD: GET

Example response:

"roles": [
    {
        "name": "partnerAdmin",
        "privileges": [
            "case/create",
            "case/update",
            "case/confirm",
            "case/list"
        ],
        "domains": [
            "xiaomi",
            "samsung"
        ]
    },
    {
        "name": "partnerLogistic",
        "privileges": [
            "stock/view",
            "stock/order" 
        ],
        "domains": [
            "xiaomi"
        ]
    }
]

3. Unit #

Unit means single repair case.

To get data about unit, you need to be permitted to list that unit. It is assigned by system administrator.

3.1. List range of units #

Request:

  • URL: /unit?since=<dateSince>[&to=<dateTo>][&status=<status>][&updatedOnly][&search=<search>][&customer=<customer>][&page=<page>][&pageLimit=<pageLimit>][&createdByMe]
  • METHOD: GET
  • example: /unit?since=2014-08-14&status=RW&customer=ABC+Electro

Units are ordered from newest.

You can limit the result to list only units with certain status (or statuses), by adding the <status> parameter into URL.

If you provide an extra parameter updatedOnly, you will get only units that has changed their status since your last request about the units. Notice that this means, that next result for this request will differ from previous, because every request restarts "updated" flags on the units.

To filter case number, identifier or serial number by some characters, use <search> parameter, to filter customer (means name in delivery address), use parameter <customer>. Note that these parameters are accepted only with at minimum 4 characters length.

You may filter only units that was created by you by appending parameter createdByMe.

Server will return JSON object with property "units" that contains array of units that met the conditions. Each unit will contain the data of case id, case number, partner's company identifier, serial number, IMEI number and the current status. See example:

Example response:

{
    "count": 2,
    "totalCount": 2,
    "currentPage": 1,
    "pagesCount": 1,
    "pageLimit": 30,
    "units": [
        {
            "id": 123789,
            "caseNumber": "XIA0123456",
            "vendor": "Xiaomi",
            "identifier": "12345",
            "serialNumber": "ABC012345678",
            "imei": "123456789012345",
            "status": "RW"
        },
        {
            "id": 123456,
            "caseNumber": "XIA6543210",
            "vendor": "Xiaomi",
            "identifier": "12346",
            "serialNumber": "DEF012345678",
            "imei": "543210987654321",
            "status": "PO"
        }
    ]
}

The "status" property will contain two characters long string (ore several ones separated with comma) expressing the position in workflow schema:

VSP case workflow schema

3.2. Get single unit #

More detailed information about single unit can be obtained as follows:

Request:

  • URL: /unit/<caseNumber>
  • URL: /unit/<id>
  • URL: /unit?serialNumber=<serialNumber>
  • URL: /unit?imei=<imeiNumber>
  • URL: /unit?identifier=<identifier>
  • METHOD: GET
  • example: /unit/XIA6543210

Example response:

{
    "id": 123456,
    "caseNumber": "XIA6543210",
    "vendor": "Xiaomi",
    "identifier": "123456",
    "serialNumber": "12345/12AB34567",
    "imei": "543210987654321",
    "serialNumberNew": null,
    "imei2": "356102050573520",
    "imeiNew": null,
    "imei2New": null,
    "macAddress": null,
    "status": "PO",
    "productNumber": "12345",
    "productName": "Tablet ABC 1",
    "warranty": "IWV",
    "language": "cs",
    "symptomCode": "AB01CDN0123",
    "symptomCodeDescription": null,
    "symptomDescription": "Customer's defect description...",
    "errorCodes": [
        {
            "code": "AB01CDN0123",
            "description": "Defective keyboard"
        }
    ],
    "fund": 111.5,
    "accessories": [
        "headphones",
        "battery"
    ],
    "accessoriesEngineer": "mt, sim slot, foile",
    "actionProposal": "Customer requests repair.",
    "visualAppearance": "Appearance of the device upon receipt...",
    "diagnosticMessage": "Message about diagnosis of the device...",
    "engineersMessage": "Engineer's repair result message...",
    "engineersNote": "P.M",
    "engineerName": "240",
    "result": "REP",
    "repairCode": "AB01",
    "repairCodeDescription": null,
    "repairLevel": null,
    "cameraNumberShots": null,
    "swCode": null,
    "shipmentIn": {
        "number": "01234567890123",
        "courier": "DPD"
    },
    "shipmentOut": {
        "number": null,
        "courier": null,
        "price": null
    },
    "purchaseDate": "2021-08-15",
    "claimDate": "2021-10-01",
    "shipmentInDate": "2021-10-01",
    "registeredDate": "2021-10-01",
    "receivedDate": "2021-10-03",
    "inProgressDate": "2021-10-04",
    "quotationDate": null,
    "quotationAcceptedDate": null,
    "finishedDate": null,
    "departedDate": null,
    "deliveryDate": null,
    "trackingNum": "null",
    "closedDate": null,
    "delivery": {
        "name": "Acme co.",
        "street": "Hollywood 14",
        "zip": "900 00",
        "city": "L.A.",
        "country": "US",
        "identificationNumber": "12345678",
        "VAT": "CZ12345678",
        "phone": "+1 555-1234",
        "fax": "+1 555-1234",
        "email": "acme@example.com",
        "contactPerson": "Wile E. Coyote",
        "customerProfile": ""
    },
    "billing": {
        "name": "Acme co. Bank",
        "street": "Hollywood 15",
        "zip": "900 00",
        "city": "L.A.",
        "country": "US",
        "identificationNumber": "12345678",
        "VAT": "CZ12345678",
    },
    "history": [
        {
            "id": 112999,
            "caseNumber": "XIA6543211",
            "type": "pair",
            "registeredDate": "2021-10-01"
        },
        {
            "id": 123456,
            "caseNumber": "XIA6543210",
            "type": "last",
            "registeredDate": "2021-10-01"
        }
    ],
    "material": [
        {
            "partNumber": "5600090C3L00",
            "partName": "Sub-Board Assy",
            "serialNumber": null,
            "pieces": 1,
            "status": "PO",
            "beforeOrderDate": "2021-09-25",
            "orderDate": "2021-09-25",
            "receivedDate": "2021-09-29"
        },
        {
            "partNumber": "5810C3L70000",
            "partName": "Main Board Assy",
            "serialNumber": "XYZ-123",
            "pieces": 1,
            "status": "RW",
            "beforeOrderDate": null,
            "orderDate": null,
            "receivedDate": "2021-09-30"
        }
    ],
    "work": [
        {
            "type": "VD2810"
            "name": "Administrative processing"
        },
        {
            "type": "VD2833"
            "name": "Work L3"
        }
    ],
    "file": {
        "count": 1,
        "quotation": {
            "count": 1,
            "list": [
                {
                    "file_id": 10000,
                    "mime_type": "image/jpeg"
                }
            ]
        }
    }
}

"warranty" can reach values:

valuewarrantorin warrantydescription
IWVvendorYESIn Warranty of Vendor
DOAvendorYESDefective On Arrive
DAPvendorYESDefective After Purchase
OOWcustomerNOOut Of Warranty
CIDcustomerNOCustomer Induced Defect
OWRcustomerNOOver Warranty Repair
NSPcustomerNONot Supported
RERserviceYESRepeated Repair
null--Unknown warranty

"result" can reach values:

valuedescriptioncategory
ACCReplace accessoriesrepaired
REPRepairedrepaired
XCHExchangerepaired
SWRSoftware Re-Imagerepaired
CNCCancelednot repaired
CNDCanceled by vendornot repaired
DBSCreditnot repaired
DIADiagnosticnot repaired
DODDamage by transportnot repaired
NOAReturn without repairnot repaired
NTFNo trouble foundnot repaired
QLEExpiration price quotationnot repaired
QRERejected price quotationnot repaired
SCRScrapnot repaired
nullNot available

The "symptomCode" is the code of the defect from a range agreed with partner's company.

In "repairCode" will be code of the defect defined by engineer.

Part "status" property will contain two characters long string expressing the position in workflow schema:

VSP part workflow schema

If "billing" data equals with the delivery, it will bring a value of null instead of described fields.

The "history" array contains history of device repair cases ordered from the oldest. The "type" property can reach value of common for common repair case, pair for case that is repaired in parallel with the main case (e.g. with different warranty) and last for the last repair. Be aware that this array contains all cases, so even the one requested.

3.3. Create new case #

To create the case, you will need an extra permission.

Request:

  • URL: /unit
  • METHOD: POST
  • Header: Content-type: application/json

Request body JSON properties:

Download case-new.schema.json.

  • (string) "identifier": Your company case identifier. It is up to you, what you will choose as identifier. It only should be unique per case. Its maximal length is 16 characters.
  • (string) "serialNumber": The serial number of the device. Either "serialNumber" or "imei" is [required].
  • (string) "imei": The IMEI number of the device.
  • (string) "imei2": The second IMEI number if the device has it.
  • (string) "vendor": [required] The vendor of the device (eg. Xiaomi, Brother).
  • (string) "productNumber": [required] The product number of the device.
  • (bool) "inWarranty": Your assumption whether the repair will be warranty. null when it is not known.
  • (string) "symptomCode": Code from a range agreed with partner's company that describes certain device symptom.
  • (string) "symptomDescription": Defect description. Either "symptomCode" or "symptomDescription" is [required].
  • (string) "visualAppearance": Outer appearance of the device upon receipt.
  • (date) "purchaseDate": The date when the end customer bought the device.
  • (date) "claimDate": When the date of the begin of complaint differs from today (ie. the day of case creating) it should be defined.
  • (string[]) "accessories": The list of attached accessories.
  • (string) "notice": The internal b2b notice.
  • (object) "delivery": [required] The delivery address information:
    • (string) "name": [required] Full name of end customer / company.
    • (string) "street": [required] Street and number.
    • (string) "zip": [required] Postal code / ZIP.
    • (string) "city": [required] City.
    • (string) "country": [required] ISO 3166-1 2-letter country code.
    • (string) "phone": Customer's phone number.
    • (string) "fax": Customer's fax number.
    • (string) "email": Customer's e-mail address.
    • (string) "contactPerson": The name of person available on given phone/e-mail contacts.
    • (string) "idNumber": National identification number. Used for billing if no billing ID provided.
    • (string) "VAT": Value added tax identification number. Used for billing if no billing VAT provided.
  • (object) "billing": The billing address information. If it is not attached, it is assumed to be the same as delivery.
    • (string) "name": [required] Full name of end customer / company.
    • (string) "street": [required] Street and number.
    • (string) "zip": [required] Postal code / ZIP.
    • (string) "city": [required] City.
    • (string) "country": ISO 3166-1 2-letter country code. Default is the same as delivery.
    • (string) "idNumber": National identification number.
    • (string) "VAT": Value added tax identification number.
  • (float) "fund": Preliminary agreement with a price limit for repair, given in a customer's country currency.
  • (object) "transport": Information on the shipment sent.
    • (string) "company": The shipping company's name.
    • (string) "tracking_number": Designation of the consignment.

Request body example:

{
    "identifier": "123456",
    "serialNumber": "DEF012345678",
    "imei": "543210987654323",
    "vendor": "Xiaomi",
    "productNumber": "99ABC012-00",
    "inWarranty": true,
    "symptomCode": "F123",
    "symptomDescription": "Customer's defect description...",
    "purchaseDate": "2014-08-15",
    "claimDate": "2014-10-01",
    "accessories": [
        "headphones",
        "battery"
    ],
    "delivery": {
        "name": "Acme co.",
        "street": "Hollywood 14",
        "zip": "900 00",
        "city": "L.A.",
        "country": "US",
        "phone": "+1 555-1234",
        "email": "acme@example.com",
        "contactPerson": "Wile E. Coyote"
    },
    "fund": 80,
    "transport": {
        "company": "UPS",
        "tracking_number": "1Z9999999999999999"
    }
}

Example Response:

{
    "message": "Case with identifier 123456 was successfully logged in under the case number XIA0123456.",
    "id": 178901,
    "caseNumber": "XIA0123456"
}

3.4. Update case #

Request:

  • URL: /unit/<caseNumber>
  • URL: /unit/<id>
  • METHOD: PUT
  • Header: Content-type: application/json
  • example: /unit/XIA0123456

Request body JSON properties:

Download case-update.schema.json.

  • (object) "delivery": The delivery address information:
    • (string) "name": Full name of end customer / company. To update address, full one is required (including country).
    • (string) "street": Street and number.
    • (string) "zip": Postal code / ZIP.
    • (string) "city": City.
    • (string) "country": ISO 3166-1 2-letter country code.
    • (string) "phone": Customer's phone number. To update contact information, all "phone", "fax" and "email" are required.
    • (string) "fax": Customer's fax number.
    • (string) "email": Customer's e-mail address.
  • (string) "symptomDescription": Defect description.
  • (string) "visualAppearance": Outer appearance of the device upon receipt.

Request body example:

{
    "symptomDescription": "Modified customer's defect description...",
    "delivery": {
        "name": "Acme Ltd",
        "street": "Hollywood 14",
        "zip": "900 00",
        "city": "L.A.",
        "country": "US"
    }
}

Example Response:

{
    "message": "Case XIA0123456 was successfully updated."
}

3.5. Approve quotation #

2016-03-22 Approve quotation deprecated

Set the case to the approved state when the customer has accepted quotation.

Request:

  • URL: /unit/approve-quotation/<caseNumber>
  • URL: /unit/approve-quotation/<id>
  • METHOD: PUT
  • example: /unit/approve-quotation/XIA0123456

Example Response:

{
    "message": "Quotation for case XIA0123456 was successfully approved."
}

3.6. Release case #

Set the case to the released state after unit has been handed to the customer.

Request:

  • URL: /unit/close/<caseNumber>
  • URL: /unit/close/<id>
  • METHOD: PUT
  • example: /unit/close/XIA0123456

Request body JSON properties:

Download case-close.schema.json.

  • (datetime) "closedDate": The date optionally with time when the unit was released.

Request body example:

{
    "closedDate": "2014-10-12"
}

Example Response:

{
    "message": "Case XIA0123456 was successfully closed."
}

3.7. List quotation for approval #

Available from 2016-03-22

More detailed information about price quotation can be obtained as follows:

Request:

  • URL: /price-quotation/
  • URL: /price-quotation/<caseNumber>
  • METHOD: GET
  • example: /price-quotation/XIA0123456

Example response:

{
    "count": 2,
    "case":
    {
        "XIA0123456":
        {
            "price": 77.55,
            "currency": "EUR"
        },
        "XIA0123789":
        {
            "price": 3500.60,
            "currency": "CZK"
        },
    }
}

3.8. Decision price quotation #

Available from 2016-03-22

Set a decision on the price quotation - approved [QPA] or rejected [QPR].

Request:

  • URL: /price-quotation/decision/
  • METHOD: PUT
  • example: /price-quotation/decision/

Request body JSON properties:

Download decision-price-quotation.schema.json.

  • (string) "caseNumber": The unique identifier for a case.
  • (float) "price": Approved on an amount.
  • (decision) "caseNumber": Your decision to price quotation. QPA (accept) or QPR (rejection).

Request body example:

{
    "caseNumber": "XIA0123456",
    "price": "58.30",
    "decision": "QPA"
}

Example Response:

{
    "message": "Quotation for case XIA0123456 was successfully approved."
}

3.9. Files #

Available from 2019-01-14

You get a list of files for the case:

Request:

  • URL: /unit-file/<caseNumber>
  • METHOD: GET
  • example: /unit-file/XIA0123456

Example response:

{
    "count": 3,
    "quotation": {
        "count": 2,
        "list": [
            {
                "file_id": 10006,
                "mime_type": "image/jpeg"
            },
            {
                "file_id": 10007,
                "mime_type": "image/jpeg"
            }
        ]
    },
    "documentation": {
        "count": 1,
        "list": [
            {
                "file_id": 10008,
                "mime_type": "image/jpeg"
            }
        ]
    }
}

You get a file in base64:

Request:

  • URL: /unit-file/<caseNumber>?file=<file_id>
  • METHOD: GET
  • example: /unit-file/XIA0123456?file=10008

Example response:

{
    "file_id": "10008",
    "type": "quotation",
    "mime_type": "image/jpeg",
    "file": "file in base64"
}

4. Transfer order #

4.1. List range of transfer orders #

Request:

  • URL: /order?since=<dateSince>[&to=<dateTo>][&page=<page>][&pageLimit=<pageLimit>]
  • METHOD: GET
  • example: /order?since=2014-11-10&to=2014-11-20

Orders are ordered from newest.

Server will return JSON object with property "orders" that contains array of orders that met the conditions. Each order is object as the one in an example:

Example response:

{
    "count": 1,
    "totalCount": 1,
    "currentPage": 1,
    "pagesCount": 1,
    "pageLimit": 30,
    "orders": [
        {
            "orderNumber": "ABC-12345",
            "status": "open",
            "country": "CZ",
            "address": [
                "recipient" : "Acme co.",
                "recipient2" : "",
                "street" : "Hollywood 14",
                "city" : "L.A.",
                "zip" : "900 00",
                "country" : "US",
                "state" : "California"
            ],
            "emails": [
                "acme@example.com"
            ],
            "createdDate": "2012-02-15",
            "dispatchMethod": "PPL",
            "priority": 2,
            "referenceId": null,
            "shipmentNumber": "123456",
            "boxNumbers": [
                "1ZW912V20499567169"
            ],
            "boxDetails": {
                "1ZW912V20499567169": {
                    "internalNumber": "H240-00067",
                    "dispatchMethod": "UPS",
                    "shipDate": "2017-03-28 09:03:31",
                    "weight": 11.9,
                    "dimensions": [ 
                        58,
                        33,
                        54
                    ]
                }
            },
            "courier": "PPL",
            "price": {
                "duty": 14.1
            },
            "material": [
                {
                    "partNumber": "305ALT3203W-B",
                    "name": "SIM Tray Dual",
                    "quantity": 9,
                    "orderQty": 10,
                    "unavailableQty": 1,
                    "swap": false
                }
            ]
        }
    ]
}

Status can reach values: open, closed or dispatched.

Address parts count is variable.

4.2. Get single transfer order #

Request:

  • URL: /order/<orderNumber>
  • METHOD: GET
  • example: /order/ABC-12345

The response is one order object, similar as the one in an example response at section 4.1.

4.3. Create new transfer order #

2017-08-01 Create new transfer order deprecated

Replaced by a new method ”Create material order” from 2017-04-01

Request:

  • URL: /order
  • METHOD: POST
  • Header: Content-type: application/json
  • Header: Expect:

Request body JSON properties:

Download material-transfer-order.schema.json.

Request is JSON array that contains one or more order objects with following properties:

  • (string) "orderNumber": [required] The order number.
  • (string) "country": [required] ISO 3166-1 2-letter country code.
  • (string) "address": Address where parts are separated with newline.
  • (array) "address": Or array of address parts. One specification of address is [required].
  • (array) "emails": List of partner e-mail addresses.
  • (string) "dispatchMethod": Dispatch method.
  • (int) "priority": Priority from 1 to 3 (1 = highest).
  • (array) "material": [required] Array of part objects with following properties:
    • (string) "partNumber": [required] Part number.
    • (int) "quantity": [required] Count of parts.

Request body example:

[
    {
        "orderNumber": "ABC-12345",
        "country": "CZ",
        "address": "Acme Ltd.\nHollywood 7\n901 00",
        "emails": [
            "acme@example.com"
        ],
        "dispatchMethod": "PPL",
        "priority": 2,
        "material": [
            {
                "partNumber": "AAAA123456",
                "quantity": 25
            },
            {
                "partNumber": "BBBB123456",
                "quantity": 4
            }
        ]
    }
]

Example Response:

{
    "message": "Order ABC-12345 was successfully logged. Booked 29 pieces of material."
}

4.4. Remove transfer order #

Request:

  • URL: /order/<orderNumber>
  • METHOD: DELETE

Order can be removed only if it is not processed yet.

4.5. Create material income #

available from 2017-04-01

By this method is it possible to manage inbound material and upload information about new parts. It’s combination of inbounds pre-alerts and “part master”.

Request:

  • URL: /material-income
  • METHOD: POST
  • Header: Content-type: application/json
  • Header: Expect:

Request body JSON properties:

Download material-order-income.schema.json.

  • (enum) "vendor": [required] The vendor of the device (eg. Xiaomi, Brother).
  • (string) "shippingNumber": [required] Number of shipment which is usable for tracking
  • (string) "orderNumber": [required] number of shipment which is used for shipment identification
  • (int) "weight": [required] weight of whole shipment in grams.
  • (int) "countOfBoxes": count of shipment internal boxes.
  • (array) "parts": [required] Array of part objects with following properties:
    • (object) "PartInfo": [required] detail information about part with following properties:
    • (string) "partNumber": [required] P/N of spare part
    • (string) "name": [required] short description of part
    • (string) "countryOfOrigin": 2 char ISO country code
    • (enum) "qtyUnit": [required] quantitative unit ['PCS','kg','m','l'/.. and so/
    • (float) "minPackQty": Minimum QTY of spare part in the smallest package
    • (float) "price": price, which is used for customs clearance
    • (string) "priceCurrency": 3- char ISO code for currency (e.g. EUR, CZK ...)
    • (string) "commodity": commodity code for customs clearance and Intrastat
    • (int) "weight": weight of each one part per quantitative unit in grams
    • (string) "boxNumber": if more internal boxes are included in one shipment
    • (int) "qty": [required] quantity in spare box
    • (string) "location": stock location code in VSP

Request body example:

{
    "vendor":"Caterpillar",
    "shippingNumber" : "CP146321",
    "orderNumber" : "CP146321",
    "weight" : 1295,
    "countOfBoxes" : 1,
    "parts" : [
        {
            "partInfo" : 
                {
                    "partNumber" : "S2-60BRQ",
                    "name" : "Main Board Assembly",
                    "countryOfOrigin" : "JP",
                    "qtyUnit" : "PCS",
                    "minPackQty" : 1,
                    "price" : 114.86,
                    "priceCurrency" : "EUR",
                    "commodity" : "8414900090",
                    "weight" : 73
                },
            "boxNumber" : "internalbox1",
            "qty" : 10,
            "location" : "D030603"
        },
        {
            "partInfo" : 
                {
                    "partNumber" : "305ALT3203W-B",
                    "name" : "SIM Tray Dual",
                    "countryOfOrigin" : "JP",
                    "qtyUnit" : "PCS",
                    "minPackQty" : 20,
                    "price" : 0.23,
                    "priceCurrency" : "EUR",
                    "commodity" : "8414900100",
                    "weight" : 4
                },
            "boxNumber" : "internalbox1",
            "qty" : 100,
            "location" : "D030654"
        }
    ]
}

4.6. List range of material income #

available from 2017-04-01

Request:

  • URL: /material-income?since=<dateSince>[&to=<dateTo>][&page=<page>] [&pageLimit=<pageLimit>]
  • METHOD: GET
  • example: /material-income?since=2014-11-10&to=2014-11-20`

Material income shipments are ordered from newest.

Server will return JSON object with property "orders" that contains array of orders that met the conditions. Each order is object as the one in an example:

Example response::

{
    "count": 1,
    "totalCount": 1,
    "currentPage": 1,
    "pagesCount": 1,
    "pageLimit": 30,
    "orders": [
        {
            "orderNumber": "CP148900",
            "status": "IN_TRANSIT",
            "parts": [
                {
                    "partNumber": "636-151-9199",
                    "name": "WATERPROOF PACKING",
                    "PCS": 1,
                    "partStatus": "IN_TRANSIT",
                    "params": {
                    "Commodity": "8529902000",
                    "Weight": "1",
                    "MinPackQty": "5",
                    "CountryOfOrigin": "ID",
                    "QtyUnit": "PCS"
                }
            },
            {
                "partNumber": "636-152-1949",
                "name": "USB PCB",
                "PCS": 5,
                "partStatus": "IN_TRANSIT",
                "params": {
                    "Commodity": "85299020",
                    "Weight": "0.7",
                    "MinPackQty": "5",
                    "CountryOfOrigin": "ID",
                    "QtyUnit": "PCS"
                }
            }
        }
    ]
}

Status can reach values: STORNO, IN_TRANSIT, RECEIVED.

4.7. Get single material income #

available from 2017-04-01

Request:

  • URL: /material-income/<orderNumber>
  • METHOD: GET
  • example: /material-income/ABC-12345`

The response is one order object, similar as the one in an example response at section 4.6. List range of material income

4.8. Create material order #

available from 2017-04-01

By this method is it possible to manage material transfer from VSP to customer.

Note, it is possible to manage Selective packing process for decrease transport taxes.

VSP Selective Packing workflow schema

Validation schema of order request

VSP Material order validation schema

Request:

  • URL: /material-transfer
  • METHOD: POST
  • Header: Content-type: application/json
  • Header: Expect:

Request body example:

Download material-order-transfer.schema.json.

Request is JSON array that contains one or more order objects with following properties:

  • (string) "vendor": [required] The vendor of the device (eg. Xiaomi, Brother).
  • (string) "orderNumber": [required] number of order which is used for shipment identification.
  • (string) "customerOrderNumber": customer internal order number
  • (string) " invoiceNumber ": number of proforma invoice – which must be added into shipment when the end customer is out of EU
  • (object) "deliveryAddress": The delivery address information:
    • (string) " recipient" [required] Full name of end customer / company. To
    • (string) " recipient2"
    • (string) "street": [required] Street and number.
    • (string) "city": [required] City.
    • (string) "zip": [required] Postal code / ZIP.
    • (string) "country": [required] ISO 3166-1 2-letter country code.
    • (string) "state": or province.
  • (object) "delivery": customer contact information
    • (string) "name": [required] contact person name
    • (string) "phone": Customer's phone number. To update contact information, all "phone", "fax" and "email" are required.
    • (string) "email": Customer's e-mail address.
  • (object) "billingAddress":
    • (string) " recipient" [required] Full name of end customer / company. To
    • (string) " recipient2"
    • (string) "street": [required] Street and number.
    • (string) "city": [required] City.
    • (string) "zip": [required] Postal code / ZIP.
    • (string) "country": [required] ISO 3166-1 2-letter country code.
    • (string) "state": or province.
    • (string) "VATNumber": VAT number
  • (string) "dispatchMethod": requested courier .g. PPL, UPS
  • (int) "priority": 1 - High, 2 - Normal, 3 - Low;
  • (string) "sellPriceCurrency": 3-char ISO code for currency (e.g. EUR, CZK ...)
  • (float) "sellPriceVAT": value of VAT if it's
  • (float) "sellPriceVATRate": percentage rate of VAT
  • (array) "material": [required] array of material object with following properties:
    • (string) "partNumber": [required] P/N of spare part
    • (string) "partDescription": part description in required form by customer
    • (int) "qty": [required] quantity in single box(line)
    • (string) "requestID": identification number of customer request
    • (string) "referenceNumber": reference number for linking invoice data
    • (string) "shipID": identification of partner request (line based)
    • (string) "ASPPartNumber": required if the customer are using another coding of P/N
    • (string) "locationCode": customer stock location code
    • (string) "customerNote": Comment: Customer note on line-base to give special comments to be printed on shipping-list/dispatch note
    • (string) "boxNumber": identification of box for Selective Packing
  • (object) "specialInstruction": use if you need to block dispatch or if you can send some message to VSP
    • (enum) "action": [‘waitWithPicking’, ‘waitWithShipping’, ‘onlyMessage’];
    • (text) "description": your additional message to VSP.

Request body example:

[
    {
        "vendor":"Nikon",
        "orderNumber" : "5099175",
        "customerOrderNumber" : "order",
        "shipID" : "5099175",
        "invoiceNumber" : "PF5099175",
        "deliveryAddress" : {
            "recipient" : "Acme co.",
            "recipient2" : "",
            "street" : "Hollywood 14",
            "city" : "L.A.",
            "zip" : "900 00",
            "country" : "US",
            "state" : "California"
        },
        "contact" : {
            "name" : "Arnold Simpson, Acme co.",
            "phone" : "+1 310 230 100 54",
            "email" : null
        },
        "billingAddress" : {
            "recipient" : "Acme co. Bank",
            "recipient2" : "",
            "street" : " Hollywood 14",
            "city" : "L.A.",
            "zip" : "900 00",
            "country" : "US",
            "state" : "California",
            "VATNumber" : "CZ12345678"
        },
        "dispatchMethod" : "BEST WAY",
        "priority" : 2,
        "sellPriceCurrency" : "USD",
        "sellPriceVAT" : "56.46",
        "sellPriceVATRate" : "15.00",
        "material" : [
            {
                "partNumber" : "S2-60BRQ",
                "partDescription" : "Main Board Assembly",
                "qty" : 2,
                "requestID" : "5645921",
                "referenceNumber" : "5645921",
                "ASPPartNumber" : null,
                "boxNumber" : null,
                "locationCode" : "I-7",
                "sellPrice" : "184.2",
                "shipID" : "5099175",
                "customerNote"  : null
            },
            {
                "partNumber" : "305ALT3203W-B",
                "partDescription" : "SIM Tray Dual",
                "qty" : 10,
                "requestID" : "5645921",
                "referenceNumber" : "5645921",
                "ASPPartNumber" : null,
                "boxNumber" : null,
                "locationCode" : "I-7",
                "sellPrice" : "0.8",
                "shipID" : "5099175",
                "customerNote"  : null
            }
        ],
        "specialInstruction" : {
            "action" : "onlyMessage",
            "description" : "Standard process"
        }
    }
]

5. Stock levels #

5.1. List stock levels #

Request:

  • URL: /stock?vendor=<vendor>&stock=<stock>
  • METHOD: GET
  • example: /stock?vendor=Xiaomi[&stock=H01]

Server will return JSON object with property "material" that contains array of parts in stock.

Example response:

{
    "count": 2,
    "material": [
        {
            "partNumber": "AAAA123456",
            "partName": "SCREW",
            "freeQuantity": 170,
            "bookedQuantity": 25,
            "orders":
            [
                "orderNumber": "ABC-12345"
            ]
        },
        {
            "partNumber": "BBBB123477",
            "partName": "NUT E-300",
            "freeQuantity": 350,
            "bookedQuantity": 0,
            "orders":
            [
            ]
        }
    ]
}

6. Parts information #

6.1. The status of parts in stock #

Request:

  • URL: /part?part=<partNumber>
  • METHOD: GET
  • example: /part?part=ABCD123-45

Server will return JSON object with property "cases" that contains array of open cases with the specified part.

Example response:

{
    "partNumber": "AAAA123-45",
    "partName": "SCREW",
    "vendor": "Xiaomi",
    "stock": {
        "PA": 274,
        "RW": 7,
        "PC": 4534,
        "CA": 3
    },
    "cases": [
    [
        "XIA012345",
        "XIA012346",
        "XIA013235",
        "XIA014346",
        "XIA015457"
    ]
}

6.2. The number of parts in a given status #

Request:

  • URL: /part?part=<partNumber>&status=<status>
  • METHOD: GET
  • example: /part?part=ABCD123-45&status=RW

Example response:

{
    "partNumber": "AAAA123-45",
    "partName": "SCREW",
    "vendor": "Xiaomi",
    "stock": 7
}

6.3. Consumption of parts on case #

  • URL: /part-consumption/<caseNumber>
  • METHOD: GET
  • example: /part-consumption/ABC0123456

Server will return JSON object with property "parts" that contains array of parts consumed in the case.

Example response:

{
    "caseNumber": "ABC0123456",
    "parts": [
        {
            "partNumber": "ABCD123-45",
            "status": "PC"
        },
        {
            "partNumber": "ABDE456-78",
            "status": "PC"
        },
        {
            "partNumber": "83ABC016-23M",
            "status": "RW"
        }
    ]
}

6.4. Consumption of parts for a specified period #

  • URL: /part-consumption?since=<dateSince>&to=<dateTo>
  • METHOD: GET
  • example: /part-consumption?since=2015-09-01&to=2015-09-10

The maximum period is 10 days.

Server will return JSON object with property "parts" that contains array of parts consumed for a specified period.

Example response:

{
    "parts": [
        {
            "caseNumber": "ABC1234567",
            "partNumber": "ABCD123-45",
            "status": "PC"
        },
        {
            "caseNumber": "CD00011236",
            "partNumber": "ABDE456-78",
            "status": "RW"
        },
        {
            "caseNumber": "CEA14788999",
            "partNumber": "83ABC016-23M",
            "status": "DP"
        }
    ]
}