Ir al contenido
Maple

    Entregas

    Administrar zonas de entrega

    Cree, actualice y liste las zonas de entrega de un local conectado, y compruebe si una coordenada tiene cobertura de entrega.

    Las zonas de entrega definen adónde entrega un local. Cada zona es un polígono GeoJSON con una tarifa de entrega y restricciones de pedido opcionales (pedido mínimo, distancia máxima, prioridad). Todos los endpoints de zonas de entrega requieren una conexión activa con el local: solo la aplicación que actúa como receptora de pedidos del local puede administrar sus zonas.

    Alcances (scopes)

    • delivery_zones:read — listar zonas, obtener una zona y comprobar la cobertura.
    • delivery_zones:write — crear, actualizar y eliminar zonas.

    Crear una zona

    Los nombres de zona deben ser únicos por local. polygon es un Polygon de GeoJSON con anillos de [longitude, latitude]; el primer anillo debe estar cerrado (el primer y el último punto son iguales).

    Terminal window
    curl -X POST $MAPLE_BASE/locations/{locationId}/delivery_zones \
      -H "Authorization: Bearer $MAPLE_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Downtown",
        "polygon": {
          "type": "Polygon",
          "coordinates": [
            [
              [-74.02, 40.70],
              [-73.99, 40.70],
              [-73.99, 40.73],
              [-74.02, 40.73],
              [-74.02, 40.70]
            ]
          ]
        },
        "delivery_fee_cents": 450,
        "priority": 0
      }'

    delivery_fee_cents tiene un valor predeterminado de 0, is_active de true, priority de 0 y zone_type de polygon. La respuesta es el objeto delivery_zone creado; use su id para los endpoints de la zona.

    Las comprobaciones de cobertura siempre evalúan polygon. zone_type: 'circle' y radius_miles son solo metadatos descriptivos: para una zona circular, envíe un polígono que aproxime el círculo.

    Listar zonas

    Terminal window
    curl $MAPLE_BASE/locations/{locationId}/delivery_zones \
      -H "Authorization: Bearer $MAPLE_KEY"

    Devuelve { "object": "list", "data": [...] } con únicamente las zonas activas.

    Actualizar una zona

    PATCH cambia solo los campos que usted envía:

    Terminal window
    curl -X PATCH $MAPLE_BASE/locations/{locationId}/delivery_zones/{zoneId} \
      -H "Authorization: Bearer $MAPLE_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "delivery_fee_cents": 550 }'

    Eliminar una zona

    Al eliminar, la zona se desactiva (deja de aparecer en los resultados de la lista y en las comprobaciones de cobertura):

    Terminal window
    curl -X DELETE $MAPLE_BASE/locations/{locationId}/delivery_zones/{zoneId} \
      -H "Authorization: Bearer $MAPLE_KEY"

    Comprobar si una coordenada tiene entrega

    Antes de cotizar una entrega, compare las coordenadas del cliente con las zonas del local:

    Terminal window
    curl -X POST $MAPLE_BASE/locations/{locationId}/delivery_zones/check \
      -H "Authorization: Bearer $MAPLE_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "latitude": 40.7128, "longitude": -74.006 }'

    La respuesta es un delivery_zone_check: in_zone indica si el local entrega allí y, cuando es verdadero, zone contiene la zona correspondiente y delivery_fee_cents su tarifa. Cuando es falso, ambos son null.

    get/update/delete de una zona devuelven 404 si la zona pertenece a otro local: un socio solo puede tocar las zonas que pertenecen al local indicado en la ruta.