Comenzar

El SDK de la Plataforma OneEntry es un SDK que proporciona una forma fácil de interactuar con la API de la Plataforma OneEntry.

---

🚀 Inicio Rápido

Póngase en marcha con OneEntry en 3 simples pasos:

1️⃣ Instalar el paquete

  npm install oneentry

2️⃣ Inicializar el SDK

  import { defineOneEntry } from 'oneentry';

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

3️⃣ Comenzar a usar la 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'
  });

🎉 ¡Eso es todo! Está listo para construir aplicaciones increíbles con OneEntry.

---

✨ Características Clave

🔐

Autenticación Segura

Gestión de tokens incorporada y soporte para OAuth

🌍

Multilenguaje

Soporte i18n con detección automática de idiomas

📝

TypeScript

Definiciones de tipo completas para una mejor experiencia de desarrollo

⚡

Ligero

Tamaño de paquete optimizado para producción

🔌

Arquitectura Modular

24 módulos especializados para todas sus necesidades

🛡️

Manejo de Errores

Manejadores de errores personalizados y modo shell

🌐 Recursos

🌍

Sitio Oficial

Aprenda más sobre la Plataforma OneEntry

🚀

Regístrate

Crea tu cuenta gratuita

💻

Npmjs

Descargar SDK

📖 Uso Detallado

Todos los Módulos Disponibles

Importe y desestructure todos los módulos que necesite:

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);  

O

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

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

---

Configuración

El segundo parámetro del constructor toma la 'config'. Contiene los siguientes valores:

• 'token' - Establezca la clave del token si su proyecto asegura "Token de API de Seguridad". Si está utilizando protección por certificado, no pase esta variable. Puede leer más sobre la seguridad de su proyecto aquí.
• 'langCode' - Establezca el "langCode" para definir el idioma predeterminado. Al especificar este parámetro una vez, no tiene que pasar el langCode a los métodos de la API de ONEENTRY. Si no ha pasado el idioma predeterminado, se establecerá en "en_US".
• 'traficLimit' - Algunos métodos utilizan más de una solicitud a OneEntry para que los datos que reciba sean completos y fáciles de trabajar. Pase el valor "true" para este parámetro para ahorrar tráfico y decidir por sí mismo qué datos necesita. El valor predeterminado es "false".
• 'rawData' - Cuando se establece en false (predeterminado), el SDK transforma automáticamente el array additionalFields en un objeto indexado por marker para un acceso más fácil. Establezca en true para recibir additionalFields como el array original de la API.
• 'auth' - Un objeto con configuraciones de autorización. Por defecto, el SDK está configurado para trabajar con tokens dentro de la sesión del usuario y no requiere ningún trabajo adicional de su parte. Al mismo tiempo, el SDK no almacena el estado de la sesión entre sesiones. Si está satisfecho con tales configuraciones, no pase la variable 'auth' en absoluto.

El 'auth' contiene las siguientes configuraciones:

• 'refreshToken' - El token de actualización del usuario. Transfiera esto aquí desde el repositorio para restaurar la sesión del usuario durante la inicialización.
• 'saveFunction' - Una función que trabaja con la actualización del token de refresco. Si desea almacenar el token entre sesiones, por ejemplo, en el almacenamiento local, pase aquí una función que haga esto. La función debe aceptar un parámetro al que se le pasará la cadena con el token.
• 'customAuth' - Si desea configurar la autorización y trabajar con tokens usted mismo, establezca este flag en true. Si desea utilizar la configuración del sdk, establezca en false o no lo transfiera en absoluto.
• 'providerMarker' - El marcador para el proveedor de autenticación. Predeterminado: 'email'. Un ejemplo de una configuración con protección de token y autenticación automática que almacena el estado entre sesiones

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'
  },
});

Un ejemplo de una configuración que está protegida con un certificado permite configurar el sistema de autorización usted mismo y guarda datos en las solicitudes.

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

Si ha elegido configurar tokens usted mismo, puede pasar el token al método de la siguiente manera. El método intermedio permite pasar un token de acceso a la solicitud. Luego llame al método requerido. Este método (setAccessToken) no debe ser llamado si el método no requiere autorización del usuario.

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

Si eligió la protección por token para garantizar la seguridad de la conexión, simplemente pase su token a la función como un parámetro opcional.

Puede obtener un token de la siguiente manera

1. Inicie sesión en su cuenta personal
2. Vaya a la pestaña "Proyectos" y seleccione un proyecto
3. Vaya a la pestaña "Acceso"
4. Establezca el interruptor en "Token de API de Seguridad"
5. Inicie sesión en el proyecto, vaya a la sección de configuración y abra la pestaña de token
6. Obtenga y copie el token de su proyecto

También puede conectar un certificado tls para proteger su proyecto. En este caso, no pase el "token" en absoluto. Al usar el certificado, configure un proxy en su proyecto. Pase una cadena vacía como parámetro de url. Aprenda más sobre el certificado 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'
  },
});

Validación de Respuestas de API

El SDK de OneEntry incluye validación opcional de respuestas de API utilizando Zod, una biblioteca de validación de esquemas orientada a TypeScript. Esta función ayuda a garantizar la integridad de los datos y la seguridad de tipos al trabajar con respuestas de API.

Características

• Opcional: La validación está desactivada por defecto y se puede habilitar por configuración
• Segura en tipos: Utiliza esquemas de Zod que se alinean con las interfaces de TypeScript
• Dos modos: Modo suave (registra errores) y modo estricto (devuelve errores)
• Cero sobrecarga en tiempo de ejecución cuando está desactivado: Sin impacto en el rendimiento si la validación está desactivada

Configuración

Habilite la validación agregando la propiedad validation a la configuración de su SDK:

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)
  }
})

Opciones de Configuración

Opción	Tipo	Predeterminado	Descripción
enabled	boolean	false	Habilitar/deshabilitar la validación de respuestas
strictMode	boolean	false	Cuando true, devuelve IError en caso de fallo de validación. Cuando false, registra errores y devuelve los datos originales
logErrors	boolean	true	Registrar errores de validación en la consola (útil para depuración)

Modos de Validación

Modo Suave (Predeterminado)

Cuando strictMode es false, los errores de validación se registran en la consola, pero la respuesta original de la API se devuelve sin cambios. Esto es útil durante el desarrollo para identificar posibles inconsistencias de datos sin romper su aplicació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

Modo Estricto

Cuando strictMode es true, los fallos de validación devuelven un objeto IError en lugar de los datos. Esto asegura que su aplicación solo procese datos validados.

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)
}

---

Formato de Campos Adicionales

Por defecto, el SDK transforma la propiedad additionalFields de un array (como lo devuelve la API) en un objeto indexado por marker. Esto facilita mucho el acceso a campos específicos sin conocer su índice.

Comportamiento predeterminado (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

Modo Crudo (rawData: true)

Si necesita el formato original de respuesta de la API (por ejemplo, por compatibilidad hacia atrás), establezca 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)

Opción de Configuración

Opción	Tipo	Predeterminado	Descripción
rawData	boolean	false	Cuando false, additionalFields se transforma en un objeto indexado por marker. Cuando true, se devuelve el array original de la API

---

Errores

Si desea escapar errores dentro del sc, deje la propiedad "errors" por defecto. En este caso, recibirá ya sea los datos de la entidad o el objeto de error. Necesita hacer una verificación de tipo. por ejemplo, verificando la propiedad statusCode con ".hasOwnProperty"

Sin embargo, si desea utilizar la construcción "try catch(e) ", establezca la propiedad "isShell" en el valor "false". En este caso, necesita manejar el error usando "try catch(e) ".

Además, puede pasar funciones personalizadas que se llamarán dentro del sdk con el código de error apropiado. Estas funciones reciben un objeto de error como argumento. Puede procesarlo usted mismo.

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),
    },
  },
})

Cuando la opción isShell: false está establecida en la configuración del SDK, tiene el siguiente efecto:

Cuando ocurre un error en las solicitudes de API (por ejemplo, errores HTTP 400, 401, 404, 500, etc., o errores de red), el SDK lanzará una excepción en lugar de devolver el objeto de error como un valor normal.

Esto le permite utilizar la construcción try/catch en el código de su aplicación para manejar errores:

try {
  const result = await api.someMethod();
  // Handling a successful result
} catch (error) {
  // Error handling
}

Si isShell: true, los errores se devuelven como valores, y necesitará verificar explícitamente el tipo de resultado para verificar:

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
}

Así, isShell: false permite un modelo de manejo de errores más familiar con try/catch, mientras que isShell: true proporciona un modelo plano donde los errores y el éxito se devuelven como valores del mismo tipo.

Al usar el SDK con la configuración predeterminada (isShell establecido en true), los errores se devuelven como valores en lugar de lanzarse como excepciones. Esto significa que la aplicación no se bloqueará debido a excepciones no manejadas, porque los errores se manejan como parte del flujo de ejecución normal. Aquí le mostramos cómo puede manejar errores en el front end sin usar try/catch:

Verifique el tipo de retorno después de llamar a un método de 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);
}

También puede crear un tipo de utilidades "IError" para verificar errores:

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);
}

Este enfoque le permite evitar el uso de construcciones try/catch mientras maneja correctamente los errores, evitando que la aplicación se bloquee.

---

📚 Próximos Pasos

Explore nuestras guías completas para aprender más:

🛍️

Comercio Electrónico

Construya catálogos de productos con filtrado y búsqueda

👤

Gestión de Usuarios

Implemente autenticación y perfiles de usuario

🛒

Órdenes y Pago

Procese órdenes y maneje pagos

📄

Páginas y Contenido

Gestione páginas dinámicas y estructuras de contenido

📝

Formularios

Aprenda a manejar formularios

📝

Datos de Formularios

Aprenda a manejar los datos de formularios

---