অধ্যায় ৭.৩ — পাবলিক API

১. উদ্দেশ্য

travoBooks-এর REST API — পার্টনার এবং থার্ড-পার্টি ডেভেলপারদের জন্য। UI নিজেই API-এর প্রথম গ্রাহক — কোনো ইন্টারনাল-অনলি এন্ডপয়েন্ট Phase 1-এ নেই।

২. মূলনীতি

RESTful: HTTP verbs (GET, POST, PUT, DELETE)
JSON: request/response body
HTTPS: সর্বদা; HTTP redirect
Versioned: URL prefix (/v1/, /v2/)
Idempotent where possible: Idempotency-Key header

৩. Authentication

Personal Access Tokens (PATs):

Authorization: Bearer tvb_live_a1b2c3d4e5f6...

টোকেন format: tvb_live_<base62-random-32> (production), tvb_test_<...> (sandbox)
Argon2id-hashed in DB
প্রতি টোকেন একটি partner-এ স্কোপড, একজন user-এর সাথে সংযুক্ত
ঐচ্ছিক expiry (max 365 days)
প্রদর্শন: শুধু তৈরির সময়

৪. Authorization

API অনুরোধ user-এর role + permissions উত্তরাধিকার সূত্রে পায়। যদি Travel Agent role → শুধু booking.create.partner অনুমতি আছে, তাহলে token সেই scope-এর মধ্যে।

৫. ভার্সনিং

/v1/bookings
/v2/bookings  (নতুন breaking change-এর জন্য)

Backward compatibility পদ্ধতি: - নতুন optional field যোগ — minor version - existing field type পরিবর্তন — major version - field মুছে ফেলা — major version, deprecation window

deprecation: minimum ১২ মাস আগে warning header।

৬. মূল এন্ডপয়েন্ট

Resource	এন্ডপয়েন্ট
Bookings	`/v1/bookings`, `/v1/bookings/{id}`
Customers	`/v1/customers`, `/v1/customers/{id}`
Invoices	`/v1/invoices`, `/v1/invoices/{id}`
Payments	`/v1/payments`, `/v1/payments/{id}`
Reports	`/v1/reports/{type}`
Webhooks	`/v1/webhooks`, `/v1/webhooks/{id}`

৭. রেট লিমিট

প্রতি partner per endpoint bucket: - Search: ৬০০/মিনিট - Booking create: ৬০/মিনিট - Ticket issue: ৩০/মিনিট - General reads: ১,২০০/মিনিট

response headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 542
X-RateLimit-Reset: 1716732000

লিমিট অতিক্রম → 429 Too Many Requests।

৮. Idempotency

POST অনুরোধে Idempotency-Key header:

Idempotency-Key: client-generated-uuid

একই key + একই payload → একই response (ডবল booking প্রতিরোধ)। একই key + ভিন্ন payload → 422 error।

৯. Error format

{
  "error": {
    "code": "BOOKING_HOLD_EXPIRED",
    "message": "The booking hold has expired",
    "request_id": "req_a1b2c3...",
    "retry_advice": "non_retryable"
  }
}

(অধ্যায় ১৪.২ — Error Codes-এ বিস্তারিত)

১০. Pagination

GET /v1/bookings?limit=50&cursor=eyJpZCI6MTAwMH0

response:

{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTA1MH0",
    "has_more": true
  }
}

Cursor-based (not offset) — better performance, no skip issues।

১১. Filtering & Sorting

GET /v1/bookings?status=ISSUED&created_after=2026-01-01&sort=-created_at

১২. Webhooks integration

API দিয়ে webhook endpoints register করুন (অধ্যায় ৭.৪ দ্রষ্টব্য)।

১৩. সাধারণ ফাঁদ

⚠️ Production token in test environment — real bookings made
⚠️ Idempotency key reuse — ভিন্ন payload conflict
⚠️ Polling instead of webhooks — rate limit hit
⚠️ Token rotation policy ছাড়া — long-lived secrets risk