Własne punkty odbioru przez API

Możesz użyć Globe, aby zintegrować własne punkty odbioru z aplikacją. Jest to szczególnie przydatne, jeśli dostarczasz do własnych sklepów lub obsługujesz niestandardową sieć punktów odbioru.

Aby samodzielnie włączyć niestandardowe punkty odbioru, musisz skonfigurować API zwracające dane punktów odbioru w ustrukturyzowanym formacie. Ten przewodnik wyjaśnia, jak zbudować i skonfigurować API do bezproblemowej współpracy z Globe.

Jak to działa

Gdy klient wyszukuje punkty odbioru w pobliżu określonej lokalizacji, Globe wyśle żądanie POST do Twojego punktu końcowego API. Twoje API powinno przetworzyć żądanie i zwrócić listę punktów odbioru w wymaganym formacie.

Struktura żądania

Globe wyśle żądanie POST z następującymi szczegółami:

Nagłówki:
- Content-Type: application/json
- X-Origin-Service: Globe Pickup Points (użyj tego, aby zweryfikować, że żądania pochodzą z Globe)
- wszelkie inne nagłówki z Twoich ustawień w Globe
Treść: Obiekt JSON z następującymi polami:

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

latitude (float): Szerokość geograficzna lokalizacji klienta.
longitude (float): Długość geograficzna lokalizacji klienta.
countryCode (string): Kod kraju ISO 3166-1 alfa-2 lokalizacji klienta (np. CZ dla Czech).
shop (string): Domena myshopify.com sklepu powiązanego z żądaniem.

Struktura odpowiedzi

Twoje API powinno zwrócić odpowiedź JSON o następującej strukturze, zawierającą maksymalnie 50 elementów posortowanych według odległości od żądanej lokalizacji. Jeśli Twoje API zwróci więcej niż 50 elementów, tylko pierwsze 50 zostanie przetworzone przez Globe.

{
  "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"
      }
    }
  ]
}

Pola

id (string): Unikalny identyfikator punktu odbioru.
longitude (float): Długość geograficzna lokalizacji punktu odbioru.
latitude (float): Szerokość geograficzna lokalizacji punktu odbioru.
name (string): Nazwa punktu odbioru.
place (string, opcjonalne): Ogólna lokalizacja lub dzielnica.
street (string): Adres ulicy.
city (string): Nazwa miasta.
zip (string): Kod pocztowy.
country (string): Kod kraju ISO 3166-1 alfa-2 (np. CZ dla Czech).
pin (string, opcjonalne): Adres URL obrazu 50×75 pikseli reprezentującego znacznik punktu odbioru na mapie.
openingHours (obiekt, opcjonalne): Godziny otwarcia dla każdego dnia tygodnia. Dni nieuwzględnione w obiekcie są traktowane jako zamknięte.

Przykład:

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

Obsługa błędów

Jeśli podczas przetwarzania żądania wystąpi błąd, Twoje API powinno zwrócić odpowiedni kod statusu HTTP i obiekt JSON z komunikatem błędu. Na przykład:

{
  "error": "Invalid request parameters"
}

Typowe błędy

400 Bad Request: Brakujące lub nieprawidłowe parametry.
500 Internal Server Error: Nieoczekiwane problemy serwera.

Przykładowa implementacja API

Poniżej znajduje się przykład implementacji wymaganego API w Node.js:

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");
});

Testowanie API

Po zaimplementowaniu API możesz je przetestować za pomocą narzędzi takich jak Postman lub curl:

Przykładowe żądanie

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"
}'

Przykładowa odpowiedź

{
  "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"
      }
    }
  ]
}

Następne kroki

Wdróż API: Hostuj swoje API na bezpiecznym serwerze z obsługą HTTPS.
Dodaj niestandardowe punkty końcowe w Globe: Dodaj nowego przewoźnika z niestandardowym punktem końcowym API.
Przetestuj integrację: Sprawdź, czy punkty odbioru są poprawnie wyświetlane w aplikacji Globe.

Jeśli masz pytania lub potrzebujesz pomocy, skontaktuj się z naszym zespołem wsparcia.