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
      • Get row cost
      • 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
        • Cancel 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á
    • Chi nhánh
      • Get all branch offices
    • Lý do hủy
      • Get all cancel reasons
  • 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
    • Hướng dẫn đẩy lead và đơn hàng về Tourwell
  • MCP
    • Hướng dẫn kết nối
  • Schemas
    • ErrorResponse
  1. Hướng dẫn tích hợp

Hướng dẫn đẩy lead và đơn hàng về Tourwell

Phiên bản 1.0 · 17/11/2026
Dành cho mọi hệ thống muốn đưa khách và đơn về CRM Tourwell: website, landing page, form quảng cáo, app bán hàng, OTA, công cụ báo giá, hệ thống nội bộ.

0. Chọn mức tích hợp#

Không cần làm hết. Chọn mức phù hợp rồi chỉ đọc các mục được liệt kê.
MứcDùng khiViệc cần làmĐọc mục
1. Đẩy leadForm web, landing page, chatbot: khách để lại thông tin, sale gọi lạiTạo lead1–5, 9–12
2. Đẩy đơnKhách đặt dịch vụ cụ thể trên hệ thống của bạn, thanh toán xử lý trên Tourwell+ Tạo đơn+ 6
3. Đơn + thanh toánHệ thống của bạn thu tiền (cổng thanh toán, chuyển khoản)+ Tạo và duyệt phiếu thu, chốt đơn+ 7
4. Đủ vòng đờiKhách huỷ, hết hạn giữ chỗ, hoàn tiền trên hệ thống của bạn+ Huỷ phiếu thu, huỷ đơn+ 8
Luồng đầy đủ (mức 4):
Lead (tuỳ chọn) ─┐
                 ▼
Tạo đơn → Tạo phiếu thu → Duyệt phiếu thu → Chốt đơn
                 └──────── Huỷ: huỷ phiếu thu → huỷ đơn

1. Quy tắc chung#

#Quy tắc
Q1Mọi API tạo (lead, đơn, phiếu thu) đều gửi kèm external_source + external_ref. Gửi lại cùng cặp mã → Tourwell trả bản ghi cũ, không tạo trùng.
Q2Lưu id Tourwell trả về. Các API sau gọi theo id.
Q3Timeout, lỗi mạng, lỗi 5xx → gửi lại nguyên request (cùng external_ref).
Q4Tiền chỉ ghi nhận qua phiếu thu (mục 7). Không dùng POST /orders/confirm-payment.
Q5Tối đa 60 request/phút cho mỗi token.

2. Kết nối#

Xem Tổng quan · Hướng dẫn xác thực · Error Response.
MụcGiá trị
Base URLhttps://<tên-miền-crm>/api/v1
HeaderAuthorization: Bearer <api_token> · Content-Type: application/json · Accept: application/json
Định dạng ngàydd/mm/YYYY HH:ii hoặc dd/mm/YYYY, giờ Việt Nam
TokenDoanh nghiệp tạo tài khoản API trên Tourwell và cấp token cho bạn. Mỗi doanh nghiệp một tên miền, một token
// Thành công
{ "success": true,  "message": "…", "data": { … } }
// Lỗi (mã lỗi nằm ở HTTP status)
{ "success": false, "message": "…", "errors": { "field": ["…"] } }

3. Mã tham chiếu ngoài (chống tạo trùng)#

TrườngQuy định
external_sourceTên hệ thống của bạn: chữ, số, _ . -, tối đa 50 ký tự, không phân biệt hoa thường. Bỏ trống = api. Nên cố định, ví dụ web, landing-tet, ota-x
external_refMã bản ghi bên bạn (mã form, mã đơn, mã giao dịch), tối đa 100 ký tự
Tình huốngKết quả
Lần đầuTạo mới, trả id
Gửi lại cùng external_source + external_ref200, trả bản ghi đã tạo kèm "duplicated": true. Các trường khác bị bỏ qua (không sửa bản ghi)
Cùng external_ref, khác external_sourceTạo bản ghi khác
2 request cùng mã đến đồng thờiRequest sau đợi request trước xong rồi trả bản ghi đó. Đợi quá 15 giây → 409, gửi lại sau vài giây
Tra lại bản ghi theo mã của bạn:
LoạiAPI
LeadGET /leads?external_source=web&external_ref=<mã>
ĐơnGET /orders?external_source=web&external_ref=<mã>
Phiếu thuGET /billings/receipts?external_source=web&external_ref=<mã>

4. Danh mục cần ánh xạ#

Kéo một lần khi bắt đầu, sau đó đồng bộ định kỳ. id khác nhau giữa các doanh nghiệp: không gán cứng trong code.
Danh mụcAPIDùng cho trườngCần từ mứcTài liệu
Nguồn kháchGET /sourcessource_id1link
Chi nhánhGET /branch-officesbranch_office_id1link
Nhân viênGET /staff/searchsale_email, follower_email1link
Trạng thái leadGET /lead-statesstate_id1link
Lịch khởi hànhGET /tourstour_id2link
Khách sạnGET /hotelshotel_id2link
Sản phẩmGET /productsproduct_id2link
Loại dịch vụGET /servicesservice_id2link
Tài khoản / quỹ nhận tiềnGET /payment-methodspayment_method_id3link
Lý do huỷ đơnGET /cancel-reasonsreason_id4link
Ghi chú:
GET /tours mặc định chỉ trả lịch đang Mở bán; status=all để lấy tất cả.
GET /branch-offices?status=active chỉ lấy chi nhánh đang hoạt động.
GET /cancel-reasons mặc định chỉ trả lý do đang dùng.

5. Tạo lead (mức 1)#

POST /leads · Create lead
{
  "external_source": "web",
  "external_ref": "FORM-20261117-0012",
  "service": "Tour Hàn Quốc 5N4Đ tháng 12",
  "contact_name": "Nguyễn Văn A",
  "contact_phone": "0912345678",
  "contact_email": "a@example.com",
  "date_range": "20/12/2026",
  "adult": 2,
  "children": 1,
  "note": "Khách hỏi qua form trang chủ",
  "source_id": 4,
  "branch_office_id": 1,
  "sale_email": "sale@congty.vn",
  "is_notify": 1
}
TrườngBắt buộcGhi chú
service✔Dịch vụ khách quan tâm
contact_name, contact_phone✔Tourwell tìm khách theo SĐT hoặc email, chưa có thì tự tạo. Khách nước ngoài gửi thêm country_code
external_source, external_ref✔ (Q1)Mục 3
source_id / source_nameNguồn khách, theo id hoặc tên
sale_emailGiao cho sale. Không gửi thì lead chưa có người phụ trách
is_notify1 = báo sale (hoặc người có quyền xem lead) ngay
Response: { "id": 9562, "code": "LU9562", "link_erp": "…", "external_source": "web", "external_ref": "FORM-…" }.
Sửa lead: PUT /leads/{id} · Update lead. ⚠️ Phải gửi đủ service, note, date_range, adult, sale_email, state_id. Trường không gửi sẽ bị ghi rỗng. Cách làm: GET /leads/{id}, sửa trường cần đổi, gửi lại toàn bộ.

6. Tạo đơn (mức 2)#

Loại đơnAPITài liệu
Tour theo lịch khởi hànhPOST /orders/tourslink
Khách sạnPOST /orders/hotelslink
1 sản phẩmPOST /orders/productslink
Nhiều dịch vụ (combo)POST /orderslink
Ví dụ đơn tour:
{
  "external_source": "web",
  "external_ref": "WEB-ORD-10023",
  "tour_id": 18055,
  "contact_name": "Nguyễn Văn A",
  "contact_phone": "0912345678",
  "contact_email": "a@example.com",
  "note_order": "Khách cần phòng tầng cao",
  "source_id": 4,
  "branch_office_id": 1,
  "follower_email": "sale@congty.vn",
  "pricing": [
    { "price_rule_id": 77, "description": "Người lớn", "unit": "pax",
      "price": 14990000, "quantity": 2, "period": 1, "vat": { "amount": 0 } }
  ]
}
TrườngBắt buộcGhi chú
tour_id✔id lịch khởi hành (chuyến có ngày đi), không phải tour mẫu
contact_name, contact_phone✔Như lead
external_source, external_ref✔ (Q1)Mục 3
pricing[]✔price_rule_id lấy từ lịch khởi hành; 0 = dòng giá tự do. vat.amount tính theo %
note_orderGhi chú đơn (tên trường là note_order)
follower_emailSale phụ trách. Không gửi → sale gần nhất của khách
mark_as_success1 = đơn thành công ngay (bỏ qua mục 7.3)
Response:
{ "success": true, "data": {
  "id": 23284, "code": "UP23284", "link_erp": "https://…/admin/order/23284/show",
  "external_source": "web", "external_ref": "WEB-ORD-10023",
  "items": [{ "id": 51201, "type_of_service_id": 1 }],
  "hold_info": { "keep_at": "2026-11-13 15:30:00", "keep_rule": 24 }
}}
hold_info.keep_at là hạn giữ chỗ do Tourwell tính theo lịch khởi hành (chỉ có khi lịch bật giữ chỗ).
Thêm hành khách (tuỳ chọn): POST /orders/{id}/passengers · link.

7. Thanh toán và chốt đơn (mức 3)#

Đã có trang hướng dẫn thanh toán trực tuyến riêng: qua Website · qua Website + cổng thanh toán. Mục này tóm tắt các bước API.

7.1 Tạo phiếu thu#

Mỗi lần khách trả tiền = 1 phiếu thu. Phiếu mới ở trạng thái chờ duyệt, chưa cộng tiền vào đơn.
POST /billings/receipts · Create receipt
{
  "external_source": "web",
  "external_ref": "TXN-889912",
  "payment_method_id": 3,
  "total_amount": 14990000,
  "payment_date": "12/11/2026 19:30",
  "payer_name": "Nguyễn Văn A",
  "gateway_txn_id": "VNPAY-123456",
  "description": "Thu cọc đơn WEB-ORD-10023",
  "allocations": [
    { "ref_type": "order", "ref_id": 23284, "amount": 14990000 }
  ]
}
TrườngBắt buộcGhi chú
payment_method_id✔Tài khoản / quỹ nhận tiền
total_amount✔
allocations[]✔ref_type = "order", ref_id = id đơn. Tổng amount ≤ total_amount
external_source, external_ref✔ (Q1)Nên dùng mã giao dịch của bạn
gateway_txn_idMã giao dịch cổng thanh toán, lưu vào ô Mã tham chiếu
currency, exchange_rateMặc định vnd. Ngoại tệ phải gửi tỷ giá
Response trả id, code, approve_status: 0 và mã QR chuyển khoản (qrcode_base64, transaction_note) nếu tài khoản nhận tiền có đủ thông tin ngân hàng.

7.2 Duyệt phiếu thu (tiền đã về)#

POST /billings/receipts/{id}/confirm-success · Confirm Receipt Success
{ "approve_at": "12/11/2026 19:35", "approve_note": "Cổng thanh toán báo thành công" }
Gọi lại phiếu đã duyệt → 200, không cộng tiền lần hai. Phiếu đã huỷ → 409.
Kiểm tra đơn đã trả đủ: GET /orders/{id} (link), so total_remaining.base <= 0.

7.3 Chốt đơn#

POST /orders/{id}/status · Change order status
{ "status": 1 }
1 = Thành công, 0 = về Đang xử lý. Đơn đã ở trạng thái đó → 400, coi như xong. Doanh nghiệp bật "phải có tiền mới chốt" → duyệt phiếu thu trước.

8. Huỷ (mức 4)#

Thứ tự:
1.
Phiếu thu chờ duyệt → huỷ phiếu.
2.
Đơn đã có phiếu đã duyệt (khách đã trả tiền) → huỷ phiếu nếu đã hoàn tiền cho khách; nếu chưa, chuyển cho nhân viên doanh nghiệp xử lý.
3.
Huỷ đơn.
Huỷ phiếu thu: POST /billings/receipts/{id}/cancel · Cancel receipt
{ "reason": "Khách huỷ đơn" }
Phiếu đã duyệt bị huỷ → Tourwell tự trừ lại tiền đã thu của đơn. Gọi lại an toàn.
Huỷ đơn: POST /orders/{id}/cancel · Cancel order
{ "reason_id": 3, "cancel_note": "Hết hạn giữ chỗ" }
Chỉ gọi một lần. Không chắc thì đọc GET /orders/{id}: status_code = 2 là đã huỷ.

9. Mã lỗi#

HTTPNghĩaXử lý
200 / 201Thành công (200 + duplicated = bản ghi đã có)Lưu id
400Sai trạng tháiĐọc message; nhiều trường hợp coi như xong
401Sai tokenDừng, báo doanh nghiệp
404Không tìm thấy idKhông thử lại
409Phiếu đã huỷ (khi duyệt) · cùng external_ref đang xử lý (khi tạo)Duyệt: không thử lại. Tạo: đợi vài giây rồi gửi lại
415Thiếu Content-Type: application/jsonSửa header
422Dữ liệu không hợp lệSửa theo message / errors, không gửi lại nguyên trạng
429Vượt 60 request/phútĐợi theo Retry-After
5xx / timeoutLỗi máy chủ hoặc mạngGửi lại nguyên request (cùng external_ref)

10. Gợi ý xử lý hàng đợi#

Đẩy qua hàng đợi (queue / outbox) thay vì gọi thẳng lúc người dùng thao tác, để mất mạng hay Tourwell bảo trì không làm mất dữ liệu.
mỗi phút, lấy ≤ 30 việc theo thứ tự tạo:
  "tạo" mà bản ghi đã có tourwell_id     → bỏ qua
  phụ thuộc bản ghi chưa có tourwell_id  → để lượt sau (vd phiếu thu của đơn chưa lên)
  gọi API:
    2xx         → lưu tourwell_id, đánh dấu xong
    429         → dừng lượt, đợi Retry-After
    409 (tạo)   → để lượt sau
    4xx khác    → đánh dấu lỗi, lưu message, báo người phụ trách
    5xx/timeout → thử lại lượt sau với nguyên request (cùng external_ref)
Thứ tự phụ thuộc: lead / đơn → phiếu thu → duyệt → chốt. Huỷ đi ngược lại: huỷ phiếu → huỷ đơn.

11. Danh sách API#

MứcViệcMethodĐường dẫnTài liệu
1Danh mụcGETxem mục 4
1Tạo leadPOST/leadslink
1Tìm lead (cả theo external_ref)GET/leads?…link
1Xem / sửa leadGET / PUT/leads/{id}xem · sửa
1Tạo khách / doanh nghiệp (tuỳ chọn, tạo lead/đơn đã tự tạo khách)POST/customers · /companiesKH · DN
2Tạo đơn tourPOST/orders/tourslink
2Tạo đơn khách sạnPOST/orders/hotelslink
2Tạo đơn 1 sản phẩmPOST/orders/productslink
2Tạo đơn nhiều dịch vụPOST/orderslink
2Thêm hành kháchPOST/orders/{id}/passengerslink
2Xem đơnGET/orders/{id}link
2Tìm đơn (cả theo external_ref)GET/orders?…link
3Tạo phiếu thuPOST/billings/receiptslink
3Sửa phiếu thu (chưa duyệt)PUT/billings/receipts/{id}link
3Tìm phiếu thu (cả theo external_ref)GET/billings/receipts?…link
3Duyệt phiếu thuPOST/billings/receipts/{id}/confirm-successlink
3Chốt / mở lại đơnPOST/orders/{id}/statuslink
4Huỷ phiếu thuPOST/billings/receipts/{id}/cancellink
4Huỷ đơnPOST/orders/{id}/cancellink

Modified at 2026-11-17 03:38:00
Previous
Kết nối hệ thống báo giá, chốt đơn nội bộ với Tourwell
Next
Hướng dẫn kết nối
Built with