Skip to content

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: true e um identificador de sessão (jti), mantidos nos refreshes.
  • 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çãoCarrinho do token
    Com cartIdO 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 cartIdO 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
    Como no login do cliente, as alterações do carrinho mesclam os itens dos outros carrinhos do cliente no mesmo canal de venda no carrinho do token, e os outros carrinhos são removidos. Leve isso em conta ao montar um carrinho fora da loja: itens que o cliente deixou em outro carrinho aparecem nele.

    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:

    CampoDescrição
    sessionIdIdentificador da sessão: o jti do token
    authenticatedAtData e hora da emissão (Y-m-d H:i:s)
    identificationE-mail do cliente
    authMethodSempre 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.

    EscopoRotas liberadas
    customerCadastro 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
    addressEndereços: /customer/address/* e PUT /cart/address
    documentsDocumentos: /customer/document/*
    cardsCartões salvos: /customer/cards/*
    ordersPedidos: /customer/orders/*
    historyHistórico: GET /customer/history
    gift-cardsGift cards: /customer/gift-cards/*
    walletCarteira: GET /customer/wallet/transaction e /cart/promotionals/customer-wallet
    point-systemSaldo de pontos no carrinho: /cart/promotionals/point-system
    wish-listListas de desejo: /customer/wish-list/*
    reviewsAvaliações e comentários: as rotas do cliente logado em /review (avaliações de produto e da loja) e DELETE /publics/products/comments/{commentId}
    Consulta do cadastro (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
    addressesaddress
    documentsdocuments
    flagscustomer
    additionalFieldscustomer
    Se o token não tiver o escopo de algum campo pedido, a consulta inteira responde 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:

  • PUT /customer/password (troca de senha)
  • /customer/mfa/* (configuração do MFA)
  • MCP do cliente (/customer/mcp)
  • 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:

  • CUSTOMER_READ: exigido por todas as rotas de clientes
  • CUSTOMER_TOKEN_WRITE: necessário para emitir o token delegado

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

POST /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 cartId sem 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

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação do usuário de integração
Content-Typeapplication/jsonTipo de conteúdo

Parâmetros de URL

ParâmetroTipoObrigatórioDescrição
customerIdintegerSimID do cliente em nome de quem o token é emitido

Parâmetros do Corpo

CampoTipoObrigatórioDescrição
scopesstring[]SimEscopos liberados no token, sem repetição. Valores aceitos: customer, address, documents, cards, orders, history, gift-cards, wallet, point-system, wish-list, reviews
ttlSecondsintegerNãoValidade do token, em segundos, de 1 a 3600. Padrão: 1800 (30 minutos)
cartIdstringNãoCarrinho 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": 900
8 }'

✅ 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}

CampoTipoDescrição
tokenstringToken do cliente, para o header Authorization: Bearer {token} das rotas do cliente e do carrinho
expiresAtdatetimeVencimento do token (Y-m-d H:i:s). Os refreshes do token mantêm esse vencimento
jtistringIdentificador da sessão. É o sessionId registrado no histórico do cliente
cartIdstringCarrinho do token: o informado em cartId ou o carrinho mais recente do cliente
scopesstring[]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 InternoCódigo HTTPDescrição
INVALID_REQUEST_PAYLOAD400scopes ausente, vazio, repetido, com o coringa * ou com escopo desconhecido, ou ttlSeconds fora do intervalo de 1 a 3600
UAPPI_STORE_CUSTOMER_IS_DISABLED401O cliente está inativo
UAPPI_API_CUSTOMER_TOKEN_INTEGRATION_ONLY403O usuário da chamada não é um usuário de integração
UAPPI_AUTH_FORBIDDEN_ACCESS403O perfil do usuário não tem os escopos CUSTOMER_READ e CUSTOMER_TOKEN_WRITE
UAPPI_STORE_CUSTOMER_NOT_FOUND404O cliente não foi encontrado na loja ou não pertence ao canal de venda da requisição
UAPPI_STORE_CART_NOT_FOUND404O carrinho informado em cartId não existe no canal de venda da requisição
UAPPI_STORE_CART_CUSTOMER_IS_ALREADY_DEFINED409O carrinho informado em cartId já está vinculado a outro cliente
USER_PROFILE_TRADE_POLICY_MISCONFIGURED422O perfil do usuário possui restrição de política comercial ativa, mas nenhuma política comercial permitida está configurada.
THROTTLE_LIMIT_REACHED429Mais de 60 requisições por minuto para o mesmo usuário e o mesmo cliente

Uappi é a melhor opção para o crescimento da sua loja!

;