> For the complete documentation index, see [llms.txt](https://docs.lojasquare.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lojasquare.com.br/api/cupons.md).

# Cupons

## Validar Cupom

<mark style="color:green;">`POST`</mark> `https://api.lojasquare.net/v1/cupons/:cupomInserido`

Valida o cupom informado na loja de acordo com os produtos no carrinho (quais produtos estão válidos para o cupom informado), e retorna todos os valores de desconto e total a ser pago após validar o cupom.

#### Headers

| Name          | Type   | Description                                                                                   |
| ------------- | ------ | --------------------------------------------------------------------------------------------- |
| AUTHORIZATION | string | Token público (KEY-API) de autorização para acesso à informações e identificação de uma loja. |

#### Request Body

| Name     | Type  | Description                                                              |
| -------- | ----- | ------------------------------------------------------------------------ |
| carrinho | array | Produtos que o player selecionou na loja e suas respectivas quantidades. |

{% tabs %}
{% tab title="200 Retorna o valor a ser cobrado no carrinho atualizado após validar o cupom: " %}

```
{
  "carrinhoAtualizado": [
    {
      "id_produto": 4,
      "quantidade": 3,
      "valorOriginal": 14,
      "valorUnitario": 12.6,
      "valorTotalProduto": 37.8,
      "descontoDoProduto": 4.2,
      "grupo": "VIPGold",
      "subServidor": "Survival"
    },
    {
      "id_produto": 1186,
      "quantidade": 1,
      "valorOriginal": 30,
      "valorUnitario": 30,
      "valorTotalProduto": 30,
      "descontoDoProduto": 0,
      "grupo": "Cash100K",
      "subServidor": "Survival"
    }
  ],
  "cupomUsado": "teste",
  "servidor": "TrowCraft",
  "valorDesconto": 4.2,
  "valorTotal": 67.8,
  "valorTotalOriginal": 72,
  "cupomDesconto": 10
}
```

{% endtab %}

{% tab title="400 Casos deste erro:

* Cupom atingiu o limite de usos.
* Quando o cupom expirar e não for mais válido." %}

```
{
    "msg": "cupom_limite"
}
###################
{
    "msg": "cupom_expirou"
}
```

{% endtab %}

{% tab title="404 Casos deste erro:

* Nome da loja informado na requisição é diferente do nome da loja que criou o cupom.
* Quando o cupom informado não for encontrado." %}

```
{
    "msg": "site_nao_encontrado"
}
###################
{
    "msg": "cupom_nao_encontrado"
}
```

{% endtab %}
{% endtabs %}

## Body Request Explicado:

Abaixo está indicado o formato esperado como body de requisição.

* **carrinho** = Array de **objetos de itens** que o comprador colocou no carrinho da loja.

Objeto de item a ser adicionado no array do carrinho:

> {\
> &#x20;   **id\_produto**: ID do produto que o comprador colocou no carrinho.\
> &#x20;   **quantidade**: quantidade selecionada no carrinho para este produto.\
> }

### Exemplo:

```
{
	"carrinho": [
		{
			"id_produto": 4,
			"quantidade": 3
		},
		{
			"id_produto": 56,
			"quantidade": 1
		}
	]
}
```

## Response:

Abaixo está indicado o formato de resposta e sua devida explicação.

* carrinhoAtualizado: Array com dados dos itens no carrinho (e valores atualizados).
* cupomUsado: Cupom usado para validar o carrinho.
* servidor: Nome da loja.
* valorDesconto: Valor total de desconto aplicado.
* valorTotal: Valor total a ser pago pelo comprador.
* valorTotalOriginal: Valor total sem aplicar descontos.
* cupomDesconto: Desconto porcentagem

### Definição dos atributos do array 'carrinhoAtualizado':

> { \
> &#x20;   "**id\_produto**": ID do produto que o comprador colocou no carrinho.\
> &#x20;   "**quantidade**": Quantidade que o comprador selecionou do produto.\
> &#x20;   "**valorOriginal**": Valor sem descontos do produto.\
> &#x20;   "**valorUnitario**": Valor após aplicar os descontos no produto (se o cupom for aplicável ao produto)\
> &#x20;   "**valorTotalProduto**": Valor Unitário vezes a Quantidade que o comprador selecionou\
> &#x20;   "**descontoDoProduto**": Valor total do desconto aplicado ao produto (considerando quantidade) \
> &#x20;   "**grupo**": Grupo do produto configurado no painel\
> &#x20;   "**subServidor**": Tipo/Modo de jogo do servidor onde o produto será entregue.\
> }


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lojasquare.com.br/api/cupons.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.