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('sua-url-do-projeto', {
    token: 'seu-token-da-api'
  });

3️⃣ Comece a usar a API

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

  // Obter perfil do usuário
  const user = await api.Users.getUser();

  // Enviar um formulário
  const formData = await api.FormData.postFormsData('formulario-contato', {
    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-do-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('sua-url', config);  

Ou

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

const api = defineOneEntry('sua-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".
• '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://meu-projeto.oneentry.cloud', {  
  token: 'meu-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://meu-projeto.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('meu.token.de.acesso').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('sua-url', {  
  token: 'meu-token',  
  langCode: 'meu-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 tipos 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://seu-projeto.oneentry.cloud', {  
  token: 'seu-token',  
  validation: {  
    enabled: true,        // Ativar validação (padrão: false)  
    strictMode: false,    // Modo estrito (padrão: false)  
    logErrors: true,      // Registrar erros de validação (padrão: true)  
  }  
})  

Opções de Configuração

Opção	Tipo	Padrão	Descrição
enabled	boolean	false	Ativar/desativar 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	Registrar 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://seu-projeto.oneentry.cloud', {  
  token: 'seu-token',  
  validation: {  
    enabled: true,  
    strictMode: false,  // Modo suave  
    logErrors: true,  
  }  
})

// Mesmo que a validação falhe, você receberá a resposta da API
const user = await api.Users.getUser()
// O console mostrará erros de validação, se houver

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://seu-projeto.oneentry.cloud', {  
  token: 'seu-token',  
  validation: {  
    enabled: true,  
    strictMode: true,   // Modo estrito  
    logErrors: true,  
  }  
})

const user = await api.Users.getUser()

// Verifique se a resposta é um erro
if ('statusCode' in user) {  
  console.error('Validação falhou:', user.message)  
} else {  
  // Segurança de tipo: user é IUserEntity  
  console.log('Usuário:', user.email)  
}

---

Erros

Se você quiser escapar de erros dentro do sc, mantenha a propriedade "errors" como 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" como "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('sua-url', {  
  token: 'meu-token',  
  langCode: 'meu-langCode',  
  errors: {  
    isShell: false,  
    customErrors: {  
      400: (error) => console.error('Requisição Inválida:', error.message),  
      401: (error) => console.error('Não Autorizado:', error.message),  
      403: (error) => console.error('Proibido:', error.message),  
      404: (error) => console.error('Não Encontrado:', error.message),  
      429: (error) => console.error('Limite de Taxa Excedido:', error.message),  
      500: (error) => console.error('Erro do Servidor:', error.message),  
      502: (error) => console.error('Gateway Inválido:', error.message),  
      503: (error) => console.error('Serviço Indisponível:', error.message),  
      504: (error) => console.error('Tempo Limite do Gateway:', 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 em seu código de aplicativo para tratar erros:

try {  
  const result = await api.someMethod();  
  // Tratamento de um resultado bem-sucedido  
} catch (error) {  
  // Tratamento de erro  
}

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) { // Assume a presença de uma propriedade statusCode no objeto de erro  
  // Tratamento de erro  
} else {  
  // Tratamento de um resultado bem-sucedido  
}

Assim, isShell: false permite um modelo de tratamento de erro 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 na interface sem usar try/catch:

Verifique o tipo de retorno após chamar um método da API:

const result = await api.someMethod();

// Verifique se o resultado é um erro
if ('statusCode' in result || 'message' in result) {  
  // Tratamento de erro  
  console.error('Erro:', result);  
} else {  
  // Tratamento de um resultado bem-sucedido  
  console.log('Sucesso:', result);  
}

Você também pode criar um tipo de utilitário "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'));  
}

// Então use assim:
const result = await api.someMethod();

if (isErrorResult(result)) {  
  // Tratamento de erro  
  console.error('Ocorreu um erro:', result);  
} else {  
  // Tratamento de um resultado bem-sucedido  
  console.log('Resultado bem-sucedido:', 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

---