Skip to main content

Quick Start Guide

Get up and running with the Delivery Locker API in 5 minutes.

Step 1: Get Your API Key​

Contact KioskForce to obtain your API credentials:

You'll receive an X-API-Key for authentication.

API Environments​

Use the appropriate base URL for your environment:

  • Production: https://api.delivery.kioskforce.com
  • Staging: https://api-staging.delivery.kioskforce.com

Step 2: Test Your Connection​

First, verify your API key works with the echo endpoint:

Option A: Using curl​

curl -X POST "https://api.delivery.kioskforce.com/api/delivery/external/v1/echo" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "hello"}'

First, install delivery-cli and configure it:

# Create configuration file
cat > env.config.json << EOF
{
  "api_key": "YOUR_API_KEY",
  "api_url": "https://api.delivery.kioskforce.com"
}
EOF

# Test connection
delivery-cli echo --message "hello"

Expected Response:

{
  "message": "hello"
}

✅ If you see this response, your API key is working correctly!

Step 3: Find Available Lockers​

Search for lockers near your delivery location:

Option A: Using curl​

curl -X POST "https://api.delivery.kioskforce.com/api/delivery/external/v1/machines/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": -6.125556,
    "longitude": 106.655830,
    "radius": 2000,
    "only_available_lockers": true,
    "packaging": {
      "width": 300,
      "height": 200,
      "depth": 400
    }
  }'
delivery-cli search-machines \
  --latitude -6.125556 \
  --longitude 106.655830 \
  --radius 2000 \
  --only-available-lockers \
  --packaging-width 300 \
  --packaging-height 200 \
  --packaging-depth 400

This searches for lockers within 2km that can fit a 30cm x 20cm x 40cm package.

Response Example:

{
  "machines": [
    {
      "machine": {
        "machine_id": "kf_tangerang_001",
        "name": "Awesome Business Park - South Wing",
        "location": "Benda, Tangerang City, Banten", 
        "latitude": -6.125556,
        "longitude": 106.655830,
        "online": true
      },
      "distance_in_metres": 150
    }
  ]
}

Step 4: Reserve a Locker​

Reserve a compartment for your delivery:

Option A: Using curl​

curl -X POST "https://api.delivery.kioskforce.com/api/delivery/external/v1/reservations" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "machine_id": "kf_tangerang_001",
    "platform_order_id": "order_12345",
    "packaging": {
      "width": 300,
      "height": 200, 
      "depth": 400,
      "weight": 1500
    },
    "notes": "Customer: John Doe, Phone: +62812345678"
  }'
delivery-cli create-reservation \
  --machine-id "kf_tangerang_001" \
  --platform-order-id "order_12345" \
  --packaging '{"width":300,"height":200,"depth":400,"weight":1500}' \
  --notes "Customer: John Doe, Phone: +62812345678"

Response Example:

{
  "reservation_id": "res_abc123",
  "machine_id": "kf_tangerang_001",
  "drop_off_code": "1234",
  "drop_off_qrcode_url": "https://api.delivery.kioskforce.com/qrcode/ABC123",
  "pickup_code": "5678", 
  "pickup_code_qrcode_url": "https://api.delivery.kioskforce.com/qrcode/DEF456"
}

🎉 Success! You now have:

  • Drop-off code (1234): Give this to your driver/rider
  • Pickup code (5678): Send this to your customer
  • QR codes: Alternative to manual codes

Step 5: Complete the Delivery​

For Driver/Rider Drop-off​

Your driver can either:

  1. Use the drop-off code (1234) on the locker touchscreen
  2. Scan the drop-off QR code with the locker's scanner
  3. API-triggered door opening (if your app supports it):

Using curl:​

curl -X POST "https://api.delivery.kioskforce.com/api/delivery/external/v1/reservations/res_abc123/dropoffs" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Using delivery-cli:​

delivery-cli dropoff --reservation-id res_abc123

For Customer Pickup​

Your customer can either:

  1. Use the pickup code (5678) on the locker touchscreen
  2. Scan the pickup QR code with the locker's scanner
  3. API-triggered door opening (if your app supports it):

Using curl:​

curl -X POST "https://api.delivery.kioskforce.com/api/delivery/external/v1/reservations/res_abc123/pickups" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Using delivery-cli:​

delivery-cli pickup --reservation-id res_abc123

Common Error Handling​

403 Unauthorized​

{
  "code": 7,
  "message": "Permission denied"
}

Solution: Check your X-API-Key header.

404 Not Found​

{
  "code": 5, 
  "message": "Resource not found"
}

Solution: Verify machine_id or reservation_id exists.

No Available Lockers​

{
  "machines": []
}

Solutions:

  • Increase search radius
  • Remove package size constraints
  • Set only_available_lockers: false

Next Steps​

Now that you've completed your first delivery workflow, explore:

Integration Checklist​

  • API key obtained and tested
  • Location search implemented
  • Reservation flow working
  • Drop-off process tested
  • Pickup process tested
  • Error handling implemented
  • Webhook endpoints configured (optional)
  • Production testing completed

Need help? Contact our API support team at api-support@kioskforce.com