DILO Seatmap
Planning

Giới thiệuOverview

DILO Seating là phần mềm sơ đồ chỗ ngồi. Nền tảng ngoài dùng API và bộ hiển thị của DILO để vẽ lại sơ đồ và cho khách chọn chỗ. DILO Seating is a seat map software. External platforms use the DILO API and renderer to draw the floor and let customers pick seats.

Đơn vị tổ chức dựng sơ đồ mặt bằng trên DILO một lần: xếp bàn, booth, khu đứng, gán hạng vé và giá cho từng khu. Rạp, đơn vị sự kiện hay web bán vé khác nhúng chính sơ đồ đó vào trang của mình để khách xem chỗ trống và chọn chỗ, thay vì phải tự xây lại công cụ sơ đồ. An organiser builds the floor once on DILO: arranges tables, booths and standing zones, then assigns a category and price to each area. Cinemas, event operators or other ticketing sites embed that same map into their own pages so guests can see what is free and choose a spot, instead of rebuilding a seat map tool from scratch.

Ranh giới sản phẩmProduct boundary

Bắt đầu nhanhQuickstart

Ba bước để hiện một sơ đồ chỗ ngồi trên trang của bạn và nhận sự kiện khi khách chọn chỗ. Three steps to show a seat map on your page and receive events when a guest picks a seat.

• Lấy khoá. Nhận cặp khoá công khai và khoá bí mật cho nền tảng của bạn qua mục Liên hệ.Get keys. Receive the public key and secret key for your platform through the Contact section.
• Nhúng sơ đồ. Thêm một thẻ chứa và gọi bộ hiển thị DILO với khoá công khai cùng mã sơ đồ.Embed the map. Add a container and call the DILO renderer with your public key and a plan id.
• Nhận sự kiện chọn chỗ. Đăng ký hàm gọi lại để biết khách vừa chọn hoặc bỏ chọn ghế nào.Receive selection events. Register a callback to learn which seats the guest selected or deselected.

<div id="dilo-seatmap"></div>
<script src="https://dilo.com.vn/js/seating-embed.js"></script>
<script>
  DILOSeating.mount('#dilo-seatmap', {
    publicKey: 'YOUR_PUBLIC_KEY',
    planId:    'PLAN_ID',
    eventId:   'EVENT_ID',
    dateKey:   '2026-08-02',
    lang:      'vi',
    theme:     'dark',
    mode:      'pick',
    onSelect:   function (obj) { console.log('chon',   obj.id, obj.category); },
    onDeselect: function (obj) { console.log('bo chon', obj.id); }
  });
</script>

Xác thựcAuthentication

Mỗi nền tảng ngoài có một không gian làm việc riêng với hai khoá, một để nhúng và một để gọi máy chủ. Each external platform has its own workspace with two keys, one for embedding and one for server side calls.

Hai loại khoáTwo kinds of key

Gọi máy chủServer side call

Đặt khoá bí mật trong header. Không bao giờ đặt khoá bí mật trong đường dẫn, tham số truy vấn hay mã trình duyệt. Put the secret key in a header. Never put the secret key in the path, a query parameter or browser code.

X-DILO-Secret: YOUR_SECRET_KEY

Nhúng sơ đồRendering

Bộ hiển thị DILO vẽ sơ đồ vào một thẻ chứa trên trang của bạn theo cấu hình bạn truyền vào. The DILO renderer draws the map into a container on your page from the configuration you pass in.

Tham số cấu hìnhConfiguration

Hai chế độTwo modes

• view: sơ đồ chỉ để xem, dùng cho trang giới thiệu sự kiện.view: the map is read only, for an event landing page.
• pick: khách bấm chọn ghế, mỗi lần bấm phát một sự kiện về trang của bạn.pick: guests tap to select, each tap emits an event to your page.

DILOSeating.mount('#dilo-seatmap', {
  publicKey: 'YOUR_PUBLIC_KEY',
  planId:  'PLAN_ID',
  eventId: 'EVENT_ID',
  dateKey: '2026-08-02',
  mode:    'view'
});

Hạng vé và giáCategories and pricing

Đọc danh sách khu vực, hạng vé, giá và trạng thái ghế để nền tảng ngoài vẽ và lọc. Read the list of objects, categories, prices and seat status so the external platform can render and filter.

Ví dụ gọiExample request

curl -s "https://dilo.com.vn/api/seating/availability?planId=PLAN_ID&eventId=EVENT_ID&dateKey=2026-08-02" \
  -H "X-DILO-Secret: YOUR_SECRET_KEY"

Phản hồiResponse

{
  "plan": {
    "planId": "PLAN_ID",
    "version": 12,
    "categories": [
      { "key": "vip", "name": "VIP",      "color": "#d14828" },
      { "key": "std", "name": "Standard", "color": "#3b82f6" },
      { "key": "ga",  "name": "Standing", "color": "#16a34a" }
    ],
    "objects": [
      { "id": "A1", "cat": "vip", "label": "Ban A1" },
      { "id": "A2", "cat": "vip", "label": "Ban A2" },
      { "id": "G1", "cat": "ga",  "label": "Khu dung" }
    ]
  },
  "state": {
    "prices": { "vip": 500000, "std": 200000, "ga": 100000 },
    "status": { "A1": "free", "A2": "held", "G1": "free" },
    "currency": "VND"
  }
}

• categories là các hạng vé, mỗi hạng có tên và màu để vẽ chú giải.categories are the ticket classes, each with a name and colour for the legend.
• objects là từng bàn, booth hoặc khu đứng, gắn với một hạng vé qua cat.objects are each table, booth or standing zone, bound to a category through cat.
• prices là giá theo hạng vé. Giá trị 0 nghĩa là vào cửa tự do.prices are per category. A value of 0 means free entry.
• status nhận một trong free, held, booked.status is one of free, held, booked.
• version tăng mỗi lần sơ đồ đổi, dùng cho đồng bộ ở mục sau.version increases whenever the map changes, used for sync in the next section.

Chọn và giữ chỗSelection and holds

Khách chọn ghế trên sơ đồ, trang của bạn nhận danh sách ghế, rồi gọi máy chủ để giữ chỗ trong năm phút. Guests pick seats on the map, your page receives the seat list, then calls the server to hold them for five minutes.

Hàm gọi lại khi chọnSelection callbacks

Ở chế độ pick, mỗi lần khách bấm một ghế, bộ hiển thị gọi onSelect hoặc onDeselect kèm mã ghế và hạng vé. In pick mode, each time a guest taps a seat the renderer calls onSelect or onDeselect with the seat id and category.

var chosen = [];
DILOSeating.mount('#dilo-seatmap', {
  publicKey: 'YOUR_PUBLIC_KEY',
  planId: 'PLAN_ID', eventId: 'EVENT_ID', dateKey: '2026-08-02',
  mode: 'pick',
  onSelect:   function (obj) { chosen.push(obj.id); },
  onDeselect: function (obj) { chosen = chosen.filter(function (id) { return id !== obj.id; }); }
});

Giữ chỗHolding seats

Khi khách bấm tiếp tục, máy chủ của bạn gọi DILO để giữ các ghế đã chọn. DILO trả về mã giữ chỗ và thời điểm hết hạn, mặc định năm phút. Hết hạn thì ghế tự nhả về trạng thái trống. When the guest continues, your server asks DILO to hold the selected seats. DILO returns a hold id and an expiry, five minutes by default. On expiry the seats return to free.

curl -s -X POST "https://dilo.com.vn/api/seating/hold" \
  -H "X-DILO-Secret: YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "planId": "PLAN_ID", "eventId": "EVENT_ID", "dateKey": "2026-08-02", "objectIds": ["A1","A2"] }'

{ "holdId": "HOLD_ID", "expiresAt": "2026-08-02T15:35:00Z" }

Đồng bộ thời gian thựcRealtime

Nền tảng ngoài lấy tình trạng ghế theo sơ đồ và ngày, dùng số phiên bản để chỉ nhận phần thay đổi. The external platform reads seat availability by plan and date, using a version number to fetch only what changed.

Gọi lại điểm truy cập tình trạng ở mục Hạng vé và giá theo chu kỳ ngắn, kèm knownVersion là số phiên bản bạn đang giữ. Nếu sơ đồ chưa đổi, DILO trả về phần trạng thái gọn. Nếu đã đổi, DILO trả về sơ đồ mới cùng số phiên bản mới. Poll the availability endpoint from the Categories and pricing section on a short cycle, passing knownVersion as the version you currently hold. If the map has not changed, DILO returns a compact status. If it has, DILO returns the new map with a new version.

curl -s "https://dilo.com.vn/api/seating/availability?planId=PLAN_ID&eventId=EVENT_ID&dateKey=2026-08-02&knownVersion=12" \
  -H "X-DILO-Secret: YOUR_SECRET_KEY"

• Nhớ kết quả tại phía nền tảng ngoài, đừng gọi mới cho từng lượt xem trang.Cache results on your side, do not call once per page view.
• Chu kỳ vài giây là đủ cho một phiên chọn chỗ đang diễn ra.A few seconds per cycle is enough for an active selection session.
• Khi knownVersion khớp phiên bản hiện tại, phần trả về chỉ gồm thay đổi trạng thái.When knownVersion matches the current version, the response carries only status changes.

Thanh toánPayment

DILO không mở thanh toán ra nền tảng ngoài. Nền tảng ngoài chỉ hiển thị và chọn chỗ, bước đặt và trả tiền chốt qua DILO. DILO does not expose payment to external platforms. The external platform only displays and selects, while booking and payment complete through DILO.

Chuyển sang luồng DILOHand over to DILO

• Sau khi giữ chỗ, chuyển khách sang luồng thanh toán DILO kèm holdId.After a hold, send the guest into the DILO payment flow with the holdId.
• DILO xác nhận đặt, thu tiền qua cổng thanh toán của DILO và phát vé cho khách.DILO confirms the booking, collects payment through the DILO gateway and issues the ticket.
• Nền tảng ngoài nhận kết quả đặt để cập nhật giao diện, không nhận thông tin thẻ hay dòng tiền.The external platform receives the booking result to update its interface, never card details or the money flow.

Bảo mậtSecurity

Nguyên tắc DILO áp dụng cho mọi giao diện mở ra bên ngoài. Principles DILO applies to every externally facing interface.

• Khoá theo từng nền tảng. Mỗi nền tảng một không gian làm việc và khoá riêng, thu hồi được độc lập.Per platform keys. Each platform gets its own workspace and keys, revocable independently.
• Khoá bí mật ở máy chủ. Chỉ khoá công khai được đặt ở trình duyệt, khoá bí mật không bao giờ lộ ra client.Secret key stays server side. Only the public key is placed in the browser, the secret key never reaches the client.
• Hạn mức gọi. Mọi khoá đều có trần theo ngày. Vượt trần trả về 429 thay vì phục vụ tiếp.Quotas. Every key has a daily ceiling. Exceeding it returns 429 rather than continuing to serve.
• Dữ liệu cá nhân. Thông tin định danh của khách không đi ra ngoài qua API seating.Personal data. Guest identifying information never leaves DILO through the seating API.
• Thanh toán khép kín. Phần thu tiền và phát vé không mở ra nền tảng ngoài.Closed payment. Money collection and ticket issuance are never exposed to the external platform.
• Quyền tối thiểu. Nền tảng chỉ nhận đúng phạm vi sơ đồ và sự kiện cần cho tích hợp đã thống nhất.Least privilege. A platform receives only the map and event scope required by the agreed integration.

Cơ hội hợp tácPartnership

DILO Seating mở cho các nền tảng có nhu cầu hiển thị và bán chỗ ngồi theo sơ đồ. DILO Seating opens to platforms that need to display and sell seated inventory from a map.

Liên hệContact

Điền biểu mẫu dưới đây. DILO phản hồi qua email bạn cung cấp. Fill in the form below. DILO replies to the email address you provide.