zmp-sdk 2.53.1 → 2.53.3

package/index.d.ts

@@ -1442,6 +1442,10 @@ type VoucherAction = {
      */
     cta: string;
 };
+/**
+ * @deprecated Dùng `AddCardParams` với `type` là `voucher`; type này sẽ bị loại bỏ cùng
+ * `addVoucher`.
+ */
 type AddVoucherData = {
     /**
      * Tên voucher / ưu đãi.
@@ -1504,6 +1508,112 @@ type AddVoucherReturns = {
      */
     oaMessageToken: string;
 };
+/**
+ * Loại thẻ mà `addCard` hỗ trợ. Hiện chỉ có `voucher`.
+ */
+type CardType = "voucher";
+type VoucherCardMeta = {
+    /**
+     * Mã voucher dạng plain text, hệ thống tự render thành QR / barcode;
+     * tối đa 140 ký tự. Bỏ trống thì thẻ không hiển thị mã.
+     */
+    code?: string;
+    /**
+     * Loại mã hiển thị, chỉ có tác dụng khi có `code`. Mặc định là `qr_code`.
+     */
+    display?: VoucherDisplayType;
+    /**
+     * Nguồn phát hành voucher.
+     */
+    partner?: string;
+    /**
+     * Tên ưu đãi, khác với `data.name`; tối đa 200 ký tự. Hiện chưa được sử dụng: thẻ
+     * không hiển thị trường này.
+     */
+    name?: string;
+    /**
+     * Tên thương hiệu / cửa hàng phát hành; tối đa 100 ký tự.
+     */
+    merchantName: string;
+    /**
+     * OA ID của merchant trên Zalo; tối đa 50 ký tự.
+     */
+    merchantOaId: string;
+    /**
+     * Tên chủ thẻ; tối đa 100 ký tự. Bỏ trống thì thẻ không hiển thị tên chủ thẻ.
+     */
+    ownerName?: string;
+    /**
+     * Điều kiện áp dụng tóm tắt, hiển thị trực tiếp trên thẻ; tối đa 500 ký tự.
+     */
+    condition: string;
+    /**
+     * Điều kiện áp dụng chi tiết; tối đa 2000 ký tự.
+     */
+    conditionDetail?: string;
+    /**
+     * Thời gian bắt đầu hiệu lực, epoch milliseconds; phải nhỏ hơn `expiredAt`.
+     */
+    validAt?: number;
+    /**
+     * Hạn sử dụng, epoch milliseconds; phải ở tương lai và không quá 365 ngày.
+     */
+    expiredAt: number;
+    /**
+     * Danh sách CTA hiển thị trên thẻ (tối đa 3).
+     */
+    actions?: VoucherAction[];
+};
+type VoucherCardData = {
+    /**
+     * Tiêu đề hiển thị trên thẻ, thường đặt bằng tên merchant; tối đa 200 ký tự.
+     */
+    title: string;
+    /**
+     * Tên voucher / ưu đãi, hiển thị nổi bật; tối đa 200 ký tự.
+     */
+    name: string;
+    /**
+     * Mô tả phụ dưới tên voucher, thường là tên chủ thẻ; tối đa 500 ký tự.
+     */
+    desc?: string;
+    /**
+     * Logo merchant dạng tròn; tối đa 500 ký tự. Dùng cho cả cửa sổ xem trước lẫn Ví QR.
+     * Bỏ trống hoặc URL load lỗi thì dùng ảnh mặc định.
+     */
+    avatarUrl?: string;
+    /**
+     * Thông tin nghiệp vụ của voucher.
+     */
+    meta: VoucherCardMeta;
+};
+/**
+ * Dữ liệu thẻ, tương ứng với `type` được truyền vào `addCard`.
+ */
+type AddCardData = VoucherCardData;
+type AddCardParams = {
+    /**
+     * Loại thẻ; hiện chỉ hỗ trợ `voucher`.
+     */
+    type: CardType;
+    /**
+     * Dữ liệu thẻ, tương ứng với `type`.
+     */
+    data: AddCardData;
+    /**
+     * Token để merchant gửi tin nhắn không tốn phí. Lấy từ callback
+     * `onDataReceived` của `showFunctionButtonWidget`.
+     */
+    interactToken?: string;
+};
+type AddCardReturns = {
+    /**
+     * Token để merchant gửi tin nhắn OA cho người dùng; không có trường này nếu không gửi
+     * `interactToken` hoặc token không hợp lệ. Vẫn có giá trị khi người dùng không
+     * thêm thẻ.
+     */
+    oaMessageToken?: string;
+};
 type TempFile = {
     /**
      * Đường dẫn các temp file đã chọn.
@@ -5356,11 +5466,12 @@ declare function addRating(args?: AsyncVoidCallback): Promise<void>;
 /**
  * Lưu voucher vào Ví QR của người dùng.
  *
- * API này gửi dữ liệu voucher từ Mini App về server trung gian. Server trung gian
- * chịu trách nhiệm đăng nhập Ví QR, mã hoá dữ liệu bằng `secureKey`, sau đó trả về
- * deeplink thêm thẻ vào Ví QR. SDK sẽ tự mở deeplink này bằng `openWebview` để đưa
- * người dùng tới màn hình thêm thẻ; deeplink không được trả về cho bên gọi, chỉ
- * trả về `oaMessageToken`.
+ * Khi gọi API, Zalo mở cửa sổ xem trước thẻ ở nửa dưới màn hình như {@link addCard}.
+ * Người dùng chọn "Thêm vào ví" thì voucher được lưu vào Ví QR, chọn "Bỏ qua" hoặc
+ * đóng cửa sổ thì không có thẻ nào được lưu. API hoàn tất khi cửa sổ đóng và trả về
+ * `oaMessageToken`.
+ *
+ * @deprecated Dùng {@link addCard} với `type` là `voucher`.
  *
  * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
  *
@@ -5373,7 +5484,7 @@ declare function addRating(args?: AsyncVoidCallback): Promise<void>;
  * @param {string} merchantLogoUrl Logo OA, dùng làm logo hiển thị trên voucher.
  * @param {string} [conditionDetail] Điều kiện áp dụng chi tiết (phụ).
  * @param {number} [validAt] Thời gian bắt đầu hiệu lực, epoch milliseconds.
- * @param {string} [code] Mã voucher; không truyền thì tự sinh QR OA của merchant.
+ * @param {string} [code] Mã voucher; không truyền thì thẻ không hiển thị mã.
  * @param {"qr_code" | "bar_code"} [display="qr_code"] Loại mã hiển thị.
  * @param {string} [ownerName] Tên khách hàng sở hữu; không truyền thì không hiển thị trên vé.
  * @param {string} [interactToken] Token để merchant gửi tin nhắn không tốn phí.
@@ -5382,9 +5493,9 @@ declare function addRating(args?: AsyncVoidCallback): Promise<void>;
  * @param {VoucherAction[]} [actions] Danh sách CTA hiển thị trên thẻ (tối đa 2);
  * nội dung button (`cta`) tối đa 15 ký tự.
  *
- * @returns {Promise<AddVoucherReturns>} Promise resolve khi tạo thẻ thành công và
- * deeplink đã được mở, trả về `oaMessageToken` (chuỗi rỗng nếu server không
- * trả về); reject kèm mã lỗi từ server nếu thất bại.
+ * @returns {Promise<AddVoucherReturns>} Promise resolve khi cửa sổ đóng lại, kể cả
+ * khi người dùng không lưu thẻ, trả về `oaMessageToken` (chuỗi rỗng nếu không truyền
+ * `interactToken` hoặc token không còn hợp lệ); reject kèm mã lỗi nếu lưu thẻ thất bại.
  *
  * @example Thêm voucher vào Ví QR:
  * ```ts
@@ -5420,6 +5531,56 @@ declare function addRating(args?: AsyncVoidCallback): Promise<void>;
  */
 declare function addVoucher(args: AsyncCallback<AddVoucherReturns> & AddVoucherData): Promise<AddVoucherReturns>;
 
+/**
+ * API lưu thẻ vào Ví QR của người dùng, hiện hỗ trợ thẻ voucher (ưu đãi).
+ *
+ * Khi gọi API, Zalo mở cửa sổ xem trước thẻ ở nửa dưới màn hình. Người dùng chọn "Thêm vào ví" thì thẻ được lưu vào Ví QR và Zalo hiện thông báo kết quả; lưu thẻ thất bại thì API trả về lỗi. Người dùng chọn "Bỏ qua" hoặc đóng cửa sổ thì không có thẻ nào được lưu; API hoàn tất ngay sau khi cửa sổ được đóng.
+ *
+ * @zaloOnly Chỉ hoạt động khi chạy bên trong ứng dụng Zalo mobile.
+ *
+ * @param {CardType} type Loại thẻ, hiện chỉ hỗ trợ `voucher`.
+ * @param {AddCardData} data Dữ liệu thẻ tương ứng với `type`. Với `voucher`, các trường bắt buộc là `title`, `name`, `meta.merchantName`, `meta.merchantOaId`, `meta.condition` và `meta.expiredAt`; xem {@link VoucherCardData} để biết toàn bộ các trường.
+ * @param {string} [interactToken] Token để Mini App gửi tin nhắn OA cho người dùng không tốn phí, lấy từ callback `onDataReceived` của {@link showFunctionButtonWidget}.
+ *
+ * @returns {AddCardReturns} `oaMessageToken` để gửi tin nhắn OA cho người dùng. Không có trường `oaMessageToken` nếu không truyền `interactToken` hoặc token không còn hợp lệ; nếu có, token vẫn được trả về kể cả người dùng không thêm vào ví.
+ *
+ * @example Thêm voucher vào Ví QR:
+ * ```ts
+ * await addCard({
+ *   type: "voucher",
+ *   data: {
+ *     title: "The Face Shop",
+ *     name: "Giảm 50% giá trị đơn hàng",
+ *     avatarUrl: "https://static.example.com/logo.png",
+ *     meta: {
+ *       code: "SUMMER50",
+ *       merchantName: "The Face Shop",
+ *       merchantOaId: "2646373759294038927",
+ *       condition: "Áp dụng cho hóa đơn trên 200.000đ",
+ *       expiredAt: 1743440399000,
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @example Gửi kèm `interactToken` lấy từ Function Button Widget:
+ * ```ts
+ * showFunctionButtonWidget({
+ *   id: "orderButton",
+ *   type: "ORDER",
+ *   text: "Tạo đơn hàng",
+ *   onDataReceived: async (interactToken) => {
+ *     const { oaMessageToken } = await addCard({
+ *       type: "voucher",
+ *       data: voucherCardData,
+ *       interactToken,
+ *     });
+ *   },
+ * });
+ * ```
+ */
+declare function addCard(args: AsyncCallback<AddCardReturns> & AddCardParams): Promise<AddCardReturns>;
+
 declare const interactOAArgs$1: ZodObject<{
     oaId: ZodString;
 }, "strip", ZodTypeAny, {
@@ -6372,6 +6533,7 @@ declare const otherApis: {
     requestSendNotification: typeof requestSendNotification;
     addRating: typeof addRating;
     addVoucher: typeof addVoucher;
+    addCard: typeof addCard;
     interactOA: typeof interactOA;
     interactOa: typeof interactOA;
     isAllowedInteractWithOA: typeof checkIsAllowedInteractWithOA;
@@ -6438,4 +6600,4 @@ declare const otherApis: {
     ZMACameraImp: typeof ZMACameraImp;
 };
 
-export { Action, AddVoucherData, AddVoucherReturns, AndroidBottomNavigationBarType, AppError, AsyncCallback, AsyncCallbackFailObject, AsyncProgressCallback, AsyncVoidCallback, AuthorizeType, CameraEvents, CameraParams, ChatType, CheckStateBioAuthenticationReturns, CheckTransactionReturns, CheckZaloCameraPermissionReturns, CheckoutKit, CheckoutPopupOpenParams, CheckoutPopupResponseData, CheckoutSDK, ChooseImageReturns, Common, ContextInfo, CreateOrderIAPReturns, CreateOrderReturns, Events as EventName, Events, FacingMode, FileInfo, FunctionProps, GetAppInfoReturns, GetAuthCodeReturns, GetBeaconDiscoveryReturns, GetDeviceInfoReturn, GetFileInfoReturns, GetLocationReturns, GetNetworkTypeReturns, GetPhoneNumberReturns, GetSettingReturn, GetStorageReturns, GetUserInfoReturns, GetZPITokenReturns, IAPMethodType, IAPPayType, IAPPayTypeType, IOSSafeAreaBottomType, IsSupportReturns, JumpStatus, KeepScreenReturns, LFSStorage, ListFile, LogData, MediaConstraints, MediaDevice, MediaPickerType, NativeCallBackData, NetworkType, OpenBioAuthenticationReturns, OpenMediaPickerReturns, OpenPostFeedReturns, OpenProfilePickerReturns, OpenProfilePickerType, OpenShareSheetReturns, OpenWebviewReturns, OrientationType, Payment, PhotoConstraint, PhotoFormat, PhotoFrame, PhotoQuality, PickAttr, PickedProfile, PlatformType, PostFeedType, ProfileInfo, ProfileType, ProrationMode, ProrationModeType, RemoveStorageReturns, RequestCameraPermissionReturns, SaveFileReturns, ScanNFCType, ScanQRCodeReturns, SelectPaymentMethodReturns, SetStorageReturns, ShareSheetType, StatusBarType, StorageInfo, StreamType, SystemInfo, TempFile, TextAlignType, UserInfo, VibrateType, VoucherAction, VoucherActionType, VoucherDisplayType, ZMACamera, ZMACameraImp, addRating, addVoucher, authorize, checkNFC, checkStateBioAuthentication, checkTransaction, checkZaloCameraPermission, chooseImage, clearStorage, closeApp, closeLoading, configAppView, connectWifi, createCameraContext, createOrder, createOrderIAP, createShortcut, otherApis as default, displayAd, downloadFile, events, favoriteApp, followOA, getAccessToken, getAppInfo, getAuthCode, getBeacons, getContext, getContextAsync, getDeviceId, getDeviceIdAsync, getDeviceInfo, getEntrySource, getIDToken, getLocation, getNetworkType, getPhoneNumber, getRouteParams, getSetting, getShareableLink, getStorage, getStorageInfo, getSystemInfo, getUserID, getUserInfo, getVersion, getZPIToken, hideKeyboard, iBeaconInfo, interactOA, interactOA as interactOa, checkIsAllowedInteractWithOA as isAllowedInteractWithOA, keepScreen, loadAd, login, minimizeApp, nativeStorage, offConfirmToExit, offKeepScreen, onCallbackData, onConfirmToExit, onKeepScreen, onNetworkStatusChange, openBioAuthentication, openChat, openDocument, openGroupList, openMediaPicker, openMiniApp, openOutApp, openPermissionSetting, openPhone, openPostFeed, openProfile, openProfilePicker, openSMS, openShareSheet, openWebview, purchase, refreshAd, removeStorage, requestCameraPermission, requestSendNotification, requestUpdateZalo, saveImageToGallery, saveVideoToGallery, scanNFC, scanQRCode, selectPaymentMethod, sendDataToPreviousMiniApp, setAccessToken, setAndroidBottomNavigationBar, setIOSBottomSafeArea, setNavigationBarColor, setNavigationBarLeftButton, setNavigationBarTitle, setStatusBar, setStorage, setupAd, showCustomOAWidget, showFunctionButtonWidget, showOAWidget, showToast, startBeaconDiscovery, stopBeaconDiscovery, trackingManager, unfollowOA, vibrate, viewOAQr };
+export { Action, AddCardData, AddCardParams, AddCardReturns, AddVoucherData, AddVoucherReturns, AndroidBottomNavigationBarType, AppError, AsyncCallback, AsyncCallbackFailObject, AsyncProgressCallback, AsyncVoidCallback, AuthorizeType, CameraEvents, CameraParams, CardType, ChatType, CheckStateBioAuthenticationReturns, CheckTransactionReturns, CheckZaloCameraPermissionReturns, CheckoutKit, CheckoutPopupOpenParams, CheckoutPopupResponseData, CheckoutSDK, ChooseImageReturns, Common, ContextInfo, CreateOrderIAPReturns, CreateOrderReturns, Events as EventName, Events, FacingMode, FileInfo, FunctionProps, GetAppInfoReturns, GetAuthCodeReturns, GetBeaconDiscoveryReturns, GetDeviceInfoReturn, GetFileInfoReturns, GetLocationReturns, GetNetworkTypeReturns, GetPhoneNumberReturns, GetSettingReturn, GetStorageReturns, GetUserInfoReturns, GetZPITokenReturns, IAPMethodType, IAPPayType, IAPPayTypeType, IOSSafeAreaBottomType, IsSupportReturns, JumpStatus, KeepScreenReturns, LFSStorage, ListFile, LogData, MediaConstraints, MediaDevice, MediaPickerType, NativeCallBackData, NetworkType, OpenBioAuthenticationReturns, OpenMediaPickerReturns, OpenPostFeedReturns, OpenProfilePickerReturns, OpenProfilePickerType, OpenShareSheetReturns, OpenWebviewReturns, OrientationType, Payment, PhotoConstraint, PhotoFormat, PhotoFrame, PhotoQuality, PickAttr, PickedProfile, PlatformType, PostFeedType, ProfileInfo, ProfileType, ProrationMode, ProrationModeType, RemoveStorageReturns, RequestCameraPermissionReturns, SaveFileReturns, ScanNFCType, ScanQRCodeReturns, SelectPaymentMethodReturns, SetStorageReturns, ShareSheetType, StatusBarType, StorageInfo, StreamType, SystemInfo, TempFile, TextAlignType, UserInfo, VibrateType, VoucherAction, VoucherActionType, VoucherCardData, VoucherCardMeta, VoucherDisplayType, ZMACamera, ZMACameraImp, addCard, addRating, addVoucher, authorize, checkNFC, checkStateBioAuthentication, checkTransaction, checkZaloCameraPermission, chooseImage, clearStorage, closeApp, closeLoading, configAppView, connectWifi, createCameraContext, createOrder, createOrderIAP, createShortcut, otherApis as default, displayAd, downloadFile, events, favoriteApp, followOA, getAccessToken, getAppInfo, getAuthCode, getBeacons, getContext, getContextAsync, getDeviceId, getDeviceIdAsync, getDeviceInfo, getEntrySource, getIDToken, getLocation, getNetworkType, getPhoneNumber, getRouteParams, getSetting, getShareableLink, getStorage, getStorageInfo, getSystemInfo, getUserID, getUserInfo, getVersion, getZPIToken, hideKeyboard, iBeaconInfo, interactOA, interactOA as interactOa, checkIsAllowedInteractWithOA as isAllowedInteractWithOA, keepScreen, loadAd, login, minimizeApp, nativeStorage, offConfirmToExit, offKeepScreen, onCallbackData, onConfirmToExit, onKeepScreen, onNetworkStatusChange, openBioAuthentication, openChat, openDocument, openGroupList, openMediaPicker, openMiniApp, openOutApp, openPermissionSetting, openPhone, openPostFeed, openProfile, openProfilePicker, openSMS, openShareSheet, openWebview, purchase, refreshAd, removeStorage, requestCameraPermission, requestSendNotification, requestUpdateZalo, saveImageToGallery, saveVideoToGallery, scanNFC, scanQRCode, selectPaymentMethod, sendDataToPreviousMiniApp, setAccessToken, setAndroidBottomNavigationBar, setIOSBottomSafeArea, setNavigationBarColor, setNavigationBarLeftButton, setNavigationBarTitle, setStatusBar, setStorage, setupAd, showCustomOAWidget, showFunctionButtonWidget, showOAWidget, showToast, startBeaconDiscovery, stopBeaconDiscovery, trackingManager, unfollowOA, vibrate, viewOAQr };