Instalação

Para começar a utilizar o Public SDK, instale o pacote via npm:

1npm install @uappi/public-sdk

📦 Pré-requisitos

Antes de instalar, recomendamos que seu projeto tenha:

• TypeScript
• Ambiente configurado com Vite
• Vue 3, apenas se você for usar os componentes

O Vue é uma peerDependency opcional: os módulos Api e Tracking não dependem dele.

⚠️ Atenção

O pacote é publicado como .ts/.vue sem etapa de build. Os módulos usam APIs do navegador (window, sessionStorage), então não rodam em Node nem em SSR. O Tracking e o PaymentHosted leem import.meta.env, o que exige um bundler no estilo Vite.

🚪 Pontos de entrada

Import	Conteúdo	Precisa de Vue?
@uappi/public-sdk	Tudo: módulos e componentes	Sim
@uappi/public-sdk/modules/Api	Módulo Api	Não
@uappi/public-sdk/modules/Tracking	Módulo Tracking	Não
@uappi/public-sdk/components	Componentes Vue	Sim
@uappi/public-sdk/modules/Api/types	Tipos do módulo Api	Não

A raiz reexporta os componentes, então importar dela puxa o Vue mesmo que você use só o Api. Em projetos sem Vue (React, Svelte, vanilla), importe pelo caminho do módulo:

1import Api from '@uappi/public-sdk/modules/Api';
2import Tracking from '@uappi/public-sdk/modules/Tracking';

⚙️ Configuração inicial

O SDK funciona de forma plug and play na maioria dos casos.

Ao importar os módulos, você já terá:

• Persistência de dados automática
• Integração com a API Pública
• Suporte a tracking (quando aplicável)

As requisições são feitas para /api/v3 no mesmo domínio em que a aplicação está rodando. Em localhost e 127.0.0.1, o SDK envia o header uappi-environment: development.

Variáveis de ambiente

🍪 Nome do cookie de autenticação

O SDK envia o header Uappi-Cookie-Name em toda requisição, com o valor token por padrão.

Para usar outro cookie, acesse a loja com ?setCookieName=. O SDK captura o valor, grava em sessionStorage (chave uappi-cookie-name) e passa a enviá-lo a partir dali. Como o sessionStorage é por aba, cada aba do navegador mantém sua própria sessão.

Nomes aceitos: ^[A-Za-z0-9_-]{1,64}$. Um valor fora desse formato é ignorado.

1import { Api } from '@uappi/public-sdk';
2
3// Nome do cookie em uso na aba atual
4Api.getCookieName();
5
6// A captura da URL acontece na primeira requisição. Se a aplicação limpa a
7// query string no boot (ex: router com replace), chame antes disso:
8Api.captureCookieName();

🔄 Migrando para a versão 2.x

A versão 2.0.0 removeu o tipo ApiResponse. Todos os métodos retornam Promise com o dado da resposta, e o estado reativo fica a cargo da aplicação. Se o seu projeto importa ApiResponse, declare um tipo próprio.

🏁 Próximo passo

SDK Público: como usar