Embed & API Guide — Dovara.Biz | Hướng Dẫn Nhúng & API

Overview

Dovara.Biz offers three ways to integrate booking into any external website or app:

Tier	Method	Best for
Tier 1	iFrame Embed	Simple websites — paste one line of HTML
Tier 2	JS Widget	Any site — floating "Book Now" button with a modal
Tier 3	REST API	Developers — full server-to-server integration

💡 Before using Tier 2 or Tier 3, generate your API Key in Settings → Embed & API.

Setup

1 Generate Your API Key

Log in to your Provider Dashboard.
Go to Settings → Embed & API.
Click Generate API Key.
Copy the key and store it securely — it will be masked after you navigate away.

⚠️ Treat your API key like a password. Never expose it in client-side JavaScript. Clicking Regenerate Key immediately invalidates the old key.

Tier 1 — iFrame Embed

2 Embed the Booking Page with an iFrame

Paste this HTML anywhere on your website to show the full booking wizard inline. Replace YOUR_EMBED_TOKEN with your token from Settings → Embed & API. The token identifies your booking page without exposing your internal provider ID.

<iframe
  src="https://dovara.biz/book?token=YOUR_EMBED_TOKEN&embed=1"
  width="100%"
  height="650"
  frameborder="0"
  allow="forms"
  loading="lazy">
</iframe>

Optional URL parameters:

Parameter	Example	Purpose
`token`	`?token=a3f8c2...`	Your embed token (from Settings → Embed & API)
`lang`	`&lang=vi`	Force a language: en, vi, th, km, lo
`embed`	`&embed=1`	Enables embed mode (no header/footer)

Tier 2 — JS Widget

3 Add a Floating "Book Now" Button

Paste one <script> tag anywhere in your page's <body>. A floating button appears — clicking it opens the booking form in a modal overlay.

<script
  src="https://dovara.biz/widget.js"
  data-token="YOUR_EMBED_TOKEN"
  data-lang="en"
  data-color="#0A76D8"
  data-label="Book Now"
  data-position="bottom-right">
</script>

Attributes:

Attribute	Default	Description
`data-token`	—	Required. Your embed token from Settings → Embed & API. Does not expose your internal provider ID.
`data-lang`	`en`	Widget language: en, vi, th, km, lo
`data-color`	`#0A76D8`	Button background colour (any CSS colour)
`data-label`	`Book Now`	Button label text
`data-position`	`bottom-right`	`bottom-right` or `bottom-left`
`data-base-url`	auto	Override base URL (advanced)

💡 The widget does not require an API key — it simply opens the embed booking page in a modal.

Tier 3 — REST API

4 Authentication

All API endpoints require your API key. Pass it as an HTTP header (recommended) or as a query parameter:

Option A — Authorization header (recommended)

Authorization: Bearer YOUR_64_CHAR_API_KEY

Option B — Query parameter

GET /api/v1/sessions.php?api_key=YOUR_64_CHAR_API_KEY&date=2026-03-25

⚠️ Never use Option B in client-side code (browser) — it exposes your key in browser history and server logs. Option B is safe only for server-to-server calls.

Rate limits:

Endpoint	Limit
GET /api/v1/sessions.php	60 requests / minute
POST /api/v1/book.php	20 requests / minute

Rate limit is per API key per minute window. HTTP 429 is returned when exceeded, with a Retry-After: 60 header.

5 GET List Available Sessions

GET https://dovara.biz/api/v1/sessions.php

Query Parameters:

Parameter	Required	Description
`date`	No	Date in `YYYY-MM-DD` format. Defaults to today.
`api_key`	Alt.	API key (or use Authorization header)

The provider is identified by your API key — no provider ID is required or accepted.

Example request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://dovara.biz/api/v1/sessions.php?date=2026-03-25"

Success response (200):

{
  "status": "ok",
  "date": "2026-03-25",
  "sessions": [
    {
      "id": 7,
      "time": "09:00",
      "title": "Trang",
      "capacity": 2,
      "booked": 1,
      "available": 1
    },
    {
      "id": 8,
      "time": "09:00",
      "title": "Lan",
      "capacity": 2,
      "booked": 0,
      "available": 2
    }
  ]
}

6 POST Create a Booking

POST https://dovara.biz/api/v1/book.php

Request body (JSON):

Field	Required	Description
`session_id`	Yes	Schedule ID from the sessions endpoint
`name`	Yes	Client full name
`email`	One of	Client email address
`phone`	One of	Client phone number (at least email or phone required)
`note`	No	Optional note to the provider

Example request:

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": 7,
    "name": "Nguyen Van A",
    "email": "nvana@example.com",
    "phone": "+84901234567",
    "note": "Please confirm by SMS"
  }' \
  "https://dovara.biz/api/v1/book.php"

Success response (201):

{
  "status": "ok",
  "ref": "BK-1Z",
  "appo_number": 2,
  "appo_id": 55,
  "session_id": 7,
  "session_date": "2026-03-25",
  "session_time": "09:00"
}

Error responses:

HTTP	code	Meaning
401	`missing_api_key`	No key provided
401	`invalid_api_key`	Key not found or provider not public
404	`session_not_found`	Session doesn't exist for this provider
409	`session_full`	No capacity remaining
409	`session_past`	Session date is in the past
422	`validation`	Missing / invalid fields
429	`rate_limited`	Too many requests

Full Example

7 JavaScript Quick-Start (Server-Side Node.js)

This example queries available sessions and then books the first available one:

const API_KEY = 'YOUR_64_CHAR_API_KEY';
const BASE    = 'https://dovara.biz';
const HEADERS = { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' };
const TODAY   = new Date().toISOString().slice(0, 10);

async function run() {
    // 1. Get sessions for today (provider derived from API key — no ID needed)
    const res1 = await fetch(`${BASE}/api/v1/sessions.php?date=${TODAY}`, { headers: HEADERS });
    const data1 = await res1.json();
    const session = data1.sessions.find(s => s.available > 0);
    if (!session) { console.log('No available sessions today.'); return; }

    // 2. Book the first available session
    const res2 = await fetch(`${BASE}/api/v1/book.php`, {
        method: 'POST',
        headers: HEADERS,
        body: JSON.stringify({
            session_id: session.id,
            name:       'Nguyen Van A',
            email:      'nvana@example.com',
            phone:      '+84901234567',
        })
    });
    const data2 = await res2.json();
    console.log('Booking confirmed:', data2.ref, '— Appo #', data2.appo_number);
}

run();

💡 Always run API calls from your server, not from a browser script, to keep the API key secret.

Tổng Quan

Dovara.Biz cung cấp ba cách tích hợp lấy hẹn vào bất kỳ website hoặc ứng dụng nào:

Cấp độ	Phương thức	Phù hợp với
Cấp 1	Nhúng iFrame	Website đơn giản — chỉ cần dán một dòng HTML
Cấp 2	Widget JS	Bất kỳ website nào — nút nổi "Lấy Hẹn" mở hộp thoại
Cấp 3	REST API	Lập trình viên — tích hợp server-to-server đầy đủ

💡 Trước khi dùng Cấp 2 hoặc Cấp 3, hãy tạo API Key trong Cài đặt → Nhúng & API.

Cài Đặt Ban Đầu

1 Tạo API Key

Đăng nhập vào Bảng Điều Khiển Nhà Cung Cấp.
Vào Cài đặt → Nhúng & API.
Nhấn Tạo API Key.
Sao chép key và lưu trữ an toàn — key sẽ bị ẩn sau khi bạn điều hướng đi.

⚠️ Hãy coi API key như mật khẩu. Không bao giờ để lộ nó trong JavaScript phía client. Nhấn Tạo lại Key sẽ vô hiệu hóa ngay lập tức key cũ.

Cấp 1 — Nhúng iFrame

2 Nhúng Trang Lấy Hẹn Bằng iFrame

Dán đoạn HTML này vào bất kỳ đâu trên website của bạn để hiển thị trình hướng dẫn lấy hẹn trực tiếp. Thay TOKEN_NHÚNG_CỦA_BẠN bằng token của bạn (xem trong Cài đặt → Nhúng & API). Token không tiết lộ ID nhà cung cấp nội bộ.

<iframe
  src="https://dovara.biz/book?token=TOKEN_NHÚNG_CỦA_BẠN&embed=1"
  width="100%"
  height="650"
  frameborder="0"
  allow="forms"
  loading="lazy">
</iframe>

Tham số URL tùy chọn:

Tham số	Ví dụ	Mục đích
`token`	`?token=a3f8c2...`	Token nhúng của bạn (từ Cài đặt → Nhúng & API)
`lang`	`&lang=vi`	Buộc ngôn ngữ: en, vi, th, km, lo
`embed`	`&embed=1`	Kích hoạt chế độ nhúng (không có header/footer)

Cấp 2 — Widget JS

3 Thêm Nút "Lấy Hẹn" Nổi

Dán một thẻ <script> vào bất kỳ đâu trong <body> của trang. Một nút nổi sẽ xuất hiện — khi nhấn sẽ mở form lấy hẹn trong hộp thoại.

<script
  src="https://dovara.biz/widget.js"
  data-token="TOKEN_NHÚNG_CỦA_BẠN"
  data-lang="vi"
  data-color="#0A76D8"
  data-label="Lấy Hẹn"
  data-position="bottom-right">
</script>

Thuộc tính:

Thuộc tính	Mặc định	Mô tả
`data-token`	—	Bắt buộc. Token nhúng của bạn từ Cài đặt → Nhúng & API. Không tiết lộ ID nhà cung cấp nội bộ.
`data-lang`	`en`	Ngôn ngữ: en, vi, th, km, lo
`data-color`	`#0A76D8`	Màu nền nút (màu CSS bất kỳ)
`data-label`	`Book Now`	Văn bản nhãn nút
`data-position`	`bottom-right`	`bottom-right` hoặc `bottom-left`

💡 Widget không yêu cầu API key — chỉ mở trang lấy hẹn nhúng trong hộp thoại.

Cấp 3 — REST API

4 Xác Thực

Tất cả endpoint API đều yêu cầu API key. Truyền qua HTTP header (khuyến nghị) hoặc query parameter:

Tùy chọn A — Authorization header (khuyến nghị)

Authorization: Bearer API_KEY_64_KÝ_TỰ

Tùy chọn B — Query parameter

GET /api/v1/sessions.php?api_key=API_KEY&date=2026-03-25

⚠️ Không dùng Tùy chọn B trong JavaScript phía client — API key sẽ bị lộ trong lịch sử trình duyệt và log server. Tùy chọn B chỉ an toàn cho các lời gọi server-to-server.

Giới hạn tốc độ:

Endpoint	Giới hạn
GET /api/v1/sessions.php	60 yêu cầu / phút
POST /api/v1/book.php	20 yêu cầu / phút

5 GET Lấy Danh Sách Ca Trống

GET https://dovara.biz/api/v1/sessions.php

Tham số query:

Tham số	Bắt buộc	Mô tả
`date`	Không	Ngày theo định dạng `YYYY-MM-DD`. Mặc định là hôm nay.

Nhà cung cấp được xác định qua API key — không cần ID nhà cung cấp.

Ví dụ phản hồi thành công (200):

{
  "status": "ok",
  "date": "2026-03-25",
  "sessions": [
    { "id": 7, "time": "09:00", "title": "Trang", "capacity": 2, "booked": 1, "available": 1 },
    { "id": 8, "time": "09:00", "title": "Lan",   "capacity": 2, "booked": 0, "available": 2 }
  ]
}

6 POST Tạo Lịch Hẹn

POST https://dovara.biz/api/v1/book.php

Body yêu cầu (JSON):

Trường	Bắt buộc	Mô tả
`session_id`	Có	ID ca từ endpoint sessions
`name`	Có	Họ tên đầy đủ của khách
`email`	Một trong hai	Địa chỉ email của khách
`phone`	Một trong hai	Số điện thoại (cần ít nhất email hoặc phone)
`note`	Không	Ghi chú tùy chọn gửi nhà cung cấp

Phản hồi thành công (201):

{
  "status": "ok",
  "ref": "BK-1Z",
  "appo_number": 2,
  "appo_id": 55,
  "session_date": "2026-03-25",
  "session_time": "09:00"
}

🔌 Dovara.Biz