Servo includes a simple REST-type API which enables other programs to communicate with the system.
The order status API allows you to programmatically query the database for the current status of a service order. You can then integrate this data to your webpage or CRM system. The order status API is public (it does not require authentication):
curl https://example.servoapp.com/api/status/?q=11012765
The response is returned as a JSON-encoded string:
{"status": "Awaiting parts", "timeline": [{"status": "Awaiting parts", "started_at": "2015-02-14T13:41:19.501856+00:00", "badge": "warning", "description": ""}, {"status": "In the service queue", "started_at": "2015-02-14T13:39:16.049317+00:00", "badge": "warning", "description": ""}], "status_description": "", "order": "11012765"}
Note: The "timeline" array is only available if you've enabled "Show timeline" under "Check-in" settings. The status_description field is taken from the description field of the status (configurable in the system settings). The "badge" field reflects the duration of the status compared to the time limits you've set in your status configuration with "success" meaning the age is within the set limits, "warning" - status age is nearing limits and "danger" meaning the age has exceeded the set limits.
To perform a warranty lookup for a device, generate an API token for a user (Settings > Users & Groups > Permissions) and then include that token in the authorization header of your request:
curl -H 'Authorization: Token 976f7492627e2c8ca3bfc77b9286db5097c69e57' https://example.servoapp.com/api/warranty/?sn=DGKFL06JDHJP
The response is returned as a JSON-encoded string:
{"description": "iMac (27-inch, Mid 2011)", "unlocked": null, "warranty_status": "OOW", "parts_and_labor_covered": false, "contract_end_date": null, "image_url": "", "sn": "DGKFL06JDHJP", "applied_activation_policy": "", "imei": "", "purchased_on": "2011-06-02", "fmip_active": false, "configuration": "IMAC 27\"/2.7QC/2X2GB/1TB/6770M"}
A single user account may have several API tokens so you can create one general API user and then use different tokens for different implementations. To revoke API access for an account, simply delete the account's API token(s).
Orders can be created through the API using an authentication token and providing the order data as a JSON object in the request body. An example with curl would look like this:
curl -H 'Authorization: Token f2acb606f32bc3e0b2b03e0325ad17d1b084e6f4' http://localhost:8000/api/orders/ -d @create_order.json
create_order.json:
{
"problem": "Problem description goes here",
"customer": {
"name": "Filipp Lepalaan",
"email": "support@servoapp.com",
"city": "Helsinki",
"zip_code": "00500",
"street_address": "Somestreet 19"
},
"attachment": {
"name": "receipt.pdf",
"data": "JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvYmoKPDwgL0xlbmd0aCA1IDAgUiAvRmlsdGVyIC9GbGF0ZURlY29kZSA+PgpzdHJlYW0KeAErVAgEAAHnAOMKZW5kc3RyZWFtCmVuZG9iago1IDAgb2JqCjExCmVuZG9iagoyIDAgb2JqCjw8IC9UeXBlIC9QYWdlIC9QYXJlbnQgMyAwIFIgL1Jlc291cmNlcyA2IDAgUiAvQ29udGVudHMgNCAwIFIgL01lZGlhQm94IFswIDAgNTk1IDg0Ml0KPj4KZW5kb2JqCjYgMCBvYmoKPDwgL1Byb2NTZXQgWyAvUERGIF0gPj4KZW5kb2JqCjMgMCBvYmoKPDwgL1R5cGUgL1BhZ2VzIC9NZWRpYUJveCBbMCAwIDU5NSA4NDJdIC9Db3VudCAxIC9LaWRzIFsgMiAwIFIgXSA+PgplbmRvYmoKNyAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMyAwIFIgPj4KZW5kb2JqCjggMCBvYmoKKFVudGl0bGVkKQplbmRvYmoKOSAwIG9iagooTWFjIE9TIFggMTAuOS41IFF1YXJ0eiBQREZDb250ZXh0KQplbmRvYmoKMTAgMCBvYmoKKEZpbGlwcCBMZXBhbGFhbikKZW5kb2JqCjExIDAgb2JqCigpCmVuZG9iagoxMiAwIG9iagooVGV4dEVkaXQpCmVuZG9iagoxMyAwIG9iagooRDoyMDE1MDUwODA4MjkxOFowMCcwMCcpCmVuZG9iagoxNCAwIG9iagooKQplbmRvYmoKMTUgMCBvYmoKWyAoKSBdCmVuZG9iagoxIDAgb2JqCjw8IC9UaXRsZSA4IDAgUiAvQXV0aG9yIDEwIDAgUiAvU3ViamVjdCAxMSAwIFIgL1Byb2R1Y2VyIDkgMCBSIC9DcmVhdG9yIDEyIDAgUgovQ3JlYXRpb25EYXRlIDEzIDAgUiAvTW9kRGF0ZSAxMyAwIFIgL0tleXdvcmRzIDE0IDAgUiAvQUFQTDpLZXl3b3JkcyAxNSAwIFIKPj4KZW5kb2JqCnhyZWYKMCAxNgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDA2NDEgMDAwMDAgbiAKMDAwMDAwMDEyNSAwMDAwMCBuIAowMDAwMDAwMjY4IDAwMDAwIG4gCjAwMDAwMDAwMjIgMDAwMDAgbiAKMDAwMDAwMDEwNyAwMDAwMCBuIAowMDAwMDAwMjI5IDAwMDAwIG4gCjAwMDAwMDAzNTEgMDAwMDAgbiAKMDAwMDAwMDQwMCAwMDAwMCBuIAowMDAwMDAwNDI2IDAwMDAwIG4gCjAwMDAwMDA0NzcgMDAwMDAgbiAKMDAwMDAwMDUxMSAwMDAwMCBuIAowMDAwMDAwNTMwIDAwMDAwIG4gCjAwMDAwMDA1NTcgMDAwMDAgbiAKMDAwMDAwMDU5OSAwMDAwMCBuIAowMDAwMDAwNjE4IDAwMDAwIG4gCnRyYWlsZXIKPDwgL1NpemUgMTYgL1Jvb3QgNyAwIFIgL0luZm8gMSAwIFIgL0lEIFsgPDRlMGI4Y2UyZmEzNjdkZjU4MThjOGE4ZjBiYTczZDM1Pgo8NGUwYjhjZTJmYTM2N2RmNTgxOGM4YThmMGJhNzNkMzU+IF0gPj4Kc3RhcnR4cmVmCjgxNAolJUVPRgo="
},
"device": {
"sn": "11112222333344445555",
"description": "MacBook Pro",
"accessories": ["Power adapter"]
}
}
A breakdown of the fields:
Field | Explanation | Example | Required |
---|---|---|---|
problem | A problem description for this order. Creates a note. | Does not work | Yes |
customer.name | Name of customer | Johnny Appleseed | Yes |
customer.email | e-mail address of customer | support@servoapp.com | Yes |
customer.phone | Phone number of customer | 3584521023124 | No |
customer.city | City of customer | Helsinki | No |
customer.zip_code | Postal code | 00500 | No |
customer.street_address | Postal address | Somestreet 19 | No |
attachment.name | Name of attached file | receipt.pdf | No |
attachment.data | An attachment to go with the problem description | BASE64-encoded data | No |
device.sn | Serial number or IMEI code of serviced device | 1111111111 | No |
device.description | Description of device | MacBook Pro | No |
device.accessories | List of accessories supplied with the device | ["power adapter", "second skin"] | No |