PostNL Connect Kit

🇳🇱 A comprehensive Node.js SDK for the PostNL API, supporting shipping, tracking, pricing, and more.

Features

✅ Barcode Generation - Generate barcodes for shipments
✅ Shipping & Labelling - Create shipping labels
✅ Price Calculation - Calculate shipping costs
✅ Delivery Timeframes - Get delivery time estimates
✅ Location Finder - Find PostNL pickup locations
✅ Track & Trace - Track shipment status
✅ TypeScript Support - Full TypeScript support with type definitions
✅ Sandbox Mode - Test environment for development

Installation

npm install postnl-connect-kit

Quick Start

const PostNL = require('postnl-connect-kit');

// Initialize the client
const postnl = new PostNL({
  apiKey: 'your-api-key',
  customerNumber: 'your-customer-number',
  customerCode: 'your-customer-code',
  sandbox: true // Use false for production
});

// Calculate shipping price
const price = await postnl.checkout.calculatePrice(
  '1012JS',  // Postal code
  '1',       // House number
  'NL'       // Country code
);

console.log('Shipping options:', price.Options);

Usage Examples

1. Price Calculation

// Get cheapest delivery option
const cheapest = await postnl.checkout.getCheapestOption(
  '1012JS',
  '1',
  'NL'
);

console.log(`Cheapest: €${cheapest.price} on ${cheapest.date}`);

// Get all delivery options with prices
const options = await postnl.checkout.calculatePrice(
  '1012JS',
  '1',
  'NL'
);

options.Options.forEach(option => {
  console.log(`Date: ${option.Date}`);
  option.Timeframes.forEach(tf => {
    console.log(`  ${tf.From}-${tf.To}: €${tf.Price?.Amount}`);
  });
});

2. Generate Barcode

// Generate single barcode
const barcode = await postnl.barcode.generate('NL');
console.log('Barcode:', barcode);

// Generate multiple barcodes
const barcodes = await postnl.barcode.generateMultiple(5, 'NL');
console.log('Barcodes:', barcodes);

3. Create Shipment and Label

const shipment = {
  Addresses: [
    {
      AddressType: '01', // Receiver
      City: 'Amsterdam',
      Countrycode: 'NL',
      HouseNr: '1',
      Street: 'Singel',
      Zipcode: '1012JS',
      Name: 'Jan Jansen',
      CompanyName: 'PostNL',
    },
    {
      AddressType: '02', // Sender
      City: 'Rotterdam',
      Countrycode: 'NL',
      HouseNr: '1',
      Street: 'Coolsingel',
      Zipcode: '3011AD',
      Name: 'Piet Pietersen',
    }
  ],
  Barcode: barcode,
  Dimension: {
    Weight: 2000, // grams
  },
  ProductCodeDelivery: '3085', // Standard shipment
  Reference: 'Order-12345',
};

const label = await postnl.shipping.createShipment(shipment);
console.log('Label created:', label.ResponseShipments[0].Labels[0].Content);

4. Track Package

// Track a shipment
const status = await postnl.tracking.track('3SDEVC123456789');

console.log('Status:', status.StatusDescription);
console.log('Phase:', status.PhaseDescription);

// Check if delivered
const delivered = await postnl.tracking.isDelivered('3SDEVC123456789');
console.log('Is delivered?', delivered);

// Get delivery history
const history = await postnl.tracking.getHistory('3SDEVC123456789');
history.forEach(event => {
  console.log(`${event.timestamp}: ${event.description}`);
});

5. Find Locations

// Find pickup locations by postal code
const locations = await postnl.locations.findByPostalCode('1012JS', 'NL');

locations.forEach(loc => {
  console.log(`${loc.Name} - ${loc.Distance}m away`);
  console.log(`  ${loc.Address.Street} ${loc.Address.HouseNumber}`);
});

// Find by city
const cityLocations = await postnl.locations.findByCity('Amsterdam', 'NL');

6. Delivery Timeframes

// Get timeframes for today
const timeframes = await postnl.timeframes.getTimeframesToday(
  '1012JS',
  'NL',
  '1'
);

timeframes.forEach(tf => {
  console.log(`Date: ${tf.Date}`);
  tf.Timeframes.forEach(slot => {
    console.log(`  ${slot.From}-${slot.To}`);
  });
});

// Get timeframes for next 5 days
const nextDays = await postnl.timeframes.getTimeframesNextDays(
  5,
  '1012JS',
  'NL'
);

API Reference

Configuration

interface PostNLConfig {
  apiKey: string;              // Your PostNL API key
  sandbox?: boolean;           // Use sandbox (default: false)
  customerNumber?: string;     // Your customer number
  customerCode?: string;       // Your customer code
  collectionLocation?: string; // Collection location code
}

Services

• postnl.barcode - Barcode generation
• postnl.shipping - Create shipments and labels
• postnl.checkout - Calculate prices and delivery options
• postnl.timeframes - Get delivery timeframes
• postnl.locations - Find pickup locations
• postnl.tracking - Track shipments

Product Codes

const ProductCode = {
  STANDARD: '3085',              // Standard delivery
  MAILBOX: '2928',              // Mailbox package
  EVENING: '3089',              // Evening delivery
  SUNDAY: '3389',               // Sunday delivery
  MORNING: '3385',              // Morning delivery
  SAMEDAY: '3189',              // Same day delivery
  INTERNATIONAL_STANDARD: '4945', // International standard
  INTERNATIONAL_TRACKED: '4952',  // International tracked
};

Error Handling

try {
  const barcode = await postnl.barcode.generate('NL');
} catch (error) {
  console.error('Error:', error.message);
}

TypeScript Support

This library is fully written in TypeScript and includes all type definitions:

import PostNL, { PostNLConfig, ShipmentRequest, ProductCode } from 'postnl-connect-kit';

const config: PostNLConfig = {
  apiKey: 'your-key',
  sandbox: true,
};

const postnl = new PostNL(config);

Environment Variables

POSTNL_API_KEY=your-api-key
POSTNL_CUSTOMER_NUMBER=your-customer-number
POSTNL_CUSTOMER_CODE=your-customer-code
POSTNL_SANDBOX=true

🧪 Testing

This project includes comprehensive tests with 19 unit tests covering all major features.

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run tests in watch mode
npm test -- --watch

Test Results

✅ Test Suites: 4 passed, 4 total
✅ Tests:       19 passed, 19 total
✅ Coverage:    53% statements, 41% branches

Tests include:

• ✅ Barcode Generation
• ✅ Price Calculation (Checkout)
• ✅ Shipment Tracking
• ✅ SDK Initialization

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

For issues and questions:

• GitHub Issues: Create an issue
• PostNL Developer Portal: https://developer.postnl.nl

Changelog

v1.0.0

• ✅ Initial release
• ✅ Barcode generation
• ✅ Shipping & labelling
• ✅ Price calculation
• ✅ Delivery timeframes
• ✅ Location finder
• ✅ Track & trace