অ্যাম্বুলেন্স প্রতিষ্ঠানের সফটওয়্যারের জন্য বেড কই API

শুরু করতে

1. প্রতিষ্ঠানের অ্যাডমিন বেড কই প্যানেলে ঢুকে প্রতিষ্ঠানের “সফটওয়্যার সংযোগ” পাতা থেকে একটি API কী বানান। কী একবারই দেখানো হয়; গোপন রাখুন। হাসপাতালের বেডের কী এখানে চলে না।
2. প্রতিটি অনুরোধে কী পাঠান X-Api-Key হেডারে। সব ঠিকানা শুরু হয় এখান থেকে: https://api.bedkoi.com/v1
3. কোন গাড়ি খালি তা জানাতে থাকুন: অনুরোধ আসে শুধু খালি বলা গাড়ির জন্য।

curl https://api.bedkoi.com/v1/partner/ambulance/requests \
  -H "X-Api-Key: bk_live_…"

ঠিকানাগুলো

• GET/partner/ambulance/providerআপনার প্রতিষ্ঠান: নাম, অবস্থা, কোন জেলায় সেবা দেয়
• GET/partner/ambulance/requestsএখন আপনাকে দেওয়া অনুরোধ (offers), পুরনোটা আগে; আর চলমান ট্রিপ (trips)
• POST/partner/ambulance/requests/{tripId}/acceptঅনুরোধ নিন: etaMinutes (কত মিনিটে পৌঁছাবেন), জানা থাকলে vehicleId আর driverId
• POST/partner/ambulance/requests/{tripId}/declineনেবেন না
• GET/partner/ambulance/tripsআপনার ট্রিপ (status=active বা done, page, pageSize)
• GET/partner/ambulance/trips/{tripId}একটি ট্রিপ: রোগী, পরিবারের ফোন, গন্তব্য, ধাপ, ভাড়া
• POST/partner/ambulance/trips/{tripId}/assignগাড়ি আর চালক ঠিক করুন বা বদলান (vehicleId, driverId); নতুন চালক SMS-এ ট্রিপের লিংক পান
• POST/partner/ambulance/trips/{tripId}/stepপরের ধাপ, ক্রমে: ON_WAY (রওনা), ARRIVED (পৌঁছেছে), PICKED_UP (রোগী উঠেছেন), DROPPED (গন্তব্যে নামানো)
• POST/partner/ambulance/trips/{tripId}/locationগাড়ি কোথায় (lat, lng, আপনার GPS থেকে), রোগী নামানো পর্যন্ত; পরিবার তাদের পাতায় দেখেন
• POST/partner/ambulance/trips/{tripId}/give-backযেতে পারছেন না (রোগী ওঠার আগে পর্যন্ত): অনুরোধ আবার অন্যদের কাছে যায় (reason)
• POST/partner/ambulance/trips/{tripId}/fareশেষ ভাড়া, আপনার ভাড়ার তালিকা থেকে: km, waitMinutes, oxygenHours, bearer, tollTaka; আনুমানিক ভাড়ার অনেক বেশি হলে reason লাগে
• POST/partner/ambulance/trips/{tripId}/paid-cashপরিবার চালককে নগদে দিয়েছেন: ট্রিপ শেষ
• GET/partner/ambulance/vehiclesআপনার গাড়ি, প্রতিটির অবস্থা (state) আর কতক্ষণ খালি ধরা হবে (freeUntil)
• PUT/partner/ambulance/vehicles/{vehicleId}/availableখালি বা বন্ধ: { "available": true }
• GET/partner/ambulance/driversআপনার চালক

অনুরোধ নেওয়া

নতুন অনুরোধ এলে খবর আসে (ambulance.offer), অথবা requests দেখুন। কাছের কয়েকটি প্রতিষ্ঠান একসঙ্গে পায়; যে আগে নেয় সে-ই পায়, দেরি হলে 409 already_taken। নেওয়ার আগে পরিবারের ফোন নম্বর দেখানো হয় না।

curl -X POST https://api.bedkoi.com/v1/partner/ambulance/requests/<tripId>/accept \
  -H "X-Api-Key: bk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "etaMinutes": 12, "vehicleId": "01a2…", "driverId": "01a3…" }'

ট্রিপ চালানো

গাড়ি আর চালক ঠিক করে ধাপগুলো ক্রমে পাঠান; রওনা আর পৌঁছানোর সময় পরিবার SMS পান। গাড়ির GPS থাকলে অবস্থান পাঠাতে থাকুন। চালক তাঁর লিংক থেকেও ধাপ দিতে পারেন; তখনও আপনার সফটওয়্যার খবর পায় (viaPartner: false)। পৌঁছানোর পর ভাড়া পাঠান; নগদে পেলে paid-cash।

curl -X POST https://api.bedkoi.com/v1/partner/ambulance/trips/<tripId>/step \
  -H "X-Api-Key: bk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "step": "ON_WAY" }'

curl -X POST https://api.bedkoi.com/v1/partner/ambulance/trips/<tripId>/location \
  -H "X-Api-Key: bk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "lat": 23.7461, "lng": 90.3742 }'

curl -X POST https://api.bedkoi.com/v1/partner/ambulance/trips/<tripId>/fare \
  -H "X-Api-Key: bk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "km": 6.4, "waitMinutes": 15 }'

খালি গাড়ি

অনুরোধ আসে শুধু খালি বলা গাড়ির জন্য, আর খালি বলা কিছুক্ষণ পর পুরনো হয়ে যায় (freeUntil)। গাড়ি খালি থাকলে মাঝে মাঝে আবার জানান; ট্রিপে থাকা গাড়ি নিজে থেকেই ধরা হয় না।

curl -X PUT https://api.bedkoi.com/v1/partner/ambulance/vehicles/<vehicleId>/available \
  -H "X-Api-Key: bk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "available": true }'

অনুরোধের খবর (ওয়েবহুক)

প্যানেলের “সফটওয়্যার সংযোগ” পাতায় একটি https ঠিকানা দিন। বেড কই সেখানে প্রতিটি খবর POST করে, সই করে; উত্তর না পেলে কয়েকবার আবার চেষ্টা করে। প্রতিটি খবরে tripId আর reference থাকে; viaPartner বলে কাজটি আপনার সফটওয়্যারের কি না।

খবরের ধরন

• ambulance.offerআপনাকে একটি অনুরোধ দেওয়া হয়েছে (বিস্তারিত offer-এ); আগে নিলে আপনার
• ambulance.offer_closedযে অনুরোধের উত্তর দেননি সেটি আর নেই: reason হলো taken (অন্য কেউ নিয়েছে), cancelled বা expired
• ambulance.trip_updatedআপনার ট্রিপ বদলেছে (পুরো ট্রিপ trip-এ)। change: accepted, assigned, step, fare, fare_answer (পরিবার ভাড়া মেনেছেন বা আপত্তি করেছেন), paid, fare_decided (বেড কই আপত্তির মীমাংসা করেছে)
• ambulance.trip_cancelledপরিবার বা বেড কই আপনার ট্রিপ বাতিল করেছে; গাড়ি পাঠানোর দরকার নেই
• ambulance.trip_given_backট্রিপটি ফিরিয়ে দেওয়া হয়েছে (প্যানেল বা সফটওয়্যার থেকে); এটি আর আপনার নয়
• pingপ্যানেলের “পরীক্ষা পাঠান”

POST https://dispatch.example.com/bedkoi
X-BedKoi-Event: ambulance.offer
X-BedKoi-Delivery: 01a1…
X-BedKoi-Timestamp: 1761552000
X-BedKoi-Signature: v1=5d41…

{
  "event": "ambulance.offer",
  "occurredAt": "2026-10-27T08:00:00.000Z",
  "tripId": "01a1…",
  "reference": "AM7K3Q9",
  "viaPartner": false,
  "offer": {
    "tripId": "01a1…",
    "reference": "AM7K3Q9",
    "type": { "id": 2, "key": "ac", "nameEn": "AC ambulance", "nameBn": "এসি অ্যাম্বুলেন্স", "critical": false, "forDeceased": false },
    "scheduledFor": null,
    "pickup": { "address": "Road 12, Dhanmondi", "lat": 23.746, "lng": 90.376, "area": "ধানমন্ডি" },
    "drop": { "address": "…", "lat": 23.738, "lng": 90.396, "area": "শাহবাগ", "hospital": { "nameEn": "…", "nameBn": "…" } },
    "estimateKm": 4.2,
    "estimateMinTaka": 1800,
    "estimateMaxTaka": 2100,
    "condition": "শ্বাসকষ্ট",
    "floor": 3,
    "hasLift": false,
    "needsBearer": true,
    "distanceKm": 1.8,
    "round": 0,
    "sentAt": "2026-10-27T08:00:00.000Z",
    "createdAt": "2026-10-27T08:00:00.000Z"
  }
}

{
  "event": "ambulance.trip_updated",
  "occurredAt": "2026-10-27T08:14:00.000Z",
  "tripId": "01a1…",
  "reference": "AM7K3Q9",
  "viaPartner": false,
  "change": "step",
  "trip": { "id": "01a1…", "status": "ARRIVED", "phone": "+8801…", "patientName": "…", "vehicleId": "01a2…", "driverId": "01a3…", "fare": { … } }
}

সই মিলিয়ে নিন

X-BedKoi-Signature হলো v1= আর HMAC-SHA256(গোপন চাবি, টাইমস্ট্যাম্প + "." + বডি)। টাইমস্ট্যাম্প থাকে X-BedKoi-Timestamp-এ। সই না মিললে বা খবর ৫ মিনিটের বেশি পুরনো হলে ফেলে দিন। একই খবর দুবার আসতে পারে: X-BedKoi-Delivery দিয়ে চিনে নিন।

// Node.js
import { createHmac, timingSafeEqual } from "node:crypto"

function fromBedKoi(rawBody, headers, secret) {
  const ts = headers["x-bedkoi-timestamp"]
  const sent = headers["x-bedkoi-signature"] ?? ""
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false
  const expected =
    "v1=" + createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex")
  return (
    sent.length === expected.length &&
    timingSafeEqual(Buffer.from(sent), Buffer.from(expected))
  )
}

<?php
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_BEDKOI_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_BEDKOI_SIGNATURE'] ?? '';
$expected = 'v1=' . hash_hmac('sha256', $ts . '.' . $raw, getenv('BEDKOI_WEBHOOK_SECRET'));
if (abs(time() - (int) $ts) > 300 || !hash_equals($expected, $sig)) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
http_response_code(200);

ভুল হলে

• 400পাঠানো তথ্য ঠিক নয়; বার্তায় কারণ লেখা থাকে।
• 401কী নেই, ভুল বা বাতিল (api_key_missing, api_key_invalid)।
• 404আপনার প্রতিষ্ঠানে এমন অনুরোধ, ট্রিপ বা গাড়ি নেই।
• 409ট্রিপ আগেই বদলে গেছে: already_taken (অন্য কেউ নিয়েছে), offer_closed, not_after_… (ধাপ ক্রমে নয়), vehicle_busy (গাড়ি অন্য ট্রিপে), provider_stopped (প্রতিষ্ঠান এখন অনুরোধ নিতে পারছে না)।
• 429মিনিটে ১২০টির বেশি অনুরোধ; একটু পরে আবার চেষ্টা করুন।

সাহায্য দরকার?

প্রশ্ন থাকলে লিখুন: [email protected]