Comece

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:

1️⃣ Instale o pacote

  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.

---

✨ Principais Recursos

🔐

Autenticação Segura

Gerenciamento de token embutido e suporte a OAuth

🌍

Multilíngue

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

📝

TypeScript

Definições de tipo completas para melhor DX

⚡

Leve

Tamanho de pacote otimizado para produção

🔌

Arquitetura Modular

24 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

📖 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,  
  FileUploading,  
  Forms,  
  FormData,  
  GeneralTypes,  
  IntegrationCollections,  
  Locales,  
  Menus,  
  Orders,  
  Pages,  
  Payments,  
  ProductStatuses,  
  Products,  
  Settings,  
  System,  
  Templates,  
  TemplatePreviews,  
  Users,  
  WS  
} = defineOneEntry('sua-url', config);  

Ou

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 tiver passado 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.
• '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 refresh. 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

1. Faça login na sua conta pessoal
2. Vá para a aba "Projetos" e selecione um projeto
3. Vá para a aba "Acesso"
4. Ative o interruptor para "Token de API de Segurança"
5. Faça login no projeto, vá para a seção de configurações e abra a aba de token
6. 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'
  },
});

Validação da Resposta da API

O SDK do OneEntry inclui validação opcional das 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 tipo ao trabalhar com respostas da API.

Recursos

• Opcional: A validação está desativada por padrão e pode ser ativada por configuração
• Segurança de tipo: Usa esquemas Zod que se alinham com interfaces TypeScript
• Dois modos: Modo suave (registra erros) e modo estrito (retorna erros)
• Zero sobrecarga em tempo de execução quando desativado: Sem impacto no desempenho se a validação estiver desligada

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 da 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, os 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 seu aplicativo.

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 seu aplicativo 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 facilita muito o acesso a 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 Raw (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

---

Erros

Se você quiser escapar erros dentro do sc, mantenha 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ê precisará 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 ocorre um erro nas 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 do seu aplicativo 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 o aplicativo 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 utilitário do tipo "IError" para verificar erros:

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

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

---

📚 Próximos Passos

Explore nossos guias abrangentes para saber mais:

🛍️

E-commerce

Construa catálogos de produtos com filtragem e pesquisa

👤

Gerenciamento de Usuários

Implemente autenticação e perfis de usuário

🛒

Pedidos e Checkout

Processar pedidos e gerenciar pagamentos

📄

Páginas e Conteúdo

Gerencie páginas dinâmicas e estruturas de conteúdo

📝

Formulários

Saiba como lidar com formulários

📝

Dados de Formulários

Saiba como lidar com dados de formulários

---