Veho API Version 1
Welcome to Veho API Version 1. You can use our API to programmatically create shipments and download shipping labels.
Authentication
To authenticate a POST request to /packages, use this code:
import request from 'request';
function signRequestOptions(options) {
// make sure headers object exists
options.headers = options.headers || {};
// put apiKey in header
options.headers['apiKey'] = '00000000-0000-0000-0000-000000000000';
options.headers['Content-Type'] = 'application/json';
return options;
}
const client = request.defaults({ baseUrl: 'https://api-basic.shipveho.com/v1' });
const myData = { /* ... */ };
const options = signRequestOptions({
method: 'POST',
uri: '/packages',
body: JSON.stringify(myData),
});
client(options, (err, response, body) => {
if (err) {
console.error('request failed', err);
} else if (response.statusCode >= 400) {
console.error('an error occurred', body);
} else {
// process body
}
});
The Veho Basic API requires an API key provided by Veho to access any endpoint.
Veho expects for the signature to be included in all API requests to the server in a header that looks like the following:
apiKey: 00000000-0000-0000-0000-000000000000
Packages
Create a new package
import request from 'request';
const client = request.defaults({ baseUrl: 'https://api-basic.shipveho.com/v1' });
const new_package = {
destination: {
street: "1002 Walnut St",
apartment: "Suite 200",
city: "Boulder",
state: "CO",
zipCode: "80302"
},
phone: "555-555-5555",
recipient: "John Smith",
instructions: "Leave on front porch behind railing. Beware of dog!",
serviceClass: "nextDay",
signatureRequired: "true",
declaredValue: 5000
};
const options = signRequestOptions({
method: 'POST',
uri: '/packages',
body: JSON.stringify(new_package),
});
client(options, (err, response, body) => {
if (err) {
console.error('request failed', err);
} else if (response.statusCode >= 400) {
console.error('error creating package', body);
} else {
console.log(`package "${body._id}" created`);
}
});
The above command returns JSON structured like this:
{
"_id": "BSG6XZQrgwieFFJPx",
"destination": {
"street": "1002 Walnut St",
"apartment": "Suite 200",
"city": "Boulder",
"state": "CO",
"zipCode": "80302"
},
"recipient": "John Smith",
"phone": "555-555-5555",
"instructions": "Leave on front porch behind railing. Beware of dog!",
"serviceClass": "nextDay",
"signatureRequired": true,
"scannedByClient": false,
"createdAt": "2018-07-29T01:09:31.690Z",
"currentState": "created",
"barcode": "veho_id_BSG6XZQrgwieFFJPx",
"zplShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.zpl",
"pdfShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.pdf",
"pngShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.png",
"rate": 1000,
"declaredValue": 5000
}
This endpoint creates a new package. This endpoint should be used by a client upon order completion or fulfillment of an item to notify Veho that there are packages to be shipped, and obtain a barcode and/or shipping label from Veho.
HTTP Request
POST https://api-basic.shipveho.com/v1/packages
Request body
Package Object
Parameter | Type | Description |
---|---|---|
destination | Destination |
address information for delivery (description below) |
serviceClass | string |
requested class of service, currently sameDay or nextDay (defaults to nextDay ) |
recipient | string |
full name of the recipient |
phone | string |
optional phone number of the recipient (used for SMS) |
instructions | string |
optional any additional delivery instructions provided by recipient to assist driver with delivery |
signatureRequired | boolean |
optional set to true if the recipient has to sign for this packages (defaults to false ) |
externalId | string |
optional any ID you want to have stored with this stop. (f.e. an order number) |
width | integer |
optional width of the package, in in |
height | integer |
optional height of the package, in in |
length | integer |
optional length of the package, in in |
weight | integer |
optional weight of the package, in lbs |
declaredValue | Number |
optional declared value of shipment, in USD pennies (5000 is $50 USD) |
Destination object
Destination is an address object in the following shape:
Parameter | Type | Description |
---|---|---|
street | string |
street address |
apartment | string |
optional apartment number, suite number, or any info on the second line of an address |
city | string |
city of the delivery address |
zipCode | string |
ZIP code of the address (view our service area) |
state | string |
state of the address (can be 2 letter postal code, or full state name) |
country | string |
2 letter ISO country code for the address |
Returns
Creating a package object returns the package object, including all the inputted data, any optional data that has default values, and some server-generated data:
Parameter | Type | Description |
---|---|---|
currentState | string |
current state of the package |
barCode | string |
content of the Code128 bar code the package will have |
zplShippingLabelLink | string |
link to zpl shipping label file |
pdfShippingLabelLink | string |
link to pdf shipping label file |
pngShippingLabelLink | string |
link to png shipping label file |
rate | Number |
rate client will be charged, in USD pennies (1000 is $10 USD) |
Get a package
import request from 'request';
const client = request.defaults({ baseUrl: 'https://api-basic.shipveho.com/v1' });
const options = signRequestOptions({
method: 'GET',
uri: '/packages/BSG6XZQrgwieFFJPx'
});
client(options, (err, response, body) => {
if (err) {
console.error('request failed', err);
} else if (response.statusCode >= 400) {
console.error('error retrieving package', body);
} else {
console.log(`package "${body._id}" created`);
}
});
The above command returns JSON structured like this:
{
"_id": "BSG6XZQrgwieFFJPx",
"destination": {
"street": "1002 Walnut St",
"apartment": "Suite 200",
"city": "Boulder",
"state": "CO",
"zipCode": "80302"
},
"phone": "555-555-5555",
"recipient": "John Smith",
"instructions": "Leave on front porch behind railing. Beware of dog!",
"serviceClass": "nextDay",
"signatureRequired": true,
"scannedByClient": false,
"createdAt": "2018-07-29T02:41:36.151Z",
"currentState": "created",
"barcode": "veho_id_BSG6XZQrgwieFFJPx",
"zplShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.zpl",
"pdfShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.pdf",
"pngShippingLabelLink": "https://api-basic.shipveho.com/v1/labels/BSG6XZQrgwieFFJPx.png",
"rate": 1000,
"declaredValue": 5000
}
This endpoint retrieves all details of an existing package.
HTTP Request
GET https://api-basic.shipveho.com/v1/packages/<ID>
URL Parameters
Parameter | Description |
---|---|
ID | _id of the package to retrieve |
Query Parameters
Parameter | Default | Description |
---|
Errors
The Veho API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request |
401 | Unauthorized -- The header did not include a valid apiKey. |
403 | Forbidden -- The requested resource cannot be accessed with this app ID. |
404 | Not Found -- The requested resource could not be found. |
405 | Method Not Allowed -- You tried to access an endpoint with an invalid method. |
406 | Not Acceptable -- You requested a format that isn't json. |
410 | Gone -- The resource requested has been removed from our servers. |
422 | Unprocessable Entity -- The request entity is syntactically correct but semantically incorrect. |
429 | Too Many Requests |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |