Onfleet Node.js Wrapper
Read this document in another language:
Français
正體中文
Español
Visit our blog post on the API wrapper project to learn more about our initiatives.
If you have any questions, please reach us by submitting an issue here or contact support@onfleet.com.
Table of contents
- Onfleet Node.js Wrapper
Synopsis
The Onfleet Node.js library provides convenient access to the Onfleet API.
Installation
npm install @onfleet/node-onfleet
For TypeScript, install the typed definition:
npm install @types/onfleet__node-onfleet
Kudos to @marcobeltempo for the contribution!
Usage
Before using the API wrapper, you will need to obtain an API key from one of your organization's admins.
Creation and integration of API keys are performed through the Onfleet dashboard.
To start utilizing the library, you simply need to create an Onfleet
object with your API key:
const onfleetApi = new Onfleet("<your_api_key>");
Optionally, you can introduce a customized timeout that is less than the default Onfleet API timeout (70,000 ms) by providing a 2nd parameter:
const onfleetApi = new Onfleet("<your_api_key>", 30000);
Optionally again, you can introduce an options object for Bottleneck as a 3rd parameter:
const onfleetApi = new Onfleet("<your_api_key>", 30000, {
LIMITER_RESERVOIR: 10, // Default: 20
LIMITER_WAIT_UPON_DEPLETION: 20000, // Default: 10000
LIMITER_MAX_CONCURRENT: 5, // Default: 1
LIMITER_MIN_TIME: 50, // Default: 50
});
Authentication
Once the Onfleet
object is created, you can test on the authentication endpoint:
onfleetApi.verifyKey(); // Returns a boolean
Unit Testing
npm test
Unit testing using Docker
docker-compose up --build
Throttling
Rate limiting is enforced by the API with a threshold of 20 requests per second across all your organization's API keys. Learn more about it here.
We have also implemented a limiter on this library to avoid you from unintentionally exceeding your rate limitations and eventually be banned for.
Responses
Responses of this library are instances of Response.
Supported CRUD Operations
Here are the operations available for each entity:
Entity | GET | POST | PUT | DELETE |
---|---|---|---|---|
Admins/Administrators | get() | create(obj) matchMetadata(obj) |
update(id, obj) | deleteOne(id) |
Containers | get(id, 'workers') get(id, 'teams') get(id, 'organizations') |
x | insertTask(id, obj) | x |
Destinations | get(id) | create(obj) matchMetadata(obj) |
x | x |
Hubs | get() | create(obj) | update(id, obj) | x |
Organization | get() get(id) |
x | x | x |
Recipients | get(id) get(name, 'name') get(phone, 'phone') |
create(obj) matchMetadata(obj) |
update(id, obj) | x |
Tasks | get(query) get(id) get(shortId, 'shortId') |
create(obj) clone(id) clone(id, obj) forceComplete(id, obj) batchCreate(obj) batchCreateAsync(obj) getBatch(id) autoAssign(obj) matchMetadata(obj) |
update(id, obj) | deleteOne(id) |
Teams | get() get(id) getWorkerEta(id, obj) getTasks(id) |
create(obj) autoDispatch(id, obj) |
update(id, obj) | deleteOne(id) |
Webhooks | get() | create(obj) | x | deleteOne(id) |
Workers | get() get(query) get(id) getByLocation(obj) getSchedule(id) getTasks(id) |
create(obj) setSchedule(id, obj) matchMetadata(obj) |
update(id, obj) insertTask(id, obj) |
deleteOne(id) |
GET Requests
To get all the documents within an endpoint, this returns a Promise
containing an array of results:
get();
get()
Examples of onfleetApi.workers.get().then((results) => { /* ... */ });
onfleetApi.workers.get({ queryParams }).then((results) => { /* ... */ });
Optionally you can send a JSON object of query params for some certain endpoints.
Refer back to API documentation for endpoints that support query parameters.
onfleetApi.workers.get({ phones: "<phone_number>" }).then((results) => { /* ... */ });
onfleetApi.tasks.get({ from: "<from_time>", to: "<to_time>" }).then((results) => { /* ... */ });
Both
{ 'analytics': 'true' }
and{ analytics: true }
work as query params since they represent a valid JSON object
To get one of the documents within an endpoint, if the optional paramName is not provided, the library will search by ID. If paramName is provided, it will search by paramName:
get(<parameter>, <paramName> (optional), <queryParam> (optional));
paramName can be any of:
id
name
phone
shortId
get(param)
Examples of onfleetApi.workers.get("<24_digit_ID>").then((result) => { /* ... */ });
onfleetApi.workers.get("<24_digit_ID>", { analytics: true }).then((result) => { /* ... */ });
onfleetApi.tasks.get("<shortId>", "shortId").then((result) => { /* ... */ });
onfleetApi.recipients.get("<phone_number>", "phone").then((result) => { /* ... */ });
onfleetApi.recipients.get("<recipient_name>", "name").then((result) => { /* ... */ });
onfleetApi.recipients
.get("<recipient_name>", "name", { skipPhoneNumberValidation: true })
.then((result) => { /* ... */ });
onfleetApi.containers.get("<24_digit_ID>", "workers").then((result) => { /* ... */ });
onfleetApi.containers.get("<24_digit_ID>", "teams").then((result) => {{ /* ... */ });
onfleetApi.containers.get("<24_digit_ID>", "organizations").then((result) => { /* ... */ });
To obtain information for a specific batch
getBatch(id)
Example of onfleetAPI.tasks.getBatch("<jobId>","jobId").then((result) => { /* ... */ });
To get a driver by location, use the getByLocation
function:
getByLocation({ queryParams });
getByLocation
Examples of const locationParams = {
longitude: -122.404,
latitude: 37.789,
radius: 10000,
};
onfleetApi.workers.getByLocation(locationParams).then((results) => { /* ... */ });
POST Requests
To create a document within an endpoint:
create({ data });
create()
Examples of const data = {
name: "John Driver",
phone: "+16173428853",
teams: ["<team_ID>", "<team_ID> (optional)", ...],
vehicle: {
type: "CAR",
description: "Tesla Model 3",
licensePlate: "FKNS9A",
color: "purple",
},
};
onfleetApi.workers.create(data);
Extended POST requests include clone
, forceComplete
, batchCreate
,batchCreateAsync
, autoAssign
on the Tasks endpoint; setSchedule
on the Workers endpoint; autoDispatch
on the Teams endpoint; and matchMetadata
on all supported entities. For instance:
onfleetApi.tasks.clone('<24_digit_ID>');
onfleetApi.tasks.forceComplete('<24_digit_ID>', { data });
onfleetApi.tasks.batchCreate({ data });
onfleetApi.tasks.batchCreateAsync({ data });
onfleetApi.tasks.autoAssign({ data });
onfleetApi.workers.setSchedule('<24_digit_ID>', { data });
onfleetApi.teams.autoDispatch('<24_digit_ID>', { data });
onfleetApi.<entity_name_pluralized>.matchMetadata({ data });
For more details, check our documentation on clone
, forceComplete
, batchCreate
, autoAssign
, setSchedule
, matchMetadata
, and autoDispatch
.
PUT Requests
To update a document within an endpoint:
update("<24_digit_ID>", { data });
update()
Examples of const newData = {
name: "Jack Driver",
};
onfleetApi.workers.update("<24_digit_ID>", newData);
insertTask()
Examples of onfleetApi.workers.insertTask("<24_digit_ID>", { data }).then((result) => { /* ... */ });
DELETE Requests
To delete a document within an endpoint:
deleteOne("<24_digit_ID>");
deleteOne()
Examples of onfleetApi.workers.deleteOne("<24_digit_ID>");
Examples of utilizing your CRUD operations
-
Get all the recipients:
onfleetApi.tasks .get({ from: "1557936000000", to: "1558022400000" }) .then((tasks) => { for (let task of tasks) { if (task.recipients[0] !== undefined) { // Do something with the recipients } } }) .catch((err) => { /* ... */ });
-
async
/await
can also be used like this:async function findAllWorkers() { try { let response = await onfleetApi.workers.get(); // Do something with the response } catch (err) { /* ... */ } } findAllWorkers();
Things NOT to do
- Inefficient pattern, use metadata instead:
// DONT onfleetApi.workers .get() .then((workers) => { for (let worker of workers) { for (let metadataEntry of worker.metadata) { if (metadataEntry.name === "hasFreezer" && metadataEntry.value) { // Do something } } } }) .catch((err) => { /* ... */ }); // DO onfleetApi.workers .matchMetadata([{"name": "hasFreezer", "type": "boolean", "value": true}]) .then((workers) => { for (let worker of workers) { // Do something } }) .catch((err) => { /* ... */ });
Go to top.