Token Delegado do Cliente (Admin)
Visão Geral
O token delegado é um token de cliente emitido para um usuário de integração 🔑. Com ele, a integração age em nome do cliente sem saber a senha dele: monta o carrinho, escolhe o endereço e conclui a compra, por exemplo num fluxo de compra rápida feito fora da loja.
Ele é o mesmo token de cliente do login, com três diferenças:
- Escopos limitados: só libera os grupos de rotas do cliente pedidos na emissão (veja Escopos do token do cliente abaixo).
- Validade curta: 30 minutos por padrão, com no máximo 1 hora.
- Marcado como delegado: o token leva
delegated: truee um identificador de sessão (jti), mantidos nos refreshes. PUT /customer/password(troca de senha)/customer/mfa/*(configuração do MFA)- MCP do cliente (
/customer/mcp) - CUSTOMER_READ: exigido por todas as rotas de clientes
- CUSTOMER_TOKEN_WRITE: necessário para emitir o token delegado
Como funciona
1. O usuário de integração chama POST /customers/{customerId}/generate-token com os escopos de que precisa.
2. A API valida o cliente (ativo e do canal de venda da requisição) e o carrinho.
3. O login fica registrado no histórico do cliente, como o login normal.
4. A resposta traz o token, que a integração usa no header Authorization: Bearer {token} das rotas públicas do cliente (/customer/, /cart/).
Carrinho do token
| Requisição | Carrinho do token |
|---|---|
Com cartId | O carrinho informado. Ele precisa ser do canal de venda da requisição e estar sem cliente vinculado ou vinculado ao mesmo cliente. Um carrinho sem cliente passa a ficar vinculado ao cliente no primeiro uso, com os itens que já tinha |
Sem cartId | O carrinho do cliente atualizado mais recentemente no canal de venda, o mesmo que o login do cliente usaria. Se o cliente não tiver carrinho, um novo é criado e vinculado a ele |
Quando o carrinho do token deixa de existir (por exemplo, depois de a compra ser concluída) ou a mesclagem devolve outro carrinho, a API devolve um token novo no header Refresh-Token, que deve substituir o anterior. Para o token delegado, esse token novo continua delegado, com o mesmo jti, os mesmos escopos e o mesmo vencimento: o refresh nunca estende a validade pedida na emissão.
Histórico do cliente
Cada emissão grava um registro no histórico do cliente com origin: authentication e action: login. O usuário de integração que emitiu o token fica em userId, userName e userEmail, e o campo after traz:
| Campo | Descrição |
|---|---|
sessionId | Identificador da sessão: o jti do token |
authenticatedAt | Data e hora da emissão (Y-m-d H:i:s) |
identification | E-mail do cliente |
authMethod | Sempre delegated-token |
Escopos do token do cliente
Toda rota do cliente logado exige um escopo, exceto a consulta do cadastro (GET /customer), que aceita qualquer token do cliente. O login do próprio cliente emite o token com o coringa *, que libera todas as rotas. O token delegado recebe só os escopos pedidos na emissão, e nunca o coringa.
| Escopo | Rotas liberadas |
|---|---|
customer | Cadastro do cliente: PUT e DELETE /customer, PUT /customer/flag, PUT /customer/additional-field e DELETE /customer/newsletter. Também libera os campos flags e additionalFields no GET /customer |
address | Endereços: /customer/address/* e PUT /cart/address |
documents | Documentos: /customer/document/* |
cards | Cartões salvos: /customer/cards/* |
orders | Pedidos: /customer/orders/* |
history | Histórico: GET /customer/history |
gift-cards | Gift cards: /customer/gift-cards/* |
wallet | Carteira: GET /customer/wallet/transaction e /cart/promotionals/customer-wallet |
point-system | Saldo de pontos no carrinho: /cart/promotionals/point-system |
wish-list | Listas de desejo: /customer/wish-list/* |
reviews | Avaliações e comentários: as rotas do cliente logado em /review (avaliações de produto e da loja) e DELETE /publics/products/comments/{commentId} |
GET /customer). Aceita qualquer token do cliente, inclusive o delegado com qualquer escopo, e devolve os dados básicos do cadastro. Os campos relacionais pedidos em fields continuam exigindo o escopo de cada dado:Campo (fields) | Escopo exigido |
|---|---|
addresses | address |
documents | documents |
flags | customer |
additionalFields | customer |
UAPPI_API_CUSTOMER_INSUFFICIENT_SCOPE (403).As rotas abaixo não têm escopo e só aceitam o login do próprio cliente (coringa). O token delegado nunca chega nelas:
O carrinho (/cart/*) não exige escopo, exceto as rotas listadas na tabela acima.
Quando o token não tem o escopo da rota, a resposta é o erro UAPPI_API_CUSTOMER_INSUFFICIENT_SCOPE (403).
> Tokens de cliente emitidos antes da existência dos escopos não têm a informação de escopo e continuam com acesso total, como o login do cliente.
Encerrando a sessão
O token delegado vence sozinho em expiresAt. Para encerrar antes, use a Revogação de Token do Cliente (POST /customers/{customerId}/revoke-token): ela derruba todos os tokens do cliente emitidos até o momento, incluindo os delegados.
Permissão
A emissão exige autenticação via middleware UserAuth de um usuário de integração e os escopos:
Usuários humanos recebem o erro UAPPI_API_CUSTOMER_TOKEN_INTEGRATION_ONLY (403), mesmo com os escopos.
A emissão aceita até 60 requisições por minuto para o mesmo usuário e o mesmo cliente. Acima disso, a resposta é THROTTLE_LIMIT_REACHED (429).
Emissão do Token Delegado do Cliente
/customers/{customerId}/generate-token
Endpoint responsável por emitir um token do cliente para o usuário de integração agir em nome dele
Descrição
Este endpoint permite ao usuário de integração obter um token do cliente para agir em nome dele nas rotas públicas do cliente e do carrinho, sem a senha do cliente.
- O token libera só os escopos informados em
scopes. O coringa*não é aceito. - A validade é de 30 minutos por padrão, com no máximo 1 hora (
ttlSeconds). - Sem
cartId, o token fica com o carrinho mais recente do cliente no canal de venda (criado, se ele não tiver nenhum). - Com um
cartIdsem cliente, o carrinho passa a ficar vinculado ao cliente no primeiro uso do token. - A emissão é registrada no histórico do cliente como um login (
authMethod: delegated-token).
Para entender o funcionamento completo e a lista de escopos, consulte a página Token Delegado do Cliente.
Permissão
Requer um usuário de integração com os escopos CUSTOMER_READ e CUSTOMER_TOKEN_WRITE.
Limite de 60 requisições por minuto para o mesmo usuário e o mesmo cliente.
Parâmetros
Headers Obrigatórios
| Header | Valor | Descrição |
|---|---|---|
Authorization | Bearer {userToken} | Token de autenticação do usuário de integração |
Content-Type | application/json | Tipo de conteúdo |
Parâmetros de URL
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| customerId | integer | Sim | ID do cliente em nome de quem o token é emitido |
Parâmetros do Corpo
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| scopes | string[] | Sim | Escopos liberados no token, sem repetição. Valores aceitos: customer, address, documents, cards, orders, history, gift-cards, wallet, point-system, wish-list, reviews |
| ttlSeconds | integer | Não | Validade do token, em segundos, de 1 a 3600. Padrão: 1800 (30 minutos) |
| cartId | string | Não | Carrinho que fica no token. Precisa ser do canal de venda da requisição e estar sem cliente ou vinculado ao mesmo cliente. Sem ele, é usado o carrinho mais recente do cliente |
1{2 "scopes": ["address", "cards"],3 "ttlSeconds": 900,4 "cartId": "4229e01c3690a1077ce89f1"5}Exemplo de Requisição
1curl --request POST \2 --url '{{MAIN_URL}}/customers/123/generate-token' \3 --header 'Authorization: Bearer SEU_TOKEN_AQUI' \4 --header 'Content-Type: application/json' \5 --data '{6 "scopes": ["address", "cards"],7 "ttlSeconds": 9008 }'✅ Resposta de Sucesso
HTTP Status: 200 OK
1{2 "status": true,3 "data": {4 "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",5 "expiresAt": "2026-11-17 16:07:29",6 "jti": "03b97e38-f616-4493-bdfb-c826771040ec",7 "cartId": "4229e01c3690a1077ce89f1",8 "scopes": ["address", "cards"]9 }10}| Campo | Tipo | Descrição |
|---|---|---|
| token | string | Token do cliente, para o header Authorization: Bearer {token} das rotas do cliente e do carrinho |
| expiresAt | datetime | Vencimento do token (Y-m-d H:i:s). Os refreshes do token mantêm esse vencimento |
| jti | string | Identificador da sessão. É o sessionId registrado no histórico do cliente |
| cartId | string | Carrinho do token: o informado em cartId ou o carrinho mais recente do cliente |
| scopes | string[] | Escopos liberados no token |
⚠️ Possíveis erros:
Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.
Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.
| Código Interno | Código HTTP | Descrição |
|---|---|---|
| INVALID_REQUEST_PAYLOAD | 400 | scopes ausente, vazio, repetido, com o coringa * ou com escopo desconhecido, ou ttlSeconds fora do intervalo de 1 a 3600 |
| UAPPI_STORE_CUSTOMER_IS_DISABLED | 401 | O cliente está inativo |
| UAPPI_API_CUSTOMER_TOKEN_INTEGRATION_ONLY | 403 | O usuário da chamada não é um usuário de integração |
| UAPPI_AUTH_FORBIDDEN_ACCESS | 403 | O perfil do usuário não tem os escopos CUSTOMER_READ e CUSTOMER_TOKEN_WRITE |
| UAPPI_STORE_CUSTOMER_NOT_FOUND | 404 | O cliente não foi encontrado na loja ou não pertence ao canal de venda da requisição |
| UAPPI_STORE_CART_NOT_FOUND | 404 | O carrinho informado em cartId não existe no canal de venda da requisição |
| UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED | 409 | O carrinho informado em cartId já está vinculado a outro cliente |
| USER_PROFILE_TRADE_POLICY_MISCONFIGURED | 422 | O perfil do usuário possui restrição de política comercial ativa, mas nenhuma política comercial permitida está configurada. |
| THROTTLE_LIMIT_REACHED | 429 | Mais de 60 requisições por minuto para o mesmo usuário e o mesmo cliente |