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

Exemplo de Objeto de Voucher

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

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

GET 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*	String	Código do Voucher
type*	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*	Bearer	JWT

200: OK

Exemplo de Resposta

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

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.

401: Unauthorized

Possíveis Erros HTTP - 401

Código	Descrição
1	Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.

403: Forbidden

Possíveis Erros HTTP - 403

Código	Descrição
10	Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.

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

POST 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*	String	ID do Voucher

Headers

Name	Type	Description
authorization*	Bearer	JWT

Request Body

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

200: OK

Exemplo de Resposta

Caso o voucher seja referente ao resgate de um benefício de um token, ele terá os seguintes campos como retorno:

{
  "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": "[e-mail]"
    },
    {
      "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:

{
  "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": "[e-mail]"
    },
    {
      "name": "Celular",
      "type": "phone",
      "placeholder": "Digite aqui seu número de celular",
      "content": "5521998789636"
    }
  ]
}

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.

401: Unauthorized

Possíveis Erros HTTP - 401

Código	Descrição
1	Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.

403: Forbidden

Possíveis Erros HTTP - 403

Código	Descrição
10	Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.

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

POST 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*	String	ID do Voucher

Headers

Name	Type	Description
authorization*	Bearer	JWT

200: OK

Exemplo de Resposta

{
  "token": {
    "id" : "798efsf3sgf",  
    "collectionId": "fs21g65eahjn"
  },
  "voucher": {
    "id": "8798wdefs",
    "type": "airdrop",
    "code": "[e-mail]",
    "revealStatus": "revealed",
    "revealDate": "2022-10-15 15:07:12",
    "redeemStatus": "redeemed",
    "redeemDate": "2022-10-15 15:07:12",
  }  
}

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.

401: Unauthorized

Possíveis Erros HTTP - 401

Código	Descrição
1	Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.

403: Forbidden

Possíveis Erros HTTP - 403

Código	Descrição
10	Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.

Gestão de Vouchers

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

GET 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*	Bearer	JWT

200: OK

Exemplo de Resposta

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

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.

401: Unauthorized

Possíveis Erros HTTP - 401

Código	Descrição
1	Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.

403: Forbidden

Possíveis Erros HTTP - 403

Código	Descrição
10	Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.

(JWT) Cria um voucher

POST 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*	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*	String	Tipo do Voucher (benefit | airdrop)

200: OK

Exemplo de Resposta

Caso o voucher seja referente ao resgate de um benefício de um token, ele terá os seguintes campos como retorno:

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

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

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.

401: Unauthorized

Possíveis Erros HTTP - 401

Código	Descrição
1	Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.

403: Forbidden

Possíveis Erros HTTP - 403

Código	Descrição
10	Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.

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

PATCH 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*	String	ID do Voucher

Headers

Name	Type	Description
authorization*	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

200: OK

Exemplo de Resposta

Caso o voucher seja referente ao resgate de um benefício de um token, ele terá os seguintes campos como retorno:

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

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

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.

401: Unauthorized

Possíveis Erros HTTP - 401

Código	Descrição
1	Credenciais de acesso necessárias. Por favor, execute sua autenticação na plataforma.

403: Forbidden

Possíveis Erros HTTP - 403

Código	Descrição
10	Credenciais de acesso expiradas. Por favor, execute novamente sua autenticação na plataforma.