Response Handling

Callback Response

When a user selects a pickup point, your callback function receives a point object containing all the relevant information about the selected location.

---

Standard Point Response

When a user successfully selects a pickup point from the map, the response object includes:

{
  "id": "0000516834",
  "lat": 46.19105,
  "lon": 18.94225,
  "name": "Andriott Kft - Sirály ABC",
  "zip": "6500",
  "addr": "Sirály utca 4.",
  "city": "Baja",
  "country": "HU",
  "type": "pick-pack-pont",
  "courier": "sameday",
  "hours": {
    "1": "05:30 - 19:00",  // Monday
    "2": "05:30 - 19:00",  // Tuesday
    "3": "05:30 - 19:00",  // Wednesday
    "4": "05:30 - 19:00",  // Thursday
    "5": "05:30 - 19:00",  // Friday
    "6": "05:30 - 13:30",  // Saturday
    "7": "05:30 - 11:00"   // Sunday
  }
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the pickup point
lat	number	Latitude coordinate
lon	number	Longitude coordinate
name	string	Name of the pickup location
zip	string	Postal/ZIP code
addr	string	Street address
city	string	City name
country	string	Country code (e.g., "HU", "RO")
type	string	Pickup point type (e.g., "locker", "shop")
courier	string	Courier service identifier
hours	object	Opening hours by day (1=Monday, 7=Sunday)

---

Fallback Mode Response

When the map cannot load (network issues, API errors) or when testing with _showError: true, the widget displays a text field where users can manually enter their preferred pickup location.

In this case, the callback receives:

{
  "fallbackInfo": "User entered text description of pickup point"
}

Handling Fallback Responses

callback: (point) => {
  if (point.fallbackInfo) {
    // Manual entry mode
    console.log("Manual pickup description:", point.fallbackInfo);
    // Save the description and handle manually
    saveManualPickupInfo(point.fallbackInfo);
  } else {
    // Standard pickup point selected
    console.log("Pickup point:", point.name);
    savePickupPoint(point);
  }
}

---

Server-Side Validation

Since pickup point selection happens on the client side, it's highly recommended to validate the selected point on your server before finalizing an order. Worth to mention that if you have your own pickup point list stored, you can use that to verify, because the ID parameter will be the same as in the courier's official list item ID.

Validation Endpoint

Make a GET request to validate the pickup point:

GET https://points-api.kvikk.hu/map/point

Required Query Parameters:

• courier - Courier identifier (e.g., "gls")
• type - Point type (e.g., "locker")
• id - Point ID (e.g., "0000516834")

Headers:

X-API-KEY: your_api_key_here

Validation Response

The validation endpoint returns the same point object structure with all details, confirming the point exists and is currently active:

{
  "id": "0000516834",
  "lat": 46.19105,
  "lon": 18.94225,
  "name": "Andriott Kft - Sirály ABC",
  "zip": "6500",
  "addr": "Sirály utca 4.",
  "city": "Baja",
  "country": "HU",
  "type": "pick-pack-pont",
  "courier": "sameday",
  "hours": { ... }
}

Best Practice

Always validate pickup points server-side before creating shipments to ensure:

• The point still exists
• The point is active and available
• The data hasn't been tampered with on the client side