JavaScript SDK
Official JavaScript SDK to connect to the MyParcel API via Node.js or browser.
Installation
Install @myparcel-dev/sdk with your package manager:
npm install @myparcel-dev/sdkUsage 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, FetchClient, PostShipments} from '@myparcel-dev/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: 1,
},
recipient: {
cc: 'NL',
city: 'Hoofddorp',
person: 'Ms. Parcel',
street: 'Antareslaan 31',
},
},
],
});
console.log(result); // [ { id: 123456, reference_identifier: '' } ] (The shipment that was just created)
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 {
request = async (endpoint, options) => {
try {
const response = await axios.request({
method: endpoint.method,
url: this.createUrl(endpoint, options),
headers: options.headers,
data: options.body,
});
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...)
Using constants
Install @myparcel-dev/constants to be able to use lots of pre-defined constants needed throughout our entire ecosystem, like carrier and package type IDs, country codes and names of delivery options.
npm install @myparcel-dev/constantsCarriers
import {CarrierId, CarrierName} from '@myparcel-dev/constants';
CarrierName.PostNl; // "postnl"
CarrierId.Dhl; // 6
Package types
import {PackageTypeId, PackageTypeName} from '@myparcel-dev/constants';
PackageTypeName.DigitalStamp; // "digital_stamp"
PackageTypeId.Package; // 1
// etc
Delivery types
import {DeliveryTypeId, DeliveryTypeName} from '@myparcel-dev/constants';
DeliveryTypeName.Standard; // "standard"
DeliveryTypeId.Pickup; // 4
// etc
Countries
Contains constants for all countries, by name
import {
NETHERLANDS,
GERMANY,
EU_COUNTRIES,
} from '@myparcel-dev/constants/countries';
NETHERLANDS; // "NL"
GERMANY; // "DE"
EU_COUNTRIES; // ["AT", "BE", ...]
States
import {
GEORGIA,
STATES_US,
STATES_CANADA,
} from '@myparcel-dev/constants/states';
GEORGIA; // "GA"
STATES_US; // ["AL", "AK", ...]
STATES_CANADA; // ["AB", "BC", ...]
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.
- Account messages
- Accounts
- API keys
- Carrier options
- Locations
- Shipments
- Shops
- Subscription capabilities
- Subscriptions
- System country codes
- System messages
- Track and trace
- Webhook subscriptions
The source of this list is src/endpoints in the js-sdk repository.
Contributing
Requirements
The source of these versions is volta and packageManager in package.json.
For the workflow, see CONTRIBUTING.md.