PostNL Service

Description

• A service layer responsible for interacting with PostNL’s API to fetch nearby collection points.
• Designed to work within a frontend or middleware layer that uses the useAjaxServer utility for making HTTP requests to internal Nitro endpoints. (/api/postnl)

Purpose

• Primarily used to help users find the nearest PostNL service point to ship a delivery order (e.g., for package drop-off or pickup).

Utilities

• Signature : static async fetchPostNLCollectionPoints(Latitude?: number, Longitude?: number, CountryCode?: string): Promise<any>
• Purpose :
  • Fetches PostNL collection points based on the user's geographic location.

Parameters

• Latitude (number, optional)
  • Geographic latitude coordinate
  • Defaults to 52.161744 (Amsterdam, Netherlands)
• Longitude (number, optional)
  • Geographic longitude coordinate
  • Defaults to 4.528659 (Amsterdam, Netherlands)
• CountryCode (string, optional)
  • ISO 3166-1 alpha-2 country code
  • Defaults to 'NL' (Netherlands)

// ~/services/postnl.service.ts
async function fetchPostNLCollectionPoints(
  Latitude = 52.161744,
  Longitude = 4.528659,
  CountryCode = "NL"
) {
  const res = await useAjaxServer("/api/postnl", {
    query: {
      Latitude,
      Longitude,
      CountryCode,
    },
  });
  if (res.Error) {
    throw new Error("No PostNL collection point found");
  }
  return res;
}

Nitro API

• Postnl private API Key can not be exposed to the client hence the request is proxied through an internal Nitro endpoint.
• GET /api/postnl

// ~/server/api/postnl.get.ts
export default defineEventHandler(async (event) => {
  const config = useRuntimeConfig();

  const { Latitude, Longitude, CountryCode } = getQuery(event);

  const postNLUrl = config.postnlUrl; // API Base URL

  const headers = {
    ContentType: "application/json",
    apikey: config.postnlApiKey, // PostNL private API Key
  };

  const res = await $fetch(postNLUrl, {
    query: {
      Latitude,
      Longitude,
      CountryCode,
    },
    headers,
  });
  return res;
});

Returns

• A Promise that resolves with the response object from the /api/postnl endpoint.
• The structure of the response depends on the backend API, but typically includes a list of nearby collection points.

Error Handling

• If the response contains an Error field, an exception is thrown with the message: "No Post-NL collection point found".
• $customClientErrorHandler makes sure a detailed report is sent to monitoring tools like datadog with proper metadata about 404 (not found).
• This helps higher-level application logic to handle failed lookups gracefully (e.g., showing a user-friendly message or fallback UI).

Dependencies

• Utilizes useAjaxServer, a helper function for making server-side HTTP requests, likely part of a custom AJAX utility or framework abstraction.
• Example usage :

// ~/stores/postnl.store.ts > actions > initPostNLCollectionPoints()
try {
  const points = await PostNLService.fetchPostNLCollectionPoints(
    latitude || 52.3702,
    longitude || 4.8952,
    countryCode || "NL"
  );
  console.log(points); // Process or display available PostNL locations
} catch (error) {
  console.error(error.message); // Handle error (e.g., no locations found)
}

Default Behaviours

• If no parameters are provided, it defaults to a predefined location in the Netherlands. This is useful for development, testing, or fallback scenarios.

References

• PostNL Nearest Points API Documentation