Bắt đầu

OneEntry Platform SDK là một SDK cung cấp cách dễ dàng để tương tác với OneEntry Platform API.

🚀 Khởi động nhanh

Bắt đầu với OneEntry trong 3 bước đơn giản:

1️⃣ Cài đặt gói

  npm install oneentry

2️⃣ Khởi tạo SDK

  import { defineOneEntry } from 'oneentry';

  const api = defineOneEntry('your-project-url', {
    token: 'your-api-token'
  });

3️⃣ Bắt đầu sử dụng API

  // Lấy sản phẩm 
  const products = await api.Products.getProducts({ limit: 10 });

  // Lấy hồ sơ người dùng
  const user = await api.Users.getUser();

  // Gửi một biểu mẫu
  const formData = await api.FormData.postFormsData('contact-form', {
    name: 'John Doe',
    email: 'john@example.com'
  });

🎉 Chỉ vậy thôi! Bạn đã sẵn sàng để xây dựng những ứng dụng tuyệt vời với OneEntry.

✨ Tính năng chính

🔐

Xác thực an toàn

Quản lý token tích hợp và hỗ trợ OAuth

🌍

Đa ngôn ngữ

Hỗ trợ i18n với phát hiện ngôn ngữ tự động

📝

TypeScript

Định nghĩa kiểu đầy đủ để cải thiện trải nghiệm phát triển

⚡

Nhẹ

Kích thước gói tối ưu cho sản xuất

🔌

Kiến trúc mô-đun

24 mô-đun chuyên biệt cho tất cả nhu cầu của bạn

🛡️

Xử lý lỗi

Bộ xử lý lỗi tùy chỉnh và chế độ shell

🌐 Tài nguyên

🌍

Trang web chính thức

Tìm hiểu thêm về OneEntry Platform

🚀

Đăng ký

Tạo tài khoản miễn phí của bạn

💻

Npmjs

Tải xuống SDK

📖 Sử dụng chi tiết

Tất cả các mô-đun có sẵn

Nhập và phân tách tất cả các mô-đun bạn cần:


import { defineOneEntry } from 'oneentry'

const config = { 
  token: 'your-app-token', 
} 
const { 
  Admins, 
  AttributesSets, 
  AuthProvider, 
  Blocks, 
  Events, 
  FileUploading, 
  Forms, 
  FormData, 
  GeneralTypes, 
  IntegrationCollections, 
  Locales, 
  Menus, 
  Orders, 
  Pages, 
  Payments, 
  ProductStatuses, 
  Products, 
  Settings, 
  System, 
  Templates, 
  TemplatePreviews, 
  Users, 
  WS 
} = defineOneEntry('your-url', config);

Hoặc

const config = { 
  token: 'your-app-token', 
}; 

const api = defineOneEntry('your-url', config); 

Cấu hình

Tham số thứ hai của hàm khởi tạo nhận 'config'. Nó chứa các giá trị sau:

'token' - Đặt khóa token nếu dự án của bạn bảo mật "Security API Token". Nếu bạn đang sử dụng bảo vệ bằng chứng chỉ, không truyền biến này. Bạn có thể đọc thêm về bảo mật của dự án của bạn tại đây.
'langCode' - Đặt "langCode" để thiết lập ngôn ngữ mặc định. Bằng cách chỉ định tham số này một lần, bạn không cần phải truyền langCode cho các phương thức ONEENTRY API. Nếu bạn không truyền ngôn ngữ mặc định, nó sẽ được đặt là "en_US".
'traficLimit' - Một số phương thức sử dụng nhiều hơn một yêu cầu đến OneEntry để dữ liệu bạn nhận được đầy đủ và dễ làm việc. Truyền giá trị "true" cho tham số này để tiết kiệm lưu lượng và tự quyết định dữ liệu bạn cần. Giá trị mặc định là "false".
'auth' - Một đối tượng với các cài đặt xác thực. Theo mặc định, SDK được cấu hình để làm việc với các token bên trong phiên của người dùng và không yêu cầu bất kỳ công việc bổ sung nào từ bạn. Đồng thời, SDK không lưu trạng thái phiên giữa các phiên. Nếu bạn hài lòng với các cài đặt như vậy, không cần truyền biến 'auth' chút nào.

'auth' chứa các cài đặt sau:

'refreshToken' - Token làm mới của người dùng. Chuyển nó từ kho lưu trữ ở đây để khôi phục phiên của người dùng trong quá trình khởi tạo.
'saveFunction' - Một hàm làm việc với token làm mới được cập nhật. Nếu bạn muốn lưu token giữa các phiên, chẳng hạn như trong bộ nhớ cục bộ, hãy truyền một hàm ở đây thực hiện điều này. Hàm phải chấp nhận một tham số mà chuỗi chứa token sẽ được truyền vào.
'customAuth' - Nếu bạn muốn cấu hình xác thực và làm việc với các token tự mình, hãy đặt cờ này thành true. Nếu bạn muốn sử dụng các cài đặt sdk, hãy đặt nó thành false hoặc không truyền nó chút nào.
'providerMarker' - Đánh dấu cho nhà cung cấp xác thực. Mặc định: 'email'. Ví dụ về một cấu hình với bảo vệ token và xác thực tự động lưu trạng thái giữa các phiên

const tokenFunction = (token) => { 
  localStorage.setItem('refreshToken', token); 
}; 

const api = defineOneEntry('https://my-project.oneentry.cloud', { 
  token: 'my-token', 
  langCode: 'en_US', 
  auth: { 
    refreshToken: localStorage.getItem('refreshToken'), 
    saveFunction: tokenFunction, 
    providerMarker: 'email' 
  }, 
}); 

Ví dụ về một cấu hình được bảo vệ bằng chứng chỉ cho phép bạn cấu hình hệ thống xác thực tự mình và lưu dữ liệu trên các yêu cầu.

const api = defineOneEntry('https://my-project.oneentry.cloud', { 
  langCode: 'en_US', 
  traficLimit: true, 
  auth: { 
    customAuth: true, 
    refreshToken: localStorage.getItem('refreshToken'), 
    providerMarker: 'email' 
  }, 
}); 

Nếu bạn đã chọn cấu hình các token tự mình, bạn có thể truyền token vào phương thức như sau. Phương thức trung gian cho phép bạn truyền một token truy cập vào yêu cầu. Sau đó gọi phương thức cần thiết. Phương thức này (setAccessToken) không nên được gọi nếu phương thức không yêu cầu xác thực người dùng.

const user = api.Users.setAccessToken('my.access.token').getUser(); 

Nếu bạn đã chọn bảo vệ token để đảm bảo an toàn kết nối, chỉ cần truyền token của bạn vào hàm như một tham số tùy chọn.

Bạn có thể nhận token như sau

Đăng nhập vào tài khoản cá nhân của bạn
Đi đến tab "Dự án" và chọn một dự án
Đi đến tab "Truy cập"
Đặt công tắc thành "Security API Token"
Đăng nhập vào dự án, đi đến phần cài đặt và mở tab token
Nhận và sao chép token của dự án bạn

Bạn cũng có thể kết nối một chứng chỉ tls để bảo vệ dự án của bạn. Trong trường hợp này, không truyền "token" chút nào. Khi sử dụng chứng chỉ, hãy thiết lập một proxy trong dự án của bạn. Truyền một chuỗi rỗng làm tham số url. Tìm hiểu thêm về chứng chỉ mtls

const saveTokenFromLocalStorage = (token) => { 
  localStorage.setItem('refreshToken', token); 
}; 

const api = defineOneEntry('your-url', { 
  token: 'my-token', 
  langCode: 'my-langCode', 
  auth: { 
    customAuth: false, 
    userToken: 'rerfesh.token', 
    saveFunction: saveTokenFromLocalStorage, 
    providerMarker: 'email' 
  }, 
}); 

Xác thực phản hồi API

OneEntry SDK bao gồm xác thực tùy chọn các phản hồi API bằng cách sử dụng Zod, một thư viện xác thực sơ đồ đầu tiên của TypeScript. Tính năng này giúp đảm bảo tính toàn vẹn dữ liệu và an toàn kiểu khi làm việc với các phản hồi API.

Tính năng

Tùy chọn: Xác thực được tắt theo mặc định và có thể được bật theo cấu hình
An toàn kiểu: Sử dụng các sơ đồ Zod phù hợp với các giao diện TypeScript
Hai chế độ: Chế độ mềm (ghi lại lỗi) và chế độ nghiêm ngặt (trả về lỗi)
Không có chi phí thời gian chạy khi tắt: Không ảnh hưởng đến hiệu suất nếu xác thực bị tắt

Cấu hình

Bật xác thực bằng cách thêm thuộc tính validation vào cấu hình SDK của bạn:

import { defineOneEntry } from 'oneentry'

const api = defineOneEntry('https://your-project.oneentry.cloud', { 
  token: 'your-token', 
  validation: { 
    enabled: true,        // Bật xác thực (mặc định: false) 
    strictMode: false,    // Chế độ nghiêm ngặt (mặc định: false) 
    logErrors: true,      // Ghi lại lỗi xác thực (mặc định: true) 
  } 
}) 

Tùy chọn cấu hình

Tùy chọn	Loại	Mặc định	Mô tả
`enabled`	`boolean`	`false`	Bật/tắt xác thực phản hồi
`strictMode`	`boolean`	`false`	Khi `true`, trả về `IError` khi xác thực thất bại. Khi `false`, ghi lại lỗi và trả về dữ liệu gốc
`logErrors`	`boolean`	`true`	Ghi lại lỗi xác thực vào bảng điều khiển (hữu ích cho việc gỡ lỗi)

Chế độ xác thực

Chế độ mềm (Mặc định)

Khi strictMode là false, lỗi xác thực được ghi lại vào bảng điều khiển, nhưng phản hồi API gốc được trả về không thay đổi. Điều này hữu ích trong quá trình phát triển để xác định các bất thường dữ liệu tiềm ẩn mà không làm hỏng ứng dụng của bạn.

const api = defineOneEntry('https://your-project.oneentry.cloud', { 
  token: 'your-token', 
  validation: { 
    enabled: true, 
    strictMode: false,  // Chế độ mềm 
    logErrors: true, 
  } 
})

// Ngay cả khi xác thực thất bại, bạn vẫn sẽ nhận được phản hồi API
const user = await api.Users.getUser()
// Bảng điều khiển sẽ hiển thị lỗi xác thực nếu có

Chế độ nghiêm ngặt

Khi strictMode là true, các lỗi xác thực sẽ trả về một đối tượng IError thay vì dữ liệu. Điều này đảm bảo ứng dụng của bạn chỉ xử lý dữ liệu đã được xác thực.

const api = defineOneEntry('https://your-project.oneentry.cloud', { 
  token: 'your-token', 
  validation: { 
    enabled: true, 
    strictMode: true,   // Chế độ nghiêm ngặt 
    logErrors: true, 
  } 
})

const user = await api.Users.getUser()

// Kiểm tra xem phản hồi có phải là lỗi không
if ('statusCode' in user) { 
  console.error('Xác thực thất bại:', user.message) 
} else { 
  // An toàn kiểu: user là IUserEntity 
  console.log('Người dùng:', user.email) 
}

Lỗi

Nếu bạn muốn bỏ qua lỗi bên trong sc, hãy để thuộc tính "errors" theo mặc định. Trong trường hợp này, bạn sẽ nhận được dữ liệu thực thể hoặc đối tượng lỗi. Bạn cần thực hiện kiểm tra kiểu. ví dụ, bằng cách kiểm tra thuộc tính statusCode với ".hasOwnProperty"

Tuy nhiên, nếu bạn muốn sử dụng cấu trúc "try catch(e) ", hãy đặt thuộc tính "isShell" thành giá trị "false". Trong trường hợp này, bạn cần xử lý lỗi bằng cách sử dụng "try catch(e) ".

Ngoài ra, bạn có thể truyền các hàm tùy chỉnh sẽ được gọi bên trong sdk với mã lỗi thích hợp. Các hàm này nhận một đối tượng lỗi làm tham số. Bạn có thể xử lý nó theo cách của mình.

const api = defineOneEntry('your-url', { 
  token: 'my-token', 
  langCode: 'my-langCode', 
  errors: { 
    isShell: false, 
    customErrors: { 
      400: (error) => console.error('Yêu cầu không hợp lệ:', error.message), 
      401: (error) => console.error('Không được phép:', error.message), 
      403: (error) => console.error('Bị cấm:', error.message), 
      404: (error) => console.error('Không tìm thấy:', error.message), 
      429: (error) => console.error('Vượt quá giới hạn tỷ lệ:', error.message), 
      500: (error) => console.error('Lỗi máy chủ:', error.message), 
      502: (error) => console.error('Cổng xấu:', error.message), 
      503: (error) => console.error('Dịch vụ không khả dụng:', error.message), 
      504: (error) => console.error('Hết thời gian cổng:', error.message), 
    }, 
  }, 
}) 

Khi tùy chọn isShell: false được đặt trong cấu hình SDK, nó có tác động như sau:

Khi xảy ra lỗi trong các yêu cầu API (ví dụ: lỗi HTTP 400, 401, 404, 500, v.v., hoặc lỗi mạng), SDK sẽ ném ra một ngoại lệ thay vì trả về đối tượng lỗi như một giá trị bình thường.

Điều này cho phép bạn sử dụng cấu trúc try/catch trong mã ứng dụng của bạn để xử lý lỗi:

try { 
  const result = await api.someMethod(); 
  // Xử lý kết quả thành công 
} catch (error) { 
  // Xử lý lỗi 
}

Nếu isShell: true, các lỗi được trả về dưới dạng giá trị, và bạn sẽ cần kiểm tra kiểu kết quả một cách rõ ràng để xác minh:

const result = await api.someMethod(); 
if ('statusCode' in result) { // Giả định sự hiện diện của thuộc tính statusCode trên đối tượng lỗi 
  // Xử lý lỗi 
} else { 
  // Xử lý kết quả thành công 
}

Do đó, isShell: false cho phép một mô hình xử lý lỗi quen thuộc hơn với try/catch, trong khi isShell: true cung cấp một mô hình phẳng nơi lỗi và thành công được trả về dưới dạng các giá trị cùng loại.

Khi sử dụng SDK với cài đặt mặc định (isShell được đặt thành true), các lỗi được trả về dưới dạng giá trị thay vì bị ném ra như các ngoại lệ. Điều này có nghĩa là ứng dụng sẽ không bị sập do các ngoại lệ không được xử lý, vì các lỗi được xử lý như một phần của luồng thực thi bình thường. Dưới đây là cách bạn có thể xử lý lỗi ở phía trước mà không cần sử dụng try/catch:

Kiểm tra kiểu trả về sau khi gọi một phương thức API:

const result = await api.someMethod();

// Kiểm tra xem kết quả có phải là lỗi không
if ('statusCode' in result || 'message' in result) { 
  // Xử lý lỗi 
  console.error('Lỗi:', result); 
} else { 
  // Xử lý kết quả thành công 
  console.log('Thành công:', result); 
}

Bạn cũng có thể tạo sử dụng loại tiện ích "IError" để kiểm tra lỗi:

import type { IError } from '../base/utils';

function isErrorResult(result: any): result is IError { 
  return result && typeof result === 'object' && 
         (result.hasOwnProperty('statusCode') || 
          result.hasOwnProperty('message')); 
}

// Sau đó sử dụng nó như thế này:
const result = await api.someMethod();

if (isErrorResult(result)) { 
  // Xử lý lỗi 
  console.error('Đã xảy ra lỗi:', result); 
} else { 
  // Xử lý kết quả thành công 
  console.log('Kết quả thành công:', result); 
}

Cách tiếp cận này cho phép bạn tránh sử dụng các cấu trúc try/catch trong khi vẫn xử lý lỗi một cách chính xác, ngăn chặn ứng dụng bị sập.

📚 Các bước tiếp theo

Khám phá các hướng dẫn toàn diện của chúng tôi để tìm hiểu thêm:

🛍️

Bắt đầu

🚀 Khởi động nhanh

1️⃣ Cài đặt gói

2️⃣ Khởi tạo SDK

3️⃣ Bắt đầu sử dụng API

✨ Tính năng chính

🌐 Tài nguyên

📖 Sử dụng chi tiết

Tất cả các mô-đun có sẵn

Cấu hình

Bạn có thể nhận token như sau

Xác thực phản hồi API

Tính năng

Cấu hình

Tùy chọn cấu hình

Chế độ xác thực

Chế độ mềm (Mặc định)

Chế độ nghiêm ngặt

Lỗi

Khi tùy chọn isShell: false được đặt trong cấu hình SDK, nó có tác động như sau:

📚 Các bước tiếp theo

Thương mại điện tử

Quản lý người dùng

Đơn hàng & Thanh toán

Trang & Nội dung

Biểu mẫu

Dữ liệu biểu mẫu

Bắt đầu

🚀 Khởi động nhanh​

1️⃣ Cài đặt gói​

2️⃣ Khởi tạo SDK​

3️⃣ Bắt đầu sử dụng API​

✨ Tính năng chính​

🌐 Tài nguyên​

📖 Sử dụng chi tiết​

Tất cả các mô-đun có sẵn​

Cấu hình​

Bạn có thể nhận token như sau​

Xác thực phản hồi API

Tính năng​

Cấu hình​

Tùy chọn cấu hình​

Chế độ xác thực​

Chế độ mềm (Mặc định)​

Chế độ nghiêm ngặt​

Lỗi​

Khi tùy chọn isShell: false được đặt trong cấu hình SDK, nó có tác động như sau:​

📚 Các bước tiếp theo​

Thương mại điện tử

Quản lý người dùng

Đơn hàng & Thanh toán

Trang & Nội dung

Biểu mẫu

Dữ liệu biểu mẫu

🚀 Khởi động nhanh

1️⃣ Cài đặt gói

2️⃣ Khởi tạo SDK

3️⃣ Bắt đầu sử dụng API

✨ Tính năng chính

🌐 Tài nguyên

📖 Sử dụng chi tiết

Tất cả các mô-đun có sẵn

Cấu hình

Bạn có thể nhận token như sau

Tính năng

Cấu hình

Tùy chọn cấu hình

Chế độ xác thực

Chế độ mềm (Mặc định)

Chế độ nghiêm ngặt

Lỗi

Khi tùy chọn isShell: false được đặt trong cấu hình SDK, nó có tác động như sau:

📚 Các bước tiếp theo