Comece

Name: OneEntry SDK
Author: OneEntry

O SDK da Plataforma OneEntry é um SDK que fornece uma maneira fácil de interagir com a API da Plataforma OneEntry.

🚀 Início Rápido

Comece a usar o OneEntry em 3 passos simples:

Instalação

  npm install oneentry

2️⃣ Inicialize o SDK

  import { defineOneEntry } from 'oneentry';

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

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

🎉 É isso! Você está pronto para construir aplicações incríveis com o OneEntry.

Usando TypeScript? Todos os tipos públicos são exportados da raiz do pacote e de oneentry/types — import type { IProductsEntity } from 'oneentry'. Veja Importando Tipos.

✨ Principais Recursos

🔐

Autenticação Segura

Gerenciamento de tokens embutido e suporte a OAuth

🌍

Multilíngue

Suporte a i18n com detecção automática de idioma

📝

TypeScript

Definições de tipo completas, importáveis da raiz do pacote

⚡

Leve

Build ESM com tree-shaking — 9.7 kB gzip em uma configuração típica

🔌

Arquitetura Modular

28 módulos especializados para todas as suas necessidades

🛡️

Tratamento de Erros

Manipuladores de erro personalizados e modo shell

🌐 Recursos

🌍

Site Oficial

Saiba mais sobre a Plataforma OneEntry

🚀

Inscreva-se

Crie sua conta gratuita

💻

Npmjs

Baixe o SDK

🧪

Sandbox do SDK JS

Experimente os métodos do SDK ao vivo no seu navegador — sem configuração necessária

📖 Uso Detalhado

Todos os Módulos Disponíveis

Importe e desestruture todos os módulos que você precisa:


import { defineOneEntry } from 'oneentry'

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

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

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

Configuração

O segundo parâmetro do construtor recebe a 'config'. Ele contém os seguintes valores:

'token' - Defina a chave do token se seu projeto exigir "Token de API de Segurança". Se você estiver usando proteção por certificado, não passe esta variável. Você pode ler mais sobre a segurança do seu projeto aqui.
'langCode' - Defina o "langCode" para definir o idioma padrão. Ao especificar este parâmetro uma vez, você não precisa passar o langCode para os métodos da API ONEENTRY. Se você não passar o idioma padrão, ele será definido como "en_US".
'traficLimit' - Alguns métodos usam mais de uma solicitação para o OneEntry para que os dados que você recebe sejam completos e fáceis de trabalhar. Passe o valor "true" para este parâmetro para economizar tráfego e decidir por si mesmo quais dados você precisa. O valor padrão é "false".
'rawData' - Quando definido como false (padrão), o SDK transforma automaticamente o array additionalFields em um objeto indexado por marker para facilitar o acesso. Defina como true para receber additionalFields como o array original da API.
'guestId' - Um identificador de visitante opcional enviado como o cabeçalho x-guest-id em solicitações não autenticadas, permitindo fluxos de carrinho/lista de desejos/atividade de visitantes. No navegador, se omitido, um id estável por dispositivo é gerado e persistido em localStorage. No servidor, você deve passar um guestId por visitante. Veja Modo Visitante abaixo. O valor padrão é undefined.
'deviceMetadata' - Uma string opcional enviada como o cabeçalho x-device-metadata (em solicitações POST e atualização de token) em vez da impressão digital que o SDK calcula a partir do ambiente atual. A API vincula tokens de atualização a este cabeçalho, então um servidor que emite tokens em nome de um navegador deve carimbar a impressão digital do navegador aqui. Veja Metadados do Dispositivo abaixo. O valor padrão é undefined.
'auth' - Um objeto com configurações de autorização. Por padrão, o SDK é configurado para trabalhar com tokens dentro da sessão do usuário e não requer nenhum trabalho adicional de sua parte. Ao mesmo tempo, o SDK não armazena o estado da sessão entre sessões. Se você estiver satisfeito com essas configurações, não passe a variável 'auth' de forma alguma.

O 'auth' contém as seguintes configurações:

'refreshToken' - O token de atualização do usuário. Transfira-o aqui do repositório para restaurar a sessão do usuário durante a inicialização.
'saveFunction' - Uma função que trabalha com a atualização do token de atualização. Se você quiser armazenar o token entre sessões, por exemplo, no armazenamento local, passe uma função aqui que faça isso. A função deve aceitar um parâmetro ao qual a string com o token será passada.
'customAuth' - Se você quiser configurar a autorização e trabalhar com tokens por conta própria, defina este sinalizador como verdadeiro. Se você quiser usar as configurações do sdk, defina como falso ou não a transfira de forma alguma.
'providerMarker' - O marcador para o provedor de autenticação. Padrão: 'email'. Um exemplo de configuração com proteção por token e autenticação automática que armazena o estado entre sessões

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

Um exemplo de configuração que é protegida por um certificado permite que você configure o sistema de autorização por conta própria e salve dados em solicitações.

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

Se você optou por configurar tokens por conta própria, pode passar o token para o método da seguinte forma. O método intermediário permite que você passe um token de acesso para a solicitação. Em seguida, chame o método necessário. Este método (setAccessToken) não deve ser chamado se o método não exigir autorização do usuário.

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

Se você escolheu a proteção por token para garantir a segurança da conexão, basta passar seu token para a função como um parâmetro opcional.

Você pode obter um token da seguinte forma

Faça login na sua conta pessoal
Vá para a aba "Projetos" e selecione um projeto
Vá para a aba "Acesso"
Defina o interruptor para "Token de API de Segurança"
Faça login no projeto, vá para a seção de configurações e abra a aba de token
Obtenha e copie o token do seu projeto

Você também pode conectar um certificado tls para proteger seu projeto. Nesse caso, não passe o "token" de forma alguma. Ao usar o certificado, configure um proxy em seu projeto. Passe uma string vazia como parâmetro de url. Saiba mais sobre o 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 Visitante

O SDK pode agir em nome de um visitante não autenticado. Quando nenhum token de acesso é definido, ele envia um cabeçalho x-guest-id nas solicitações, o que permite que endpoints cientes de visitantes funcionem sem um usuário logado - os fluxos de carrinho, lista de desejos e atividade do usuário, assim como os blocos de personalização (recentemente visualizados, recomendações pessoais, e outros).

Como o id do visitante é resolvido:

Um guestId configurado explicitamente (de config.guestId ou setGuestId) sempre prevalece.
No navegador, quando nenhum é fornecido, um id estável é gerado (via Web Crypto quando disponível) e persistido em localStorage sob a chave oneentry_guest_id, espelhando a estratégia de metadados do dispositivo. Ele permanece estável entre sessões e abas.
Caso contrário, o id é undefined e o cabeçalho x-guest-id é simplesmente omitido.

⚠️ Lado do servidor: o SDK nunca gera automaticamente um id de visitante no servidor. Uma única instância compartilhada de defineOneEntry vazaria um carrinho/lista de desejos de visitante entre todos os visitantes anônimos. No servidor, você deve passar um guestId por visitante você mesmo (via config.guestId ou setGuestId).

O cabeçalho é omitido para solicitações autenticadas (quando um token de acesso é definido), então um usuário logado sempre opera em seus próprios dados.

Definindo o id do visitante na inicialização

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

Definindo ou limpando o id do visitante em tempo de execução

setGuestId funciona como setAccessToken - é encadeável e retorna a instância do módulo. Passe uma string vazia para limpá-lo (o SDK então recai sobre o id baseado em localStorage no navegador, ou sobre nenhum id de visitante no 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('');

Metadados do Dispositivo

O SDK envia um cabeçalho x-device-metadata em solicitações POST e na atualização de token. Por padrão, é uma impressão digital calculada a partir do ambiente atual (plataforma, agente do usuário, idioma, tela, fuso horário, além de um id de instância persistente), usada pela API para análises e prevenção de fraudes.

A API vincula tokens de atualização a este cabeçalho. Um token de atualização emitido enquanto uma impressão digital foi enviada só pode ser atualizado enquanto a mesma impressão digital for enviada — que é exatamente o problema quando o token é emitido no servidor em nome de um navegador (por exemplo, uma troca de código OAuth que mantém o segredo do cliente no lado do servidor): o token ficaria vinculado à impressão digital do servidor e o navegador nunca poderia atualizá-lo.

deviceMetadata resolve isso: o servidor carimba a impressão digital do navegador, e o token de atualização emitido permanece atualizável a partir daquele navegador.

Lendo o valor no navegador

getDeviceMetadata() está disponível em todos os módulos e retorna a string exata que o SDK envia — a substituição se uma for definida, caso contrário, a impressão 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 }),
});

Definindo a substituição

Passe-a na inicialização:

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

Ou defina-a em tempo de execução com setDeviceMetadata(deviceMetadata) — disponível em todos os módulos e encadeável, como setAccessToken. Passar uma string vazia limpa a substituição e recai sobre a impressão 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	Descrição
`getDeviceMetadata()`	`string`	A string `x-device-metadata` que esta instância envia (substituição ou impressão digital calculada)
`setDeviceMetadata(value)`	instância do módulo	Define a substituição; uma string vazia a limpa

Validação de Resposta da API

O SDK OneEntry inclui validação opcional de respostas da API usando Zod, uma biblioteca de validação de esquema voltada para TypeScript. Este recurso ajuda a garantir a integridade dos dados e a segurança de tipos ao trabalhar com respostas da API.

Recursos

Opcional: A validação está desativada por padrão e pode ser ativada por configuração
Segura em termos de tipo: Usa esquemas Zod que se alinham com interfaces TypeScript
Dois modos: Modo suave (registra erros) e modo estrito (retorna erros)
Custo zero quando desativado: Zod e os esquemas de resposta são carregados sob demanda — na primeira vez que uma resposta realmente precisa ser validada. Com a validação desativada, eles nunca chegam ao seu pacote (veja Tamanho do Pacote & Formatos de Módulo)

Configuração

Ative a validação adicionando a propriedade validation à sua configuração do 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)
  }
})

Opções de Configuração

Opção	Tipo	Padrão	Descrição
`enabled`	`boolean`	`false`	Ativar/desativar a validação de resposta
`strictMode`	`boolean`	`false`	Quando `true`, retorna `IError` em caso de falha na validação. Quando `false`, registra erros e retorna os dados originais
`logErrors`	`boolean`	`true`	Registra erros de validação no console (útil para depuração)

Modos de Validação

Modo Suave (Padrão)

Quando strictMode é false, erros de validação são registrados no console, mas a resposta original da API é retornada inalterada. Isso é útil durante o desenvolvimento para identificar possíveis inconsistências de dados sem quebrar sua aplicação.

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 Estrito

Quando strictMode é true, falhas de validação retornam um objeto IError em vez dos dados. Isso garante que sua aplicação processe apenas dados 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 Adicionais

Por padrão, o SDK transforma a propriedade additionalFields de um array (como retornado pela API) em um objeto indexado por marker. Isso torna muito mais fácil acessar campos específicos sem saber seu índice.

Comportamento Padrão (`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 Cru (`rawData: true`)

Se você precisar do formato original da resposta da API (por exemplo, para compatibilidade retroativa), defina 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)

Opção de Configuração

Opção	Tipo	Padrão	Descrição
`rawData`	`boolean`	`false`	Quando `false`, `additionalFields` é transformado em um objeto indexado por `marker`. Quando `true`, o array original da API é retornado

O restante da normalização que o SDK aplica aos valores de atributos - desdobramento de arquivo único, conversão numérica, null para valores não definidos, ordenação por position - é descrito em Valores de Atributos.

Erros

Se você quiser escapar de erros dentro do sc, deixe a propriedade "errors" por padrão. Nesse caso, você receberá os dados da entidade ou o objeto de erro. Você precisa fazer uma verificação de tipo. por exemplo, verificando a propriedade statusCode com ".hasOwnProperty"

No entanto, se você quiser usar a construção "try catch(e) ", defina a propriedade "isShell" para o valor "false". Nesse caso, você precisa tratar o erro usando "try catch(e) ".

Além disso, você pode passar funções personalizadas que serão chamadas dentro do sdk com o código de erro apropriado. Essas funções recebem um objeto de erro como argumento. Você pode processá-lo por conta própria.

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

Quando a opção isShell: false é definida na configuração do SDK, ela tem o seguinte efeito:

Quando um erro ocorre em solicitações da API (por exemplo, erros HTTP 400, 401, 404, 500, etc., ou erros de rede), o SDK lançará uma exceção em vez de retornar o objeto de erro como um valor normal.

Isso permite que você use a construção try/catch no código da sua aplicação para tratar erros:

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

Se isShell: true, os erros são retornados como valores, e você precisará verificar explicitamente o tipo do 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
}

Assim, isShell: false permite um modelo de tratamento de erros mais familiar com try/catch, enquanto isShell: true fornece um modelo plano onde erros e sucessos são retornados como valores do mesmo tipo.

Ao usar o SDK com a configuração padrão (isShell definido como true), os erros são retornados como valores em vez de lançados como exceções. Isso significa que a aplicação não travará devido a exceções não tratadas, pois os erros são tratados como parte do fluxo normal de execução. Aqui está como você pode tratar erros no front-end sem usar try/catch:

Verifique o tipo de retorno após chamar um método da 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);
}

Você também pode criar um tipo de utilitário "IError" para verificar erros:

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

Essa abordagem permite que você evite usar construções try/catch enquanto ainda trata erros corretamente, prevenindo que a aplicação trave.

📚 Próximos Passos

Explore nossos guias abrangentes para saber mais:

🛍️

🚀 Início Rápido​

Instalação​

2️⃣ Inicialize o SDK​

3️⃣ Comece a usar a API​

✨ Principais Recursos​

🌐 Recursos​

📖 Uso Detalhado​

Todos os Módulos Disponíveis​

Configuração​

Você pode obter um token da seguinte forma​

Modo Visitante​

Definindo o id do visitante na inicialização​

Definindo ou limpando o id do visitante em tempo de execução​

Metadados do Dispositivo​

Lendo o valor no navegador​

Definindo a substituição​

Validação de Resposta da API​

Recursos​

Configuração​

Opções de Configuração​

Modos de Validação​

Modo Suave (Padrão)​

Modo Estrito​

Formato de Campos Adicionais​

Comportamento Padrão (rawData: false)​

Modo Cru (rawData: true)​

Opção de Configuração​

Erros​

Quando a opção isShell: false é definida na configuração do SDK, ela tem o seguinte efeito:​

📚 Próximos Passos​

E-commerce

Gerenciamento de Usuários

Pedidos & Checkout

Páginas & Conteúdo

Formulários

Dados de Formulários

Importando Tipos

Tamanho do Pacote

Valores de Atributos

Intervalos de Tempo

🚀 Início Rápido

Instalação

2️⃣ Inicialize o SDK

3️⃣ Comece a usar a API

✨ Principais Recursos

🌐 Recursos

📖 Uso Detalhado

Todos os Módulos Disponíveis

Configuração

Você pode obter um token da seguinte forma

Modo Visitante

Definindo o id do visitante na inicialização

Definindo ou limpando o id do visitante em tempo de execução

Metadados do Dispositivo

Lendo o valor no navegador

Definindo a substituição

Validação de Resposta da API

Recursos

Configuração

Opções de Configuração

Modos de Validação

Modo Suave (Padrão)

Modo Estrito

Formato de Campos Adicionais

Comportamento Padrão (`rawData: false`)

Modo Cru (`rawData: true`)

Opção de Configuração

Erros

Quando a opção isShell: false é definida na configuração do SDK, ela tem o seguinte efeito:

📚 Próximos Passos