Đơn hàng cửa hàng

Liệt kê cửa hàng bán hàng Đọc

POST/2.0/api/shop-list-workspaces

Liệt kê các cửa hàng bán hàng (workspace) mà chủ token đang là nhân viên Active, kèm vai trò. Gọi đầu tiên để lấy workspace_id truyền cho các API shop-* khác.

Tham số

Không có tham số. Gửi body {}.

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-list-workspaces \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "total": 2,
    "items": [
      {
        "workspace_id": "152034",
        "name": "Thời Trang An Nhiên",
        "role": "OWNER",
        "is_owner": true
      },
      {
        "workspace_id": "167820",
        "name": "Mỹ Phẩm Hoa Sen",
        "role": "STAFF",
        "is_owner": false
      }
    ]
  }
}

role là OWNER, MANAGER hoặc STAFF; workspace_id là chuỗi số.

Lưu ý

• Workspace là tài khoản bán hàng: đơn hàng, sản phẩm, khách hàng, phiếu giao hàng đều thuộc một workspace. Khác với storefront (trang cửa hàng online) trả về từ shop-list-stores.
• workspace_id trùng với trường ladisales_store_id của account-list-workspaces. Không dùng store_id của LadiPage cho các API shop-*.
• Trả tối đa 50 workspace, không phân trang.
• Chỉ đọc.

Liệt kê trang cửa hàng online Đọc

POST/2.0/api/shop-list-stores

Liệt kê các trang cửa hàng online (storefront) của một workspace, kèm URL công khai. Dùng khi cần biết đơn hàng đến từ cửa hàng online nào.

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-list-stores \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": "152034",
  "keyword": "thoi trang"
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "total": 1,
    "page": 1,
    "items": [
      {
        "storefront_id": 48213,
        "name": "Thời Trang An Nhiên",
        "active": true,
        "url": "https://thoitrangannhien.ladi.me",
        "updated_at": "2026-10-21T14:32:10+07:00"
      }
    ]
  }
}

active = true khi cửa hàng đang bật; url là địa chỉ đã xuất bản (rỗng nếu chưa xuất bản).

Lưu ý

• Sắp xếp mới tạo trước.
• Tên trường items[].store của shop-list-orders là tên storefront này.
• Chỉ đọc.

Liệt kê đơn hàng Đọc

POST/2.0/api/shop-list-orders

Liệt kê đơn hàng của cửa hàng, mới nhất trước, lọc theo nhóm trạng thái, từ khoá và khoảng ngày tạo. Email và số điện thoại khách bị che; xem đầy đủ bằng shop-get-order.

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-list-orders \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "filter": "PAYMENT_PENDING",
  "from_date": "2026-10-01",
  "to_date": "2026-10-31",
  "page": 1,
  "limit": 50
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "total": 2,
    "page": 1,
    "items": [
      {
        "order_id": 1048576,
        "reference_no": "100235",
        "status": "Open",
        "is_draft": false,
        "payment_status": "Pending",
        "shipping_status": "Delivering",
        "total": 890000,
        "created_at": "2026-10-27T09:15:42+07:00",
        "customer": "Nguyễn Văn An",
        "customer_phone": "******5678",
        "customer_email": "an***@example.com",
        "payment_method": "COD",
        "store": "Thời Trang An Nhiên",
        "tags": [
          {
            "tag_id": 3127,
            "name": "Khách VIP"
          }
        ]
      },
      {
        "order_id": 1048571,
        "reference_no": "100234",
        "status": "Open",
        "is_draft": true,
        "payment_status": "Pending",
        "shipping_status": null,
        "total": 450000,
        "created_at": "2026-10-26T16:03:18+07:00",
        "customer": "Trần Thị Bình",
        "customer_phone": "******4321",
        "customer_email": "bi***@gmail.com",
        "payment_method": "BANK",
        "store": "Thời Trang An Nhiên",
        "tags": []
      }
    ]
  }
}

status: Open | Canceled; payment_status: Pending | Success | Canceled | Refund; shipping_status: Pending | ReadyToPick | Delivering | DeliveredToPostMan | Delivered | Returning | Returned | Canceled (null với đơn nháp). customer_phone, customer_email đã bị che.

Lưu ý

• Phân trang bằng page + limit; total là tổng số đơn khớp bộ lọc.
• Chỉ lọc được theo các tham số trên. Không có bộ lọc theo phương thức thanh toán, nguồn đơn, kênh, tag hay nhân viên phụ trách.
• Nhân viên vai trò STAFF chỉ thấy đơn do mình tạo, đơn được giao cho mình hoặc đơn chưa có người phụ trách. OWNER và MANAGER thấy mọi đơn.
• Đơn vượt hạn mức đơn của gói vẫn hiện trong danh sách nhưng tên và thông tin liên hệ khách bị che.
• Chỉ đọc.

Xem chi tiết đơn hàng Đọc

POST/2.0/api/shop-get-order

Lấy đầy đủ một đơn hàng theo order_id hoặc mã đơn hiển thị cho khách (reference_no): khách hàng, địa chỉ giao, sản phẩm, thanh toán, phiếu giao hàng, tag, ghi chú.

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-get-order \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "reference_no": "100235"
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "order_id": 1048576,
    "reference_no": "100235",
    "status": "Open",
    "is_draft": false,
    "payment_status": "Success",
    "shipping_status": "Delivering",
    "total": 890000,
    "created_at": "2026-10-27T09:15:42+07:00",
    "customer": {
      "customer_id": 7300512,
      "name": "Nguyễn Văn An",
      "email": "an.nguyen@example.com",
      "phone": "0912345678"
    },
    "shipping_address": {
      "name": "Nguyễn Văn An",
      "phone": "0912345678",
      "address": "12 Nguyễn Trãi, Phường Bến Thành, Quận 1, TP. Hồ Chí Minh"
    },
    "items": [
      {
        "product_id": 250417,
        "variant_id": 610882,
        "name": "Áo sơ mi linen - Trắng / M",
        "price": 420000,
        "quantity": 2,
        "total": 840000
      }
    ],
    "sub_total": 840000,
    "shipping_fee": 30000,
    "discount_fee": 0,
    "paid": 890000,
    "payment_method": "BANK",
    "shipments": [
      {
        "shipment_id": 562301,
        "status": "Delivering",
        "tracking_number": "GHN8XK29Q1"
      }
    ],
    "tags": [
      {
        "tag_id": 3127,
        "name": "Khách VIP"
      }
    ],
    "note": "Khách hẹn giao sau 17h"
  }
}

paid = số tiền đã thu trừ phần đã hoàn.

Lưu ý

• Email, số điện thoại khách hiện đầy đủ (không che như shop-list-orders).
• items[].name là tên lưu trên dòng đơn (kèm phiên bản), vẫn còn khi sản phẩm đã bị xoá.
• Nhân viên vai trò STAFF chỉ xem được đơn do mình tạo, đơn được giao cho mình hoặc đơn chưa có người phụ trách; đơn khác trả lỗi không tìm thấy.
• Đơn bị ẩn do vượt hạn mức đơn của gói trả lỗi kèm thông báo nâng gói.
• Chỉ đọc.

Liệt kê tag đơn hàng Đọc

POST/2.0/api/shop-list-order-tags

Liệt kê toàn bộ tag đơn hàng của cửa hàng kèm số đơn đang gắn. Dùng để lấy tag_id cho shop-update-order-tags.

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-list-order-tags \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": "152034"
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "items": [
      {
        "tag_id": 3127,
        "name": "Khách VIP",
        "order_count": 42
      },
      {
        "tag_id": 3098,
        "name": "Giao gấp",
        "order_count": 15
      }
    ]
  }
}

Tag mới tạo đứng trước.

Lưu ý

• Trả toàn bộ tag, không phân trang.
• Không có API tạo tag mới; tạo tag trên trang quản trị đơn hàng.
• Chỉ đọc.

Liệt kê đơn chưa hoàn tất Đọc

POST/2.0/api/shop-list-incomplete-orders

Liệt kê đơn chưa hoàn tất (khách đã điền thông tin ở trang thanh toán nhưng chưa đặt xong), mới nhất trước. Dùng để chăm sóc lại khách bỏ giỏ.

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-list-incomplete-orders \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "keyword": "0912",
  "page": 1,
  "limit": 20
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "total": 1,
    "page": 1,
    "items": [
      {
        "checkout_id": 883417,
        "created_at": "2026-10-28T20:47:05+07:00",
        "customer": "Lê Minh Châu",
        "customer_phone": "******9012",
        "customer_email": "ch***@gmail.com",
        "total": 650000,
        "reminder_email_sent": false
      }
    ]
  }
}

customer_phone, customer_email đã bị che; reminder_email_sent = true khi đã gửi email nhắc khách.

Lưu ý

• Chỉ gồm đơn chưa thanh toán và đã có thông tin khách. Khi đơn liên quan được đánh dấu đã thanh toán (shop-mark-order-paid), đơn chưa hoàn tất tương ứng bị xoá khỏi danh sách.
• Không có bộ lọc ngày và không có API xem chi tiết một đơn chưa hoàn tất.
• Chỉ đọc.

Tạo đơn hàng Tạo

POST/2.0/api/shop-create-order

Tạo đơn hàng cho một khách (tìm theo số điện thoại hoặc email, chưa có thì tạo khách mới). Giá lấy từ sản phẩm, trừ tồn kho ngay, không gửi email cho khách.

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-create-order \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_name": "Nguyễn Văn An",
  "customer_phone": "0912345678",
  "address": "12 Lý Thường Kiệt, Phường Hàng Bài, Quận Hoàn Kiếm, Hà Nội",
  "items": [
    {
      "variant_id": 884213,
      "quantity": 2
    }
  ],
  "payment_method": "COD",
  "shipping_fee": 30000
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "status": "created",
    "order_id": 1048580,
    "reference_no": "100236",
    "total": 870000,
    "reached_plan_limit": true
  }
}

reached_plan_limit chỉ có (= true) khi cửa hàng đã vượt hạn mức đơn của gói.

Lưu ý

• Chạy ngay, không có bước xem trước. Gọi lại với cùng nội dung sẽ tạo thêm một đơn trùng. Không có API xoá đơn; muốn bỏ đơn thì dùng shop-cancel-order.
• Khách hàng: API tìm khách trong cửa hàng có cùng số điện thoại HOẶC email. Tìm thấy thì gắn đơn vào khách đó và giữ nguyên tên, email, số điện thoại đã lưu (tên khách trên đơn là tên đã lưu, customer_name chỉ dùng cho người nhận). Không thấy thì tạo khách mới; việc này gửi webhook tạo khách hàng (nếu cửa hàng đã cấu hình) và đồng bộ khách sang LadiWork theo cấu hình kết nối của cửa hàng.
• Giá: lấy theo giá hiện tại của từng biến thể. Không truyền được giá riêng, mã giảm giá, thuế, tag hay trường tuỳ chỉnh. Tổng đơn = tổng tiền hàng + shipping_fee. Tổng bằng 0 thì đơn tự thành đã thanh toán (COD).
• Tồn kho: trừ ngay khi tạo, kể cả đơn chưa thanh toán. Biến thể có theo dõi tồn kho và không cho bán khi hết hàng mà không đủ số lượng thì API báo lỗi, đơn không được tạo. Sản phẩm sự kiện, dịch vụ hết suất cũng báo lỗi.
• Thông báo: không gửi email cho khách. Đơn được phân công nhân viên theo quy tắc phân công tự động của cửa hàng; nhân viên được phân công nhận email thông báo. Webhook tạo đơn của cửa hàng (nếu có) được gửi; paid = true thì gửi thêm webhook thanh toán thành công, đồng thời tạo vé (sản phẩm sự kiện) và mở quyền học (sản phẩm khoá học).
• Đơn được tạo ở trạng thái Open, không phải đơn nháp, trạng thái giao hàng Pending, không gắn với storefront nào.
• Hạn mức gói: đơn tính vào hạn mức đơn của gói. Khi đã vượt hạn mức, đơn vẫn được tạo (và vẫn trừ tồn kho) nhưng bị ẩn, shop-get-order trả lỗi cho tới khi nâng gói.
• Lấy variant_id: trong trang quản lý sản phẩm, hoặc từ items[].variant_id của một đơn cũ qua shop-get-order.
• Quyền: theo vai trò và nhóm quyền của chủ token trong cửa hàng, giống thao tác trên trang quản trị.

Sửa ghi chú đơn hàng Cập nhật

POST/2.0/api/shop-update-order-note

Thay toàn bộ ghi chú nội bộ của một đơn đang mở (khách không thấy ghi chú này).

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-update-order-note \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": 1048576,
  "note": "Khách hẹn giao sau 17h"
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "status": "saved",
    "order_id": 1048576
  }
}

Lưu ý

• Chỉ áp dụng cho đơn đang mở (status Open). Đơn đã huỷ trả lỗi không tồn tại.
• Muốn thêm vào ghi chú cũ thì đọc note từ shop-get-order rồi gửi lại cả đoạn.
• Tác dụng phụ: ghi lịch sử đơn khi ghi chú thay đổi; đơn chưa có người phụ trách sẽ được giao cho chủ token; gửi webhook cập nhật đơn của cửa hàng (nếu có). Tag và trường tuỳ chỉnh của đơn giữ nguyên.

Gắn hoặc gỡ tag đơn hàng Cập nhật

POST/2.0/api/shop-update-order-tags

Gắn thêm và/hoặc gỡ tag khỏi một đơn hàng theo tag_id. Tag phải có sẵn trong cửa hàng (shop-list-order-tags).

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-update-order-tags \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": 1048576,
  "add_tag_ids": [
    3127
  ],
  "untag_ids": [
    3098
  ]
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "status": "saved",
    "order_id": 1048576,
    "added": ["Khách VIP"],
    "taken_off": ["Giao gấp"]
  }
}

added và taken_off là danh sách tên tag đã gắn và đã gỡ.

Lưu ý

• Phải gửi ít nhất một trong add_tag_ids, untag_ids.
• Có tag_id không thuộc cửa hàng thì API báo lỗi và không đổi gì.
• Không áp dụng cho đơn đã huỷ.
• Các tag được xử lý lần lượt (gắn trước, gỡ sau); nếu lỗi giữa chừng thì những tag đã xử lý trước đó vẫn được giữ.

Đánh dấu đơn đã thanh toán Cập nhật

POST/2.0/api/shop-mark-order-paid

Đánh dấu một đơn chưa thanh toán là đã thanh toán đủ. Khách nhận email xác nhận thanh toán; tồn kho được trừ nếu lúc tạo đơn chưa trừ.

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-mark-order-paid \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": 1048576,
  "payment_method": "BANK"
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "status": "paid",
    "order_id": 1048576,
    "reference_no": "100235"
  }
}

Lưu ý

• Điều kiện: đơn đang mở (status Open), không phải đơn nháp và payment_status đang là Pending. Không thoả thì API báo lỗi kèm trạng thái hiện tại của đơn.
• Chạy ngay, không có bước xem trước. Không có API đảo ngược (bỏ đánh dấu đã thanh toán).
• Tác dụng phụ: số tiền đã thu = tổng đơn, ghi thời điểm thanh toán; trừ tồn kho nếu chưa trừ; đơn chưa có người phụ trách được giao cho chủ token; LUÔN gửi email xác nhận thanh toán cho khách; gửi webhook thanh toán thành công của cửa hàng (nếu có); tạo vé cho sản phẩm sự kiện, mở quyền học cho sản phẩm khoá học; xoá đơn chưa hoàn tất gắn với đơn này; ghi lịch sử đơn.
• Đơn bị ẩn do vượt hạn mức đơn của gói không đánh dấu được (API báo lỗi như shop-get-order).

Huỷ đơn hàng Cập nhật

POST/2.0/api/shop-cancel-order

Huỷ một đơn chưa giao. Khách nhận email báo huỷ; hàng KHÔNG tự trả về kho.

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-cancel-order \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": 1048576,
  "reason": "Khách đổi ý"
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "status": "canceled",
    "order_id": 1048576,
    "reference_no": "100235"
  }
}

Lưu ý

• Điều kiện: đơn chưa bị huỷ và trạng thái giao hàng còn Pending, Canceled hoặc trống. Đơn đã bắt đầu giao (ReadyToPick, Delivering, Delivered...) không huỷ được qua API.
• Chạy ngay, không có bước xem trước. Không có API mở lại đơn đã huỷ.
• Tồn kho không được hoàn tự động: điều chỉnh tồn kho trên trang quản trị sản phẩm nếu cần.
• Không hoàn tiền: đơn đã thanh toán vẫn giữ payment_status Success sau khi huỷ.
• Tác dụng phụ: LUÔN gửi email báo huỷ cho khách; huỷ vé của sản phẩm sự kiện và thu hồi quyền học của sản phẩm khoá học; gửi webhook huỷ đơn của cửa hàng (nếu có); ghi lịch sử đơn kèm lý do.

Liệt kê phiếu giao hàng Đọc

POST/2.0/api/shop-list-shipments

Liệt kê phiếu giao hàng của cửa hàng, mới nhất trước, kèm trạng thái giao, đơn vị vận chuyển và mã vận đơn.

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-list-shipments \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "Delivering",
  "page": 1,
  "limit": 20
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "total": 1,
    "page": 1,
    "items": [
      {
        "shipment_id": 562301,
        "shipment_no": "SH562301",
        "order_id": 1048576,
        "order_no": "100235",
        "status": "Delivering",
        "carrier": "GHN",
        "tracking_number": "GHN8XK29Q1",
        "cod_status": "Pending",
        "total": 890000,
        "created_at": "2026-10-27T10:02:31+07:00"
      }
    ]
  }
}

cod_status là trạng thái tiền thu hộ: Pending | Paid (đã thu) | Received (đã nhận tiền).

Lưu ý

• Chỉ gồm phiếu giao chính thức, không gồm phiếu nháp.
• Phân trang bằng page + limit.
• Chỉ đọc.

Xem chi tiết phiếu giao hàng Đọc

POST/2.0/api/shop-get-shipment

Lấy một phiếu giao hàng kèm sản phẩm, người nhận, địa chỉ và mã vận đơn.

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-get-shipment \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "shipment_id": 562301
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "shipment_id": 562301,
    "shipment_no": "SH562301",
    "order_id": 1048576,
    "status": "Delivering",
    "carrier": "GHN",
    "tracking_number": "GHN8XK29Q1",
    "cod_status": "Pending",
    "receiver": "Nguyễn Văn An",
    "receiver_phone": "0912345678",
    "address": "12 Nguyễn Trãi, Phường Bến Thành, Quận 1, TP. Hồ Chí Minh",
    "items": [
      {
        "name": "Áo sơ mi linen - Trắng / M",
        "quantity": 2,
        "price": 420000
      }
    ],
    "total": 890000
  }
}

Lưu ý

• Phiếu nháp hoặc không thuộc cửa hàng trả lỗi không tìm thấy.
• Chỉ đọc.

Cập nhật mã vận đơn Cập nhật

POST/2.0/api/shop-update-tracking-number

Ghi mã vận đơn của đơn vị vận chuyển vào một phiếu giao hàng, thay mã cũ nếu có.

Tham số

Ví dụ

curl -X POST https://api.ladipage.net/2.0/api/shop-update-tracking-number \
  -H "api-key: $LADIPAGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "shipment_id": 562301,
  "tracking_number": "GHN8XK29Q1"
}'

Kết quả

{
  "code": 200,
  "message": "Success",
  "data": {
    "status": "saved",
    "shipment_id": 562301,
    "previous": "GHN7PL04B3",
    "tracking_number": "GHN8XK29Q1"
  }
}

previous là mã vận đơn trước khi đổi (rỗng nếu chưa có).

Lưu ý

• Phiếu phải tồn tại và không phải phiếu nháp, nếu không API báo lỗi.
• Chỉ đổi mã vận đơn được lưu: không đổi trạng thái giao, không gửi thông báo cho khách, không gọi sang đơn vị vận chuyển.