# Vouchers

## Resumo

Um voucher é um código resgatável atrelado à um benefício. Tal código de resgate é criado e gerenciado internamente dentro da API de benefícios, mas suas rotas podem ser utilizadas individualmente também.

No caso de um resgate de um voucher por um membro de uma comunidade, a interação com a API de voucher deve ser direta, através da rota de resgate `/vouchers/:voucherId`.

### Objeto Voucher

<details>

<summary>Exemplo de Objeto de Voucher</summary>

```javascript
{
  "id": "8798wdefs",
  "type": "benefit" | "airdrop",
  "tokenBenefitId": "789fgres1as" | null,
  "collectionId": null | "fs21g65eahjn",
  "tokenId" : null | "798efsf3sgf",  
  "code": "50OFF",
  "requiredFormData": [
    {
      "name": "Endereço",
      "type": "text"
      "placeholder": "Digite aqui seu endereço para entrega de benefícios",
      "content": null
    },
    {
      "name": "E-mail",
      "type": "email"
      "placeholder": "Digite aqui seu melhor e-mail",
      "content": null
    },
    {
      "name": "Celular",
      "type": "phone",
      "placeholder": "Digite aqui seu número de celular",
      "content": null
    }
  ]
  "revealStatus": "revealed",
  "revealDate": "2022-10-15 15:07:12"
  "redeemStatus": null,
  "redeemDate": null
}
```

</details>

### Endpoints

#### Resgate de vouchers

* **GET** /v1/vouchers/:voucherId/validate
* **POST** /v1/vouchers/:voucherId
* **POST** /v1/vouchers/:voucherId/redeem

#### Gestão de vouchers

* **GET** /v1/vouchers/collection/:collectionId/manage
* **POST**  /v1/vouchers/manage
* **PATCH** /v1/vouchers/:voucherId/manage

### Resgate de Vouchers

## (JWT) Verifica se um dado código de voucher é valido

<mark style="color:blue;">`GET`</mark> `https://goblockchain.io/gotokens-api/v1/vouchers/validate`

Essa rota revela ao usuário se um dado voucher é válido.

Nível de permissionamento necessário: `company_admin`, `company_moderator`, `community_admin`, `community_moderator`, `member`

#### Query Parameters

| Name                                   | Type   | Description                                           |
| -------------------------------------- | ------ | ----------------------------------------------------- |
| code<mark style="color:red;">\*</mark> | String | Código do Voucher                                     |
| type<mark style="color:red;">\*</mark> | String | Tipo do Voucher (`benefit` \| `airdrop`)              |
| tokenBenefitId                         | String | ID do Benefício (necessário caso tipo seja `benefit`) |
| collectionId                           | String | ID da Coleção (necessário caso tipo seja `airdrop`)   |
| tokenId                                | String | ID do Token (necessário caso tipo seja `airdrop`)     |

#### Headers

| Name                                            | Type   | Description |
| ----------------------------------------------- | ------ | ----------- |
| authorization<mark style="color:red;">\*</mark> | Bearer | JWT         |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Exemplo de Resposta" %}

```javascript
{
  "isValid": true,
  "voucherId" : "d78w9a-aw8d746-1vse3r2d-wd8a79",
  "requiredFormData" : [
    {
      "name": "Endereço",
      "type": "text"
      "placeholder": "Digite aqui seu endereço para entrega de benefícios"
    },
    {
      "name": "E-mail",
      "type": "email"
      "placeholder": "Digite aqui seu melhor e-mail"
    },
    {
      "name": "Celular",
      "type": "phone",
      "placeholder": "Digite aqui seu número de celular"
    }
  ]
}
```

{% endtab %}

{% tab title="Campos da Resposta" %}

* **`isValid`** *- Boolean*

  Variável que retorna se um dado código de voucher é válido ou não.

* **`voucherId`** *- String*

  Identificador próprio do voucher.

* **`requiredFormData`** *- Array of Objects*

  Conjunto de dados necessários para liberação do uso do voucher.

  * **`name`** *- String*

    Nome do campo de dados necessário.
  * **`type`** *- String*

    Tipo de dado solicitado.
  * **`placeholder`** *- String*

    Texto auxiliar de preenchimento do campo.
    {% endtab %}
    {% endtabs %}
    {% endtab %}

{% tab title="401: Unauthorized " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 401" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">1</td><td>Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% endtab %}

{% tab title="403: Forbidden " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 403" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">10</td><td>Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## (JWT) Revela o código de um determinado voucher

<mark style="color:green;">`POST`</mark> `https://goblockchain.io/gotokens-api/v1/vouchers/:voucherId`

Essa rota revela ao usuário o código de um voucher que o mesmo tem direito caso todos seus campos da requisição sejam válidos.

Nível de permissionamento necessário: `company_admin`, `company_moderator`, `community_admin`, `community_moderator`, `member`

#### Path Parameters

| Name                                        | Type   | Description   |
| ------------------------------------------- | ------ | ------------- |
| voucherId<mark style="color:red;">\*</mark> | String | ID do Voucher |

#### Headers

| Name                                            | Type   | Description |
| ----------------------------------------------- | ------ | ----------- |
| authorization<mark style="color:red;">\*</mark> | Bearer | JWT         |

#### Request Body

| Name             | Type       | Description                                             |
| ---------------- | ---------- | ------------------------------------------------------- |
| requiredFormData | \[Objects] | Conjunto de campos obrigatórios para resgate do voucher |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Exemplo de Resposta" %}
Caso o voucher seja referente ao **resgate de um benefício** de um token, ele terá os seguintes campos como retorno:

```javascript
{
  "id": "8798wdefs",
  "type": "benefit"
  "tokenBenefitId": "789fgres1as",
  "code": "50OFF",
  "revealStatus": "revealed",
  "revealDate": "2022-10-15 15:07:12",
  "requiredFormData": [
    {
      "name": "Endereço",
      "type": "text"
      "placeholder": "Digite aqui seu endereço para entrega de benefícios",
      "content": "Rua Aristides Maia, 204, Catumbi, Rio de Janeiro, RJ"
    },
    {
      "name": "E-mail",
      "type": "email"
      "placeholder": "Digite aqui seu melhor e-mail",
      "content": "meu@email.com"
    },
    {
      "name": "Celular",
      "type": "phone",
      "placeholder": "Digite aqui seu número de celular",
      "content": "5521998789636"
    }
  ]
}
```

Caso o voucher seja referente ao **resgate direto de um token**, como atrelado à uma coleção do tipo Airdrop ou POAP, ele terá os seguintes campos como retorno:

```javascript
{
  "id": "8798wdefs",
  "type": "airdrop",
  "collectionId": "fs21g65eahjn",
  "tokenId" : "798efsf3sgf",  
  "code": "B87QM",
  "revealStatus": "revealed",
  "revealDate": "2022-10-15 15:07:12",
  "requiredFormData": [
    {
      "name": "Endereço",
      "type": "text"
      "placeholder": "Digite aqui seu endereço para entrega de benefícios",
      "content": "Rua Aristides Maia, 204, Catumbi, Rio de Janeiro, RJ"
    },
    {
      "name": "E-mail",
      "type": "email"
      "placeholder": "Digite aqui seu melhor e-mail",
      "content": "meu@email.com"
    },
    {
      "name": "Celular",
      "type": "phone",
      "placeholder": "Digite aqui seu número de celular",
      "content": "5521998789636"
    }
  ]
}
```

{% endtab %}

{% tab title="Campos da Resposta" %}

* **`id`** *- String*

  Identificador próprio do benefício.

* **`type`** *- String*

  Determina o tipo de voucher à que se refere. Pode ser *`benefit`* ou *`airdrop`*.

* **`benefitId`** *- String*

  Identificador próprio relativo ao benefício com o qual o voucher se relaciona, quando ele é do tipo *`benefit`*.

* **`collectionId`** *- String*

  Identificador próprio relativo à coleção com o qual o voucher se relaciona, quando ele é do tipo *`airdrop`*.

* **`tokenId`** *- String*

  Identificador próprio relativo ao token resgatável com o qual o voucher se relaciona, quando ele é do tipo *`airdrop`*.

* **`code`** *- String*

  Código de resgate do benefício.

* **`revealStatus`** *- String*

  Status de revelação do código do benefício. Pode ser *`revealed`* ou *`hidden`*.

* **`revealDate`** *- DateTime*

  Data e hora da revelação do código do benefício.

* **`requiredFormData`** *- Array of Objects*

  Conjunto de dados necessários para liberação do uso do voucher.

  * **`name`** *- String*

    Nome do campo de dados necessário.
  * **`type`** *- String*

    Tipo de dado solicitado.
  * **`placeholder`** *- String*

    Texto auxiliar de preenchimento do campo.
  * **`content`** *- String*

    Conteúdo preenchido pelo usuário no resgate do voucher.
    {% endtab %}
    {% endtabs %}
    {% endtab %}

{% tab title="401: Unauthorized " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 401" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">1</td><td>Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% endtab %}

{% tab title="403: Forbidden " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 403" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">10</td><td>Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## (JWT) Resgata um código de voucher de Airdrop ou POAP

<mark style="color:green;">`POST`</mark> `https://goblockchain.io/gotokens-api/v1/vouchers/:voucherId/redeem`

Essa rota deve ser usada para resgatar um voucher de Airdrop ou POAP.

Internamente, ela revalida o voucher antes do resgate ocorrer de fato e inicia uma transação de envio do token para o usuário logado.

Nível de permissionamento necessário: qualquer

#### Path Parameters

| Name                                        | Type   | Description   |
| ------------------------------------------- | ------ | ------------- |
| voucherId<mark style="color:red;">\*</mark> | String | ID do Voucher |

#### Headers

| Name                                            | Type   | Description |
| ----------------------------------------------- | ------ | ----------- |
| authorization<mark style="color:red;">\*</mark> | Bearer | JWT         |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Exemplo de Resposta" %}

```javascript
{
  "token": {
    "id" : "798efsf3sgf",  
    "collectionId": "fs21g65eahjn"
  },
  "voucher": {
    "id": "8798wdefs",
    "type": "airdrop",
    "code": "user@email.com",
    "revealStatus": "revealed",
    "revealDate": "2022-10-15 15:07:12",
    "redeemStatus": "redeemed",
    "redeemDate": "2022-10-15 15:07:12",
  }  
}
```

{% endtab %}

{% tab title="Campos da Resposta" %}

* **`token`** *- String*

  Armazena dados relativos ao token resgatado.

  * **`id`** *- String*

    Identificador próprio relativo ao token resgatado.
  * **`collectionId`** *- String*

    Identificador próprio relativo à coleção com o qual o token se relaciona.

* **`voucher`** *- String*

  Armazena dados relativos ao voucher.

  * **`id`** *- String*

    Identificador próprio do benefício.
  * **`type`** *- String*

    Determina o tipo de voucher à que se refere. Pode ser *`benefit`* ou *`airdrop`*.
  * **`code`** *- String*

    Código de resgate do benefício.
  * **`revealStatus`** *- String*

    Status de revelação do código do benefício. Pode ser *`revealed`* ou *`hidden`*.
  * **`revealDate`** *- DateTime*

    Data e hora da revelação do código do benefício.
  * **`redeemStatus`** *- String*

    Status de resgate do código do benefício. Pode ser *`null`* ou *`redeemed`*.
  * **`redeemDate`** *- DateTime*

    Data e hora do resgate do código do benefício.
    {% endtab %}
    {% endtabs %}
    {% endtab %}

{% tab title="401: Unauthorized " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 401" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">1</td><td>Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% endtab %}

{% tab title="403: Forbidden " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 403" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">10</td><td>Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

### Gestão de Vouchers

## (JWT) Lista os vouchers de uma collection e seus status

<mark style="color:blue;">`GET`</mark> `https://goblockchain.io/gotokens-api/v1/vouchers/collection/:collectionId/manage`

Nível de permissionamento necessário: `company_admin`, `company_moderator`, `community_admin`, `community_moderator`

#### Path Parameters

| Name         | Type   | Description   |
| ------------ | ------ | ------------- |
| collectionId | String | ID da Coleção |

#### Headers

| Name                                            | Type   | Description |
| ----------------------------------------------- | ------ | ----------- |
| authorization<mark style="color:red;">\*</mark> | Bearer | JWT         |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Exemplo de Resposta" %}

```javascript
[
  {
    "tokenId": "12se3ferfgs789v",
    "codes": [
      {
        "code": "0C22AE2D",
        "redeemStatus": "redeemed",
        "redeemDate": "2022-11-30T17:22:26.246Z"
      },
      {
        "code": "E4EA2988",
        "redeemStatus": null,
        "redeemDate": null
      },
      {
        "code": "2A59D7D0",
        "redeemStatus": null,
        "redeemDate": null
      }
    ]
  },
  {
    "tokenId": "789dfs123fescd8x",
    "codes": [
      {
        "code": "6B040A13",
        "redeemStatus": null,
        "redeemDate": null
      },
      {
        "code": "E08B117C",
        "redeemStatus": null,
        "redeemDate": null
      },
      {
        "code": "E70E1223",
        "redeemStatus": null,
        "redeemDate": null
      }
    ]
  },
```

{% endtab %}

{% tab title="Campos da Resposta" %}

* **`tokenId`** *- String*

  Identificador único do banco de dados de um Token.

* **`codes`** *- Array of Objects*

  Conjunto de dados necessários para liberação do uso do voucher.

  * **`code`** *- String*

    Código de resgate do Token.
  * **`redeemStatus`** *- String*

    Status do uso do código de resgate.
  * **`redeemDate`** *- DateTime*

    Data do uso do código de resgate.
    {% endtab %}
    {% endtabs %}
    {% endtab %}

{% tab title="401: Unauthorized " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 401" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">1</td><td>Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% endtab %}

{% tab title="403: Forbidden " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 403" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">10</td><td>Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## (JWT) Cria um voucher

<mark style="color:green;">`POST`</mark> `https://goblockchain.io/gotokens-api/v1/vouchers/manage`

Nível de permissionamento necessário: `company_admin`, `company_moderator`, `community_admin`, `community_moderator`

#### Headers

| Name                                            | Type   | Description |
| ----------------------------------------------- | ------ | ----------- |
| authorization<mark style="color:red;">\*</mark> | Bearer | JWT         |

#### Request Body

| Name                                   | Type       | Description                                                                   |
| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
| code                                   | String     | Código de resgate do voucher. Se não for passado, será gerado randomicamente. |
| tokenBenefitId                         | String     | ID do Benefício (caso tipo seja `benefit`)                                    |
| collectionId                           | String     | ID da Coleção (caso tipo seja `airdrop`)                                      |
| tokenId                                | String     | ID da Coleção (caso tipo seja `airdrop`)                                      |
| requiredFormData                       | \[Objects] | Conjunto de campos obrigatórios para resgate do voucher                       |
| type<mark style="color:red;">\*</mark> | String     | Tipo do Voucher (`benefit` \| `airdrop`)                                      |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Exemplo de Resposta" %}
Caso o voucher seja referente ao **resgate de um benefício** de um token, ele terá os seguintes campos como retorno:

```javascript
{
  "id": "8798wdefs",
  "type": "benefit"
  "tokenBenefitId": "789fgres1as",
  "code": "50OFF",
  "revealStatus": "unrevealed",
  "revealDate": null,
  "redeemStatus": null,
  "redeemDate": null,
  "requiredFormData" : [
    {
      "name": "Endereço",
      "type": "text"
      "placeholder": "Digite aqui seu endereço para entrega de benefícios"
    },
    {
      "name": "E-mail",
      "type": "email"
      "placeholder": "Digite aqui seu melhor e-mail"
    },
    {
      "name": "Celular",
      "type": "phone",
      "placeholder": "Digite aqui seu número de celular"
    }
  ]
}
```

Caso o voucher seja referente ao **resgate direto de um token**, como atrelado à uma coleção do tipo Airdrop ou POAP, ele terá os seguintes campos como retorno:

```javascript
{
  "id": "8798wdefs",
  "type": "airdrop",
  "collectionId": "fs21g65eahjn",
  "tokenId" : "798efsf3sgf",  
  "code": "B87QM",
  "revealStatus": "unrevealed",
  "revealDate": null,
  "redeemStatus": null,
  "redeemDate": null,
  "requiredFormData" : [
    {
      "name": "Endereço",
      "type": "text"
      "placeholder": "Digite aqui seu endereço para entrega de benefícios"
    },
    {
      "name": "E-mail",
      "type": "email"
      "placeholder": "Digite aqui seu melhor e-mail"
    },
    {
      "name": "Celular",
      "type": "phone",
      "placeholder": "Digite aqui seu número de celular"
    }
  ]
}
```

{% endtab %}

{% tab title="Campos da Resposta" %}

* **`id`** *- String*

  Identificador próprio do benefício.

* **`type`** *- String*

  Determina o tipo de voucher à que se refere. Pode ser *`benefit`* ou *`airdrop`*.

* **`benefitId`** *- String*

  Identificador próprio relativo ao benefício com o qual o voucher se relaciona, quando ele é do tipo *`benefit`*.

* **`collectionId`** *- String*

  Identificador próprio relativo à coleção com o qual o voucher se relaciona, quando ele é do tipo *`airdrop`*.

* **`tokenId`** *- String*

  Identificador próprio relativo ao token resgatável com o qual o voucher se relaciona, quando ele é do tipo *`airdrop`*.

* **`code`** *- String*

  Código de resgate do benefício.

* **`revealStatus`** *- String*

  Status de revelação do código do benefício. Pode ser *`revealed`* ou *`hidden`*.

* **`revealDate`** *- DateTime*

  Data e hora da revelação do código do benefício.

* **`requiredFormData`** *- Array of Objects*

  Conjunto de dados necessários para liberação do uso do voucher.

  * **`name`** *- String*

    Nome do campo de dados necessário.
  * **`type`** *- String*

    Tipo de dado solicitado.
  * **`placeholder`** *- String*

    Texto auxiliar de preenchimento do campo.
  * **`content`** *- String*

    Conteúdo preenchido pelo usuário no resgate do voucher.
    {% endtab %}
    {% endtabs %}
    {% endtab %}

{% tab title="401: Unauthorized " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 401" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">1</td><td>Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% endtab %}

{% tab title="403: Forbidden " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 403" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">10</td><td>Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## (JWT) Atualiza as informações de um voucher

<mark style="color:purple;">`PATCH`</mark> `https://goblockchain.io/gotokens-api/v1/vouchers/:voucherId/manage`

Nível de permissionamento necessário: `company_admin`, `company_moderator`, `community_admin`, `community_moderator`

#### Path Parameters

| Name                                        | Type   | Description   |
| ------------------------------------------- | ------ | ------------- |
| voucherId<mark style="color:red;">\*</mark> | String | ID do Voucher |

#### Headers

| Name                                            | Type   | Description |
| ----------------------------------------------- | ------ | ----------- |
| authorization<mark style="color:red;">\*</mark> | Bearer | JWT         |

#### Request Body

| Name             | Type       | Description                                             |
| ---------------- | ---------- | ------------------------------------------------------- |
| code             | String     | Código de resgate do voucher                            |
| redeemStatus     | String     | Status de uso do voucher                                |
| redeemDate       | DateTime   | Data do uso do voucher                                  |
| revealStatus     | String     | Status de revelação do código do voucher                |
| revealDate       | DateTime   | Data de revelação do código do voucher                  |
| requiredFormData | \[Objects] | Conjunto de campos obrigatórios para resgate do voucher |

{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Exemplo de Resposta" %}
Caso o voucher seja referente ao **resgate de um benefício** de um token, ele terá os seguintes campos como retorno:

```javascript
{
  "id": "8798wdefs",
  "type": "benefit"
  "tokenBenefitId": "789fgres1as",
  "code": "10OFF",
  "revealStatus": "revealed",
  "revealDate": "2022-10-14 12:27:31",
  "redeemStatus": null,
  "redeemDate": null,
  "requiredFormData" : [
    {
      "name": "Endereço",
      "type": "text"
      "placeholder": "Digite aqui seu endereço para entrega de benefícios"
    },
    {
      "name": "E-mail",
      "type": "email"
      "placeholder": "Digite aqui seu melhor e-mail"
    },
    {
      "name": "Celular",
      "type": "phone",
      "placeholder": "Digite aqui seu número de celular"
    }
  ]
}
```

Caso o voucher seja referente ao **resgate direto de um token**, como atrelado à uma coleção do tipo Airdrop ou POAP, ele terá os seguintes campos como retorno:

```javascript
{
  "id": "8798wdefs",
  "type": "airdrop",
  "collectionId": "fs21g65eahjn",
  "tokenId" : "798efsf3sgf",  
  "code": "B750M",
  "revealStatus": "revealed",
  "revealDate": "2022-10-14 12:27:31",
  "redeemStatus": null,
  "redeemDate": null,
  "requiredFormData" : [
    {
      "name": "Endereço",
      "type": "text"
      "placeholder": "Digite aqui seu endereço para entrega de benefícios"
    },
    {
      "name": "E-mail",
      "type": "email"
      "placeholder": "Digite aqui seu melhor e-mail"
    },
    {
      "name": "Celular",
      "type": "phone",
      "placeholder": "Digite aqui seu número de celular"
    }
  ]
}
```

{% endtab %}

{% tab title="Campos da Resposta" %}

* **`id`** *- String*

  Identificador próprio do benefício.

* **`type`** *- String*

  Determina o tipo de voucher à que se refere. Pode ser *`benefit`* ou *`airdrop`*.

* **`benefitId`** *- String*

  Identificador próprio relativo ao benefício com o qual o voucher se relaciona, quando ele é do tipo *`benefit`*.

* **`collectionId`** *- String*

  Identificador próprio relativo à coleção com o qual o voucher se relaciona, quando ele é do tipo *`airdrop`*.

* **`tokenId`** *- String*

  Identificador próprio relativo ao token resgatável com o qual o voucher se relaciona, quando ele é do tipo *`airdrop`*.

* **`code`** *- String*

  Código de resgate do benefício.

* **`revealStatus`** *- String*

  Status de revelação do código do benefício. Pode ser *`hidden`* ou *`revealed`*.

* **`revealDate`** *- DateTime*

  Data e hora da revelação do código do benefício.

* **`redeemStatus`** *- String*

  Status de resgate do código do benefício. Pode ser *`null`* ou *`redeemed`*.

* **`redeemDate`** *- DateTime*

  Data e hora do resgate do código do benefício.

* **`requiredFormData`** *- Array of Objects*

  Conjunto de dados necessários para liberação do uso do voucher.

  * **`name`** *- String*

    Nome do campo de dados necessário.
  * **`type`** *- String*

    Tipo de dado solicitado.
  * **`placeholder`** *- String*

    Texto auxiliar de preenchimento do campo.
  * **`content`** *- String*

    Conteúdo preenchido pelo usuário no resgate do voucher.
    {% endtab %}
    {% endtabs %}
    {% endtab %}

{% tab title="401: Unauthorized " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 401" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">1</td><td>Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% endtab %}

{% tab title="403: Forbidden " %}
{% tabs %}
{% tab title="Possíveis Erros HTTP - 403" %}

<table><thead><tr><th width="152" align="center">Código</th><th>Descrição</th></tr></thead><tbody><tr><td align="center">10</td><td>Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions: 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.gotokens.io/gotokens/api-fidelidade/vouchers.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.