Saltar al contenido principal

Comenzar

NPM VersionBundle Size

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

🚀 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('tu-url-del-proyecto', {
    token: 'tu-token-de-api'
  });

3️⃣ Comenzar a usar la API​

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

  // Obtener perfil de usuario
  const user = await api.Users.getUser();

  // Enviar un formulario
  const formData = await api.FormData.postFormsData('contact-form', {
    name: 'John Doe',
    email: 'john@example.com'
  });

🎉 ¡Eso es todo! Estás 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 idioma

📝
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 tus necesidades

🛡️
Manejo de Errores

Manejadores de errores personalizados y modo shell

🌐 Recursos​

📖 Uso Detallado​

Todos los Módulos Disponibles​

Importa y desestructura todos los módulos que necesites:


import { defineOneEntry } from 'oneentry'

const config = {  
  token: 'tu-token-de-app',  
}  
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('tu-url', config);

O

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

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

Configuración​

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

  • 'token' - Establece la clave del token si tu proyecto asegura "Token de API de Seguridad". Si estás utilizando protección por certificado, no pases esta variable. Puedes leer más sobre la seguridad de tu proyecto aquí.
  • 'langCode' - Establece el "langCode" para definir el idioma predeterminado. Al especificar este parámetro una vez, no tienes que pasar el langCode a los métodos de la API de ONEENTRY. Si no has 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 recibas sean completos y fáciles de trabajar. Pasa el valor "true" para este parámetro para ahorrar tráfico y decidir por ti mismo qué datos necesitas. El valor predeterminado es "false".
  • '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 tu parte. Al mismo tiempo, el SDK no almacena el estado de la sesión entre sesiones. Si estás satisfecho con tales configuraciones, no pases la variable 'auth' en absoluto.

La 'auth' contiene las siguientes configuraciones:

  • 'refreshToken' - El token de actualización del usuario. Transfírelo aquí desde el repositorio para restaurar la sesión del usuario durante la inicialización.
  • 'saveFunction' - Una función que trabaja con el token de actualización. Si deseas almacenar el token entre sesiones, por ejemplo, en el almacenamiento local, pasa 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 deseas configurar la autorización y trabajar con tokens tú mismo, establece este flag en true. Si deseas usar la configuración del sdk, configúralo en false o no lo transfieras en absoluto.
  • 'providerMarker' - El marcador para el proveedor de autenticación. Predeterminado: 'email'. Un ejemplo de 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://mi-proyecto.oneentry.cloud', {  
  token: 'mi-token',  
  langCode: 'en_US',  
  auth: {  
    refreshToken: localStorage.getItem('refreshToken'),  
    saveFunction: tokenFunction,  
    providerMarker: 'email'  
  },  
});

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

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

Si has elegido configurar los tokens tú mismo, puedes pasar el token al método de la siguiente manera.
El método intermedio permite pasar un token de acceso a la solicitud. Luego llama 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('mi.token.de.acceso').getUser();

Si elegiste la protección de token para asegurar la seguridad de la conexión, simplemente pasa tu token a la función como un parámetro opcional.

Puedes obtener un token de la siguiente manera​

  1. Inicia sesión en tu cuenta personal
  2. Ve a la pestaña "Proyectos" y selecciona un proyecto
  3. Ve a la pestaña "Acceso"
  4. Activa el interruptor en "Token de API de Seguridad"
  5. Inicia sesión en el proyecto, ve a la sección de configuración y abre la pestaña de token
  6. Obtén y copia el token de tu proyecto

También puedes conectar un certificado tls para proteger tu proyecto. En este caso, no pases el "token" en absoluto. Al usar el certificado, configura un proxy en tu proyecto. Pasa una cadena vacía como parámetro de url.
Aprende más sobre el certificado mtls

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

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

Validación de Respuestas de API

OneEntry SDK 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​

Habilita la validación añadiendo la propiedad validation a tu configuración del SDK:

import { defineOneEntry } from 'oneentry'

const api = defineOneEntry('https://tu-proyecto.oneentry.cloud', {  
  token: 'tu-token',  
  validation: {  
    enabled: true,        // Habilitar validación (predeterminado: false)  
    strictMode: false,    // Modo estricto (predeterminado: false)  
    logErrors: true,      // Registrar errores de validación (predeterminado: true)  
  }  
})

Opciones de Configuración​

OpciónTipoPredeterminadoDescripción
enabledbooleanfalseHabilitar/deshabilitar la validación de respuestas
strictModebooleanfalseCuando true, devuelve IError en caso de fallo de validación. Cuando false, registra errores y devuelve los datos originales
logErrorsbooleantrueRegistrar 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 tu aplicación.

const api = defineOneEntry('https://tu-proyecto.oneentry.cloud', {  
  token: 'tu-token',  
  validation: {  
    enabled: true,  
    strictMode: false,  // Modo suave  
    logErrors: true,  
  }  
})

// Incluso si la validación falla, obtendrás la respuesta de la API
const user = await api.Users.getUser()
// La consola mostrará errores de validación si los hay

Modo Estricto​

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

const api = defineOneEntry('https://tu-proyecto.oneentry.cloud', {  
  token: 'tu-token',  
  validation: {  
    enabled: true,  
    strictMode: true,   // Modo estricto  
    logErrors: true,  
  }  
})

const user = await api.Users.getUser()

// Verifica si la respuesta es un error
if ('statusCode' in user) {  
  console.error('La validación falló:', user.message)  
} else {  
  // Seguro en tipos: user es IUserEntity  
  console.log('Usuario:', user.email)  
}

Errores​

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

Sin embargo, si deseas usar la construcción "try catch(e) ", establece la propiedad "isShell" en el valor "false".
En este caso, necesitas manejar el error usando "try catch(e) ".

Además, puedes 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. Puedes procesarlo tú mismo.

const api = defineOneEntry('tu-url', {  
  token: 'mi-token',  
  langCode: 'mi-langCode',  
  errors: {  
    isShell: false,  
    customErrors: {  
      400: (error) => console.error('Solicitud Incorrecta:', error.message),  
      401: (error) => console.error('No Autorizado:', error.message),  
      403: (error) => console.error('Prohibido:', error.message),  
      404: (error) => console.error('No Encontrado:', error.message),  
      429: (error) => console.error('Límite de Tasa Excedido:', error.message),  
      500: (error) => console.error('Error del Servidor:', error.message),  
      502: (error) => console.error('Puerta de Enlace Incorrecta:', error.message),  
      503: (error) => console.error('Servicio No Disponible:', error.message),  
      504: (error) => console.error('Tiempo de Espera de la Puerta de Enlace:', error.message),  
    },  
  },  
})

Cuando la opción isShell: false está configurada 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 te permite usar la construcción try/catch en tu código de aplicación para manejar errores:

try {  
  const result = await api.someMethod();  
  // Manejo de un resultado exitoso  
} catch (error) {  
  // Manejo de errores  
}

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

const result = await api.someMethod();  
if ('statusCode' in result) { // Asume la presencia de una propiedad statusCode en el objeto de error  
  // Manejo de errores  
} else {  
  // Manejo de un resultado exitoso  
}

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 configurado 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í te mostramos cómo puedes manejar errores en el front end sin usar try/catch:

Verifica el tipo de retorno después de llamar a un método de API:

const result = await api.someMethod();

// Verifica si el resultado es un error
if ('statusCode' in result || 'message' in result) {  
  // Manejo de errores  
  console.error('Error:', result);  
} else {  
  // Manejo de un resultado exitoso  
  console.log('Éxito:', result);  
}

También puedes crear un tipo de utilidad "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'));  
}

// Luego úsalo así:
const result = await api.someMethod();

if (isErrorResult(result)) {  
  // Manejo de errores  
  console.error('Ocurrió un error:', result);  
} else {  
  // Manejo de un resultado exitoso  
  console.log('Resultado exitoso:', result);  
}

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

📚 Próximos Pasos​

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