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.

🚀 Bắt đầu nhanh

Khởi động 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

  // Fetch products 
  const products = await api.Products.getProducts({ limit: 10 });

  // Get user profile
  const user = await api.Users.getUser();

  // Submit a form
  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 bảo mật

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 chưa 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".
'rawData' - Khi được đặt là false (mặc định), SDK tự động chuyển đổi mảng additionalFields thành một đối tượng được khóa bởi marker để dễ dàng truy cập hơn. Đặt thành true để nhận additionalFields dưới dạng mảng gốc từ API.
'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, hãy không truyền biến 'auth' hoàn toàn.

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

'refreshToken' - Token làm mới của người dùng. Chuyển nó vào đây từ kho để 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ậ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 làm đ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ó hoàn toàn.
'providerMarker' - Đánh dấu cho nhà cung cấp xác thực. Mặc định: 'email'. Một ví dụ về 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'
  },
});

Một ví dụ về cấu hình được bảo vệ bằng chứng chỉ cho phép bạn tự cấu hình hệ thống xác thực 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 ninh 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" hoàn toàn. 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 cho 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 bị vô hiệu hóa 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 bị vô hiệu hóa: 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,        // Enable validation (default: false)
    strictMode: false,    // Strict mode (default: false)
    logErrors: true,      // Log validation errors (default: 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, các 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ăng 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,  // Soft mode
    logErrors: true,
  }
})

// Even if validation fails, you'll get the API response
const user = await api.Users.getUser()
// Console will show validation errors if any

Chế độ nghiêm ngặt

Khi strictMode là true, các lỗi xác thực 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,   // Strict mode
    logErrors: true,
  }
})

const user = await api.Users.getUser()

// Check if response is an error
if ('statusCode' in user) {
  console.error('Validation failed:', user.message)
} else {
  // Type-safe: user is IUserEntity
  console.log('User:', user.email)
}

Định dạng trường bổ sung

Theo mặc định, SDK chuyển đổi thuộc tính additionalFields từ một mảng (như được trả về bởi API) thành một đối tượng được khóa bởi marker. Điều này giúp dễ dàng truy cập các trường cụ thể mà không cần biết chỉ số của chúng.

Hành vi mặc định (`rawData: false`)

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  // rawData is false by default — no need to pass it explicitly
})

// additionalFields is an object keyed by marker:
const field = attribute.additionalFields['my_field']
console.log(field.value)  // direct access, no array search needed

Chế độ gốc (`rawData: true`)

Nếu bạn cần định dạng phản hồi API gốc (ví dụ: để tương thích ngược), hãy đặt rawData: true:

const api = defineOneEntry('https://your-project.oneentry.cloud', {
  token: 'your-token',
  rawData: true,
})

// additionalFields is the original array from the API:
const field = attribute.additionalFields.find(f => f.marker === 'my_field')
console.log(field.value)

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

Tùy chọn	Loại	Mặc định	Mô tả
`rawData`	`boolean`	`false`	Khi `false`, `additionalFields` được chuyển đổi thành một đối tượng được khóa bởi `marker`. Khi `true`, mảng gốc từ API được trả về

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 đối 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('Bad Request:', error.message),
      401: (error) => console.error('Unauthorized:', error.message),
      403: (error) => console.error('Forbidden:', error.message),
      404: (error) => console.error('Not Found:', error.message),
      429: (error) => console.error('Rate Limit Exceeded:', error.message),
      500: (error) => console.error('Server Error:', error.message),
      502: (error) => console.error('Bad Gateway:', error.message),
      503: (error) => console.error('Service Unavailable:', error.message),
      504: (error) => console.error('Gateway Timeout:', error.message),
    },
  },
})

Khi tùy chọn isShell: false được đặt trong cấu hình SDK, nó có tác động 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();
  // Handling a successful result
} catch (error) {
  // Error handling
}

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

const result = await api.someMethod();
if ('statusCode' in result) { // Assumes the presence of a statusCode property on the error object
  // Error handling
} else {
  // Handling a successful result
}

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), 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ì 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 loại trả về sau khi gọi một phương thức API:

const result = await api.someMethod();

// Check if the result is an error
if ('statusCode' in result || 'message' in result) {
  // Error handling
  console.error('Error:', result);
} else {
  // Handling a successful result
  console.log('Success:', result);
}

Bạn cũng có thể tạo các 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'));
}

// Then use it like this:
const result = await api.someMethod();

if (isErrorResult(result)) {
  // Error handling
  console.error('Произошла ошибка:', result);
} else {
  // Handling a successful result
  console.log('Успешный результат:', 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ý đúng lỗi, 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

🚀 Bắt đầu 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

Định dạng trường bổ sung

Hành vi mặc định (`rawData: false`)

Chế độ gốc (`rawData: true`)

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

Lỗi

Khi tùy chọn isShell: false được đặt trong cấu hình SDK, nó có tác động 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 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​

Định dạng trường bổ sung​

Hành vi mặc định (rawData: false)​

Chế độ gốc (rawData: true)​

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

Lỗi​

Khi tùy chọn isShell: false được đặt trong cấu hình SDK, nó có tác động 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 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

Định dạng trường bổ sung

Hành vi mặc định (`rawData: false`)

Chế độ gốc (`rawData: true`)

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

Lỗi

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

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