HomeDocumentationJavaScript SDK

JavaScript SDK

Latest version of @myparcel-dev/sdk on npm
myparcelnl/js-sdk issues on GitHub
myparcelnl/js-sdk pull requests on GitHub

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/sdk

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, 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/constants

Carriers

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.

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.

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.

Edit this page
Last updated: 
Contributors Edie Lemoine, Rick van Laarhoven, Richard Perdaan