Vlastní výdejní místa přes API

Globe můžete použít k integraci vlastních výdejních míst do aplikace. To je zvláště užitečné, pokud doručujete do vlastních prodejen nebo provozujete vlastní síť výdejních míst.

Pro vlastní zapnutí vlastních výdejních míst musíte nastavit API, které vrací data výdejních míst ve strukturovaném formátu. Tento průvodce vysvětluje, jak vytvořit a nakonfigurovat vaše API pro bezproblémovou spolupráci s Globe.

Jak to funguje

Když zákazník vyhledává výdejní místa v blízkosti konkrétní lokace, Globe odešle POST požadavek na váš API endpoint. Vaše API by mělo požadavek zpracovat a vrátit seznam výdejních míst v požadovaném formátu.

Struktura požadavku

Globe odešle POST požadavek s následujícími údaji:

Hlavičky:
- Content-Type: application/json
- X-Origin-Service: Globe Pickup Points (použijte k ověření, že požadavky pocházejí z Globe)
- další hlavičky z vašeho nastavení v Globe
Tělo: JSON objekt s těmito poli:

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

latitude (float): Zeměpisná šířka lokace zákazníka.
longitude (float): Zeměpisná délka lokace zákazníka.
countryCode (string): Kód země ISO 3166-1 alpha-2 lokace zákazníka (např. CZ pro Českou republiku).
shop (string): Doména myshopify.com obchodu spojeného s požadavkem.

Struktura odpovědi

Vaše API by mělo vrátit JSON odpověď s následující strukturou, maximálně 50 položek seřazených podle vzdálenosti od požadované lokace. Pokud vaše API vrátí více než 50 položek, Globe zpracuje pouze prvních 50.

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

Pole

id (string): Jedinečný identifikátor výdejního místa.
longitude (float): Zeměpisná délka lokace výdejního místa.
latitude (float): Zeměpisná šířka lokace výdejního místa.
name (string): Název výdejního místa.
place (string, volitelné): Obecná lokace nebo čtvrť.
street (string): Ulice a číslo.
city (string): Název města.
zip (string): PSČ.
country (string): Kód země ISO 3166-1 alpha-2 (např. CZ pro Českou republiku).
pin (string, volitelné): URL obrázku 50x75 pixelů reprezentujícího pin výdejního místa na mapě.
openingHours (object, volitelné): Otevírací doba pro každý den v týdnu. Dny, které nejsou zahrnuty, se považují za zavřené.

Příklad:

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

Zpracování chyb

Pokud při zpracování požadavku dojde k chybě, vaše API by mělo vrátit příslušný HTTP stavový kód a JSON objekt s chybovou zprávou. Například:

{
  "error": "Invalid request parameters"
}

Běžné chyby

400 Bad Request: Chybějící nebo neplatné parametry.
500 Internal Server Error: Neočekávané problémy serveru.

Příklad implementace API

Níže je příklad implementace požadovaného API v 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");
});

Testování vašeho API

Po implementaci API jej můžete testovat pomocí nástrojů jako Postman nebo curl:

Příklad požadavku

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

Příklad odpovědi

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

Další kroky

Nasazení API: Hostujte vaše API na zabezpečeném serveru s HTTPS.
Přidání vlastních endpointů do Globe: Přidejte nového dopravce s vlastním API endpointem.
Testování integrace: Ověřte, že výdejní místa se správně zobrazují v aplikaci Globe.

Máte-li dotazy nebo potřebujete pomoc, kontaktujte náš tým podpory.