Skip to content

Cartão Presente

Visão Geral

O módulo de Cartão Presente (Gift Card) 🎁 é uma solução estratégica que permite à loja oferecer créditos pré-pagos como produtos do catálogo.

Ele possibilita que créditos sejam adquiridos por consumidores ou gerados administrativamente para campanhas de fidelização, bonificações ou estornos.

Diferente de um cupom de desconto, o Gift Card atua como um valor monetário real vinculado ao ecossistema da loja.

Ao ser resgatado, o saldo é creditado diretamente na carteira virtual (wallet) do cliente, permitindo o abatimento total ou parcial no valor de novos pedidos durante o checkout.

O sistema suporta tanto a geração automática (após a confirmação de pagamento de um produto configurado como gift card) quanto a geração manual em lote para ações promocionais, garantindo rastreabilidade completa de cada código gerado.

Entidades Envolvidas

* Produto Gift Card: Produto do catálogo (tipo serviço) que contém as definições base, como o valor nominal padrão.

* Gift Card Gerado: O registro individual contendo o código único (code), o valor atual, e o status de resgate.

* Cliente (Customer): O usuário final que recebe o vínculo do crédito em sua carteira virtual.

* Usuário Administrativo: Responsável pela configuração, geração manual e auditoria dos lotes.

Notas e Considerações

As operações deste módulo exigem os escopos de permissão GIFT_CARD_READ para consultas e GIFT_CARD_WRITE para ações que alteram o estado dos registros.

É importante destacar que um gift card gerado manualmente pode ser removido apenas se não possuir vínculo com um cliente.

Gift cards originados de pedidos de venda possuem regras de segurança mais rígidas para garantir a integridade financeira do crédito do consumidor.

Listagem de gift cards

GET /products/gift-cards

Retorna lista paginada de gift cards da loja, com resumo do produto associado, ordenação e condições de busca

Descrição

O endpoint de listagem permite consultar todos os gift cards gerados no ecossistema da loja 🎁.

Ele é essencial para processos de auditoria, permitindo que o lojista visualize códigos ativos, valores nominais e o status de resgate de cada cartão.

Para acessar este recurso, é necessário possuir a permissão GIFT_CARD_READ.

O retorno inclui dados detalhados da geração (como o usuário responsável) e, caso o cartão já tenha sido utilizado ou vinculado, as informações do cliente (customer) correspondente.

Cada registro também traz um objeto product, que fornece o contexto do produto do catálogo que originou o gift card, facilitando a identificação da campanha ou tipo de oferta vinculada ao código.

Parâmetros

Headers Obrigatórios

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

Campos de Condição Disponíveis

CampoTipoDescrição
codestringCódigo único do gift card
productIdintegerID do produto do catálogo vinculado ao gift card
orderItemIdintegerID do item de pedido que originou o gift card (em casos de geração automática)
userIdintegerID do usuário administrativo que gerou o cartão
userNamestringNome do usuário que gerou o cartão
userEmailstringE-mail do usuário que gerou o cartão
valuenumberValor nominal do gift card
createdAtstringData de criação do registro

Campos de Ordenação Disponíveis

CampoDescrição
idIdentificador único do gift card
createdAtData de criação do registro

Exemplo de Requisição

1curl --request GET \
2  --url "{{MAIN_URL}}/products/gift-cards" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "order": [
7      {
8        "field": "createdAt",
9        "order": "DESC"
10      }
11    ],
12    "condition": {
13      "type": "AND",
14      "conditions": [
15        {
16            "field": "value",
17            "value": 50
18        }
19      ]
20    },
21    "limit": 10,
22    "offset": 0
23  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "productId": 38,
8        "product": {
9          "productId": 38,
10          "brandId": 1,
11          "brandName": "Techbrand",
12          "mainCategoryId": 10,
13          "mainCategoryName": "Eletrônicos",
14          "type": "product",
15          "sku": "GIFT-100",
16          "name": "Cartão Presente R$ 100",
17          "active": true,
18          "url": "/gift-card-100.html",
19          "comparisonPrice": 100,
20          "stock": 999,
21          "medias": [],
22          "combination": [],
23          "currentAttributes": [],
24          "restriction": null
25        },
26        "orderItemId": null,
27        "code": "ABC123XYZ9",
28        "value": 100,
29        "userId": 2,
30        "userName": "Admin Uappi",
31        "userEmail": "admin@uappi.com.br",
32        "createdAt": "2026-05-22 10:00:00",
33        "activatedAt": ""
34      }
35    ],
36    "pagination": {
37      "limit": 10,
38      "offset": 0,
39      "pages": 1,
40      "registers": 1
41    }
42  }
43}

Geração de gift cards em lote

POST /products/gift-cards/generate

Gera múltiplos gift cards (códigos) por produto, informando productId, valor e quantidade em cada item do lote

Descrição

O endpoint de geração permite a criação manual de códigos de gift card em massa 🎁.

Ele é utilizado quando o lojista deseja gerar um lote de cartões para campanhas promocionais ou bonificações, sem que haja necessariamente um pedido de compra associado.

Para realizar esta operação, é necessário o escopo de permissão GIFT_CARD_WRITE.

O lojista pode definir a quantidade de códigos a serem gerados para cada produto (productId) e, opcionalmente, especificar um valor nominal customizado.

Caso o valor não seja informado, o sistema utilizará o valor configurado no cadastro do produto.

A resposta fornece um detalhamento individual para cada item do lote enviado, permitindo identificar quais produtos tiveram seus códigos gerados com sucesso e quais apresentaram inconsistências (como produtos que não são do tipo Gift Card).

Parâmetros

Headers Obrigatórios

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

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
giftCardsarraySimLista de lotes para geração de códigos
giftCards.*.productIdintegerSimID do produto (deve ser configurado como Gift Card no catálogo)
giftCards.*.quantityintegerSimQuantidade de códigos únicos a serem gerados
giftCards.*.valuenumberNãoValor nominal de cada cartão do lote. Se omitido, usa o valor da configuração do produto

Exemplo de Requisição

1curl --request POST \
2  --url "{{MAIN_URL}}/products/gift-cards/generate" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "giftCards": [
7      {
8        "productId": 1,
9        "value": 100,
10        "quantity": 2
11      }
12    ]
13  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "productId": 38,
6      "orderItemId": null,
7      "value": 100,
8      "quantity": 2,
9      "error": null,
10      "giftCards": [
11        {
12          "id": 10,
13          "productId": 38,
14          "orderItemId": null,
15          "code": "GIFT789XYZ",
16          "value": 100,
17          "userId": 2,
18          "userName": "Admin Uappi",
19          "userEmail": "admin@uappi.com.br",
20          "createdAt": "2026-05-22 11:00:00",
21          "activatedAt": ""
22        },
23        {
24          "id": 11,
25          "productId": 38,
26          "orderItemId": null,
27          "code": "GIFT456ABC",
28          "value": 100,
29          "userId": 2,
30          "userName": "Admin Uappi",
31          "userEmail": "admin@uappi.com.br",
32          "createdAt": "2026-05-22 11:00:00",
33          "activatedAt": ""
34        }
35      ]
36    }
37  ]
38}

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_STORE_PRODUCT_GIFT_CARD_NOT_FOUND404O produto solicitado não possui configuração de gift card ativa.
UAPPI_STORE_GIFT_CARD_ALREADY_GENERATED400Já foram gerados gift cards para o item informado.

Configuração de gift card do produto

PUT /products/gift-cards/{productId}

Salva a configuração de gift card vinculada a um produto do catálogo (valor padrão e metadados da configuração)

Descrição

O endpoint de configuração permite estabelecer as regras básicas para produtos do tipo Gift Card no catálogo 🎁.

Por meio dele, o lojista define parâmetros globais para o produto, como o valor nominal (value) que será sugerido ou aplicado durante a geração automática ou manual de códigos.

Esta operação exige o escopo de permissão GIFT_CARD_WRITE.

É importante notar que as alterações realizadas aqui afetam a configuração do produto no catálogo e não os códigos de gift card que já foram gerados anteriormente.

Para utilizar este endpoint, o produto já deve estar previamente cadastrado no catálogo e configurado como um serviço.

A resposta confirma os dados gravados, incluindo o registro do usuário responsável pela última alteração.

Parâmetros

Headers Obrigatórios

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

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
productIdintegerSimID único do produto no catálogo que receberá a configuração de gift card

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
valuenumberSimValor nominal padrão do gift card (formato decimal)

Exemplo de Requisição

1curl --request PUT \
2  --url "{{MAIN_URL}}/products/gift-cards/38" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "value": 150
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "productId": 1,
5    "value": 150,
6    "userId": 2,
7    "userName": "Admin Uappi",
8    "userEmail": "admin@uappi.com.br",
9    "createdAt": "2026-05-22 13:00:00"
10  }
11}

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_STORE_PRODUCT_NOT_FOUND404O produto solicitado não foi encontrado.
UAPPI_STORE_PRODUCT_MUST_BE_SERVICE400O produto deve estar configurado como um serviço para aceitar configurações de gift card.
UAPPI_STORE_PRODUCT_IS_PARENT400Não é possível configurar gift card em um produto pai (com variações).
UAPPI_STORE_PRODUCT_IS_VARIATION400Não é possível configurar gift card diretamente em uma variação individual.

Remoção da configuração de gift card do produto

DELETE /products/gift-cards/{productId}

Remove a configuração de gift card de um produto do catálogo (valor padrão e vínculo de configuração no produto)

Descrição

O endpoint de remoção permite excluir as definições de gift card de um produto específico do catálogo 🎁.

Ao executar esta ação, o produto deixa de ser identificado pelo sistema como um emissor de gift cards, removendo parâmetros como o valor nominal padrão.

Esta operação exige o escopo de permissão GIFT_CARD_WRITE.

É fundamental destacar que a remoção da configuração do produto não afeta os códigos de gift card que já foram gerados e estão ativos na loja; ela apenas interrompe a capacidade do produto de originar novos cartões.

Não é necessário o envio de corpo (body) na requisição, apenas a identificação do produto através do productId na URL.

Parâmetros

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {userToken}Token de autenticação do usuário

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
productIdintegerSimID único do produto no catálogo cuja configuração de gift card será removida

Exemplo de Requisição

1curl --request DELETE \
2  --url "{{MAIN_URL}}/products/gift-cards/38" \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_STORE_PRODUCT_GIFT_CARD_NOT_FOUND404O produto informado não possui uma configuração de gift card ativa para ser removida.

Vínculo de gift cards em lote

PUT /products/gift-cards/link

Associa múltiplos gift cards já gerados a clientes, com resultado por item do array links

Descrição

O endpoint de vínculo permite associar códigos de gift card a clientes registrados 🎁.

Esta operação é o passo final para a ativação do crédito, onde o valor nominal do cartão é transferido para a carteira virtual (wallet) do consumidor.

Para realizar esta associação, é necessário o escopo de permissão GIFT_CARD_WRITE.

O lojista pode identificar o gift card através do seu giftCardId ou diretamente pelo code impresso no cartão.

É fundamental que o cliente (customerId) já exista na base de dados e que o gift card ainda não possua um vínculo ativo.

A resposta detalha o status de cada tentativa de vínculo no lote, confirmando a transação na carteira do cliente ou indicando falhas de validação.

Parâmetros

Headers Obrigatórios

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

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
linksarraySimLista de vínculos a serem processados
links.*.customerIdintegerSimID único do cliente que receberá o crédito
links.*.giftCardIdintegerCondicionalID do registro do gift card. Obrigatório se code não for informado
links.*.codestringCondicionalCódigo alfanumérico do gift card. Obrigatório se giftCardId não for informado

Exemplo de Requisição

1curl --request PUT \
2  --url "{{MAIN_URL}}/products/gift-cards/link" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "links": [
7      {
8        "giftCardId": 10,
9        "customerId": 1001
10      },
11      {
12        "code": "GIFT456ABC",
13        "customerId": 1002
14      }
15    ]
16  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "giftCardId": 10,
6      "code": null,
7      "customerId": 1001,
8      "error": null
9    },
10    {
11      "giftCardId": null,
12      "code": "GIFT456ABC",
13      "customerId": 1002,
14      "error": "UAPPI_STORE_GIFT_CARD_ALREADY_LINKED"
15    }
16  ]
17}

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_STORE_GIFT_CARD_NOT_FOUND404O gift card solicitado não foi encontrado.
UAPPI_STORE_CUSTOMER_NOT_FOUND404O cliente solicitado não foi encontrado.
UAPPI_STORE_GIFT_CARD_ALREADY_LINKED400O gift card já possui um vínculo ativo e não pode ser reassociado.

Remoção de gift cards em lote

DELETE /products/gift-cards

Remove múltiplos gift cards já gerados, com resultado por id informado no corpo

Descrição

O endpoint de remoção permite a exclusão definitiva de códigos de gift card gerados na loja 🎁.

Esta ação é útil para invalidar lotes gerados incorretamente ou códigos promocionais que perderam a validade antes de serem distribuídos.

Para executar esta remoção, é necessário o escopo de permissão GIFT_CARD_WRITE.

O sistema impõe regras rígidas de segurança para evitar a invalidação de créditos em posse dos consumidores:

  • Apenas gift cards gerados manualmente podem ser removidos.
  • Gift cards que já possuem vínculo com um cliente ou que foram gerados automaticamente através de pedidos de venda não podem ser excluídos por este endpoint.

A resposta detalha o sucesso ou a falha para cada ID enviado, garantindo que o lojista tenha controle total sobre quais códigos foram efetivamente invalidados.

Parâmetros

Headers Obrigatórios

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

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
idsinteger[]SimArray contendo os IDs dos gift cards que devem ser removidos

Exemplo de Requisição

1curl --request DELETE \
2  --url "{{MAIN_URL}}/products/gift-cards" \
3  --header "Content-Type: application/json" \
4  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
5  --data '{
6    "ids": [10, 11]
7  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": [
4    {
5      "giftCardId": 10,
6      "error": null
7    },
8    {
9      "giftCardId": 11,
10      "error": "UAPPI_STORE_GIFT_CARD_ALREADY_LINKED"
11    }
12  ]
13}

⚠️ Possíveis erros:

Código InternoCódigo HttpDescrição
UAPPI_STORE_GIFT_CARD_NOT_FOUND404O gift card solicitado não foi encontrado.
UAPPI_STORE_GIFT_CARD_ALREADY_LINKED400O gift card já possui um vínculo com cliente e não pode ser removido.
UAPPI_STORE_GIFT_CARD_IS_AUTOMATIC400O gift card foi gerado automaticamente por um pedido e sua remoção manual não é permitida.

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

Institucional

;