Egyedi csomagátvételi pontok API-n keresztül

A Globe segítségével egyedi csomagátvételi pontokat integrálhat az alkalmazásba. Ez különösen hasznos, ha saját üzletekbe szállít, vagy saját csomagátvételi pont hálózatot üzemeltet.

Az egyedi csomagátvételi pontok aktiválásához be kell állítania egy API-t, amely strukturált formátumban adja vissza a csomagátvételi pontok adatait. Ez az útmutató elmagyarázza, hogyan hozhat létre és konfigurálhat API-t a Globe zökkenőmentes együttműködéséhez.

Hogyan működik

Amikor egy ügyfél egy adott helyszín közelében keres csomagátvételi pontokat, a Globe POST kérést küld az Ön API végpontjára. Az API-nak fel kell dolgoznia a kérést, és a szükséges formátumban kell visszaadnia a csomagátvételi pontok listáját.

A kérés struktúrája

A Globe POST kérést küld a következő adatokkal:

Fejlécek:
- Content-Type: application/json
- X-Origin-Service: Globe Pickup Points (ezzel ellenőrizheti, hogy a kérések a Globe-tól érkeznek)
- további fejlécek a Globe beállításaiból
Törzs: JSON objektum a következő mezőkkel:

{
  "latitude": 50.08804,
  "longitude": 14.42076,
  "countryCode": "CZ",
  "shop": "store.myshopify.com"
}

latitude (float): Az ügyfél helyszínének szélességi foka.
longitude (float): Az ügyfél helyszínének hosszúsági foka.
countryCode (string): Az ügyfél helyszínének ISO 3166-1 alpha-2 országkódja (pl. CZ Csehország esetén).
shop (string): A kéréssel kapcsolatos áruház myshopify.com domainje.

A válasz struktúrája

Az API-nak JSON választ kell visszaadnia az alábbi struktúrával, legfeljebb 50 elemmel, a kért helyszíntől való távolság szerint rendezve. Ha az API több mint 50 elemet ad vissza, a Globe csak az első 50-et dolgozza fel.

{
  "data": [
    {
      "id": "cz-123456",
      "longitude": 14.42076,
      "latitude": 50.08804,
      "name": "Praha Pickup Point",
      "place": "Retail Store",
      "street": "Na Příkopě 12",
      "city": "Prague",
      "zip": "110 00",
      "country": "CZ",
      "pin": "https://example.com/pin-image.png",
      "openingHours": {
        "monday": "10:00 - 11:00, 12:00 - 15:00",
        "tuesday": "09:00 - 17:00"
      }
    }
  ]
}

Mezők

id (string): A csomagátvételi pont egyedi azonosítója.
longitude (float): A csomagátvételi pont helyszínének hosszúsági foka.
latitude (float): A csomagátvételi pont helyszínének szélességi foka.
name (string): A csomagátvételi pont neve.
place (string, opcionális): Általános helyszín vagy kerület.
street (string): Utca és házszám.
city (string): A város neve.
zip (string): Irányítószám.
country (string): ISO 3166-1 alpha-2 országkód (pl. CZ Csehország esetén).
pin (string, opcionális): Egy 50x75 pixeles kép URL-je, amely a csomagátvételi pontot jelölő tűt jelenít meg a térképen.
openingHours (object, opcionális): Nyitvatartási idő a hét minden napjára. A nem szereplő napokat zártnak tekintik.

Példa:

  {
    "monday": "10:00 - 11:00, 12:00 - 15:00",
    "tuesday": "09:00 - 17:00"
  }

Hibakezelés

Ha a kérés feldolgozása során hiba lép fel, az API-nak a megfelelő HTTP állapotkódot és egy hibaüzenetet tartalmazó JSON objektumot kell visszaadnia. Például:

{
  "error": "Invalid request parameters"
}

Gyakori hibák

400 Bad Request: Hiányzó vagy érvénytelen paraméterek.
500 Internal Server Error: Váratlan szerverproblémák.

API megvalósítási példa

Az alábbiakban egy példa látható a szükséges API Node.js-ben való megvalósítására:

const express = require("express");
const app = express();
app.use(express.json());

app.post("/pickup-points", (req, res) => {
  const { latitude, longitude, countryCode, shop } = req.body;

  // Validate request body
  if (!latitude || !longitude || !countryCode || !shop) {
    return res.status(400).json({ error: "Missing required fields" });
  }

  // Example pickup points
  const pickupPoints = [
    {
      id: "cz-123456",
      longitude: 14.42076,
      latitude: 50.08804,
      name: "Praha Pickup Point",
      place: "Retail Store",
      street: "Na Příkopě 12",
      city: "Prague",
      zip: "110 00",
      country: "CZ",
      pin: "https://example.com/pin-image.png",
      openingHours: {
        monday: "10:00 - 11:00, 12:00 - 15:00",
        tuesday: "09:00 - 17:00"
      }
    }
  ];

  res.json({ data: pickupPoints });
});

app.listen(3000, () => {
  console.log("Custom Pickup Points API is running on port 3000");
});

Az API tesztelése

Az API megvalósítása után olyan eszközökkel tesztelheti, mint a Postman vagy a curl:

Kérés példa

curl -X POST https://your-api.com/pickup-points \
-H "Content-Type: application/json" \
-H "X-Origin-Service: Globe Pickup Points" \
-d '{
  "latitude": 50.08804,
  "longitude": 14.42076,
  "countryCode": "CZ",
  "shop": "store.myshopify.com"
}'

Válasz példa

{
  "data": [
    {
      "id": "cz-123456",
      "longitude": 14.42076,
      "latitude": 50.08804,
      "name": "Praha Pickup Point",
      "place": "Retail Store",
      "street": "Na Příkopě 12",
      "city": "Prague",
      "zip": "110 00",
      "country": "CZ",
      "pin": "https://example.com/pin-image.png",
      "openingHours": {
        "monday": "10:00 - 11:00, 12:00 - 15:00",
        "tuesday": "09:00 - 17:00"
      }
    }
  ]
}

Következő lépések

Az API telepítése: Helyezze el az API-t egy biztonságos HTTPS-szerveren.
Egyéni végpontok hozzáadása a Globe-hoz: Adjon hozzá új futárszolgálatot egyéni API végponttal.
Az integráció tesztelése: Ellenőrizze, hogy a csomagátvételi pontok helyesen jelennek-e meg a Globe alkalmazásban.

Ha kérdése van, vagy segítségre van szüksége, forduljon a támogatási csapatunkhoz.