Guía del SDK de API Fragment para apps y bots de Telegram

La mayoría de las ideas de comercio en Telegram chocan con la misma pared después del prototipo: el bot o la Mini App es fácil de crear, pero el fulfilment de Stars y Premium sigue necesitando un flujo de backend fiable. Por eso los desarrolladores buscan una API Fragment.

MyStars FaaS aporta esa capa que falta. FaaS significa Fragment as a Service: tu producto de Telegram conserva la experiencia de usuario y la base de datos de pedidos, mientras MyStars expone el flujo de fulfilment mediante una API, SDK oficiales y actualizaciones de estado firmadas.

Usa esta guía cuando quieras conectar una app, bot, marketplace, herramienta para creadores o flujo de revendedor de Telegram reales, no solo leer otra introducción a una API.

La arquitectura limpia: API de Telegram delante, API Fragment detrás

Mantén el límite simple.

Tu capa de API de Telegram gestiona las partes que los usuarios pueden ver: comandos de bot, teclados en línea, pantallas de Mini App, tarjetas de pedido, mensajes y respuestas de soporte.

Tu capa de servidor es dueña de tu lógica de negocio: pedidos locales, margen, reglas antifraude, controles de administración, escrituras en base de datos y evidencia para soporte.

La capa MyStars FaaS gestiona el flujo de Fragment as a Service: precios, comprobaciones de destinatario, creación de pedidos, instrucciones de pago y estado de fulfilment.

Esa separación es importante para la seguridad. No pongas la clave de API de MyStars en el frontend de una Mini App de Telegram. El cliente debe hablar con tu backend; tu backend debe hablar con MyStars.

Instala el SDK para tu stack

Para backends de Node.js y TypeScript, usa el @mystars-tg/faas-sdk oficial:

npm install @mystars-tg/faas-sdk

Para backends de Python, usa el paquete mystars-faas oficial:

pip install mystars-faas

Ambos paquetes se publican como SDK oficiales de MyStars FaaS y dirigen a quienes desarrollan a la documentación interactiva de la API. La documentación actual de los paquetes describe compatibilidad con FaaS API v1.9.0, algo útil al comparar ejemplos del SDK con la referencia de la API.

Crea la primera ruta de backend en TypeScript

La primera ruta no debe intentar hacerlo todo. Empieza con una acción solo de servidor que cotice, compruebe al destinatario y cree un pedido de fulfilment a partir de tu propio ID de pedido local.

Antes del código, esta es la explicación en lenguaje claro de lo que hace:

• crea un cliente MyStars en el backend usando MYSTARS_API_KEY;
• pide a MyStars el precio actual de la cantidad de Stars seleccionada;
• comprueba si el nombre de usuario de Telegram puede recibir el producto;
• se detiene pronto si el destinatario no es elegible, en lugar de crear un pedido erróneo;
• crea el pedido de fulfilment usando tu localOrderId estable como base de la idempotencia;
• devuelve la cotización y el objeto de pedido de MyStars para que tu app pueda almacenar y mostrar la instrucción de pago.

import { MyStarsClient } from "@mystars-tg/faas-sdk";

const client = MyStarsClient.production(process.env.MYSTARS_API_KEY!);

export async function createStarsOrder(input: {
  username: string;
  quantity: number;
  localOrderId: string;
}) {
  const quote = await client.getPricing({
    type: "stars",
    quantity: input.quantity,
    payment_currency: "ton",
  });

  const recipient = await client.checkRecipient({
    type: "stars",
    recipient: { username: input.username },
  });

  if (!recipient.eligible) {
    return { ok: false, message: recipient.telegram_message };
  }

  const order = await client.createOrder(
    {
      type: "stars",
      recipient: { username: input.username },
      quantity: input.quantity,
      payment_currency: "ton",
      callback_url: "https://your-app.example.com/webhooks/mystars",
    },
    { idempotencyKey: `local-${input.localOrderId}` },
  );

  return { ok: true, quote, order };
}

La parte importante es la clave de idempotencia. Usa algo estable de tu propio sistema. Si la solicitud HTTP vence después de que el pedido se haya creado en el servidor, reintenta con la misma clave en vez de duplicarlo.

Hay algunas líneas que merecen atención adicional:

• MyStarsClient.production(...) significa que la solicitud va a la API de MyStars en vivo, así que usa un pedido de prueba/local en tu propio sistema hasta que estés listo para tráfico real.
• getPricing(...) proporciona a tu backend una cotización actual. No codifiques precios de forma fija en la interfaz del bot.
• payment_currency: "ton" es el enum/nombre de API para la ruta de pago nativa en este ejemplo de SDK. En la interfaz de tu producto, etiqueta esa ruta como Gram o Gram (ex. TON). Reserva TON para el nombre de la blockchain/red.
• checkRecipient(...) protege al comprador de pagar por un nombre de usuario o producto que no puede cumplirse.
• callback_url es donde MyStars puede enviar actualizaciones de estado del pedido tras crearlo.
• idempotencyKey es la protección contra pedidos duplicados. Debe venir del pedido de tu base de datos, no de un valor aleatorio generado en el navegador.

Crea el mismo flujo en Python asíncrono

Los equipos de Python suelen querer código asíncrono porque su framework de bot de Telegram ya lo es. El SDK de Python lo admite directamente.

Este ejemplo hace el mismo trabajo que la ruta de TypeScript, pero en Python:

• abre un cliente MyStars asíncrono durante la solicitud;
• pide una cotización de Premium en usdt_ton;
• comprueba al destinatario antes de crear el pedido;
• devuelve un mensaje de error seguro si el destinatario no puede recibir Premium;
• crea el pedido con una URL de callback para actualizaciones de estado;
• devuelve la cotización y el pedido para que tu bot pueda almacenarlos y mostrar al usuario el siguiente paso.

from mystars_faas import AsyncMyStarsClient

async def create_premium_order(username: str, months: int, local_order_id: str):
    async with AsyncMyStarsClient.production(MYSTARS_API_KEY) as client:
        quote = await client.get_pricing(
            type="premium",
            months=months,
            payment_currency="usdt_ton",
        )

        recipient = await client.check_recipient(username, type="premium")
        if not recipient.eligible:
            return {"ok": False, "message": recipient.telegram_message}

        order = await client.create_order(
            type="premium",
            recipient=username,
            months=months,
            payment_currency="usdt_ton",
            callback_url="https://your-app.example.com/webhooks/mystars",
            idempotency_key=f"local-{local_order_id}",
        )

        return {"ok": True, "quote": quote, "order": order}

Cuando lo lleves a producción, usa un manejo exacto del dinero, conserva la clave de API en una variable de entorno y almacena la instrucción de pago exactamente como se devuelve. Si la instrucción incluye un memo/comentario, trátalo como datos, no como texto que puedas reescribir.

Para un desarrollador menos experimentado, la idea clave es esta: el ejemplo de código no es un bot completo. Es la parte de backend a la que llama tu bot cuando el usuario ya ha elegido un producto. El bot de Telegram todavía necesita sus propios handlers, botones, escrituras en base de datos y mensajes para el usuario alrededor de esta función.

Añade verificación de webhooks antes del lanzamiento

Una integración estilo API Fragment no termina cuando la creación de pedidos funciona. Tu app también necesita una ruta de estado fiable.

Manejador mínimo de webhook:

1. Recibe el cuerpo de la solicitud sin procesar.
2. Lee el encabezado X-Faas-Signature.
3. Verifica la firma con tu secreto de webhook.
4. Deduplica por ID y estado de pedido de MyStars.
5. Actualiza tu pedido local solo si la transición es válida.
6. Notifica al usuario mediante tu bot de Telegram o Mini App.

El SDK de TypeScript documenta ayudantes de webhook como constructEvent, middleware para Express y compatibilidad con Fastify. El SDK de Python incluye WebhookVerifier e integraciones para frameworks web de Python habituales.

Mantén un trabajo de sondeo o conciliación como respaldo. Los webhooks son la ruta rápida; la conciliación es lo que te salva cuando aparece un caso límite de red a las 3 a. m.

Usa el bot blueprint como referencia de trabajo

El bot blueprint de Python de MyStars es la mejor fuente cuando quieres ver juntas todas las piezas en movimiento. Usa mystars-faas==0.1.3 para fulfilment, un servidor aiohttp para comprobaciones de estado y webhooks de MyStars, Postgres y Redis para el estado, monitorización de TON Center para pagos on-chain y comandos de administración para margen y conciliación.

No trates el blueprint como una plantilla de marca. Trátalo como un mapa de ingeniería:

• dónde crear el pedido local;
• dónde llamar a las comprobaciones de destinatario;
• dónde aplicar margen;
• dónde monitorizar el pago;
• dónde llamar al fulfilment;
• dónde editar la tarjeta de pedido de Telegram tras un estado final.

La cuenta de GitHub de MyStars también publica los repositorios de los SDK, por lo que puedes inspeccionar el código fuente, los ejemplos y la estructura de paquetes cuando necesites depurar más allá de un README.

Endpoints de backend que debes crear en tu propia app

Una integración pequeña de nivel producción normalmente empieza con estas rutas:

POST /api/faas/quote
POST /api/faas/recipient-check
POST /api/orders
POST /webhooks/mystars
GET  /api/orders/:id
POST /api/admin/reconcile

El bot de Telegram o la Mini App debe llamar a tu propia ruta /api/orders, no directamente a MyStars. Tu ruta puede entonces validar al usuario, crear un pedido local, llamar al SDK, almacenar el pedido de fulfilment devuelto y enviar de vuelta solo los campos seguros que necesita tu cliente.

Detalles de pago que los usuarios no deben adivinar

Si tu producto muestra una pantalla de pago, sé preciso. Para los flujos de MyStars, USDT significa USDT en TON. Las demás redes de USDT no son intercambiables. Para la ruta nativa, los ejemplos actuales de API aún pueden usar payment_currency: "ton"; el texto de cara al comprador debe usar Gram / GRAM (ex. TON) para el token y TON para la red.

Lee el campo expires_at del pedido en lugar de codificar de forma fija un tiempo de espera de pago. La documentación indica que la ventana de pago se extendió a 1 hora, y expires_at sigue siendo la fuente de verdad.

Qué probar antes del tráfico real

Realiza estas comprobaciones antes de enviar usuarios al flujo:

• un pedido de Stars y un pedido de Premium;
• una ruta de destinatario no elegible;
• reintentar la creación del pedido con la misma clave de idempotencia;
• firmas de webhook válidas e inválidas;
• entrega duplicada de eventos de webhook;
• manejo de pedidos vencidos;
• evidencia para soporte: nombre de usuario, ID de pedido local, ID de pedido de MyStars, hash de pago, memo/comentario y estado;
• acceso solo de administrador para comandos de margen, conciliación, reembolso, difusión y fulfilment manual.

Esta es la parte poco glamurosa, pero es la que hace que un bot de Telegram Stars se sienta fiable en vez de experimental.

Preguntas frecuentes

¿Es esta una API Fragment pública y directa?

MyStars FaaS es una capa de Fragment as a Service. Tu app se integra con las API y los SDK de MyStars, mientras MyStars gestiona el flujo de fulfilment detrás de esa interfaz.

¿Puedo usarla desde una Mini App de Telegram?

Sí. Mantén la clave de API en tu backend. La Mini App debe llamar a tu servidor y tu servidor debe llamar a MyStars FaaS.

¿Con qué paquete debo empezar?

Usa @mystars-tg/faas-sdk para Node.js y TypeScript. Usa mystars-faas para Python y bots asíncronos de Telegram.

¿Necesito el bot blueprint?

No, pero resulta útil si estás creando un bot estilo revendedor con pagos, comandos de administración, conciliación y actualizaciones de estado.

¿Cuál es el primer hito más seguro?

Crea una prueba integral: cotización → comprobación de destinatario → pedido local → pedido de MyStars → webhook verificado o actualización por sondeo. Cuando funcione, añade margen, política de reembolso, herramientas de administración y flujos de soporte.

Para la referencia de API, los enlaces de SDK y las notas del contrato actual, empieza por la documentación de MyStars.