QuickPickups Partner API

curl https://backend.quickpickups.es/api/partners/v1/coverage

curl https://backend.quickpickups.es/api/partners/v1/me \
  -H "Authorization: Bearer $QP_KEY"

curl -X POST https://backend.quickpickups.es/api/partners/v1/quotes \
  -H "Authorization: Bearer $QP_KEY" -H "Content-Type: application/json" \
  -d '{
    "pickup":  {"place": "BCN", "terminal": "T1"},
    "dropoff": {"lat": 41.3870, "lng": 2.1701,
                "address": "Plaça de Catalunya 1, 08002 Barcelona"},
    "pickup_at": "2026-11-02T14:30:00+01:00",
    "passengers": 3,
    "luggage": 3,
    "child_seats": [{"type_id": 1, "count": 1}]
  }'

{
  "id": "qt_Jx8d2kq0Lw3mZp1a",
  "object": "quote",
  "status": "ok",
  "expires_at": "2026-10-16T12:30:00+02:00",
  "currency": "EUR",
  "options": [
    {
      "option_id": "qt_Jx8d2kq0Lw3mZp1a.3",
      "vehicle_class": {"id": 3, "code": "comfort", "name": "Comfort",
                        "max_passengers": 4, "max_luggage": 3,
                        "model_guaranteed": false},
      "vehicles": 1,
      "price_per_vehicle": …,
      "price": …,
      "currency": "EUR",
      "pricing_basis": "net_rate"
    }
  ],
  "unavailable": [
    {"vehicle_class": {"id": 9, "name": "Minibus 16"},
     "reason": "too_soon", "min_lead_hours": 48}
  ]
}

curl -X POST https://backend.quickpickups.es/api/partners/v1/bookings \
  -H "Authorization: Bearer $QP_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2f0e-6c3a-4d0e-9a51-0b7f2b8f9e21" \
  -d '{
    "quote_id": "qt_Jx8d2kq0Lw3mZp1a",
    "option_id": "qt_Jx8d2kq0Lw3mZp1a.3",
    "partner_reference": "YOUR-REF-102938",
    "passenger": {"name": "Jane Doe", "phone": "+44 7700 900123"},
    "flight_number": "BA478",
    "notes": "Two large suitcases and a pushchair"
  }'

{
  "id": "QP26K4M7PX",
  "object": "booking",
  "environment": "live",
  "status": "confirmed",
  "partner_reference": "YOUR-REF-102938",
  "pickup_at": "2026-11-02T14:30:00+01:00",
  "pickup": {"place": "BCN", "terminal": "T1", "lat": 41.2889, "lng": 2.0731,
             "address": "Barcelona-El Prat Airport (BCN) - Terminal T1"},
  "vehicles": 1,
  "price": …,
  "currency": "EUR",
  "policies": {"free_waiting_minutes": 60, "meet_and_greet": true,
               "flight_tracking": true},
  "cancellation": {"cancellable": true,
                   "free_until": "2026-11-01T14:30:00+01:00",
                   "fee_pct": 0, "fee": 0},
  "tracking_url": "https://..."
}

curl -X PATCH https://backend.quickpickups.es/api/partners/v1/bookings/QP26K4M7PX \
  -H "Authorization: Bearer $QP_KEY" -H "Content-Type: application/json" \
  -d '{"pickup_at": "2026-11-02T16:00:00+01:00", "flight_number": "BA480"}'

# 409 price_changed  →  resend with "accept_price_change": true

curl -X POST https://backend.quickpickups.es/api/partners/v1/bookings/QP26K4M7PX/cancel \
  -H "Authorization: Bearer $QP_KEY" -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

{"dry_run": true, "fee": 0.0, "fee_pct": 0.0,
 "free_until": "2026-11-01T14:30:00+01:00", "currency": "EUR"}

{
  "id": "QP26K4M7PX",
  "status": "driver_on_the_way",
  "driver": {"first_name": "Marta", "phone": "+34 600 000 000",
             "vehicle": {"make": "Toyota", "model": "Corolla Hybrid",
                         "colour": "White", "plate": "1234 ABC"}},
  "location": {"lat": 41.305, "lng": 2.081,
               "updated_at": "2026-11-02T14:12:03+01:00"},
  "eta_minutes": 6,
  "location_status": "live",
  "passenger_chat_url": "https://..."
}

POST https://your-system.example.com/webhooks/quickpickups
QP-Signature: t=1792141200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
QP-Event-Id: evt_Qm3xB0c8Lr1s9TzKp2aWv
QP-Event-Type: driver.assigned

{
  "id": "evt_Qm3xB0c8Lr1s9TzKp2aWv",
  "type": "driver.assigned",
  "created_at": "2026-11-02T13:05:44+01:00",
  "environment": "live",
  "data": {"booking": { "...": "same object as GET /bookings/{id}" }}
}

import hashlib, hmac, time

def verify(secret: str, raw_body: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

const crypto = require("crypto");

function verify(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

curl -X POST https://backend.quickpickups.es/api/partners/v1/sandbox/bookings/QP26K4M7PX/advance \
  -H "Authorization: Bearer $QP_TEST_KEY" -H "Content-Type: application/json" \
  -d '{"to": "driver_arrived"}'

# → webhooks driver.assigned, driver.on_the_way, driver.arrived

{
  "error": {"code": "quote_expired",
            "message": "The quote has expired. Request a new one."},
  "request_id": "req_3f9a1c2b7d4e5f60"
}