aftership
v8.1.0
Published
node.js SDK for AfterShip API
Downloads
16,728
Readme
aftership-sdk-node
node.js SDK for AfterShip API
Key features
- The SDK is now isomorphic, you can use it on both client and server side.
- Support IntelliSense in IDE
- Support TypeScript
Installation
npm install aftership
Quick Start
const { AfterShip } = require('aftership');
const aftership = new AfterShip('YOUR_API_KEY');
aftership.courier.listAllCouriers()
.then(result => console.log(result))
.catch(err => console.log(err));
/** Console
{ total: 335,
couriers:
[ ... ]
}
*/
Test
npm run test
Table of contents
- Constructor(api_key[, options])
- Endpoints
- Rate Limiter
- Error Handling
- Examples
- Migrations
- Help
- Contributing
Constructor(api_key[, options])
Create AfterShip instance with options
api_key
- Require - your Aftership API keyoptions
- Optional - object of request optionsendpoint
- string, AfterShip endpoint, default 'https://api.aftership.com/tracking/2023-10'user_agent_prefix
- string, prefix of User-Agent in headers, default 'aftership-sdk-nodejs'auth_type
-number, if authentication type is AES, useAuthType.Aes
, defaultAuthType.ApiKey
.api_secret
-string, if authentication type is AES, it is required.
Example:
// Construct with options
const aftership = new AfterShip('YOUR_API_KEY', {
auth_type: AuthType.Aes, api_secret:'YOUR_API_SECRET'
});
Endpoints
The AfterShip instance has the following properties which are exactly the same as the API endpoins:
courier
- Get a list of our supported couriers.tracking
- Create trackings, update trackings, and get tracking results.last_checkpoint
- Get tracking information of the last checkpoint of a tracking.notification
- Get, add or remove contacts (sms or email) to be notified when the status of a tracking has changed.
Make request in a specific endpoint
// GET /trackings/:slug/:tracking_number
aftership.tracking
.getTracking({
slug: "ups",
tracking_number: "1234567890",
})
.then(result => console.log(result))
.catch(err => console.log(err));
Rate Limiter
See the Rate Limit to understand the AfterShip rate limit policy.
You can get the recent rate limit by aftership.rate_limit
. Initially all value are null
.
const { AfterShip } = require('aftership');
const aftership = new AfterShip('YOUR_API_KEY');
console.log(aftership.rate_limit);
// console output
// { reset: null, limit: null, remaining: null }
After making an API call, it will be set.
aftership.courier.listCouriers()
.then(result => {
console.log(result);
console.log(aftership.rate_limit);
})
.catch(err => console.log(err));
// console output
// { limit: 600, remaining: 599, reset: 1453281417 }
Error Handling
There are 3 kinds of error
- SDK Error
- Request Error
- API Error
Error object of this SDK contain fields:
type
- Require - type of the error, please handle each error by this fieldmessage
- Optional - detail message of the errordata
- Optional - data lead to the errorcode
- Optional - error code for API Errorresponse_body
- Optional - response body of API Error
Please handle each error by its
type
, since it is a require field
SDK Error
Error return by the SDK instance, mostly invalid param type when calling constructor
or endpoint method
error.type
is one of error_enum
Throw by the SDK instance
const { AfterShip } = require('aftership');
const aftership = new AfterShip('YOUR_API_KEY');
// GET /notifications/:slug/:tracking_number
aftership.notification.getNotification()
.then(result => console.log(result))
.catch(err => console.log(err));
/*
{ Error: HandlerError: You must specify the id or slug and tracking number
type: 'HandlerError',
code: '',
data: undefined,
responseBody: '' }
*/
Request Error
Error return by the request
moduleerror.type
could be ETIMEDOUT
, ECONNRESET
, etc.
Catch by promise
const { AfterShip } = require('aftership');
const aftership = new AfterShip('YOUR_API_KEY');
aftership.courier.listCouriers()
.then(result => console.log(result))
.catch(err => console.log(err));
/*
{ Error: getaddrinfo ENOTFOUND api.aftership.com api.aftership.com:443
type: 'ENOTFOUND',
code: 'ENOTFOUND',
... }
*/
API Error
Error return by the Aftership APIerror.type
should be same as request error.
Catch by promise
const { AfterShip } = require('aftership');
const aftership = new AfterShip('INVALID_API_KEY');
aftership.courier.listCouriers()
.then(result => console.log(result))
.catch(err => console.log(err));
/*
{ [Error: Invalid API key.]
type: 'Unauthorized',
message: 'Invalid API key.',
code: 401,
data: {},
response_body: '{"meta":{"code":401,"message":"Invalid API key.","type":"Unauthorized"},"data":{}}' }
*/
Examples
/couriers
GET /couriers
aftership.courier.listCouriers()
.then(result => console.log(result))
.catch(e => console.log(e));
GET /couriers/all
aftership.courier.listAllCouriers()
.then(result => console.log(result))
.catch(e => console.log(e));
POST /couriers/detect
const payload = {
'tracking': {
'tracking_number': '906587618687',
'tracking_postal_code': 'DA15BU',
'tracking_ship_date': '20131231',
'tracking_account_number': '1234567890',
'slug': ['dhl', 'ups', 'fedex']
}
};
aftership.courier.detectCouriers(payload)
.then(result => console.log(result))
.catch(e => console.log(e));
/trackings
POST /trackings
const payload = {
'tracking': {
'slug': 'dhl',
'tracking_number': '123456789',
'title': 'Title Name',
'smses': [
'+18555072509',
'+18555072501'
],
'emails': [
'[email protected]',
'[email protected]'
],
'order_id': 'ID 1234',
'order_id_path': 'http://www.aftership.com/order_id=1234',
'custom_fields': {
'product_name': 'iPhone Case',
'product_price': 'USD19.99'
}
}
};
aftership.tracking
.createTracking(payload)
.then((result) => console.log(result))
.catch((e) => console.log(e));
DELETE /trackings/:slug/:tracking_number
aftership.tracking
.deleteTracking({
slug: "ups",
tracking_number: "1234567890",
})
.then((result) => console.log(result))
.catch((e) => console.log(e));
GET /trackings
const query = {
slug: 'dhl,ups,usps'
};
aftership.tracking
.listTrackings(query)
.then((result) => console.log(result))
.catch((e) => console.log(e));
GET /trackings/:slug/:tracking_number
aftership.tracking
.getTracking({
slug: "ups",
tracking_number: "1234567890",
})
.then((result) => console.log(result))
.catch((e) => console.log(e));
Tip: You can also add optional_parameters
to /:slug/:tracking_number
// GET /trackings/:slug/:tracking_number?tracking_postal_code=:postal_code&tracking_ship_date=:ship_date
aftership.tracking
.getTracking({
slug: "ups",
tracking_number: "1234567890",
optional_parameters: {
tracking_postal_code: "1234",
tracking_ship_date: "20200423",
}
})
.then((result) => console.log(result))
.catch((e) => console.log(e));
Pro Tip: You can always use /:id to replace /:slug/:tracking_number.
// GET /trackings/:id
aftership.tracking
.getTracking({
id: "1234567890",
})
.then((result) => console.log(result))
.catch((e) => console.log(e));
PUT /trackings/:slug/:tracking_number
const payload = {
tracking: {
title: "New Title",
},
};
aftership.tracking
.updateTracking({
slug: "ups",
tracking_number: "1234567890",
}, payload)
.then((result) => console.log(result))
.catch((e) => console.log(e));
POST /trackings/:slug/:tracking_number/retrack
aftership.tracking
.retrack({
slug: "ups",
tracking_number: "1234567890",
})
.then((result) => console.log(result))
.catch((e) => console.log(e));
POST /trackings/:slug/:tracking_number/mark-as-completed
aftership.tracking
.markAsCompleted({
slug: "ups",
tracking_number: "1234567890",
}, {
reason: "DELIVERED"
})
.then((result) => console.log(result))
.catch((e) => console.log(e));
/last_checkpoint
GET /last_checkpoint/:slug/:tracking_number
aftership.last_checkpoint.getLastCheckpoint({
slug: 'ups',
tracking_number: '1234567890',
})
.then(result => console.log(result))
.catch(e => console.log(e));
/notifications
GET /notifications/:slug/:tracking_number
aftership.notification.getNotification({
slug: 'ups',
tracking_number: '1234567890',
})
.then(result => console.log(result))
.catch(e => console.log(e));
POST /notifications/:slug/:tracking_number/add
const payload = {
'notification': {
'emails': ['[email protected]','[email protected]','invalid EMail @ Gmail. com'],
'smses': ['+85291239123', '+85261236123', 'Invalid Mobile Phone Number']
}
};
aftership.notification.addNotification({
slug: 'ups',
tracking_number: '1234567890',
}, payload)
.then(result => console.log(result))
.catch(e => console.log(e));
POST /notifications/:slug/:tracking_number/remove
const payload = {
'notification': {
'emails': ['[email protected]','[email protected]','invalid EMail @ Gmail. com'],
'smses': ['+85291239123', '+85261236123', 'Invalid Mobile Phone Number']
}
};
aftership.notification.removeNotification({
slug: 'ups',
tracking_number: '1234567890',
}, payload)
.then(result => console.log(result))
.catch(e => console.log(e));
Migrations
// v5 (old version)
const Aftership = require('aftership')('YOUR_API_KEY');
Aftership.call('GET', '/couriers/all').then(function (result) {
console.log(result);
}).catch(function (err) {
console.log(err);
});
// v6 (new version)
const { AfterShip } = require('aftership');
const aftership = new AfterShip('YOUR_API_KEY');
aftership.courier.listAllCouriers()
.then(result => console.log(result))
.catch(err => console.log(err));
Help
If you get stuck, we're here to help. The following are the best ways to get assistance working through your issue:
- Issue Tracker for questions, feature requests, bug reports and general discussion related to this package. Try searching before you create a new issue.
- Slack AfterShip-SDKs: a Slack community, you can find the maintainers and users of this package in #aftership-sdks.
Contributing
For details on contributing to this repository, see the contributing guide.
License
Copyright (c) 2016-2020 AfterShip
Licensed under the MIT license.