API

Visão geral

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

As quests de API são usadas para automatizar quests em plataformas externas. Pode usá-las para confirmar que o utilizador se registou ou fez uma compra, abriu um PR para um issue 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 pode usar para estabelecer parcerias com outras comunidades Zealy. Saiba mais sobre como configurá-lo abaixo.

Noções básicas

Criar uma tarefa "API"

1. Clique em 'Adicionar tarefa'.
2. Selecione 'Api'.
3. Defina o endpoint a chamar e uma chave de API, se necessário.
4. Escolha como os utilizadores se podem identificar. Pode selecionar entre Email, Twitter, Discord, Endereço de carteira, ou Zealy Connect.

• Se escolher ligação de carteira, também pode escolher qual a rede a usar.

• Se escolher Zealy Connect, siga estes passos:

  1. Defina o URL de redirecionamento: Este URL será usado para autenticação. Vamos redirecionar os utilizadores para este URL para que se autentiquem no seu sistema.

  

  2. Gere um segredo da comunidade: É necessário gerar um segredo da comunidade para que o Zealy Connect funcione. Pode criar o segredo nas definições do Zealy Connect na secção Integrações das definiçõ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 a gestão do Zealy Connect, consulte a documentação do Zealy Connect.

Integração com o Domino

O Domino é o Zapier da Web3. Permite-lhe ampliar as capacidades do Zealy e rever automaticamente tarefas que não são suportadas nativamente, tais como:

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

Consulte a respetiva documentação para a integração.

Teste do endpoint

Ao configurar o endpoint, executaremos automaticamente os seguintes testes para garantir que o endpoint funciona como esperado:

1. Verificar se a chamada não demora mais de 10 segundos
2. Verificar se a mensagem de erro está no formato correto para que a possamos mostrar ao utilizador
3. Garantir que não se trata de nenhum dos códigos de estado inesperados. O endpoint deve devolver apenas 200 ou 400.

Criar um endpoint personalizado

Pedido

Pode usar as tarefas de API com um POST endpoint personalizado que aceite 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
  };
}

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

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

Resposta

Se a ação tiver sido executada com sucesso pelo utilizador, deve devolver um 200 estado. O utilizador poderá então reclamar a tarefa com sucesso.

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

Caso contrário, o 400 estado deve ser devolvido na resposta juntamente com uma mensagem no corpo. A mensagem será apresentada com o requestId gerado para ajudar você e o utilizador a depurar quaisquer problemas. Certifique-se de que é 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 o seu endpoint personalizado localmente, precisa de uma forma de expor o seu servidor local à internet para que o Zealy possa enviar-lhe pedidos de API. O ngrok é uma ferramenta que cria túneis seguros para o localhost e é perfeita para este propósito. Siga estes passos para configurar o ngrok e testar o seu endpoint:

Passo 1: Instalar o ngrok Descarregue o ngrok a partir do site do ngrok. Siga as instruções de instalação para o seu sistema operativo.

Passo 2: Configurar o ngrok Registe-se numa conta ngrok gratuita e obtenha o seu authtoken a partir do painel do ngrok. Ligue a sua conta ngrok executando ngrok authtoken YOUR_AUTH_TOKEN no seu terminal, substituindo YOUR_AUTH_TOKEN pelo token do seu painel do ngrok.

Passo 3: Iniciar o seu servidor local Certifique-se de que o seu servidor local que aloja o endpoint está em execução. Por exemplo, se o seu servidor for uma aplicação Node.js, pode executar node server.js.

Passo 4: Expor o seu servidor local com o 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 apresentará um URL de encaminhamento no terminal (por exemplo, https://abc123.ngrok.io). Este é o URL público que o Zealy usará para chegar ao seu servidor local.

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

Nota: Lembre-se de que os URLs do ngrok são temporários e mudam sempre que reinicia o ngrok, a menos que tenha uma subscrição paga que suporte subdomínios personalizados. Certifique-se de que atualiza o endpoint no Zealy sempre que reiniciar o ngrok.

Seguindo estes passos, pode testar e depurar facilmente o seu endpoint personalizado num ambiente de desenvolvimento local antes de o implementar num servidor de produção.

Integração com o Zealy Connect

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

• zealyUserId: Um identificador único para o utilizador no sistema Zealy, usado para o associar à sua plataforma.
• callback: O URL para redirecionar o utilizador de volta após a conclusão da autenticação, para que possa reclamar a tarefa.
• signature: Um hash SHA-256 usado para verificar a autenticidade do pedido, garantindo que teve origem no Zealy.

Aqui está um exemplo completo de endpoint que 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. Verificar a assinatura

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

Utilizamos o algoritmo de hash SHA256 para gerar a assinatura. Para a verificar, 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 passo seguinte depende do que pretende fazer, mas os clientes normalmente iniciam sessão do utilizador atual na sua plataforma e associam o ID de utilizador da sua plataforma ao Zealy User ID. Segue-se 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. Redirecionar de volta para a Zealy

O último passo é redirecionar o utilizador de volta para a Zealy com o ID de utilizador da sua plataforma, para que possamos permitir que o utilizador reivindique a tarefa, usando o parâmetro de consulta callback que fornecemos. Também precisa de gerar uma assinatura para que possamos verificar que a chamada vem de si 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 utilizador da sua plataforma para o podermos enviar como parte do corpo da tarefa da API.

O utilizador poderá agora reivindicar a tarefa e qualquer outra tarefa que utilize o Zealy Connect com o mesmo URL de redirecionamento. Vamos memorizar isto para que o utilizador não tenha de se conectar para cada tarefa.

Se precisar de eliminar a associação Zealy Connect de um utilizador, pode usar a rota da API Delete Zealy Connect for Member. Esta rota permite-lhe remover a associação Zealy Connect de um membro específico. Após chamar esta rota, o utilizador terá de voltar a conectar a conta para utilizar novamente as funcionalidades do Zealy Connect.

FAQ