JavaScript SDK
Official JavaScript SDK to connect to the MyParcel API via Node.js or browser.
Installation
Install [@myparcel/sdk] with your package manager:
Usage examples
Basic usage
The client is Promise-based, so you can use async/await
, or Promise.then
.
First, instantiate an SDK and pass the endpoints you want to use.
import { createPrivateSdk, PostShipments } from '@myparcel/sdk';
const clientConfig = {
headers: {
Authorization: 'bearer ' + MY_BASE_64_ENCODED_API_KEY
}
};
const sdk = createPrivateSdk(new FetchClient(clientConfig), [
new PostShipments(),
]);
Then call the endpoint. There are constants available in our SDK for data like carriers, package types, delivery types and more. See constants
const result = await sdk.postShipments({
body: [
{
carrier: 1,
options: {
package_type: 'package',
},
recipient: {
cc: 'NL',
city: 'Hoofddorp',
person: 'Ms. Parcel',
street: 'Antareslaan 31',
},
},
]
});
console.log(result); // [ 123456 ] (The ID of the shipment that was just created)
Using constants
Our SDK exposes some constants to make working with our API easier.
- Carriers
import { CARRIERS } from '@myparcelnl/sdk'; CARRIERS.POSTNL_NAME // "postnl"
- Package types: Contains all package types' names and IDs.
import { PACKAGE_TYPES } from '@myparcelnl/sdk'; PACKAGE_TYPES.DIGITAL_STAMP_NAME // "digital_stamp" PACKAGE_TYPES.PACKAGE_ID // 1 PACKAGE_TYPES.LETTER // { ID: 3, NAME: "letter" } // etc
- Delivery types
import { DELIVERY_TYPES } from '@myparcelnl/sdk'; DELIVERY_TYPES.STANDARD_NAME // "standard" DELIVERY_TYPES.PICKUP_ID // 4 DELIVERY_TYPES.MORNING // { ID: 1, NAME: "morning" } // etc
- Countries: Contains constants for all countries, by name.
import { COUNTRIES } from '@myparcelnl/sdk'; COUNTRIES.NETHERLANDS // "NL" COUNTRIES.GERMANY // "DE" // etc
Creating a new endpoint
To create a new endpoint, you can extend either AbstractPrivateEndpoint
or AbstractPublicEndpoint
and fill in the derived class as needed.
Feel free to add open a pull request to add it to our repository! See contributing.
Creating a new client
In this example we're creating an Axios client.
class AxiosClient extends AbstractClient {
async request(endpoint, options) {
try {
const response = await axios.request({
method: endpoint.method,
url: this.createUrl(endpoint, options),
headers: {
...this.getHeaders(),
...endpoint.getHeaders()
}
});
return response.data;
} catch (e) {
return e.response.data;
}
}
}
Now use the new client with an SDK instance:
const sdk = createPublicSdk(new AxiosClient(), [new GetCarriers()]);
const carriers = await sdk.getCarriers();
console.log(carriers); // [ { "id": 1, "name": "postnl", (etc...)
Endpoints
Public
Public endpoints do not require authorization and are safe to use in a browser.
- Delivery options
- Pickup locations
- Carriers
Private
Private endpoints require an Authorization header. This should be a base64 encoded MyParcel API key. You can create one in the shop settings in our [backoffice]. See [Authorization] in the API documentation for more information.
- Shipments
Contributing
Requirements
Basics
- Fork this repository and clone it to your machine
- Install dependencies using Yarn:
yarn
Make your changes
- Try to conform to our code style. Make sure to enable ESLint in your editor.
- You should make only one change in each branch.
Add or update tests
Run tests with the following command:
yarn run test:coverage
- Coverage % needs to be equal to or greater than that of the previous commit.
- If you added a new file, the corresponding test(s) should go inside
<filename>.spec.ts
in the same directory.
Commit
Make as many commits as you'd like. We use Conventional Commits and semantic-release to simplify the process of releasing updates by automating release notes and changelogs based on the rules of @commitlint/config-conventional.
Your branch will be squashed into one single valid commit before merging.
Create a pull request
- Keep your pull requests focused on single subjects
- Please explain what you changed and why
- We will review your code and thoroughly test it before squashing and merging your pull request