Benefícios

Utilidades associadas aos tokens para engajamento de comunidade

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

Exemplo de Objeto de Benefício
{
  "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",
    }
  ]
}

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

GET https://goblockchain.io/gotokens-api/v1/benefits

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

Query Parameters

NameTypeDescription

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

NameTypeDescription

authorization*

Bearer

JWT

{
  "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"
    },
  ]
}

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

GET 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

NameTypeDescription

id

String

ID do Benefício

Headers

NameTypeDescription

authorization*

Bearer

JWT

{
  "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"
}

Exibe benefícios de um token público

GET https://goblockchain.io/gotokens-api/v1/benefits/token/:tokenId

Nível de permissionamento necessário: qualquer

Path Parameters

NameTypeDescription

tokenId*

String

ID do token

{
  "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"],
    }
  ]
}

Gestão de Benefícios

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

GET https://goblockchain.io/gotokens-api/v1/benefits/manage

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

Query Parameters

NameTypeDescription

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

NameTypeDescription

authorization*

Bearer

JWT

{
  "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",
        }
      ]
    },
  ]
}

(JWT) Cria um benefício e seus vouchers

POST 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

NameTypeDescription

authorization*

Bearer

JWT

Request Body

NameTypeDescription

name*

String

Nome do Benefício

type*

String

Tipo de resgate do Benefício. Valores possíveis: ['benefit', 'airdrop']

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 códigos de Vouchers relacionados ao benefício

hasVouchers

Boolean

Indicativo de atrelar ou não vouchers aos tokens

companyId*

String

ID da Empresa

communityId*

String

ID da Comunidade

collectionId*

String

ID da Coleção

tags

Array

Tags do Benefício

rewardType*

String

O benefício em si é digital ou físico?

Valores possíveis: ['digital', 'physical']

status

String

Status de atividade do benefício. Por padrão é 'active'

Valores possíveis: ['active', 'disabled']

{
  "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",
    }
  ]
}

(JWT) Lista as informações de um determinado benefício para um administrador

GET 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

NameTypeDescription

benefitId

String

ID do Benefício

Headers

NameTypeDescription

authorization*

Bearer

JWT

{
  "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",
    }
  ]
}

(JWT) Atualiza as informações de um benefício

PATCH 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

NameTypeDescription

benefitId

String

ID do Benefício

Headers

NameTypeDescription

authorization*

Bearer

JWT

Request Body

NameTypeDescription

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

{
  "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",
    }
  ]
}

(JWT) Desativa um benefício

DELETE 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

NameTypeDescription

id

String

ID do Benefício

Headers

NameTypeDescription

authorization*

Bearer

JWT

PreviousTokenNextVouchers

Last updated