API

Descripción general

Esta guía trata sobre la tarea de API. Puedes encontrar nuestra documentación completa de la API aquí.

Las misiones de API se utilizan para automatizar misiones en plataformas externas. Puedes usarlas para confirmar que el usuario se ha registrado o ha realizado una compra, ha abierto un PR para un issue en Github o para añadir soporte de Reddit. Las posibilidades son infinitas. Para empezar y probar la funcionalidad, ofrecemos un endpoint básico que puedes usar para hacer alianzas con otras comunidades de Zealy. Aprende más sobre cómo configurarlo a continuación.

Conceptos básicos

Crear una tarea de "API"

1. Haz clic en 'Añadir tarea'.
2. Selecciona 'Api'.
3. Define el endpoint al que llamar y una clave de API si es necesario.
4. Elige cómo pueden identificarse los usuarios. Puedes seleccionar entre Correo electrónico, Twitter, Discord, Dirección de wallet, o Zealy Connect.

• Si eliges conexión de wallet, también puedes elegir qué red usar.

• Si eliges Zealy Connect, sigue estos pasos:

  1. Define la URL de redirección: Esta URL se usará para la autenticación. Redirigiremos a los usuarios a esta URL para que se autentiquen en tu sistema.

  

  2. Genera un secreto de comunidad: Se requiere generar un secreto de comunidad para que Zealy Connect funcione. Puedes crear el secreto desde la configuración de Zealy Connect en la sección de Integraciones de la configuración de tu comunidad.

  

Para obtener información detallada sobre cómo se espera que funcionen las API, consulta la documentación de la API y para obtener orientación sobre cómo gestionar Zealy Connect, consulta la documentación de Zealy Connect.

Integración con Domino

Domino es el Zapier de Web3. Te permite ampliar las capacidades de Zealy y revisar automáticamente tareas que no son compatibles de forma nativa, como:

• Comprobar si el nombre o la biografía de Twitter de un usuario contiene una palabra específica
• Comprobar el saldo de NFT y tokens de un usuario
• Verificar que un usuario ha invitado a un cierto número de personas en Discord
• Y muchas más

Consulta su documentación para la integración.

Prueba del endpoint

Al configurar el endpoint, ejecutaremos automáticamente las siguientes pruebas para asegurarnos de que el endpoint funciona como se espera:

1. Comprobar que la llamada no tarde más de 10 segundos
2. Verificar que el mensaje de error tenga el formato correcto para que podamos mostrarlo al usuario
3. Asegurarnos de que no se devuelva ninguno de los códigos de estado inesperados. El endpoint solo debe devolver 200 o 400.

Crear un endpoint personalizado

Solicitud

Puedes usar las tareas de API con un POST endpoint personalizado que acepte el siguiente cuerpo:

{
  /**
   * 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
  };
}

Puedes protegerlo con una clave de API que se establece al crear la tarea. La clave de API se enviará en los encabezados así:

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

Respuesta

Si el usuario ha realizado la acción correctamente, debes devolver un 200 estado. El usuario podrá entonces reclamar la tarea con éxito.

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

De lo contrario, se debe devolver el 400 estado en la respuesta junto con un mensaje en el cuerpo. El mensaje se mostrará con el requestId generado para ayudarte a ti y al usuario a depurar cualquier problema. Asegúrate de que sea lo más descriptivo posible.

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

Ejemplo 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'));

Pruebas locales con ngrok

Al desarrollar y probar tu endpoint personalizado localmente, necesitas una forma de exponer tu servidor local a Internet para que Zealy pueda enviarle solicitudes de API. ngrok es una herramienta que crea túneles seguros a localhost y es perfecta para este propósito. Sigue estos pasos para configurar ngrok y probar tu endpoint:

Paso 1: Instalar ngrok Descarga ngrok desde el sitio web de ngrok. Sigue las instrucciones de instalación para tu sistema operativo.

Paso 2: Configurar ngrok Regístrate para obtener una cuenta gratuita de ngrok y obtén tu authtoken desde el panel de ngrok. Conecta tu cuenta de ngrok ejecutando ngrok authtoken YOUR_AUTH_TOKEN en tu terminal, reemplazando YOUR_AUTH_TOKEN con el token de tu panel de ngrok.

Paso 3: Iniciar tu servidor local Asegúrate de que tu servidor local que aloja el endpoint esté en ejecución. Por ejemplo, si tu servidor es una aplicación Node.js, podrías ejecutar node server.js.

Paso 4: Exponer tu servidor local con ngrok Abre una nueva ventana de terminal e inicia un túnel ngrok al puerto de tu servidor local (por ejemplo, 3000) usando ngrok http http://127.0.0.1:3000. ngrok mostrará una URL de reenvío en la terminal (por ejemplo, https://abc123.ngrok.io). Esta es la URL pública que Zealy usará para llegar a tu servidor local.

Paso 5: Configurar tu tarea de API en Zealy Usa la URL de reenvío de ngrok como URL del endpoint al configurar tu tarea de API en Zealy. Asegúrate de añadir cualquier ruta requerida, por ejemplo, https://abc123.ngrok.io/claim.

Nota: Recuerda que las URL de ngrok son temporales y cambian cada vez que reinicias ngrok, a menos que tengas una suscripción de pago que admita subdominios personalizados. Asegúrate de actualizar el endpoint en Zealy cada vez que reinicies ngrok.

Siguiendo estos pasos, puedes probar y depurar fácilmente tu endpoint personalizado en un entorno de desarrollo local antes de implementarlo en un servidor de producción.

Integración de Zealy Connect

Al usar Zealy Connect, redirigiremos al usuario a la URL especificada durante la configuración de la tarea. Incluiremos los siguientes parámetros de consulta:

• zealyUserId: Un identificador único para el usuario en el sistema de Zealy usado para vincularlo con tu plataforma.
• callback: La URL a la que redirigir al usuario después de completar la autenticación para que pueda reclamar la tarea.
• signature: Un hash SHA-256 usado para verificar la autenticidad de la solicitud, asegurando que se originó en Zealy.

Aquí tienes un ejemplo completo de endpoint que puedes usar como punto 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 la firma

Lo primero que debe hacer tu aplicación es validar la firma usando tu secreto de comunidad. Esta validación asegura que la llamada proviene genuinamente de nosotros y no ha sido modificada.

Usamos el algoritmo de hash SHA256 para generar la firma. Para verificarla, puedes usar el siguiente enfoque:

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. Usa el ID de usuario de Zealy

El siguiente paso depende de lo que quieras hacer, pero los clientes suelen iniciar sesión con el usuario actual en tu plataforma y vincular el ID de usuario de tu plataforma con el ID de usuario de Zealy. A continuación, un ejemplo:

  /**
   * 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. Redirige de vuelta a Zealy

El último paso es redirigir al usuario de vuelta a Zealy con el ID de usuario de tu plataforma para que podamos permitirle reclamar la tarea, usando el parámetro de consulta callback que proporcionamos. También debes generar una firma para que podamos verificar que la llamada proviene de ti y no ha sido modificada. Consulta el ejemplo a continuación:

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

Una vez que recibamos el callback, validaremos la firma y almacenaremos el ID de usuario de tu plataforma para poder enviarlo como parte del cuerpo de la tarea de la API.

El usuario ahora podrá reclamar la tarea y cualquier otra tarea que use Zealy Connect con la misma URL de redirección. Lo recordaremos para que el usuario no tenga que conectarse en cada tarea.

Si necesitas eliminar la asociación de Zealy Connect de un usuario, puedes usar la ruta de API Delete Zealy Connect for Member. Esta ruta te permite eliminar la asociación de Zealy Connect de un miembro específico. Después de llamar a esta ruta, el usuario deberá volver a conectar su cuenta para usar las funciones de Zealy Connect nuevamente.

Preguntas frecuentes