Skip to content

🎫 Documentação de Vouchers

📋 Visão Geral

Um voucher é um crédito promocional vinculado diretamente a um cliente, adicionado automaticamente à sua carteira no momento da criação.

Diferente de cupons, o voucher não exige código: o saldo é creditado de forma imediata e pode ser utilizado pelo cliente em suas próximas compras.

🔄 Entidades Envolvidas

Cada voucher está obrigatoriamente vinculado a um Cliente (customerId), que receberá o crédito em sua carteira.

O voucher também registra o usuário autenticado que realizou a criação — identificado pelos campos userId, userName e userEmail — garantindo rastreabilidade operacional.

O objeto customer é retornado preenchido na listagem e como null na resposta de criação.

📌 Notas e Considerações

  • O campo hash é gerado automaticamente pelo sistema com 8 caracteres alfanuméricos em minúsculo. Não é possível informá-lo manualmente.
  • Ao criar um voucher, o sistema registra uma transação na carteira do cliente com a ação add, creditando o valor informado de forma imediata.
  • Os campos userId, userName e userEmail são preenchidos automaticamente a partir da sessão do usuário autenticado, sem necessidade de envio na requisição.
  • O evento CREATE_PROMOTIONAL_VOUCHER é disparado após a criação bem-sucedida do voucher.

📋 Listagem de Vouchers

GET /promotionals/vouchers

Retorna a listagem paginada de vouchers cadastrados na loja

📋 Descrição

Endpoint utilizado para listar todos os vouchers cadastrados na loja, com suporte a paginação, filtros e ordenação.

O objeto customer é retornado preenchido em cada registro, com os dados resumidos do cliente vinculado ao voucher.

Requer o escopo VOUCHER_READ.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

🔍 Campos de Condição Disponíveis

CampoTipoDescrição
customerIdintegerID do cliente vinculado ao voucher
userIdintegerID do usuário que criou o voucher
hashstringCódigo único do voucher
valuenumberValor do crédito concedido
userNamestringNome do usuário que criou o voucher
createdAtdatetimeData de criação
customerNamestringNome do cliente (alias de customer.name_corporate_name)

🔃 Campos de Ordenação Disponíveis

CampoDescrição
idID do voucher
hashCódigo do voucher
valueValor do crédito
userNameNome do usuário criador
createdAtData de criação

💡 Exemplo de Requisição

> Nota: esta API aceita corpo JSON em requisições GET, seguindo a convenção da plataforma. Utilize o header Content-Type: application/json e envie os parâmetros no corpo da requisição.

1curl --request GET \
2  --url {{MAIN_URL}}/promotionals/vouchers \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "limit": 10,
7    "offset": 0
8  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "customerId": 3,
8        "userId": 2,
9        "userName": "Admin uappi",
10        "userEmail": "admin@uappi.com.br",
11        "hash": "daiuysbh",
12        "value": 123,
13        "observation": null,
14        "customer": {
15          "id": 3,
16          "tradePolicyId": 1,
17          "email": "customeruappi@email.com",
18          "nameCorporateName": "Customer teste",
19          "tradeName": "",
20          "phone": "+12345678912",
21          "active": true,
22          "masked": false
23        },
24        "createdAt": "2026-04-27 14:20:03"
25      }
26    ],
27    "pagination": {
28      "limit": 10,
29      "offset": 0,
30      "pages": 1,
31      "registers": 1
32    }
33  }
34}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código InternoHTTPDescrição
UAPPI_AUTH_INVALID401❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED403❌ O usuário não possui a permissão VOUCHER_READ.

➕ Criação de Voucher

POST /promotionals/vouchers

Permite criar um novo voucher e creditar o valor na carteira do cliente

📋 Descrição

Endpoint responsável por criar um novo voucher e creditá-lo automaticamente na carteira do cliente informado.

Ao criar um voucher, o sistema valida a existência do cliente, gera um hash único de 8 caracteres alfanuméricos em minúsculo e registra uma transação de crédito na carteira do cliente com o valor informado.

Os campos hash, userId, userName e userEmail são preenchidos automaticamente pelo sistema — não devem ser enviados na requisição. O objeto customer retorna como null na resposta de criação.

Requer os escopos VOUCHER_READ e VOUCHER_WRITE.

📝 Parâmetros

🏷️ Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer SEU_TOKEN_AQUIToken de autenticação

📦 Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
customerIdinteger✅ SimID do cliente que receberá o voucher
valuenumber✅ SimValor do crédito a ser concedido (aceita até 6 casas decimais)
observationstring❌ NãoObservação opcional sobre o voucher

💡 Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/promotionals/vouchers \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "customerId": 3,
7    "value": 50,
8    "observation": "Voucher de boas-vindas"
9  }'

✅ Resposta de Sucesso

HTTP Status: 201 Created

1{
2  "status": true,
3  "data": {
4    "id": 2,
5    "customerId": 3,
6    "userId": 2,
7    "userName": "Admin uappi",
8    "userEmail": "admin@uappi.com.br",
9    "hash": "dlhs9t3y",
10    "value": 50,
11    "observation": "Voucher de boas-vindas",
12    "customer": null,
13    "createdAt": "2026-05-06 17:22:22"
14  }
15}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

Código InternoHTTPDescrição
UAPPI_AUTH_INVALID401❌ O token de autenticação é inválido ou está ausente.
UAPPI_AUTH_DISABLED403❌ O usuário não possui a permissão VOUCHER_WRITE.
UAPPI_STORE_CUSTOMER_NOT_FOUND400❌ O cliente informado não foi encontrado.

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

Institucional

;