# Benefícios

## Resumo

Se tratando de um programa de loyalties, é imprescindível que a API seja flexível o suficiente para garantir que a comunidade terá interesse em se manter engajada com benefícios exclusivos de sua participação no sistema.

Os benefícios são relacionados diretamente às NFTs, criando, assim, utilidades exclusivas para elas.

Caso o programa utilize "moedas", elas precisam ser trocadas por uma NFT para que o dono conquiste o benefício.

Os benefícios poderão ser digitais ou físicos, podendo expirar ou não. 

Exemplos:

* Físico - Acesso a evento de música
* Físico - Voucher de desconto no ecommerce 
* Digital - Acesso ao grupo do Discord

Um benefício físico ou digital poderá ser associado à vouchers únicos que são apresentados quando um proprietário da NFT desejar. Esses vouchers são temporários, reduzindo riscos de segurança. 

Cenário:

* João possui uma NFT que lhe dá direito para assistir um show de música. Ao chegar na portaria, ele solicita a geração de um QRCode que deverá ser escaneado enquanto estiver válido. Caso o tempo expire, ele precisará solicitar um novo QRCode. 

Como as NFTs podem ser negociadas no mercado secundário, a API de benefícios permite que que eles sejam associados ao metadata das NFTs, para que compradores possam visualizá-los na Opensea, por exemplo.

### Objeto Benefits

<details>

<summary>Exemplo de Objeto de Benefício</summary>

```javascript
{
  "id": "8798wdefs",
  "collectionId": "8th97sh19f3",
  "communityId": "gdr153ht789",
  "companyId": "yliki156sro",
  "name": "Benefit 1",
  "description": "Benefit 1 description",
  "externalUrl": "https://external-url.com",
  "type": "digital",
  "expirationDate": "2022-12-31 23:59:59",
  "tags": ["ambiental", "arte", "empreeendedorismo"],
  "hasVouchers": true,
  "elegibleTokens": [
    {
      "tokenId": "ijoaedwij",
      "voucherId": "45a1dw36"
    },
    {
      "tokenId": "879esf465",
      "voucherId": "0grte8789r",
    },
    {
      "tokenId":"213e6854f",
      "voucherId": "1e3wfa58ad8",
    },
    {
      "tokenId":"1c5e6799aw",
      "voucherId": "798fdsqwew87",
    }
  ]
}
```

</details>

### Endpoints

#### Benefícios

* **GET** /v1/benefits
* **GET** /v1/benefits/:benefitId
* **GET** /v1/benefits/token/:tokenId

#### Gestão de Benefícios

* **GET** /v1/benefits/manage
* **POST** /v1/benefits/manage
* **GET** /v1/benefits/:benefitId/manage
* **PATCH** /v1/benefits/:benefitId/manage
* **DELETE** /v1/benefits/:benefitId/manage

### Benefícios

## (JWT) Lista os benefícios que o usuário logado tem direito

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

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

#### Query Parameters

| Name   | Type   | Description                                    |
| ------ | ------ | ---------------------------------------------- |
| name   | String | Nome do Benefício                              |
| id     | String | ID do Benefício                                |
| limit  | String | Limite de resultados na busca                  |
| offset | String | Quantidade de resultados para avançar da busca |
| type   | String | Tipo de resgate do Benefício                   |
| tags   | Array  | Tags do Benefício                              |

#### Headers

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

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

```javascript
{
  "benefits": [
    {
      "id": "8798wdefs",
      "communityId": "gdr153ht789",
      "companyId": "yliki156sro",
      "collectionId": "789efe178d,
      "name": "Benefit 1 from Token A",
      "description": "Benefit 1 description",
      "externalUrl": "https://external-url.com",
      "type": "digital",
      "tags": ["ambiental", "arte", "empreeendedorismo"],
      "expirationDate": "2022-12-31 23:59:59",
      "relatedVoucherId": "78r9sersd5",
      "relatedTokenId": "weda845dwa"
    },
    {
      "id": "8798wdefs",
      "companyId": "yliki156sro",
      "communityId": "gdr153ht789",
      "collectionId": "grd874r187ws,
      "name": "Benefit 1 from Token B",
      "description": "Benefit 1 description",
      "externalUrl": "https://external-url.com",
      "type": "digital",
      "tags": ["ambiental", "arte", "empreeendedorismo"],
      "expirationDate": null,
      "relatedVoucherId": null,
      "relatedTokenId": "weda845dwa"
    },
    {
      "id": "8798wdefs",
      "companyId": "yliki156sro",
      "communityId": "gdr153ht789",
      "collectionId": "grd874r187ws,
      "name": "Benefit 2 from Token B",
      "description": "Benefit 2 description",
      "externalUrl": "https://external-url.com",
      "type": "digital",
      "tags": ["ambiental", "arte", "empreeendedorismo"],
      "expirationDate": "2022-12-31 23:59:59",
      "relatedVoucherId": "rtg897drg15",
      "relatedTokenId": "4gre68refs1"
    },
  ]
}
    
```

{% endtab %}

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

* **`benefits`** *- Array of Objects*

  Armazena as informações de cada benefício que o usuário logado tem direito.

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

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

    Identificador próprio da empresa gestora da comunidade.
  * **`communityId`** *- String*

    Identificador próprio da comunidade gestora da coleção.
  * **`collectionId`** *- String*

    Identificador próprio da coleção do token com aquele benefício.
  * **`name`** *- String*

    Nome do benefício.
  * **`description`** *- String*

    Descrição do benefício, podendo conter instruções de seu resgate.
  * **`externalUrl`** *- String*

    Link para redirecionamento externo caso o benefício exija alguma ação externa.
  * **`type`** *- String*

    Tipo de resgate do benefício. Pode ser `digital` ou `physical`.
  * **`expirationDate`** *- DateTime*

    Data e hora de validade do benefício, quando necessário.
  * **`relatedVoucherId`** *- String*

    Identificador próprio do voucher relacionado àquele benefício. Pode ser null caso o benefício não dê direito à um voucher.
  * **`relatedTokenId`** *- String*

    Identificador próprio do token que dá direito àquele benefício.
  * **`tags`** *- Array*

    Conjunto de tags 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 %}

## (JWT) Lista os informações de um dos benefícios que o usuário logado tem direito

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

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

#### Path Parameters

| Name | Type   | Description     |
| ---- | ------ | --------------- |
| id   | String | ID do Benefício |

#### Headers

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

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

```javascript
{
  "id": "8798wdefs",
  "communityId": "gdr153ht789",
  "companyId": "yliki156sro",
  "collectionId": "789efe178d,
  "name": "Benefit 1 from Token A",
  "description": "Benefit 1 description",
  "externalUrl": "https://external-url.com",
  "type": "digital",
  "tags": ["ambiental", "arte", "empreeendedorismo"],
  "expirationDate": "2022-12-31 23:59:59",
  "relatedVoucherId": "78an9gr16wa",
  "relatedTokenId": "weda845dwa"
}
```

{% endtab %}

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

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

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

  Identificador próprio da empresa gestora da comunidade.
* **`communityId`** *- String*

  Identificador próprio da comunidade gestora da coleção.
* **`collectionId`** *- String*

  Identificador próprio da coleção do token com aquele benefício.
* **`name`** *- String*

  Nome do benefício.
* **`description`** *- String*

  Descrição do benefício, podendo conter instruções de seu resgate.
* **`externalUrl`** *- String*

  Link para redirecionamento externo caso o benefício exija alguma ação externa.
* **`type`** *- String*

  Tipo de resgate do benefício. Pode ser `digital` ou `physical`.
* **`expirationDate`** *- DateTime*

  Data e hora de validade do benefício, quando necessário.
* **`relatedVoucherId`** *- String*

  Identificador próprio do voucher relacionado àquele benefício.
* **`relatedTokenId`** *- String*

  Identificador próprio do token que dá direito àquele benefício.
* **`tags`** *- Array*

  Conjunto de tags 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 %}

## Exibe benefícios de um token público

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

Nível de permissionamento necessário: qualquer

#### Path Parameters

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

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

```javascript
{
  "benefits": [
    {
      "id": "8798wdefs",
      "name": "Benefit 1 from Token A",
      "description": "Benefit 1 description",
      "tags": ["ambiental", "arte", "empreeendedorismo"],
    },
    {
      "id": "798shgrtd2",
      "name": "Benefit 2 from Token A",
      "description": "Benefit 2 description",
      "tags": ["ambiental", "arte", "empreeendedorismo"],
    }
  ]
}
```

{% endtab %}

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

* **`benefits`** *- Object*

  Lista de benefícios do token, se houver.

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

    Identificador único do benefício no banco de dados.
  * **`name`** *- String*

    Nome do benefício.
  * **`description`** *- String*

    Descrição do benefício.
  * **`tags`** *- Array*

    Conjunto de tags do benefício.
    {% endtab %}
    {% endtabs %}
    {% endtab %}
    {% endtabs %}

### Gestão de Benefícios

## (JWT) Lista os benefícios que o usuário tem acesso de edição

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

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

#### Query Parameters

| Name   | Type   | Description                                    |
| ------ | ------ | ---------------------------------------------- |
| name   | String | Nome do Benefício                              |
| id     | String | ID do Benefício                                |
| limit  | String | Limite de resultados na busca                  |
| offset | String | Quantidade de resultados para avançar da busca |
| type   | String | Tipo de resgate do Benefício                   |
| tags   | Array  | Tags do Benefício                              |

#### Headers

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

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

```javascript
{
  "benefits": [
    {
      "id": "8798wdefs",
      "communityId": "gdr153ht789",
      "companyId": "yliki156sro",
      "collectionId": "789efe178d,
      "name": "Benefit 1 from Token A",
      "description": "Benefit 1 description",
      "externalUrl": "https://external-url.com",
      "type": "digital",      
      "expirationDate": "2022-12-31 23:59:59",
      "hasVouchers": true,
      "elegibleTokens": [
        {
          "tokenId": "ijoaedwij",
          "voucherId": "45a1dw36"
        },
        {
          "tokenId": "879esf465",
          "voucherId": "0grte8789r",
        },
        {
          "tokenId":"213e6854f",
          "voucherId": "1e3wfa58ad8",
        },
        {
          "tokenId":"1c5e6799aw",
          "voucherId": "798fdsqwew87",
        }
      ]
    },
    {
      "id": "8798wdefs",
      "companyId": "yliki156sro",
      "communityId": "gdr153ht789",
      "collectionId": "grd874r187ws,
      "name": "Benefit 1 from Token B",
      "description": "Benefit 1 description",
      "externalUrl": "https://external-url.com",
      "type": "digital",
      "expirationDate": null,
      "hasVouchers": false,
      "elegibleTokens": [
        {
          "tokenId": "ijoaedwij",
          "voucherId": null
        },
        {
          "tokenId": "879esf465",
          "voucherId": null,
        },
        {
          "tokenId":"213e6854f",
          "voucherId": null,
        },
        {
          "tokenId":"1c5e6799aw",
          "voucherId": null,
        }
      ]
    },
    {
      "id": "8798wdefs",
      "companyId": "yliki156sro",
      "communityId": "gdr153ht789",
      "collectionId": "grd874r187ws,
      "name": "Benefit 2 from Token B",
      "description": "Benefit 2 description",
      "externalUrl": "https://external-url.com",
      "type": "digital",
      "expirationDate": "2022-12-31 23:59:59",
      "hasVouchers": true,
      "elegibleTokens": [
        {
          "tokenId": "ijoaedwij",
          "voucherId": "45a1dw36"
        },
        {
          "tokenId": "879esf465",
          "voucherId": "0grte8789r",
        },
        {
          "tokenId":"213e6854f",
          "voucherId": "1e3wfa58ad8",
        },
        {
          "tokenId":"1c5e6799aw",
          "voucherId": "798fdsqwew87",
        }
      ]
    },
  ]
}
    
```

{% endtab %}

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

* **`benefits`** *- Array of Objects*

  Armazena as informações de cada benefício que o usuário logado tem direito.

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

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

    Identificador próprio da empresa gestora da comunidade.
  * **`communityId`** *- String*

    Identificador próprio da comunidade gestora da coleção.
  * **`collectionId`** *- String*

    Identificador próprio da coleção do token com aquele benefício.
  * **`name`** *- String*

    Nome do benefício.
  * **`description`** *- String*

    Descrição do benefício, podendo conter instruções de seu resgate.
  * **`externalUrl`** *- String*

    Link para redirecionamento externo caso o benefício exija alguma ação externa.
  * **`type`** *- String*

    Tipo de resgate do benefício. Pode ser `digital` ou `physical`.
  * **`expirationDate`** *- DateTime*

    Data e hora de validade do benefício, quando necessário.
  * **`tags`** *- Array*

    Conjunto de tags do benefício
  * **`hasVouchers`** *- Boolean*

    Indica se determinado benefício deve possuir vouchers atrelados aos tokens. Caso *`true`*, a API atribui os códigos passados na requisição. Caso não sejam passados códigos, ela gerará códigos aleatórios de 8 caracteres distintos para cada token associado. Caso *`false`*, nenhum tratamento adicional é feito e os campos *`voucherId`* dentro de *`elegibleTokens`* são preenchidos como *`null`*.
  * **`elegibleTokens`***- Array of Objects*

    Armazena os dados dos identificadores de tokens e vouchers relacionados àquele benefício.

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

      Identificador próprio do token que dá direito àquele benefício.
    * **`voucherId`** *- String*

      Identificador próprio relativos ao voucher relacionados ao benefício. Pode ser `null` se o benefício não der direito à um 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) Cria um benefício e seus vouchers

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

Essa rota permite a criação de um benefício e a aplicação dele à diversos tokens, assim como a criação sequencial de cada um dos vouchers passados como parâmetro em `voucherCodes`, já retornando na resposta o objeto final com os `id` dos vouchers.

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                                                                                                     |
| ------------------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------- |
| name<mark style="color:red;">\*</mark>           | String     | Nome do Benefício                                                                                               |
| type<mark style="color:red;">\*</mark>           | String     | Tipo de resgate do Benefício. Valores possíveis: \['benefit', 'airdrop']                                        |
| description<mark style="color:red;">\*</mark>    | String     | Descrição do Benefício                                                                                          |
| externalUrl                                      | String     | Link para redirecionamento externo do benefício                                                                 |
| expirationDate                                   | DateTime   | Data limite de resgate do código ou validade do benefício                                                       |
| elegibleTokens<mark style="color:red;">\*</mark> | \[Objects] | Lista de IDs de Tokens e códigos de Vouchers relacionados ao benefício                                          |
| hasVouchers                                      | Boolean    | Indicativo de atrelar ou não vouchers aos tokens                                                                |
| companyId<mark style="color:red;">\*</mark>      | String     | ID da Empresa                                                                                                   |
| communityId<mark style="color:red;">\*</mark>    | String     | ID da Comunidade                                                                                                |
| collectionId<mark style="color:red;">\*</mark>   | String     | ID da Coleção                                                                                                   |
| tags                                             | Array      | Tags do Benefício                                                                                               |
| rewardType<mark style="color:red;">\*</mark>     | String     | <p>O benefício em si é digital ou físico?</p><p>Valores possíveis: \['digital', 'physical']</p>                 |
| status                                           | String     | <p>Status de atividade do benefício. Por padrão é 'active'</p><p>Valores possíveis: \['active', 'disabled']</p> |

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

```javascript
{
  "id": "8798wdefs",
  "companyId": "yliki156sro",
  "communityId": "gdr153ht789",
  "collectionId": "grd874r187ws",
  "name": "Benefit 2 from Token B",
  "description": "Benefit 2 description",
  "externalUrl": "https://external-url.com",
  "type": "benefit",
  "rewardType": "digital",
  "tags": ["ambiental", "arte", "empreeendedorismo"],
  "expirationDate": "2022-12-31 23:59:59",
  "hasVouchers": true,
  "elegibleTokens": [
    {
      "tokenId": "ijoaedwij",
      "voucherId": "45a1dw36"
    },
    {
      "tokenId": "879esf465",
      "voucherId": "0grte8789r",
    },
    {
      "tokenId":"213e6854f",
      "voucherId": "1e3wfa58ad8",
    },
    {
      "tokenId":"1c5e6799aw",
      "voucherId": "798fdsqwew87",
    }
  ]
}
```

{% endtab %}

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

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

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

  Identificador próprio da empresa gestora da comunidade.
* **`communityId`** *- String*

  Identificador próprio da comunidade gestora da coleção.
* **`collectionId`** *- String*

  Identificador próprio da coleção do token com aquele benefício.
* **`name`** *- String*

  Nome do benefício.
* **`description`** *- String*

  Descrição do benefício, podendo conter instruções de seu resgate.
* **`externalUrl`** *- String*

  Link para redirecionamento externo caso o benefício exija alguma ação externa.
* **`type`** *- String*

  Tipo de resgate do benefício. Pode ser `benefit` ou `airdrop`.
* **`rewardType`** *- String*

  Tipo do benefício em si. Pode ser `digital` ou `physical`.
* **`status`***- String*

  Status de atividade do benefício. Pode ser `active` ou `disabled`.
* **`tags`** *- Array*

  Conjunto de tags do benefício.
* **`expirationDate`** *- DateTime*

  Data e hora de validade do benefício, quando necessário.
* **`hasVouchers`** *- Boolean*

  Indica se determinado benefício deve possuir vouchers atrelados aos tokens. Caso *`true`*, a API atribui os códigos passados na requisição. Caso não sejam passados códigos, ela gerará códigos aleatórios de 8 caracteres distintos para cada token associado. Caso *`false`*, nenhum tratamento adicional é feito e os campos *`voucherId`* dentro de *`elegibleTokens`* são preenchidos como *`null`*.
* **`elegibleTokens`***- Array of Objects*

  Armazena os dados dos identificadores de tokens e vouchers relacionados àquele benefício.

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

    Identificador próprio do token que dá direito àquele benefício.
  * **`voucherId`** *- String*

    Identificador próprio relativos ao voucher relacionados ao benefício. Pode ser `null` se o benefício não der direito à um 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) Lista as informações de um determinado benefício para um administrador

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

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

#### Path Parameters

| Name      | Type   | Description     |
| --------- | ------ | --------------- |
| benefitId | String | ID do Benefício |

#### Headers

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

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

```javascript
{
  "id": "8798wdefs",
  "communityId": "gdr153ht789",
  "companyId": "yliki156sro",
  "collectionId": "789efe178d,
  "name": "Benefit 1 from Token A",
  "description": "Benefit 1 description",
  "externalUrl": "https://external-url.com",
  "type": "digital",
  "tags": ["ambiental", "arte", "empreeendedorismo"],
  "expirationDate": "2022-12-31 23:59:59",
  "hasVouchers": true,
  "elegibleTokens": [
    {
      "tokenId": "ijoaedwij",
      "voucherId": "45a1dw36"
    },
    {
      "tokenId": "879esf465",
      "voucherId": "0grte8789r",
    },
    {
      "tokenId":"213e6854f",
      "voucherId": "1e3wfa58ad8",
    },
    {
      "tokenId":"1c5e6799aw",
      "voucherId": "798fdsqwew87",
    }
  ]
}
    
```

{% endtab %}

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

* **`benefits`** *- Array of Objects*

  Armazena as informações de cada benefício que o usuário logado tem direito.

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

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

    Identificador próprio da empresa gestora da comunidade.
  * **`communityId`** *- String*

    Identificador próprio da comunidade gestora da coleção.
  * **`collectionId`** *- String*

    Identificador próprio da coleção do token com aquele benefício.
  * **`name`** *- String*

    Nome do benefício.
  * **`description`** *- String*

    Descrição do benefício, podendo conter instruções de seu resgate.
  * **`externalUrl`** *- String*

    Link para redirecionamento externo caso o benefício exija alguma ação externa.
  * **`type`** *- String*

    Tipo de resgate do benefício. Pode ser `digital` ou `physical`.
  * **`tags`** *- Array*

    Conjunto de tags do benefício.
  * **`expirationDate`** *- DateTime*

    Data e hora de validade do benefício, quando necessário.
  * **`hasVouchers`** *- Boolean*

    Indica se determinado benefício deve possuir vouchers atrelados aos tokens. Caso *`true`*, a API atribui os códigos passados na requisição. Caso não sejam passados códigos, ela gerará códigos aleatórios de 8 caracteres distintos para cada token associado. Caso *`false`*, nenhum tratamento adicional é feito e os campos *`voucherId`* dentro de *`elegibleTokens`* são preenchidos como *`null`*.
  * **`elegibleTokens`***- Array of Objects*

    Armazena os dados dos identificadores de tokens e vouchers relacionados àquele benefício.

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

      Identificador próprio do token que dá direito àquele benefício.
    * **`voucherId`** *- String*

      Identificador próprio relativos ao voucher relacionados ao benefício. Pode ser `null` se o benefício não der direito à um 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 benefício

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

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

#### Path Parameters

| Name      | Type   | Description     |
| --------- | ------ | --------------- |
| benefitId | String | ID do Benefício |

#### Headers

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

#### Request Body

| Name           | Type       | Description                                                    |
| -------------- | ---------- | -------------------------------------------------------------- |
| name           | String     | Nome do Benefício                                              |
| type           | String     | Tipo de resgate do Benefício                                   |
| description    | String     | Descrição do Benefício                                         |
| externalUrl    | String     | Link para redirecionamento externo do benefício                |
| expirationDate | DateTime   | Data limite de resgate do código ou validade do benefício      |
| elegibleTokens | \[Objects] | Lista de IDs de Tokens e de Vouchers relacionados ao benefício |
| hasVouchers    | Boolean    | Indicativo de atrelar ou não vouchers aos tokens               |
| tags           | Array      | Tags do Benefício                                              |

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

```javascript
{
  "id": "8798wdefs",
  "companyId": "yliki156sro",
  "communityId": "gdr153ht789",
  "collectionId": "grd874r187ws,
  "name": "Benefit 2 from Token B",
  "description": "Benefit 2 description",
  "externalUrl": "https://external-url.com",
  "type": "digital",
  "tags": ["ambiental", "arte", "empreeendedorismo"],
  "expirationDate": "2022-12-31 23:59:59",
  "hasVouchers": true,
  "elegibleTokens": [
    {
      "tokenId": "ijoaedwij",
      "voucherId": "45a1dw36"
    },
    {
      "tokenId": "879esf465",
      "voucherId": "0grte8789r",
    },
    {
      "tokenId":"213e6854f",
      "voucherId": "1e3wfa58ad8",
    },
    {
      "tokenId":"1c5e6799aw",
      "voucherId": "798fdsqwew87",
    }
  ]
}
```

{% endtab %}

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

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

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

  Identificador próprio da empresa gestora da comunidade.
* **`communityId`** *- String*

  Identificador próprio da comunidade gestora da coleção.
* **`collectionId`** *- String*

  Identificador próprio da coleção do token com aquele benefício.
* **`name`** *- String*

  Nome do benefício.
* **`description`** *- String*

  Descrição do benefício, podendo conter instruções de seu resgate.
* **`externalUrl`** *- String*

  Link para redirecionamento externo caso o benefício exija alguma ação externa.
* **`type`** *- String*

  Tipo de resgate do benefício. Pode ser `digital` ou `physical`.
* **`tags`** *- Array*

  Conjunto de tags do benefício.
* **`expirationDate`** *- DateTime*

  Data e hora de validade do benefício, quando necessário.
* **`hasVouchers`** *- Boolean*

  Indica se determinado benefício deve possuir vouchers atrelados aos tokens. Caso *`true`*, a API atribui os códigos passados na requisição. Caso não sejam passados códigos, ela gerará códigos aleatórios de 8 caracteres distintos para cada token associado. Caso *`false`*, nenhum tratamento adicional é feito e os campos *`voucherId`* dentro de *`elegibleTokens`* são preenchidos como *`null`*.
* **`elegibleTokens`***- Array of Objects*

  Armazena os dados dos identificadores de tokens e vouchers relacionados àquele benefício.

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

    Identificador próprio do token que dá direito àquele benefício.
  * **`voucherId`** *- String*

    Identificador próprio relativos ao voucher relacionados ao benefício. Pode ser `null` se o benefício não der direito à um 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) Desativa um benefício

<mark style="color:red;">`DELETE`</mark> `https://goblockchain.io/gotokens-api/v1/benefits/:benefitId/manage`

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

#### Path Parameters

| Name | Type   | Description     |
| ---- | ------ | --------------- |
| id   | String | ID do Benefício |

#### Headers

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

{% tabs %}
{% tab title="204: No Content " %}

{% 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/beneficios.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.