Vntix API v1

GET /api/v1/products

Lấy danh sách sản phẩm.

Request mẫu

GET /api/v1/products?page=1&page_size=10&date=2026-05-01&get_packages=1 HTTP/1.1
Host: dev.vntix.vn
Authorization: Bearer your_partner_token

Tham số query

Param	Bắt buộc	Mô tả
page	Không	Mặc định 1
page_size	Không	Mặc định 20, tối đa 100
date	Không	Y-m-d, dùng cho logic giá nội bộ
get_packages	Không	1/true/yes/on sẽ nhúng packages

Response thành công mẫu

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "title": "Vé tham quan mẫu",
      "description": "Mô tả ngắn",
      "currency": "VND",
      "provider": "sun",
      "updated_at": 1760000000,
      "packages": [
        {
          "id": 1,
          "title": "Gói tiêu chuẩn",
          "description": "",
          "include": "",
          "exclude": "",
          "terms_service": "",
          "status": 1,
          "prices": []
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 10,
    "total": 1,
    "has_more": false,
    "with_packages": true,
    "request_id": "abc123",
    "partner_id": 5
  }
}

Mô tả trường response

Trường	Kiểu	Mô tả
success	boolean	Luôn là true khi thành công.
data[]	array	Danh sách sản phẩm theo trang hiện tại.
data[].id	integer	ID sản phẩm (product_id).
data[].title	string	Tên sản phẩm.
data[].description	string	Mô tả ngắn sản phẩm.
data[].currency	string	Đơn vị tiền tệ, hiện tại là VND.
data[].provider	string	Nhà cung cấp vé nội bộ (ví dụ: sun).
data[].updated_at	integer	Unix timestamp cập nhật gần nhất.
data[].packages	array	Chỉ có khi gọi với get_packages=true.
meta.page	integer	Trang hiện tại.
meta.page_size	integer	Số bản ghi trên mỗi trang.
meta.total	integer	Tổng số sản phẩm thỏa điều kiện.
meta.has_more	boolean	Còn dữ liệu trang sau hay không.
meta.with_packages	boolean	Xác nhận response có nhúng package.
meta.request_id	string	Mã request để tra soát log.
meta.partner_id	integer	ID partner đang gọi API.

GET /api/v1/products/{productId}/packages

Lấy package + price của 1 product.

Request mẫu

GET /api/v1/products/12345/packages HTTP/1.1
Host: dev.vntix.vn
Authorization: Bearer your_partner_token

Response thành công mẫu

{
  "success": true,
  "data": {
    "product": {
      "id": 12345,
      "title": "Vé tham quan mẫu"
    },
    "packages": [
      {
        "id": 1,
        "title": "Gói tiêu chuẩn",
        "description": "",
        "include": "",
        "exclude": "",
        "terms_service": "",
        "status": 1,
        "prices": []
      }
    ]
  },
  "meta": {
    "request_id": "abc123",
    "partner_id": 5
  }
}

Mô tả trường response

Trường	Kiểu	Mô tả
success	boolean	Luôn là true khi thành công.
data.product.id	integer	ID sản phẩm.
data.product.title	string	Tên sản phẩm.
data.packages[]	array	Danh sách package của sản phẩm.
data.packages[].id	integer	ID package nội bộ.
data.packages[].title	string	Tên package.
data.packages[].description/include/exclude/terms_service	string	Thông tin mô tả package.
data.packages[].status	integer	Trạng thái package.
data.packages[].prices[]	array	Các khoảng giá và price rule tương ứng.
meta.request_id	string	Mã request để tra soát log.
meta.partner_id	integer	ID partner đang gọi API.

GET /api/v1/products/{productId}

Lấy chi tiết 1 sản phẩm theo productId, luôn bao gồm dữ liệu packages.

Request mẫu

GET /api/v1/products/12345 HTTP/1.1
Host: dev.vntix.vn
Authorization: Bearer your_partner_token

Response thành công mẫu

{
  "success": true,
  "data": {
    "id": 12345,
    "title": "Vé tham quan mẫu",
    "description": "Mô tả ngắn",
    "currency": "VND",
    "provider": "sun",
    "updated_at": 1760000000,
    "packages": [
      {
        "id": 1,
        "title": "Gói tiêu chuẩn",
        "description": "",
        "include": "",
        "exclude": "",
        "terms_service": "",
        "status": 1,
        "prices": []
      }
    ]
  },
  "meta": {
    "request_id": "abc123",
    "partner_id": 5
  }
}

Mô tả trường response

Trường	Kiểu	Mô tả
success	boolean	Luôn là true khi thành công.
data.id	integer	ID sản phẩm.
data.title	string	Tên sản phẩm.
data.description	string	Mô tả ngắn sản phẩm.
data.currency	string	Đơn vị tiền tệ, hiện tại là VND.
data.provider	string	Nhà cung cấp vé.
data.updated_at	integer	Unix timestamp cập nhật gần nhất.
data.packages[]	array	Danh sách package và thông tin giá.
meta.request_id	string	Mã request để tra soát log.
meta.partner_id	integer	ID partner đang gọi API.

POST /api/v1/booking/create

Tạo booking giữ chỗ, chưa issue, chưa paid.

Request mẫu

POST /api/v1/booking/create HTTP/1.1
Host: dev.vntix.vn
Authorization: Bearer your_partner_token
Content-Type: application/json

{
  "product_id": 12345,
  "package_id": 1,
  "date": "2026-05-01",
  "lines": [
    { "price_rule_id": 111, "quantity": 2 }
  ],
  "contact": {
    "full_name": "Nguyen Van A",
    "tel": "0909123456",
    "email": "a@example.com",
    "address": "HCM"
  },
  "idempotency_key": "partner-ord-2026-001",
  "partner_order_code": "PARTNER-001",
  "note": "Ghi chú"
}

Response thành công mẫu (201)

{
  "success": true,
  "data": {
    "code": "VT123456",
    "date": "2026-05-01",
    "status": 1,
    "issue": 0,
    "provider": "sun",
    "total_price": 900000,
    "paid": 0,
    "customers": [
      { "price_rule_id": 111, "quantity": 2, "price": 450000, "discount": 0 }
    ],
    "tickets": []
  },
  "meta": {
    "request_id": "abc123",
    "partner_id": 5
  }
}

Mô tả trường response

Trường	Kiểu	Mô tả
success	boolean	Luôn là true khi tạo thành công.
data.code	string	Mã booking (vd: VT123456).
data.date	string	Ngày sử dụng (Y-m-d).
data.status	integer	Trạng thái đơn (create API mặc định giữ chỗ).
data.issue	integer	Trạng thái xuất vé (0: chưa, 1: đã).
data.provider	string	Nhà cung cấp vé.
data.total_price	number	Tổng tiền hệ thống tính theo lines.
data.paid	number	Số tiền đã ghi nhận thanh toán tại thời điểm trả về.
data.customers[]	array	Danh sách dòng khách tương ứng với lines.
data.tickets[]	array	Thông tin vé (thường rỗng khi vừa tạo booking).
meta.request_id	string	Mã request để tra soát log.
meta.partner_id	integer	ID partner đang gọi API.

GET /api/v1/bookings/{bookingCode}

Lấy chi tiết booking.

Request mẫu

GET /api/v1/bookings/VT123456 HTTP/1.1
Host: dev.vntix.vn
Authorization: Bearer your_partner_token

Response thành công mẫu

{
  "success": true,
  "data": {
    "code": "VT123456",
    "date": "2026-05-01",
    "status": 1,
    "issue": 0,
    "provider": "sun",
    "total_price": 900000,
    "paid": 0,
    "customers": [
      { "price_rule_id": 111, "quantity": 2, "price": 450000, "discount": 0 }
    ],
    "tickets": []
  },
  "meta": {
    "request_id": "abc123",
    "partner_id": 5
  }
}

Mô tả trường response

Trường	Kiểu	Mô tả
success	boolean	Luôn là true khi lấy chi tiết thành công.
data.code	string	Mã booking.
data.date	string	Ngày sử dụng.
data.status	integer	Trạng thái đơn hiện tại.
data.issue	integer	Trạng thái xuất vé.
data.provider	string	Nhà cung cấp vé.
data.total_price	number	Tổng tiền booking.
data.paid	number	Số tiền đã thanh toán ghi nhận.
data.customers[]	array	Danh sách dòng khách của booking.
data.tickets[]	array	Danh sách vé (nếu đã issue).
meta.request_id	string	Mã request để tra soát log.
meta.partner_id	integer	ID partner đang gọi API.

POST /api/v1/bookings/{bookingCode}/issue

Issue vé. Nếu booking thuộc api_partner, hệ thống sẽ debit ví trước khi issue.

Request mẫu

POST /api/v1/bookings/VT123456/issue HTTP/1.1
Host: dev.vntix.vn
Authorization: Bearer your_partner_token
Content-Type: application/json

{}

Luồng xử lý tóm tắt

• Check booking tồn tại, thuộc partner, chưa issue.
• Check ví và số dư khả dụng (balance + credit_limit).
• Debit ví reference booking_debit.
• Cập nhật booking sang status=2, paid=total_price.
• Gọi hàm issue nội bộ.
• Nếu issue fail sau debit: credit refund booking_issue_refund.

Response thành công mẫu

{
  "success": true,
  "data": {
    "code": "VT123456",
    "date": "2026-05-01",
    "status": 2,
    "issue": 1,
    "provider": "sun",
    "total_price": 900000,
    "paid": 900000,
    "customers": [
      { "price_rule_id": 111, "quantity": 2, "price": 450000, "discount": 0 }
    ],
    "tickets": [
      {
        "code": "TICKET001"
      }
    ]
  },
  "meta": {
    "request_id": "abc123",
    "partner_id": 5
  }
}

Mô tả trường response

Trường	Kiểu	Mô tả
success	boolean	Luôn là true khi xuất vé thành công.
data.code	string	Mã booking.
data.status	integer	Trạng thái sau xuất vé (thường là đã thanh toán/hoàn tất).
data.issue	integer	Trạng thái xuất vé (1 = đã xuất).
data.paid	number	Số tiền đã ghi nhận sau khi issue.
data.total_price	number	Tổng tiền booking.
data.customers[]	array	Danh sách dòng khách.
data.tickets[]	array	Danh sách mã vé đã xuất.
meta.request_id	string	Mã request để tra soát log.
meta.partner_id	integer	ID partner đang gọi API.

GET /api/v1/wallet/balance

Kiểm tra số dư ví hiện tại của partner.

Request mẫu

GET /api/v1/wallet/balance HTTP/1.1
Host: dev.vntix.vn
Authorization: Bearer your_partner_token

Response thành công mẫu

{
  "success": true,
  "data": {
    "partner_id": 5,
    "wallet_id": 12,
    "status": "active",
    "balance": 2000000,
    "credit_limit": 500000,
    "available": 2500000
  },
  "meta": {
    "request_id": "abc123",
    "partner_id": 5
  }
}

Mô tả trường response

Trường	Kiểu	Mô tả
success	boolean	Luôn là true khi lấy ví thành công.
data.partner_id	integer	ID partner sở hữu ví.
data.wallet_id	integer	ID ví nội bộ.
data.status	string	Trạng thái ví (active, suspended...).
data.balance	number	Số dư hiện tại của ví.
data.credit_limit	number	Hạn mức tín dụng bổ sung.
data.available	number	Số dư khả dụng = balance + credit_limit.
meta.request_id	string	Mã request để tra soát log.
meta.partner_id	integer	ID partner đang gọi API.