Extension point

Extension point (target) là vị trí POS mở sẵn để app gắn vào. Mỗi target quy định: hiển thị ở đâu, kiểu hiển thị nào, module nhận dữ liệu ngữ cảnh gì và phải trả về gì.

#Cách đặt tên

Target gắn với một loại bản ghi của POS có tên dạng <resource>.<vị trí>, ví dụ order.details.action hay purchase.index.selection-action. Các resource dùng chung tên vị trí, nên app viết cho đơn hàng dùng y hệt cho phiếu nhập hay phiếu chuyển kho. Một số vị trí không có ở mọi resource: sản phẩm không có mẫu in (print-action), khách hàng chỉ có box, action và cột (xem customer.*).

#Danh sách target

<resource> là một trong order, product, purchase, export, warehouse_transfer. Sản phẩm không có print-action vì chỉ in mã vạch.

#Quy ước module

Mọi module là một ES module có export default một hàm. Hàm nhận dữ liệu ngữ cảnh (giống pos.data) và có thể là async.

// Extension có giao diện (block, action modal/fullscreen, trang Worker UI): tự render vào document.body
export default async function (data) {
  render(<App data={data} />, document.body);
}

// Extension headless và hook: trả về kết quả theo target
export default async function (data) {
  return { message: 'Đã xong' };
}

#Kiểu dữ liệu dùng chung

Dữ liệu ngữ cảnh có cùng dạng cho mọi resource: data.resource cho biết loại bản ghi, data.record là bản ghi đã lưu (data.records ở thanh thao tác hàng loạt), data.draft là dữ liệu form chi tiết đang hiển thị.

type Resource = 'order' | 'product' | 'purchase' | 'export' | 'warehouse_transfer';

type RefOf<R extends Resource> = {
  order: OrderRef;
  product: ProductRef;
  purchase: PurchaseRef;
  export: ExportRef;
  warehouse_transfer: WarehouseTransferRef;
}[R];

type DraftOf<R extends Resource> = {
  order: OrderDraft;
  product: ProductDraft;
  purchase: PurchaseDraft;
  export: ExportDraft;
  warehouse_transfer: WarehouseTransferDraft;
}[R];

// Form chi tiết: *.details.action, *.details.block, *.before_submit
type DetailsData<R extends Resource> = {
  resource: R;
  mode: 'create' | 'edit';
  record: RefOf<R> | null;   // null khi bản ghi chưa lưu
  draft: DraftOf<R>;         // gồm cả phần chưa lưu
};

// Một dòng của danh sách: *.index.action
type IndexData<R extends Resource> = {
  resource: R;
  record: RefOf<R>;
};

// Thanh thao tác hàng loạt: *.index.selection-action
type SelectionData<R extends Resource> = {
  resource: R;
  records: RefOf<R>[];       // tối đa 500 bản ghi
};

Ví dụ pos.data trong purchase.details.action:

{
  "resource": "purchase",
  "mode": "edit",
  "record": { "id": "7c1d…", "display_id": 318, "custom_id": null, "status": 0, "warehouse_id": "a52f…", "updated_at": "2026-10-06T02:45:00" },
  "draft": { "status": 0, "warehouse_id": "a52f…", "supplier_products_id": "e09b…", "tags": [], "note": null, "items": [{ "variation_id": "41aa…", "quantity": 20, "imported_price": 1850000 }], "total_price": 37000000 }
}

#Mã bản ghi

#Kiểu dữ liệu theo resource

type OrderRef = {
  id: string | number;      // mã đơn hiển thị (mã tuỳ chỉnh nếu shop dùng, ngược lại là mã hệ thống)
  system_id: number;        // mã đơn hệ thống, như trường system_id của đơn trong Open API: /shops/{shop_id}/orders/{system_id}
  status: number;
  updated_at: string;       // ISO 8601
};

type OrderDraft = {
  status: number;
  customer_id: string | null;
  bill_full_name: string | null;
  bill_phone_number: string | null;
  warehouse_id: string | null;
  tags: (number | string)[];
  note: string | null;
  items: {
    variation_id: string;
    product_id: string;
    quantity: number;
    price: number;          // đơn giá sau giảm giá dòng
  }[];
  total_price: number;
};

type ProductRef = {
  id: string;               // UUID: /shops/{shop_id}/products/{id}
  display_id: number;
  custom_id: string | null; // mã sản phẩm
  name: string;
  is_hide: boolean;
  updated_at: string;
};

type ProductDraft = {
  name: string;
  custom_id: string | null;
  category_ids: number[];
  brand_id: number | null;
  tags: (number | string)[];
  variations: {
    id: string | null;      // null với mẫu mã chưa lưu
    custom_id: string | null;
    barcode: string | null;
    retail_price: number;
  }[];
};

type PurchaseRef = {
  id: string;               // UUID: /shops/{shop_id}/purchases/{id}
  display_id: number;
  custom_id: string | null;
  status: number;
  warehouse_id: string;
  updated_at: string;
};

type PurchaseDraft = {
  status: number;
  warehouse_id: string | null;
  supplier_products_id: string | null;   // nhà cung cấp
  tags: (number | string)[];
  note: string | null;
  items: {
    variation_id: string;
    quantity: number;
    imported_price: number;
  }[];
  total_price: number;
};

type ExportRef = {
  id: string;               // UUID: /shops/{shop_id}/export/{id}
  display_id: number;
  custom_id: string | null;
  status: number;
  type: number;             // loại phiếu xuất theo Open API (xuất thường, xuất hàng lỗi…)
  warehouse_id: string;
  updated_at: string;
};

type ExportDraft = {
  status: number;
  type: number;
  warehouse_id: string | null;
  tags: (number | string)[];
  note: string | null;
  export_items: {
    variation_id: string;
    quantity: number;
  }[];
};

type WarehouseTransferRef = {
  id: string;               // UUID: /shops/{shop_id}/transfers/{id}
  display_id: number;
  custom_id: string | null;
  status: number;
  from_warehouse_id: string;
  to_warehouse_id: string;
  updated_status_at: string;
};

type WarehouseTransferDraft = {
  status: number;
  from_warehouse_id: string | null;
  to_warehouse_id: string | null;
  note: string | null;
  items: {
    variation_id: string;
    quantity: number;
  }[];
};

• Tên trường và mã trạng thái theo Open API. Trường người dùng không được xem (ví dụ giá nhập khi không có quyền tương ứng) bị bỏ ra; trường nằm trong access.hidden_order_fields bị bỏ khỏi OrderDraft (giá trị thành undefined).
• Dữ liệu ngữ cảnh chỉ gồm các trường tối thiểu. Cần thêm thì gọi Open API bằng pos.api (xem Runtime API).
• Nếu bản ghi không thoả giới hạn access của app (kho, danh mục sản phẩm, nguồn đơn…), POS không hiển thị extension cho bản ghi đó.

#nav.item

Thêm mục vào menu chính, mở một trang app.page.

Không có module. Mục chỉ hiện với người được thấy app (mặc định mọi thành viên của shop, xem Vòng đời app).

#app.page

Trang riêng của app.

Dữ liệu ngữ cảnh:

type PageData = {
  path: string;                     // phần sau /apps/<handle>, ví dụ "/returns"
  query: Record<string, string>;    // query string của URL POS
};

• Trang iframe: URL đồng bộ hai chiều; app đổi route bên trong thì URL của POS đổi theo, nên tải lại trang, nút quay lại và chia sẻ link đều đúng. Trang kết nối với POS qua SDK, xem Runtime API › Trang iframe.
• Trang Worker UI: worker không có history. Đổi đường dẫn bằng pos.navigate({ page, path, query }); POS cập nhật URL rồi phát data-change với path, query mới, không tạo lại worker. Nút quay lại của trình duyệt cũng phát data-change.
• Trang Worker UI dựng bằng pos-page, pos-filter-bar, pos-stat, pos-chart, pos-tabs, pos-table cùng các element khác theo Màn hình chuẩn (xem Component). Tiêu đề và nút chính trên thanh tiêu đề của POS đặt qua pos.page như trang iframe (xem Runtime API › Trang Worker UI).

import { render } from 'preact';
import { useEffect, useState } from 'preact/hooks';

function Report() {
  const [tab, setTab] = useState(pos.data.query.tab || 'day');
  useEffect(() => pos.on('data-change', (data) => setTab(data.query.tab || 'day')), []);
  return (
    <pos-page heading="Doanh thu" width="full">
      <pos-tabs tabs={[{ id: 'day', label: 'Theo ngày' }, { id: 'source', label: 'Theo nguồn' }]} selected={tab} onChange={(e) => pos.navigate({ page: 'report', query: { tab: e.detail } })}>
        <pos-chart type={tab == 'day' ? 'line' : 'pie'} xKey="label" data={[{ label: '01/10', revenue: 12500000 }]} series={[{ key: 'revenue', label: 'Doanh thu', format: 'money' }]} />
      </pos-tabs>
    </pos-page>
  );
}

export default function () {
  pos.page?.setTitle('Báo cáo doanh thu');
  render(<Report />, document.body);
}

#*.details.action

Thêm mục vào menu thao tác của form chi tiết. Các mục của app nằm trong nhóm "Ứng dụng" ở cuối menu, theo thứ tự khai báo.

Dữ liệu ngữ cảnh: DetailsData<R>.

Với đơn hàng, mục của app không hiện khi menu đang ở chế độ chỉ in hoặc bị ẩn thao tác.

#Kiểu action

Với headless:

• Trả về message thì POS hiện toast thành công với nội dung đó.
• Ném lỗi (throw new Error('...')) thì POS hiện toast lỗi với error.message.
• refresh mặc định true: POS tải lại bản ghi sau khi chạy xong.
• Thời gian chạy tối đa 30 giây; quá thời gian thì worker bị dừng và báo lỗi.

Các video dưới đây dùng đơn hàng; resource khác hoạt động giống hệt.

#should_render

Module should_render nhận cùng dữ liệu ngữ cảnh và trả về boolean.

• POS tính trước khi bản ghi vừa tải hoặc thay đổi, lưu kết quả theo mã bản ghi và thời điểm cập nhật (updated_status_at với phiếu chuyển kho).
• Timeout 300 ms; quá thời gian hoặc lỗi thì ẩn mục.
• Ưu tiên dùng conditions trong manifest; chỉ dùng should_render khi điều kiện phức tạp.

#*.index.action

Như *.details.action nhưng nằm trên từng dòng của danh sách.

Dữ liệu ngữ cảnh: IndexData<R>.

#*.index.selection-action

Mục trên thanh thao tác khi chọn nhiều bản ghi trong danh sách.

Dữ liệu ngữ cảnh: SelectionData<R>. Với navigate, query kèm theo đủ các mã, ví dụ purchase_ids=<id>,<id>,....

#*.details.block

Box nằm trong form chi tiết.

• Dữ liệu ngữ cảnh: DetailsData<R> (như *.details.action).
• Khi người dùng sửa form, POS cập nhật pos.data và phát sự kiện data-change (xem Runtime API › Sự kiện).
• Box có chiều rộng bằng cột chứa nó, chiều cao tự co giãn theo nội dung.
• Box không chặn hiển thị form: trong lúc worker khởi động, POS hiện khung chờ.

#*.after_save

Chạy sau khi tạo hoặc cập nhật bản ghi thành công trên form chi tiết của POS web.

type AfterSaveInput<R extends Resource> = {
  resource: R;
  mode: 'create' | 'edit';
  record: RefOf<R>;
};

• Không chặn người dùng; giá trị trả về bị bỏ qua.
• Lỗi chỉ ghi vào nhật ký lỗi của app, không hiện cho người dùng.

#*.before_submit

Chạy trước khi tạo hoặc cập nhật bản ghi trên form chi tiết của POS web.

type BeforeSubmitInput<R extends Resource> = DetailsData<R>;

type BeforeSubmitResult =
  | { ok: true; changes?: BeforeSubmitChanges }
  | { ok: false; message: string };   // message tối đa 200 ký tự, hiện cho người dùng

type BeforeSubmitChanges = {
  note?: string;                      // ghi đè ghi chú, tối đa 2.000 ký tự
  add_tags?: (number | string)[];     // thêm thẻ theo mã thẻ của shop, tối đa 20
};

• Nhiều app chạy song song. Chỉ cần một hook trả ok: false là bản ghi không được lưu; POS hiện tất cả message.
• Hết timeout_ms hoặc module lỗi: xử lý theo on_error (allow cho lưu, block chặn lưu).
• changes chỉ sửa được ghi chú và thêm thẻ. POS áp vào form rồi mới lưu, kèm thông báo tên app đã sửa.

• Trường resource không có thì bị bỏ qua. Mã thẻ không có trong shop hoặc đã gắn thì bỏ qua. Lấy mã thẻ bằng Open API hoặc list_shop_meta của MCP.
• Hai app trả hai note khác nhau thì POS chặn lưu và báo trùng ghi chú. Thẻ của nhiều app được cộng dồn.
• changes sai dạng được xử lý như module lỗi (theo on_error).

export default defineExtension('order.before_submit', async (data) => {
  if (data.draft.total_price < 20_000_000) return { ok: true };
  return { ok: true, changes: { add_tags: [12], note: `${data.draft.note ?? ''}\nĐơn lớn: kiểm tra trước khi giao`.trim() } };
});

#Khi nào hook chạy

*.before_submit và *.after_save chỉ chạy khi người dùng bấm lưu trên form chi tiết của POS web. Hook không chạy với thay đổi từ nơi khác: menu trạng thái trên dòng của danh sách, cập nhật hàng loạt, nhập Excel, Open API, app mobile hay đồng bộ sàn. Quy tắc bắt buộc đúng mọi lúc cần làm ở phía server.

#customer.*

Khách hàng có box, action và cột như các resource khác, nhưng không có before_submit, after_save (hồ sơ khách lưu từng ô ngay khi sửa, không có nút Lưu chung) và mẫu in.

Hồ sơ khách mở ở trang Khách hàng, từ form đơn và các màn hình khác đều có box và action. Danh sách khách đang lọc khách đã xoá thì không có action, cột của app.

type CustomerRef = {
  id: string;                       // dùng với Open API: /shops/{shop_id}/customers/{id}
  name: string;
  phone_numbers: string[];
  tags: (number | string)[];
  level_id: string | null;
  assigned_user_id: string | null;
  updated_at: string | null;
};

type CustomerData = { resource: 'customer'; record: CustomerRef };   // cùng dạng IndexData<'customer'>

• Manifest: trường như target cùng vị trí ở resource khác (*.details.action, *.details.block, *.index.column…). Khách hàng không có conditions; cần ẩn theo dữ liệu thì dùng should_render.
• refresh của action headless và pos.refresh() tải lại trang danh sách khách đang xem; hồ sơ đang mở từ danh sách nhận dữ liệu mới theo. Hồ sơ mở từ form đơn hay màn hình khác chưa tự tải lại.
• navigate kèm customer_id hoặc customer_ids trong query.
• Sửa thông tin khách ngay trong hồ sơ thì box nhận data-change với dữ liệu mới.
• Như *.details.block: worker của box khởi động khi box lọt vào màn hình, trong lúc chờ POS hiện khung chờ.

#*.print-action

Mẫu in của app trong ô "Mẫu in", người dùng chọn như mẫu in thường; module trả HTML, POS lọc rồi mở hộp thoại in của trình duyệt.

Sản phẩm chỉ in mã vạch nên không có target này.

type PrintResource = 'order' | 'purchase' | 'export' | 'warehouse_transfer';
type PrintData<R extends PrintResource> = { resource: R; records: RefOf<R>[] };   // 1–500 bản ghi
type PrintResult = { html: string; title?: string };                             // html tối đa 2 MB

• Chạy như action headless: tối đa 30 giây, gọi được pos.api, pos.toast. Lỗi hoặc kết quả sai dạng thì POS báo không in được và ghi nhật ký lỗi.
• Bản ghi ngoài giới hạn access của app không gửi cho module. In bằng mẫu của app không cộng số lần in của đơn.
• Dữ liệu ngữ cảnh chỉ có mã và thông tin tóm tắt (RefOf<R>); cần dòng hàng, khách, tiền thì gọi Open API theo mã bản ghi.
• HTML được lọc trước khi in: bỏ script, thuộc tính sự kiện (onclick…), iframe, form, link, meta. Bản in chạy trong iframe không có script. Dùng <style> hoặc style="…" để trình bày, @page để đặt khổ giấy, break-after: page để sang trang.
• Ảnh theo cùng quy tắc với pos-image: data:image/…;base64,…, public/<tên file> trong gói, hoặc URL https:// thuộc network.allowed_origins. Ảnh khác, font và CSS tải từ ngoài bị chặn. Mã vạch, QR nên vẽ bằng SVG hoặc ảnh data:.

export default defineExtension('purchase.print-action', async ({ records }) => {
  const details = await Promise.all(records.map((purchase) => pos.api.get(`/shops/${pos.shop.id}/purchases/${purchase.id}`)));
  const pages = details.map(({ data }) => `<section class="slip"><h1>Phiếu nhập ${data.display_id}</h1><p>${data.items.length} dòng hàng</p></section>`);
  return {
    title: 'Phiếu nhập ERP',
    html: `<style>@page { size: A5; margin: 8mm } .slip { break-after: page }</style>${pages.join('')}`,
  };
});

#*.index.column

Cột của app trong danh sách, nằm trước cột cố định bên phải (Trạng thái) hoặc cuối bảng. Có cho cả 5 resource và khách hàng. POS gọi module một lần cho các bản ghi đang hiển thị trên trang, không gọi theo từng dòng.

type ColumnData<R extends Resource> = { resource: R; records: RefOf<R>[] };       // bản ghi trên trang, tối đa 500
type ColumnResult = { values: Record<string, string | number | null> };         // khoá là mã bản ghi

Khoá của values là mã dùng với Open API (xem Mã bản ghi): system_id với đơn, id với resource khác.

• Chạy như hook: timeout 5 giây, chỉ gọi được pos.api. Gom các lệnh gọi Open API bằng Promise.all hoặc dùng endpoint danh sách.
• Kết quả được nhớ theo bản ghi và thời điểm cập nhật: danh sách tải lại (đổi trang, socket) chỉ gọi module cho bản ghi mới hoặc vừa đổi.
• Bản ghi không có trong values, bản ghi ngoài giới hạn access và khi module lỗi: ô để trống. Chuỗi dài hơn 200 ký tự bị cắt.
• Cột của app luôn hiện, chưa nằm trong phần cài đặt cột của danh sách.

export default defineExtension('order.index.column', async ({ records }) => {
  const ids = records.map((order) => order.system_id).join(',');
  const response = await fetch(`https://erp.example.com/pos-orders?ids=${ids}`);
  const erp: Record<string, string> = await response.json();
  return { values: erp };
});