API

Visão geral

Este guia é sobre a tarefa de API. Você pode encontrar nossa documentação completa da API aqui.

As quests de API são usadas para automatizar quests em plataformas externas. Você pode usá-las para confirmar que o usuário se registrou ou fez uma compra, abriu um PR para um problema no Github ou para adicionar suporte ao Reddit. As possibilidades são infinitas. Para começar e experimentar a funcionalidade, oferecemos um endpoint básico que você pode usar para fazer parcerias com outras comunidades Zealy. Saiba mais sobre como configurá-lo abaixo.

Básico

Criando uma tarefa "API"

1. Clique em 'Adicionar tarefa'.
2. Selecione 'Api'.
3. Defina o endpoint a ser chamado e uma chave de API, se necessário.
4. Escolha como os usuários podem se identificar. Você pode selecionar entre Email, Twitter, Discord, Endereço da carteira, ou Zealy Connect.

• Se escolher conexão de carteira, você também pode escolher qual rede usar.

• Se escolher Zealy Connect, siga estas etapas:

  1. Defina a URL de redirecionamento: Esta URL será usada para autenticação. Redirecionaremos os usuários para esta URL para que se autentiquem no seu sistema.

  

  2. Gere um segredo da comunidade: Gerar um segredo da comunidade é necessário para que o Zealy Connect funcione. Você pode criar o segredo nas configurações do Zealy Connect na seção Integrações nas configurações da sua comunidade.

  

Para informações detalhadas sobre como as APIs devem funcionar, consulte a documentação da API e para orientações sobre como gerenciar o Zealy Connect, consulte a documentação do Zealy Connect.

Integração com Domino

Domino é o Zapier da Web3. Ele permite estender as capacidades do Zealy e revisar automaticamente tarefas que não são suportadas nativamente, como:

• Verificar se o nome ou a bio do Twitter de um usuário contém uma palavra específica
• Verificar o saldo de NFT e tokens de um usuário
• Verificar se um usuário convidou um certo número de pessoas no Discord
• E muito mais

Confira a documentação deles para integração.

Teste de endpoint

Ao configurar o endpoint, executaremos automaticamente os seguintes testes para garantir que o endpoint esteja funcionando conforme o esperado:

1. Verificar se a chamada não leva mais de 10 segundos
2. Verificar se a mensagem de erro está no formato correto para que possamos exibi-la ao usuário
3. Garantir que não seja nenhum dos códigos de status inesperados. O endpoint deve retornar apenas 200 ou 400.

Criando um endpoint personalizado

Requisição

Você pode usar as tarefas de API com um POST endpoint personalizado que aceita o seguinte corpo:

{
  /**
   * The user id on Zealy
   */
  userId: string;
  /**
   * Your community id on Zealy, if you use the endpoint
   * on multiple communities this might be useful
   */
  communityId: string;
  /**
   * Your community's subdomain on Zealy, if you use the endpoint
   * on multiple communities this might be useful
   */
  subdomain: string;
  /**
   * The id of the quest
   */
  questId: string;
  /**
   * This will be generated on every claim as a way to look up an error.
   * It will also be displayed for the user when a claim fails.
   */
  requestId: string;
  /**
   * Accounts will be sent if at least one identification method has been configured
   */
  accounts?: {
    /**
     * The user's email address
     */
    email?: string;
    /**
     * The user's Ethereum wallet address that he has authenticated with
     */
    wallet?: string;
    /**
     * The user's Discord id and handle
     */
    discord?: {
      id: string;
      handle: string;
    };
    /**
     * The user's Twitter id and username
     */
    twitter?: {
      id: string;
      username: string;
    };
    /**
     * Your platform user ID stored as part of the Zealy Connect integration
    */
    zealy-connect: string
  };
}

Você pode protegê-lo com uma chave de API definida ao criar a tarefa. A chave de API será enviada nos cabeçalhos assim:

{
  "X-Api-Key": apiKey,
}

Resposta

Se a ação foi executada com sucesso pelo usuário, você deve retornar um 200 status. O usuário então reivindicará a tarefa com sucesso.

{
  "message": "User completed the action"
}

Caso contrário, o 400 status deve ser retornado na resposta junto com uma mensagem no corpo. A mensagem será exibida com o requestId gerado para ajudar você e o usuário a depurar quaisquer problemas. Certifique-se de que seja o mais descritiva possível.

{
  "message": "We could not find a user with email kenny@zealy.io"
}

Exemplo de código

// server.js
//
// Use this sample code to handle quest verification in your endpoint.
//
// 1) Paste this code into a new file (server.js)
//
// 2) Install dependencies
//   npm install express
//
// 3) Run the server on http://localhost:3000
//   node server.js
 
const express = require('express');
const app = express();
 
const apiKey = '5888a6800dbac634e52d8504f097e064'; // Replace with your API key configured in Zealy task
 
app.post('/claim', express.raw({ type: 'application/json' }), (req, res) => {
  const payload = req.body;
  const headers = req.headers
 
  if (apiKey !== headers['x-api-key']) {
    throw new Error('Invalid API Key')
  }
 
 
  const success = true; // Replace with custom logic
 
  if (!success) {
    return res.status(400).send({
      message: 'Validation failed' // Replace with custom error message - will be displayed to the user
    })
  }
 
  return res.status(200).send({
    message: "Quest completed"
  })
});
 
app.listen(3000, () => console.log('Running on port 3000'));

Teste local com ngrok

Ao desenvolver e testar seu endpoint personalizado localmente, você precisa de uma maneira de expor seu servidor local à internet para que o Zealy possa enviar solicitações de API para ele. O ngrok é uma ferramenta que cria túneis seguros para o localhost e é perfeita para esse propósito. Siga estas etapas para configurar o ngrok e testar seu endpoint:

Etapa 1: Instale o ngrok Baixe o ngrok no site do ngrok. Siga as instruções de instalação para o seu sistema operacional.

Etapa 2: Configure o ngrok Inscreva-se para uma conta gratuita do ngrok e obtenha seu authtoken no painel do ngrok. Conecte sua conta ngrok executando ngrok authtoken YOUR_AUTH_TOKEN no seu terminal, substituindo YOUR_AUTH_TOKEN pelo token do seu painel ngrok.

Etapa 3: Inicie seu servidor local Certifique-se de que seu servidor local que hospeda o endpoint esteja em execução. Por exemplo, se seu servidor for um aplicativo Node.js, você pode executar node server.js.

Etapa 4: Exponha seu servidor local com ngrok Abra uma nova janela de terminal e inicie um túnel ngrok para a porta do seu servidor local (por exemplo, 3000) usando ngrok http http://127.0.0.1:3000. O ngrok exibirá uma URL de encaminhamento no terminal (por exemplo, https://abc123.ngrok.io). Esta é a URL pública que o Zealy usará para acessar seu servidor local.

Etapa 5: Configure sua tarefa de API no Zealy Use a URL de encaminhamento do ngrok como a URL do endpoint ao configurar sua tarefa de API no Zealy. Certifique-se de anexar qualquer caminho necessário, por exemplo, https://abc123.ngrok.io/claim.

Nota: Lembre-se, as URLs do ngrok são temporárias e mudam toda vez que você reinicia o ngrok, a menos que você tenha uma assinatura paga que suporte subdomínios personalizados. Certifique-se de atualizar o endpoint no Zealy toda vez que reiniciar o ngrok.

Seguindo estas etapas, você pode testar e depurar facilmente seu endpoint personalizado em um ambiente de desenvolvimento local antes de implantá-lo em um servidor de produção.

Integração com Zealy Connect

Ao usar o Zealy Connect, redirecionaremos o usuário para a URL especificada durante a configuração da tarefa. Incluiremos os seguintes parâmetros de consulta:

• zealyUserId: Um identificador único para o usuário no sistema Zealy usado para vinculá-lo à sua plataforma.
• callback: A URL para redirecionar o usuário de volta após a conclusão da autenticação para que ele possa reivindicar a tarefa.
• signature: Um hash SHA-256 usado para verificar a autenticidade da solicitação, garantindo que ela se originou do Zealy.

Aqui está um exemplo completo de endpoint que você pode usar como ponto de partida:

 
const YOUR_COMMUNITY_SECRET = "fdb68b155a1ccf2e636c7cd7e0816530"; // Replace with your secret generated in Settings > Integrations > Zealy Connect
 
app.get("/connect", (req, res) => {
  // Extract the query parameters
  const { zealyUserId, signature, callbackUrl } = req.query;
 
  /**
   * Verifying signature to ensure the request is coming from Zealy
   */
  const fullUrl = new URL(
    `${req.protocol}://${req.get("host")}${req.originalUrl}`
  );
  fullUrl.searchParams.delete("signature");
 
  const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
  hmac.update(fullUrl.toString());
  const generatedSignature = hmac.digest("hex");
 
  if (generatedSignature !== signature){
    return res.status(400).send("Invalid signature");
  }
 
  /**
   * Redirect to login if the user is not authenticated
   */
  if (!req.session.user) {
    res.redirect(`/login?redirect=${encodeURIComponent(req.originalUrl)}`); // Redirect back after the user logs in
  }
 
  /**
   * Save the Zealy User ID (optional)
  */
  // await updateUser(req.session.user.id, { zealyId: zealyUserId });
 
 
  /**
   * Redirect Back to Zealy
   */
  const userId = req.session.user.id; // Replace with your platform user ID
 
  const callbackWithParams = new URL(callbackUrl as string);
  callbackWithParams.searchParams.append("identifier", userId);
 
  const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
  hmac.update(callbackWithParams.toString());
  const callbackSignature = hmac.digest("hex");
 
  callbackWithParams.searchParams.append("signature", callbackSignature);
 
  res.redirect(callbackWithParams.toString());
});

1. Verifique a Assinatura

A primeira coisa que sua aplicação deve fazer é validar a assinatura usando o segredo da sua comunidade. Essa validação garante que a chamada é genuinamente nossa e não foi modificada.

Usamos o algoritmo de hash SHA256 para gerar a assinatura. Para verificá-la, você pode usar a seguinte abordagem:

const fullUrl = new URL(
  `${req.protocol}://${req.get("host")}${req.originalUrl}`
);
fullUrl.searchParams.delete("signature");
 
const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
hmac.update(fullUrl.toString());
const generatedSignature = hmac.digest("hex");
 
const isSignatureValid = generatedSignature === req.query.signature;

2. Use o Zealy User ID

O próximo passo depende do que você quer fazer, mas os clientes geralmente fazem login do usuário atual na sua plataforma e vinculam o ID de usuário da sua plataforma ao Zealy User ID. Abaixo está um exemplo:

  /**
   * Redirect to login if the user is not authenticated
   */
  if (!req.session.user) {
    res.redirect(`/login?redirect=${encodeURIComponent(req.originalUrl)}`); // Redirect back after the user logs in
  }
 
  /**
   * Save the Zealy User ID (optional)
  */
  // await updateUser(req.session.user.id, { zealyId: zealyUserId });
 

3. Redirecione de Volta para o Zealy

O último passo é redirecionar o usuário de volta para o Zealy com o ID de usuário da sua plataforma para que possamos permitir que o usuário reivindique a tarefa, usando o parâmetro de consulta callback que fornecemos. Você também precisa gerar uma assinatura para que possamos verificar que a chamada vem de você e não foi modificada. Veja o exemplo abaixo:

const callbackWithParams = new URL(callbackUrl as string);
callbackWithParams.searchParams.append("identifier", connectedUserId); // Set it to your platform user ID
 
const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
hmac.update(callbackWithParams.toString());
const callbackSignature = hmac.digest("hex");
 
callbackWithParams.searchParams.append("signature", callbackSignature);
 
res.redirect(callbackWithParams.toString());

4. Zealy

Assim que recebermos o callback, validaremos a assinatura e armazenaremos o ID de usuário da sua plataforma para que possamos enviá-lo como parte do corpo da tarefa da API.

O usuário agora poderá reivindicar a tarefa e qualquer outra tarefa que use o Zealy Connect com a mesma URL de redirecionamento. Vamos lembrar disso para que o usuário não precise se conectar para cada tarefa.

Se você precisar excluir a associação de Zealy Connect de um usuário, pode usar a rota da API Delete Zealy Connect for Member. Essa rota permite remover a associação de Zealy Connect de um membro específico. Após chamar essa rota, o usuário precisará reconectar a conta para usar os recursos do Zealy Connect novamente.

FAQ