Puntos de recogida personalizados mediante API

Puede usar Globe para integrar sus propios puntos de recogida en la app. Esto es especialmente útil si realiza entregas a sus propias tiendas o gestiona una red de puntos de recogida personalizada.

Para habilitar puntos de recogida personalizados por su cuenta, necesita configurar una API que devuelva los datos de los puntos de recogida en un formato estructurado. Esta guía explica cómo crear y configurar su API para que funcione perfectamente con Globe.

Cómo funciona

Cuando un cliente busca puntos de recogida cerca de una ubicación específica, Globe enviará una solicitud POST a su endpoint de API. Su API debe procesar la solicitud y devolver una lista de puntos de recogida en el formato requerido.

Estructura de la solicitud

Globe enviará una solicitud POST con los siguientes detalles:

Encabezados:
- Content-Type: application/json
- X-Origin-Service: Globe Pickup Points (úsalo para verificar que las solicitudes provienen de Globe)
- cualquier otro encabezado de su configuración en Globe
Cuerpo: Un objeto JSON con estos campos:

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

latitude (float): Latitud de la ubicación del cliente.
longitude (float): Longitud de la ubicación del cliente.
countryCode (string): Código de país ISO 3166-1 alfa-2 de la ubicación del cliente (p. ej., CZ para la República Checa).
shop (string): El dominio myshopify.com de la tienda asociada con la solicitud.

Estructura de la respuesta

Su API debe devolver una respuesta JSON con la siguiente estructura, que contenga un máximo de 50 elementos ordenados por distancia desde la ubicación solicitada. Si su API devuelve más de 50 elementos, Globe solo procesará los primeros 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"
      }
    }
  ]
}

Campos

id (string): Identificador único del punto de recogida.
longitude (float): Longitud de la ubicación del punto de recogida.
latitude (float): Latitud de la ubicación del punto de recogida.
name (string): El nombre del punto de recogida.
place (string, opcional): Ubicación general o barrio.
street (string): Dirección de la calle.
city (string): Nombre de la ciudad.
zip (string): Código postal.
country (string): Código de país ISO 3166-1 alfa-2 (p. ej., CZ para la República Checa).
pin (string, opcional): URL de una imagen de 50x75 píxeles que representa el pin del punto de recogida en el mapa.
openingHours (object, opcional): Horario de apertura para cada día de la semana. Los días no incluidos se consideran cerrados.

Ejemplo:

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

Manejo de errores

Si ocurre un error al procesar la solicitud, su API debe devolver un código de estado HTTP apropiado y un objeto JSON con un mensaje de error. Por ejemplo:

{
  "error": "Invalid request parameters"
}

Errores comunes

400 Bad Request: Parámetros faltantes o no válidos.
500 Internal Server Error: Problemas inesperados del servidor.

Ejemplo de implementación de API

A continuación se muestra un ejemplo de cómo implementar la API requerida en 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");
});

Probar su API

Una vez implementada la API, puede probarla con herramientas como Postman o curl:

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Próximos pasos

Despliegue su API: Aloje su API en un servidor seguro habilitado con HTTPS.
Añada sus endpoints personalizados en Globe: Añada un nuevo transportista con un endpoint de API personalizado.
Pruebe la integración: Verifique que los puntos de recogida se muestren correctamente en la app Globe.

Si tiene preguntas o necesita ayuda, contacte con nuestro equipo de soporte.