| Hệ thống của bạn gửi | Tourwell tự tạo | Ai dùng tiếp |
|---|---|---|
| Đơn đã chốt: khách, tour, giá bán | Đơn hàng | Sale theo dõi thanh toán, công nợ |
| Yêu cầu chuyển điều hành | Mã đ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ến | Dự 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 |
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.Authorization: Bearer {API_TOKEN}
Content-Type: application/json
Accept: application/json| Dữ liệu | Cách ghi | Ví dụ |
|---|---|---|
| Ngày của tour, đơn hàng | dd/mm/yyyy | 01/12/2026 |
Ngày của dòng chi phí (check_in, check_out) | yyyy-mm-dd | 2026-12-01 |
| Số tiền | Chỉ ghi số, không dấu chấm, không ký hiệu tiền | 15900000 |
"success": true, dữ liệu nằm trong data.422, phần errors cho biết trường nào sai.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).| Cần ID của | Gọi API | ID nằm ở |
|---|---|---|
| Sản phẩm tour | GET /api/v1/products?code={mã sản phẩm} · Chi tiết | data[].id |
| Loại dịch vụ (khách sạn, xe, vé…) | GET /api/v1/services | data[].id |
| Nhà cung cấp | GET /api/v1/suppliers?name={tên} · Chi tiết | data[].id |
| Nhân viên điều hành | GET /api/v1/staff/search?q={tên hoặc email} · Chi tiết | data[].id |
Lưu ý: Hãy kiểm tra qua API, không dùng ID trong ví dụ của tài liệu.
| Trường hợp | Làm theo |
|---|---|
| Tour đoàn: cả chuyến dành cho một khách hoặc một công ty | Cá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 tour | Cách 3 |
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" }
]
}
]
}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.{ "success": true, "data": { "id": 1746, "code": "UP1746", "items": [ { "id": 2329 } ] } }data.id (1746) và mã dịch vụ data.items[0].id (2329).POST https://{ten-mien}/api/v1/orders/{order_id}/transfer-operator · Chi tiết API{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.{ "success": true, "data": { "order_id": 1746, "tours": [ { "tour_id": 1252, "tour_code": "TOUR-2612-001" } ] } }data.tours[0].tour_id (1252).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.
POST https://{ten-mien}/api/v1/tours/{tour_id}/costs · Chi tiết API{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"
}mode (luôn ghi "estimate" = dự toán), loại dịch vụ type_of_service_id, đơn giá price.| Trường | Nghĩa | Không gửi thì lấy |
|---|---|---|
supplier_id | Nhà cung cấp | Chưa chọn nhà cung cấp |
description | Tên khoản chi | Trống |
quantity | Số lượng: số phòng, số xe, số vé… | 1 |
period | Số đêm, số ngày hoặc số lần | 1 |
foc | Số lượng được miễn phí | 0 |
vat | Thuế VAT (%) | 0 |
vat_type | ex-vat = giá chưa có VAT, inc-vat = giá đã có VAT | ex-vat |
currency_code, exchange_rate | Loại tiền và tỷ giá quy ra VND | vnd, 1 |
{ "success": true, "data": { "id": 3113, "mode": "estimate", "grand_total": 77760000 } }data.id (3113), dùng khi cần sửa hoặc xóa.{ "actions": [ { "action_type": "join_existing", "item_ids": [2330], "existing_tour_id": 1252 } ] }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"]
}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.{ "success": true, "data": { "id": 1251, "code": "TOUR-2612-002", "type": "join", "status": 1 } }data.id (1251).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.
POST https://{ten-mien}/api/v1/orders · Chi tiết API{
"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" } ] }
]
}POST https://{ten-mien}/api/v1/orders · Chi tiết API{
"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ì.{ "success": true, "data": { "id": 1750, "items": [ { "id": 2336 }, { "id": 2337 } ] } }data.id và mã từng dịch vụ data.items[].id.POST https://{ten-mien}/api/v1/orders/{order_id}/transfer-operator · Chi tiết API{
"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" }
]
}{
"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.tour_type.{ "success": true, "data": { "tours": [ { "tour_id": 1256, "tour_code": "KS-2612-001", "tour_type": "single" } ] } }data.tours[].tour_id.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 } }
]
}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 }| Việc | Gọi API |
|---|---|
| Xem các dòng dự toán | GET /api/v1/tours/{tour_id}/costs?mode=estimate |
| Sửa một dòng | PATCH /api/v1/tours/{tour_id}/costs/{cost_id} · Chi tiết |
| Xóa một dòng | DELETE /api/v1/tours/{tour_id}/costs/{cost_id}?mode=estimate · Chi tiết |
mode:{ "mode": "estimate", "quantity": 11 }| Mã lỗi | Nghĩa | Cách xử lý |
|---|---|---|
400 | Không thực hiện được, ví dụ đơn đã hủy hoặc chưa có thanh toán | Đọc nội dung message |
401 | Sai API token | Kiểm tra lại token |
404 | Không tìm thấy | Kiểm tra lại mã trên đường dẫn |
409 | Mã đơn / mã tour đã tồn tại | Xem bảng bên dưới |
422 | Dữ liệu gửi lên chưa đúng | Sửa theo nội dung errors |
429 | Gọi quá nhanh | Chờ 1 phút rồi gọi lại |
500 hoặc mất kết nối | Lỗi hệ thống hoặc mạng | Gọi lại sau ít phút |
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ước | Gọi lại lần nữa thì nhận | Lấy lại mã đã tạo bằng cách |
|---|---|---|
| Tạo đơn hàng | Lỗi 409 | GET /api/v1/orders?code={order_code} → data[0].id · Chi tiết |
| Lập mã điều hành | Lỗi 422 báo mã đã tồn tại | GET /api/v1/tours/{tour_code} → data.id · Chi tiết |
| Tạo lịch khởi hành | Lỗi 409 | Mã có sẵn trong kết quả, mục data.id |
| Ghi dự toán | Có thể bị trùng dòng | Xem danh sách dự toán trước, chưa có dòng đó mới gửi lại |
tour_id), không phải mã đơn hàng.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.[ ] rồi gửi cho AI. Đi lần lượt từ prompt 1.Đọ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.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.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]