Comenzar

Name: OneEntry SDK
Author: OneEntry

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

Ponte en marcha con OneEntry en 3 simples pasos:

Instalación

  npm install oneentry

2️⃣ Inicializa el SDK

  import { defineOneEntry } from 'oneentry';

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

3️⃣ Comienza 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ás listo para construir aplicaciones increíbles con OneEntry.

¿Usando TypeScript? Cada tipo público se exporta desde la raíz del paquete y desde oneentry/types — import type { IProductsEntity } from 'oneentry'. Consulta Importando Tipos.

✨ 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, importables desde la raíz del paquete

⚡

Ligero

Construcción ESM que se puede optimizar — 9.7 kB gzip en una configuración típica

🔌

Arquitectura Modular

28 módulos especializados para todas tus necesidades

🛡️

Manejo de Errores

Manejadores de errores personalizados y modo shell

🌐 Recursos

🌍

Sitio Oficial

Aprende más sobre la Plataforma OneEntry

🚀

Regístrate

Crea tu cuenta gratuita

💻

Npmjs

Descargar SDK

🧪

Sandbox del SDK de JS

Prueba los métodos del SDK en vivo en tu navegador — sin configuración requerida

📖 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-aplicación',
}
const {
  Admins,
  AttributesSets,
  AuthProvider,
  Blocks,
  Events,
  Filters,
  FileUploading,
  Forms,
  FormData,
  GeneralTypes,
  IntegrationCollections,
  Locales,
  Menus,
  Orders,
  Pages,
  Payments,
  ProductStatuses,
  Products,
  Search,
  Subscriptions,
  Settings,
  System,
  Templates,
  TemplatePreviews,
  UserActivity,
  Users,
  WS
} = defineOneEntry('tu-url', config);

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' - 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".
'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. Establece en true para recibir additionalFields como el array original de la API.
'guestId' - Un identificador de invitado opcional enviado como el encabezado x-guest-id en solicitudes no autenticadas, habilitando flujos de carrito/lista de deseos/actividad de invitados. En el navegador, si se omite, se genera un id estable por dispositivo y se persiste en localStorage. En el servidor, debes pasar un guestId por visitante. Consulta Modo invitado a continuación. El valor predeterminado es undefined.
'deviceMetadata' - Una cadena opcional enviada como el encabezado x-device-metadata (en solicitudes POST y actualización de token) en lugar de la huella digital que el SDK calcula desde el entorno actual. La API vincula los tokens de actualización a este encabezado, por lo que un servidor que emite tokens en nombre de un navegador debe sellar la huella digital del navegador aquí. Consulta Metadatos del dispositivo a continuación. El valor predeterminado es undefined.
'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.

El 'auth' contiene las siguientes configuraciones:

'refreshToken' - El token de actualización del usuario. Transfié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://my-project.oneentry.cloud', {
  token: 'my-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://my-project.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('my.access.token').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

Inicia sesión en tu cuenta personal
Ve a la pestaña "Proyectos" y selecciona un proyecto
Ve a la pestaña "Acceso"
Activa el interruptor "Token de API de Seguridad"
Inicia sesión en el proyecto, ve a la sección de configuración y abre la pestaña de token
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('your-url', {
  token: 'my-token',
  langCode: 'my-langCode',
  auth: {
    customAuth: false,
    userToken: 'rerfesh.token',
    saveFunction: saveTokenFromLocalStorage,
    providerMarker: 'email'
  },
});

Modo Invitado

El SDK puede actuar en nombre de un invitado no autenticado. Cuando no se establece un token de acceso, envía un encabezado x-guest-id en las solicitudes, lo que permite que los puntos finales conscientes de invitados funcionen sin un usuario conectado - los flujos de carrito, lista de deseos y actividad del usuario, así como los bloques de personalización (recientemente visto, recomendaciones personales, y otros).

Cómo se resuelve el id de invitado:

Un guestId configurado explícitamente (de config.guestId o setGuestId) siempre tiene prioridad.
En el navegador, cuando no se proporciona ninguno, se genera un id estable (a través de Web Crypto cuando está disponible) y se persiste en localStorage bajo la clave oneentry_guest_id, reflejando la estrategia de metadatos del dispositivo. Se mantiene estable a través de sesiones y pestañas.
De lo contrario, el id es undefined y el encabezado x-guest-id simplemente se omite.

⚠️ Del lado del servidor: el SDK nunca genera automáticamente un id de invitado en el servidor. Una única instancia compartida de defineOneEntry de otro modo filtraría un carrito/lista de deseos de invitados entre todos los visitantes anónimos. En el servidor, debes pasar un guestId por visitante tú mismo (a través de config.guestId o setGuestId).

El encabezado es omitido para solicitudes autenticadas (cuando se establece un token de acceso), por lo que un usuario conectado siempre opera sobre sus propios datos.

Estableciendo el id de invitado en la inicialización

const api = defineOneEntry('https://my-project.oneentry.cloud', {
  token: 'my-token',
  guestId: 'visitor-123', // per-visitor id, required on the server
});

Estableciendo o limpiando el id de invitado en tiempo de ejecución

setGuestId funciona como setAccessToken - es encadenable y devuelve la instancia del módulo. Pasa una cadena vacía para limpiarlo (el SDK luego vuelve al id respaldado por localStorage en el navegador, o a no tener id de invitado en absoluto en el servidor).

// Set the guest id, then call a guest-aware method
const cart = await api.Users.setGuestId('visitor-123').getCart();

// Clear the guest id
api.Users.setGuestId('');

Metadatos del Dispositivo

El SDK envía un encabezado x-device-metadata en solicitudes POST y en la actualización de token. Por defecto, es una huella digital calculada desde el entorno actual (plataforma, agente de usuario, idioma, pantalla, zona horaria, más un id de instancia persistente), utilizada por la API para análisis y prevención de fraude.

La API vincula los tokens de actualización a este encabezado. Un token de actualización emitido mientras se envió una huella digital puede ser refrescado solo mientras se envía la misma huella digital — lo que es exactamente el problema cuando el token se emite en el servidor en nombre de un navegador (por ejemplo, un intercambio de código OAuth que mantiene el secreto del cliente del lado del servidor): el token estaría vinculado a la huella digital del servidor y el navegador nunca podría refrescarlo.

deviceMetadata resuelve esto: el servidor sella la huella digital del navegador, y el token de actualización emitido permanece refrescable desde ese navegador.

Leyendo el valor en el navegador

getDeviceMetadata() está disponible en cada módulo y devuelve la cadena exacta que el SDK envía — la sobreescritura si se establece una, de lo contrario la huella digital calculada:

// Browser: obtain the fingerprint and forward it to your backend
const deviceMetadata = api.Users.getDeviceMetadata();

await fetch('/api/oauth/exchange', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ code, deviceMetadata }),
});

Estableciendo la sobreescritura

Pásalo en la inicialización:

const api = defineOneEntry('https://my-project.oneentry.cloud', {
  token: 'my-token',
  deviceMetadata, // the string forwarded from the browser
});

O configúralo en tiempo de ejecución con setDeviceMetadata(deviceMetadata) — disponible en cada módulo y encadenable, como setAccessToken. Pasar una cadena vacía limpia la sobreescritura y vuelve a la huella digital calculada:

// Server: issue tokens bound to the browser's fingerprint
const auth = await api.AuthProvider
  .setDeviceMetadata(deviceMetadata)
  .auth('email', authData);

// Clear the override
api.AuthProvider.setDeviceMetadata('');

Método	Retorna	Descripción
`getDeviceMetadata()`	`string`	La cadena `x-device-metadata` que esta instancia envía (sobreescritura, o huella digital calculada)
`setDeviceMetadata(value)`	instancia del módulo	Establece la sobreescritura; una cadena vacía la limpia

Validación de Respuestas de API

El SDK de OneEntry incluye validación opcional de respuestas de API usando Zod, una biblioteca de validación de esquemas orientada a TypeScript. Esta característica 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 costo cuando está desactivado: Zod y los esquemas de respuesta se cargan bajo demanda — la primera vez que una respuesta realmente tiene que ser validada. Con la validación desactivada, nunca llegan a tu paquete (consulta Tamaño del Paquete y Formatos de Módulo)

Configuración

Habilita la validación agregando la propiedad validation a la configuración de tu 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`	Registra 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://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 tu 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 por Defecto (`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 necesitas el formato original de respuesta de la API (por ejemplo, por compatibilidad hacia atrás), establece 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

El resto de la normalización que el SDK aplica a los valores de atributos - desempaquetado de un solo archivo, conversión numérica, null para valores no establecidos, ordenación por position - se describe en Valores de Atributos.

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('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 te permite usar la construcción try/catch en tu código de 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ás 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 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();

// 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 puedes crear un tipo de utilidades "IError" para verificar errores:

import type { IError } from 'oneentry';

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 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:

🛍️

🚀 Inicio Rápido​

Instalación​

2️⃣ Inicializa el SDK​

3️⃣ Comienza a usar la API​

✨ Características Clave​

🌐 Recursos​

📖 Uso Detallado​

Todos los Módulos Disponibles​

Configuración​

Puedes obtener un token de la siguiente manera​

Modo Invitado​

Estableciendo el id de invitado en la inicialización​

Estableciendo o limpiando el id de invitado en tiempo de ejecución​

Metadatos del Dispositivo​

Leyendo el valor en el navegador​

Estableciendo la sobreescritura​

Validación de Respuestas de API​

Características​

Configuración​

Opciones de Configuración​

Modos de Validación​

Modo Suave (Predeterminado)​

Modo Estricto​

Formato de Campos Adicionales​

Comportamiento por Defecto (rawData: false)​

Modo Crudo (rawData: true)​

Opción de Configuración​

Errores​

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

📚 Próximos Pasos​

Comercio Electrónico

Gestión de Usuarios

Pedidos y Pago

Páginas y Contenido

Formularios

Datos de Formularios

Importando Tipos

Tamaño del Paquete

Valores de Atributos

Intervalos de Tiempo

🚀 Inicio Rápido

Instalación

2️⃣ Inicializa el SDK

3️⃣ Comienza a usar la API

✨ Características Clave

🌐 Recursos

📖 Uso Detallado

Todos los Módulos Disponibles

Configuración

Puedes obtener un token de la siguiente manera

Modo Invitado

Estableciendo el id de invitado en la inicialización

Estableciendo o limpiando el id de invitado en tiempo de ejecución

Metadatos del Dispositivo

Leyendo el valor en el navegador

Estableciendo la sobreescritura

Validación de Respuestas de API

Características

Configuración

Opciones de Configuración

Modos de Validación

Modo Suave (Predeterminado)

Modo Estricto

Formato de Campos Adicionales

Comportamiento por Defecto (`rawData: false`)

Modo Crudo (`rawData: true`)

Opción de Configuración

Errores

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

📚 Próximos Pasos