Como Autenticar
A API trabalha com autenticação por meio de assinatura de um Json Web Token (JWT) e fornece 2 maneiras de se autenticar.
Tipos de Autenticação
1. Autenticação via cookie
Normalmente essa opção é usada por aplicações frontends que são executadas de forma públicas em navegadores (store‑fronts, checkout, etc.) para armazenar o token de forma segura em um cookie de navegador configurado com HttpOnly, Secure e SameSite=Strict.
Envie o seguinte header nas requisições feitas por sua aplicação:
1Uappi-Cookie-Name: cookie-nameO backend criará/atualizará um cookie com o nome informado e o retornará no cabeçalho Set-Cookie. O valor "cookie-name" é apenas um exemplo — escolha qualquer nome que sua aplicação prefira; a API usará esse nome para ler/escrever o cookie correspondente ao cliente/usuário. Sempre use HTTPS e evite expor o cookie em URLs ou logs.
1.1 Logout
Como a autenticação via cookie é gerenciada pela API UAPPI, o backend é responsável por criar, atualizar e remover o cookie de autenticação conforme necessário. Para encerrar a sessão do usuário e excluir o cookie de autenticação de forma segura, utilize esse endpoint de logout:https://sua-loja-uappi.com.br/api/v3/logout
Remove o cookie gerado de autenticação!
2. Autenticação via cabeçalho de autorização
Essa é a opção mais tradicional, indicada para aplicações server‑side (ERPs, CRMs, integrações back‑end). Envie o header Authorization com o esquema Bearer contendo o token (normalmente um JWT):
1Authorization: Bearer <token>Boas práticas:
- Use sempre HTTPS ao transmitir tokens.
- Não registre tokens em logs nem exponha em URLs.
- Tokens podem expirar; trate respostas 401 para renovar/reauthenticar.
- A API valida assinatura e claims do JWT (por exemplo, exp, iss, aud).
- Prefira flows com refresh tokens quando necessário para sessões longas.
🙋🏽 Autenticação como usuário:
Existem recursos que exigem a autenticação de um usuário para serem executados, para isso você vai precisar ter um usuário cadastrado na loja desejada. Após adquirir esse usuário, basta seguir com o Login de Usuário.
🙋🏼♀️ Autenticação como cliente:
Também existem recursos que exigem a autenticação de um cliente para serem executados, para isso você vai precisar ter um cliente cadastrado na loja desejada. Após adquirir esse cliente, basta seguir com o Login de clientes.
⚠️ Possíveis erros no processo de autenticação:
O Processo de autenticação pode resultar em alguns erros, aqui temos alguns deles que pode ajudar a entender o problema:
| Código Interno | Código Http | Descrição |
|---|---|---|
| UAPPI_AUTH_INVALID_USER | 401 | O recurso solicitado precisa de um usuário autenticado. |
| UAPPI_AUTH_DISABLED_USER | 403 | O usuário em questão foi desabilitado. |
| UAPPI_AUTH_USER_NOT_FOUND | 404 | O usuário não foi encontrado. |
| EXPIRED_AUTH_TOKEN | 401 | O Token de autenticação expirou. |
| INVALID_AUTH_TOKEN | 401 | O Token de autenticação não é válido. |
| INVALID_AUTH_HOST | 403 | O Token de autenticação não pertece a loja requisitada. |
| INVALID_CUSTOMER | 401 | O recurso solicitado precisa de um cliente autenticado. |
| UAPPI_STORE_CUSTOMER_NOT_FOUND | 404 | O cliente não foi encontrado. |