1. Hướng dẫn tích hợp
Tourwell Open APIs
  • Tổng quan
  • Hướng dẫn xác thực
  • API Zalo Mini App (Beta)
  • API Changelog
  • Error Response
  • Khách hàng
    • v1
      • Get by id
      • Get all customer
      • Create customer
      • Update customer
      • Get order history
      • Get destinations
      • Get guests
      • Get by id care history
      • Create company
      • Get all care history
      • Get all company
  • Đơn hàng
    • v1
      • Get by id
      • Get all order
      • Get Passengers Order
      • Create order tour
      • Create order product
      • Create order hotel
      • Create order flight
      • Confirm payment order
      • Cancel order
      • Import Order Flight
      • Create cost order
      • Update cost order
      • Delete cost order
      • Transfer operator
      • Create order multiple services
      • Add services to order.
      • Change order status
      • Add Passengers Order
      • Update Passenger Order
      • Delete Passenger Order
  • Điều hành
    • v1
      • Overview
      • Create row cost
      • Update row cost
      • Delete row cost
  • Sản phẩm
    • v1
      • Create product
      • Get by id
      • Calendar pricing
      • Get all product
      • Get schedule by id
      • Update product
  • Chiết tinh giá
    • v1
  • Nhà cung cấp
    • v1
      • Get all suppliers
      • Get suppliers products
      • Get all tour guides
      • Create Supplier & Hotel
      • Create Prices Suppliers products
      • Append Prices Hotel
  • Lịch khởi hành
    • v1
      • Get all tour
      • Create tour
      • Get tour detail
      • Get tour orders
  • Lead (Cơ hội)
    • Overview
    • Update History
    • v1
      • Get all lead
      • Get by id
      • Create lead
      • Update lead
  • Báo giá
    • v1
      • Get all
      • Update schedules
      • Update policy
  • Khách sạn
    • v1
      • Get all hotel
      • Get by id
  • Kế toán
    • Phiếu thu
      • v1
        • Get all receipt
        • Create receipt
        • Update receipt
        • Confirm Receipt Success
    • Phiếu chi
      • v1
        • Get all payment
        • Confirm Payment
    • Hóa đơn bán ra
      • Update invoice
      • Issue Invoice
      • Get by id
      • Cancel invoice
    • Hóa đơn mua vào
      • Import
    • Thu hộ/Chi hộ
  • Phê duyệt
    • v1
      • Overview
      • Summary
      • Approvals
  • Cấu hình
    • Zalo ZNS
      • Danh sách Tag
      • Get token
    • Địa điểm
      • Search
    • Nhân sự nội bộ
      • Search
    • Webhook
      • Hướng dẫn cài đặt
    • Trạng thái khách hàng
      • Get All
    • Hạng thành viên
      • Get All
    • Loại dịch vụ
      • Get All
    • Mã sân bay
      • Get All Airport
    • Phương thức thanh toán
      • Get All
    • Nguồn bán hàng
      • Get All
    • Phễu chuyển đổi lead
      • Trạng thái lead
      • Trạng thái báo giá
  • Hướng dẫn tích hợp
    • Hướng dẫn tích hợp thanh toán trực tuyến qua Website và Tourwell
    • Hướng dẫn tích hợp thanh toán trực tuyến qua Website, Cổng thanh toán và Tourwell
    • Kết nối hệ thống báo giá, chốt đơn nội bộ với Tourwell
  • MCP
    • Hướng dẫn kết nối
  • Schemas
    • ErrorResponse
  1. Hướng dẫn tích hợp

Kết nối hệ thống báo giá, chốt đơn nội bộ với Tourwell

Phiên bản 1.2 · Cập nhật 11/11/2026

Tích hợp này dùng để làm gì#

Doanh nghiệp đang báo giá và chốt đơn tour trên một hệ thống khác (phần mềm báo giá, website, app bán hàng, file tính giá…) thường phải nhập lại tay sang Tourwell để điều hành và kế toán làm tiếp.
Tích hợp này giúp hệ thống của bạn tự đẩy dữ liệu sang Tourwell ngay khi chốt đơn:
Hệ thống của bạn gửiTourwell tự tạoAi dùng tiếp
Đơn đã chốt: khách, tour, giá bánĐơn hàngSale theo dõi thanh toán, công nợ
Yêu cầu chuyển điều hànhMã điều hành (hồ sơ tour)Điều hành đặt dịch vụ, phân công HDV
Các khoản chi dự kiếnDự toán + phiếu đặt dịch vụ gửi nhà cung cấpĐiều hành, kế toán kiểm soát chi phí và lãi dự kiến

Trước khi bắt đầu#

1. Thông tin Tourwell cung cấp cho bạn
Địa chỉ API: https://{ten-mien}/api/v1, trong đó {ten-mien} là tên miền Tourwell của doanh nghiệp, ví dụ https://congty.tourwell.vn/api/v1.
API token: chuỗi bí mật dùng để xác thực, Tourwell cấp khi bật tích hợp cho doanh nghiệp. Liên hệ bộ phận hỗ trợ Tourwell để nhận token.
2. Mọi lần gọi API đều gửi kèm 3 header
Authorization: Bearer {API_TOKEN}
Content-Type: application/json
Accept: application/json
3. Quy ước dữ liệu
Dữ liệuCách ghiVí dụ
Ngày của tour, đơn hàngdd/mm/yyyy01/12/2026
Ngày của dòng chi phí (check_in, check_out)yyyy-mm-dd2026-12-01
Số tiềnChỉ ghi số, không dấu chấm, không ký hiệu tiền15900000
4. Giới hạn: tối đa 60 lần gọi mỗi phút cho mỗi token. Khi đẩy nhiều tour cùng lúc, nên gọi cách nhau khoảng 1 giây.
5. Đọc kết quả trả về
Thành công: "success": true, dữ liệu nằm trong data.
Dữ liệu gửi lên bị sai: mã lỗi 422, phần errors cho biết trường nào sai.
Ví dụ actions.0.item_ids nghĩa là trường item_ids trong phần tử đầu tiên của actions (đánh số từ 0).

Bước 0 – Lấy mã danh mục#

Tourwell nhận diện sản phẩm, loại dịch vụ, nhà cung cấp, nhân viên bằng ID dạng số. Bạn lấy các ID này một lần, lưu lại để dùng ở các bước sau.
Cần ID củaGọi APIID nằm ở
Sản phẩm tourGET /api/v1/products?code={mã sản phẩm} · Chi tiếtdata[].id
Loại dịch vụ (khách sạn, xe, vé…)GET /api/v1/servicesdata[].id
Nhà cung cấpGET /api/v1/suppliers?name={tên} · Chi tiếtdata[].id
Nhân viên điều hànhGET /api/v1/staff/search?q={tên hoặc email} · Chi tiếtdata[].id
Lưu ý: Hãy kiểm tra qua API, không dùng ID trong ví dụ của tài liệu.

Chọn cách làm phù hợp#

Trường hợpLàm theo
Tour đoàn: cả chuyến dành cho một khách hoặc một công tyCách 1
Tour ghép: mở một lịch khởi hành, bán cho nhiều khách lẻCách 2
Dịch vụ lẻ: khách sạn, vé máy bay, visa, vé tham quan, xe… bán riêng, không theo tourCách 3

Cách 1 – Tour đoàn#

Gồm 3 bước: tạo đơn hàng → lập mã điều hành → ghi dự toán.

Bước 1. Tạo đơn hàng#

POST https://{ten-mien}/api/v1/orders · Chi tiết API
{
  "contact_name": "Công ty ABC",
  "contact_phone": "0901234567",
  "order_code": "ORD-000123",
  "items": [
    {
      "service_id": 10,
      "tour_type": "group",
      "product_id": 125,
      "depart_date": "01/12/2026",
      "return_date": "05/12/2026",
      "pricing": [
        { "price": 15900000, "quantity": 18, "description": "Người lớn" },
        { "price": 12900000, "quantity": 2, "description": "Trẻ em" }
      ]
    }
  ]
}
Bắt buộc: tên khách contact_name, số điện thoại contact_phone, loại dịch vụ service_id (chọn loại Tour), ngày đi depart_date.
tour_type: "group": đánh dấu đây là tour đoàn.
order_code: mã đơn bên hệ thống của bạn. Nên gửi để tránh tạo trùng đơn (xem phần Khi gọi API bị lỗi).
pricing: giá bán cho khách, mỗi dòng là một loại khách.
Kết quả:
{ "success": true, "data": { "id": 1746, "code": "UP1746", "items": [ { "id": 2329 } ] } }
👉 Ghi lại: mã đơn data.id (1746) và mã dịch vụ data.items[0].id (2329).
🖥️ Trên Tourwell: đơn hàng mới xuất hiện trong danh sách Đơn hàng, có khách, tour, giá bán và tổng tiền.

Bước 2. Lập mã điều hành#

POST https://{ten-mien}/api/v1/orders/{order_id}/transfer-operator · Chi tiết API
Ví dụ {order_id} = 1746, mã đơn ở bước 1.
{
  "actions": [
    {
      "action_type": "create_new",
      "item_ids": [2329],
      "tour_type": "group",
      "tour_code": "TOUR-2612-001",
      "tour_name": "Đoàn ABC – Hàn Quốc 01/12",
      "operator_ids": [12]
    }
  ]
}
action_type: "create_new": tạo mã điều hành mới.
item_ids: mã dịch vụ đã ghi lại ở bước 1.
tour_type: "group": tour đoàn.
tour_code: mã tour bên hệ thống của bạn. Để trống thì Tourwell tự tạo mã.
operator_ids: nhân viên điều hành phụ trách (lấy ở bước 0), có thể bỏ trống.
Kết quả:
{ "success": true, "data": { "order_id": 1746, "tours": [ { "tour_id": 1252, "tour_code": "TOUR-2612-001" } ] } }
👉 Ghi lại: mã điều hành data.tours[0].tour_id (1252).
🖥️ Trên Tourwell: tour xuất hiện ở mục Điều hành, giao cho nhân viên điều hành bạn đã chọn để bắt đầu xử lý.
Sau bước này, đơn hàng chuyển sang trạng thái Thành công và được khóa lại, không sửa được nữa.
Nếu doanh nghiệp bạn quy định đơn phải có thanh toán mới được chuyển điều hành, hãy ghi nhận thanh toán cho đơn trước.

Bước 3. Ghi dự toán#

POST https://{ten-mien}/api/v1/tours/{tour_id}/costs · Chi tiết API
Ví dụ {tour_id} = 1252, mã điều hành ở bước 2. Mỗi khoản chi phí gửi một lần.
{
  "mode": "estimate",
  "type_of_service_id": 3,
  "supplier_id": 58,
  "description": "Khách sạn 4 sao Seoul",
  "price": 1800000,
  "quantity": 10,
  "period": 4,
  "vat": 8,
  "check_in": "2026-12-01",
  "check_out": "2026-12-05"
}
Bắt buộc: mode (luôn ghi "estimate" = dự toán), loại dịch vụ type_of_service_id, đơn giá price.
Các trường còn lại:
TrườngNghĩaKhông gửi thì lấy
supplier_idNhà cung cấpChưa chọn nhà cung cấp
descriptionTên khoản chiTrống
quantitySố lượng: số phòng, số xe, số vé…1
periodSố đêm, số ngày hoặc số lần1
focSố lượng được miễn phí0
vatThuế VAT (%)0
vat_typeex-vat = giá chưa có VAT, inc-vat = giá đã có VATex-vat
currency_code, exchange_rateLoại tiền và tỷ giá quy ra VNDvnd, 1
Cách tính tiền: đơn giá × (số lượng − miễn phí) × số đêm × tỷ giá, rồi cộng VAT.
Ví dụ trên: 1.800.000 × 10 × 4 = 72.000.000, cộng VAT 8% = 77.760.000 đ.
Kết quả:
{ "success": true, "data": { "id": 3113, "mode": "estimate", "grand_total": 77760000 } }
👉 Ghi lại: mã dòng chi phí data.id (3113), dùng khi cần sửa hoặc xóa.
🖥️ Trên Tourwell: khoản chi hiện trong tab Dự toán của tour, tổng chi và lãi dự kiến được tính lại ngay. Khi có chọn nhà cung cấp, Tourwell tự tạo phiếu đặt dịch vụ để điều hành gửi cho nhà cung cấp đó.

Đoàn có nhiều đơn hàng#

Đơn đầu tiên làm đủ 3 bước. Các đơn sau chỉ làm bước 1 và bước 2, trong đó bước 2 ghép vào mã điều hành đã có:
{ "actions": [ { "action_type": "join_existing", "item_ids": [2330], "existing_tour_id": 1252 } ] }
Dự toán chỉ ghi một lần cho cả đoàn.

Cách 2 – Tour ghép#

Gồm 3 bước: tạo lịch khởi hành → tạo đơn cho từng khách → ghi dự toán.

Bước 1. Tạo lịch khởi hành#

POST https://{ten-mien}/api/v1/tours · Chi tiết API
{
  "type": "join",
  "product_id": 125,
  "tour_code": "TOUR-2612-002",
  "depart": "01/12/2026",
  "return": "05/12/2026",
  "total_seat": 30,
  "not_over_seat": 1,
  "followers": ["dieuhanh@congty.vn"]
}
Bắt buộc: loại tour type (join = tour ghép), sản phẩm product_id, ngày đi depart, tổng số chỗ total_seat.
not_over_seat: 1: không cho bán quá số chỗ.
followers: email nhân viên điều hành, phải là email đã có trên Tourwell.
Giá bán, lịch trình, tài liệu đính kèm tự lấy theo sản phẩm.
Kết quả:
{ "success": true, "data": { "id": 1251, "code": "TOUR-2612-002", "type": "join", "status": 1 } }
👉 Ghi lại: mã lịch khởi hành data.id (1251).
🖥️ Trên Tourwell: lịch khởi hành mới hiện trong Lịch khởi hành, sale bán được ngay và theo dõi được số chỗ còn trống.
Nếu doanh nghiệp bạn có quy trình duyệt tour, lịch mới tạo sẽ chờ duyệt trên Tourwell trước khi mở bán.

Bước 2. Tạo đơn cho từng khách#

POST https://{ten-mien}/api/v1/orders · Chi tiết API
Chỉ cần ghi mã lịch khởi hành và giá:
{
  "contact_name": "Nguyễn Văn A",
  "contact_phone": "0912345678",
  "order_code": "ORD-000124",
  "items": [
    { "tour_id": 1251, "pricing": [ { "price": 15900000, "quantity": 2, "description": "Người lớn" } ] }
  ]
}
Tour ghép không cần lập mã điều hành: đơn tự gắn vào lịch khởi hành.
🖥️ Trên Tourwell: khách hiện trong danh sách khách của lịch khởi hành, số chỗ đã bán tự cập nhật.

Bước 3. Ghi dự toán#

Làm giống bước 3 của cách 1, thay bằng mã lịch khởi hành (1251).

Cách 3 – Dịch vụ lẻ#

Dùng cho khách sạn, vé máy bay, visa, vé tham quan, xe… bán riêng.
Gồm 3 bước: tạo đơn hàng → lập mã điều hành → điền giá vốn vào dự toán.

Bước 1. Tạo đơn hàng#

POST https://{ten-mien}/api/v1/orders · Chi tiết API
Một đơn có thể gồm nhiều dịch vụ lẻ.
{
  "contact_name": "Nguyễn Văn B",
  "contact_phone": "0912345678",
  "order_code": "ORD-000125",
  "items": [
    {
      "service_id": 2,
      "depart_date": "10/12/2026",
      "return_date": "12/12/2026",
      "note_service": "Khách sạn Ladalat, phòng hướng hồ",
      "pricing": [
        { "price": 1500000, "quantity": 2, "period": 2, "description": "Phòng đôi" }
      ]
    },
    {
      "service_id": 5,
      "depart_date": "10/12/2026",
      "pricing": [
        { "price": 450000, "quantity": 2, "description": "Xe đón sân bay" }
      ]
    }
  ]
}
service_id: loại dịch vụ, lấy ở bước 0 (khách sạn, vé máy bay, xe…).
depart_date: ngày sử dụng. return_date: ngày kết thúc, ví dụ ngày trả phòng.
pricing: giá bán. Với khách sạn, quantity là số phòng, period là số đêm.
note_service: tên khách sạn, chuyến bay… để điều hành biết cần đặt gì.
Kết quả:
{ "success": true, "data": { "id": 1750, "items": [ { "id": 2336 }, { "id": 2337 } ] } }
👉 Ghi lại: mã đơn data.id và mã từng dịch vụ data.items[].id.

Bước 2. Lập mã điều hành#

POST https://{ten-mien}/api/v1/orders/{order_id}/transfer-operator · Chi tiết API
Mỗi dịch vụ một mã điều hành (thường dùng):
{
  "actions": [
    { "action_type": "create_new", "item_ids": [2336], "tour_code": "KS-2612-001" },
    { "action_type": "create_new", "item_ids": [2337], "tour_code": "XE-2612-001" }
  ]
}
Gộp nhiều dịch vụ vào một mã điều hành, ví dụ khách sạn kèm xe đón:
{
  "actions": [
    { "action_type": "create_new", "item_ids": [2336, 2337], "main_item_id": 2336, "tour_code": "KS-2612-001" }
  ]
}
main_item_id: dịch vụ chính, mã điều hành lấy theo loại dịch vụ này. Các dịch vụ còn lại đi kèm.
Không cần gửi tour_type.
Kết quả:
{ "success": true, "data": { "tours": [ { "tour_id": 1256, "tour_code": "KS-2612-001", "tour_type": "single" } ] } }
👉 Ghi lại: mã điều hành data.tours[].tour_id.
🖥️ Trên Tourwell: dịch vụ xuất hiện ở mục Điều hành theo đúng loại (khách sạn, vé, xe…). Tourwell tự tạo sẵn các dòng dự toán theo từng dòng giá bán, có số lượng nhưng chưa có giá vốn.

Bước 3. Điền giá vốn vào dự toán#

Vì dòng dự toán đã được tạo sẵn, bạn sửa giá vào các dòng đó, không tạo dòng mới để tránh trùng.
3a. Xem các dòng có sẵn: GET https://{ten-mien}/api/v1/tours/{tour_id}/costs?mode=estimate
{
  "data": [
    { "id": 3119, "description": "Phòng đôi", "estimate": { "price": 0, "quantity": 2, "period": 2 } },
    { "id": 3120, "description": "Xe đón sân bay", "estimate": { "price": 0, "quantity": 2, "period": 1 } }
  ]
}
3b. Điền giá vốn cho từng dòng: PATCH https://{ten-mien}/api/v1/tours/{tour_id}/costs/{cost_id} · Chi tiết API
{ "mode": "estimate", "price": 1100000, "supplier_id": 58, "vat": 8 }
Có thêm khoản chi chưa nằm trong đơn (phí dịch vụ, phụ thu…), thêm dòng mới như bước 3 của cách 1.

Xem, sửa, xóa dự toán#

ViệcGọi API
Xem các dòng dự toánGET /api/v1/tours/{tour_id}/costs?mode=estimate
Sửa một dòngPATCH /api/v1/tours/{tour_id}/costs/{cost_id} · Chi tiết
Xóa một dòngDELETE /api/v1/tours/{tour_id}/costs/{cost_id}?mode=estimate · Chi tiết
Khi sửa, chỉ cần gửi trường muốn đổi, kèm mode:
{ "mode": "estimate", "quantity": 11 }

Khi gọi API bị lỗi#

Mã lỗiNghĩaCách xử lý
400Không thực hiện được, ví dụ đơn đã hủy hoặc chưa có thanh toánĐọc nội dung message
401Sai API tokenKiểm tra lại token
404Không tìm thấyKiểm tra lại mã trên đường dẫn
409Mã đơn / mã tour đã tồn tạiXem bảng bên dưới
422Dữ liệu gửi lên chưa đúngSửa theo nội dung errors
429Gọi quá nhanhChờ 1 phút rồi gọi lại
500 hoặc mất kết nốiLỗi hệ thống hoặc mạngGọi lại sau ít phút
Gọi lại mà không bị trùng dữ liệu
Khi mất kết nối, bạn không biết lần gọi trước đã thành công hay chưa. Hãy luôn gửi order_code và tour_code theo hệ thống của bạn: nếu dữ liệu đã có, Tourwell sẽ báo lỗi thay vì tạo thêm bản mới.
Mất kết nối ở bướcGọi lại lần nữa thì nhậnLấy lại mã đã tạo bằng cách
Tạo đơn hàngLỗi 409GET /api/v1/orders?code={order_code} → data[0].id · Chi tiết
Lập mã điều hànhLỗi 422 báo mã đã tồn tạiGET /api/v1/tours/{tour_code} → data.id · Chi tiết
Tạo lịch khởi hànhLỗi 409Mã có sẵn trong kết quả, mục data.id
Ghi dự toánCó thể bị trùng dòngXem danh sách dự toán trước, chưa có dòng đó mới gửi lại

Lưu ý khi tích hợp#

Lưu ngay các mã nhận được (mã đơn, mã dịch vụ, mã điều hành, mã dòng chi phí) vào hệ thống của bạn. Khi chạy lại, bỏ qua bước đã có mã.
Dự toán ghi vào mã điều hành (tour_id), không phải mã đơn hàng.
Chỉ tự động gọi lại khi gặp lỗi 429, 500 hoặc mất kết nối. Các lỗi khác cần sửa dữ liệu trước.
Giữ API token ở phía máy chủ, không đặt trong website hoặc ứng dụng điện thoại.
Cần hỗ trợ, gửi cho Tourwell: thời điểm gọi, đường dẫn API, dữ liệu đã gửi và kết quả nhận được (che token).

Gợi ý prompt cho công cụ AI lập trình#

Bạn có thể nhờ AI (Claude, ChatGPT, Cursor, Copilot…) viết phần kết nối. Copy prompt bên dưới, điền vào phần trong [ ] rồi gửi cho AI. Đi lần lượt từ prompt 1.

Prompt 1 – Viết chức năng kết nối#

Đọc tài liệu tích hợp Tourwell tại https://docs-api.tourwell.vn/doc-2519390 và viết giúp tôi
chức năng tự đẩy đơn đã chốt từ hệ thống của tôi sang Tourwell.

Hệ thống của tôi:
- Viết bằng: [VD: PHP Laravel / Node.js / Python / Google Apps Script]
- Dữ liệu đơn và tour lưu ở: [VD: MySQL, bảng orders và tour_costs / Google Sheet]
- Tôi bán: [tour đoàn / tour ghép / dịch vụ lẻ – có thể chọn nhiều]
- Muốn đẩy sang Tourwell khi: [VD: bấm nút "Chốt đơn" / tự chạy mỗi 15 phút]

Yêu cầu:
- Làm đúng các bước trong tài liệu ứng với loại tôi bán.
- Lưu lại các mã Tourwell trả về. Chạy lại thì bỏ qua bước đã xong, không tạo trùng.
- Luôn gửi mã đơn, mã tour theo hệ thống của tôi (order_code, tour_code).
- Lấy ID sản phẩm, loại dịch vụ, nhà cung cấp qua API tra cứu, không dùng số trong ví dụ.
- Dịch vụ lẻ: sửa giá vốn vào các dòng dự toán Tourwell tạo sẵn, không thêm dòng mới.
- Để API token trong biến môi trường, ghi log mỗi lần gọi API.

Hỏi lại tôi nếu còn thiếu thông tin trước khi viết code.

Prompt 2 – Chạy thử với một đơn#

Chạy thử chức năng với đơn [mã đơn của tôi]. Với từng bước, cho tôi xem đã gọi API nào,
Tourwell trả về gì và đã lưu mã nào. Chưa chạy cho các đơn khác.
Chạy xong, mở Tourwell kiểm tra đơn hàng, mã điều hành và dự toán đã đúng chưa.

Prompt 3 – Khi gặp lỗi#

Gọi API Tourwell bị lỗi. Đối chiếu mục "Khi gọi API bị lỗi" trong tài liệu
https://docs-api.tourwell.vn/doc-2519390, tìm nguyên nhân và sửa giúp tôi.
Lỗi nhận được: [dán nội dung lỗi]
Modified at 2026-11-12 01:57:03
Previous
Hướng dẫn tích hợp thanh toán trực tuyến qua Website, Cổng thanh toán và Tourwell
Next
Hướng dẫn kết nối
Built with