API de Telegram Stars para B2B: vende Stars y Premium

Si tu producto ya tiene clientes, un checkout o una audiencia en Telegram, no necesitas montar una operación de fulfilment independiente para vender productos digitales de Telegram. La API de Fulfilment de MyStars permite a tu backend crear y seguir pedidos de Telegram Stars y Telegram Premium entregados a un @username de Telegram.

Por eso resulta práctica para tiendas de revendedores, bots y Mini Apps de Telegram, plataformas de creadores, servicios de regalos, programas de fidelidad, agencias, marketplaces y productos que quieran añadir una compra de Telegram sin enviar a cada cliente por un flujo manual de soporte.

¿Quién debería usar una API de Telegram Stars?

Usa una API de Telegram Stars cuando Stars o Premium formen parte del producto que vendes, no para una compra manual puntual de tu propio equipo.

Entre las implementaciones B2B habituales están:

• Tiendas de revendedores que venden paquetes de Stars o duraciones de Premium junto con otros bienes digitales;
• Bots y Mini Apps de Telegram que recopilan un nombre de usuario, muestran una cotización actual y envían el pedido a un backend;
• Plataformas de creadores y comunidades que ayudan a su audiencia a recargar antes de una publicación de pago, una acción de bot o una experiencia premium;
• Productos de regalos y fidelidad que convierten una recompensa de campaña en Telegram Stars o Premium para un destinatario identificado;
• Agencias y servicios gestionados que necesitan un flujo de fulfilment repetible en lugar de procesar manualmente cada solicitud de cliente;
• Marketplaces que necesitan un registro de pedido auditable y un evento cuando se completa la entrega.

La API es una capa de fulfilment, no un widget de frontend. Tu producto conserva la experiencia de cliente, el checkout y las reglas comerciales. Tu servidor usa MyStars para cotizar, validar, crear, pagar y conciliar el pedido de fulfilment de Telegram.

¿Qué puedes vender mediante la API de MyStars?

El catálogo actual admite dos tipos de producto:

• Telegram Stars: un pedido usa una cantidad de Stars;
• Telegram Premium: un pedido usa una duración de Premium en meses.

Stars y Premium resuelven necesidades distintas del comprador, así que preséntalos por separado en tu interfaz. Stars son un saldo de Telegram que se puede gastar en creadores, canales, bots y bienes digitales. Premium es un regalo de suscripción para una cuenta de Telegram. Si tu cliente compara planes Premium en lugar de integrar una API, dirígelo al checkout de Telegram Premium.

No codifiques de forma fija tamaños de paquetes, duraciones de planes, monedas ni precios en una app cliente. La documentación de la API de MyStars expone datos en vivo de productos, monedas y precios para que tu catálogo siga las reglas actuales de la API.

Cómo vender Telegram Stars por API: el flujo de fulfilment B2B

Una integración fiable sigue una secuencia breve pero intencionada. El pedido se crea en tu backend; el cliente nunca debe ver una clave de API ni gestionar instrucciones de pago on-chain que corresponden a tu servicio.

1. Carga el catálogo actual y las monedas de pago. Lee los productos y monedas disponibles cuando se inicia la integración y actualízalos con una cadencia razonable. Así evitas que una versión antigua de la app ofrezca una opción no disponible.
2. Solicita una cotización en vivo. Pide al endpoint de precios el producto elegido, la cantidad o duración y la moneda de pago. Usa el importe devuelto como importe de liquidación; no calcules un precio a partir de supuestos de tipo de cambio almacenados en caché.
3. Comprueba el destinatario antes de cobrar o crear el pedido. Envía el @username de Telegram del destinatario y el producto elegido al endpoint de comprobación de destinatario. Una comprobación de destinatario de Stars y una comprobación de elegibilidad de Premium no son intercambiables.
4. Crea un pedido idempotente. Envía el producto seleccionado, el destinatario, la moneda de pago, una URL de callback si usas webhooks y un Idempotency-Key estable generado a partir de tu propio ID interno de pedido.
5. Liquida exactamente la instrucción de pago devuelta. La respuesta del pedido contiene la dirección de destino, el importe, el memo, la cadena y el vencimiento. Tu servicio de pagos debe usar esos valores exactamente, en lugar de una dirección de cartera o memo guardado en la configuración de la aplicación.
6. Concilia el estado final de entrega. Consulta el endpoint de estado del pedido como respaldo o recibe el estado final a través de tu webhook. Marca como completado el pedido de tu cliente solo cuando se cumplan tus reglas de conciliación.

Esta secuencia es lo que diferencia una integración B2B de API de Telegram Stars de un simple enlace de compra: cada paso puede almacenarse, reintentarse con seguridad, observarse y ser atendido por tu equipo de producto.

Los datos que debe conservar tu backend

Tu base de datos es la fuente de verdad del pedido de cara al cliente. Guarda información suficiente para explicar un pedido a soporte, reintentar una operación segura y conciliar un pago en blockchain sin exponer secretos.

Como mínimo, conserva:

• tu ID interno de pedido y el ID de pedido de MyStars;
• la clave de idempotencia usada para crear ese pedido;
• el tipo de producto, la cantidad de Stars o la duración de Premium y el nombre de usuario del destinatario;
• la moneda cotizada, importe, cadena, vencimiento y memo de pago;
• el hash de transacción on-chain tras la liquidación;
• tu estado de pago, el estado del pedido de MyStars, la carga útil del webhook o la marca temporal de sondeo y el resultado final del fulfilment.

Un Idempotency-Key importa porque los sistemas reales reintentan. Un tiempo de espera de red después de POST /v1/orders no prueba que no haya ocurrido nada. Reintentar con la misma clave estable permite a tu backend recuperarse sin crear un segundo pedido de fulfilment para la misma compra del cliente.

Webhooks, sondeo y ciclo de vida del pedido

Tu cliente puede pagar primero a tu producto, mientras tu servicio liquida la instrucción de MyStars después. Eso crea tres estados operativos que no deben confundirse:

1. el cliente pagó tu producto;
2. tu servicio envió el pago on-chain del pedido de MyStars;
3. MyStars entregó Stars o Premium al destinatario de Telegram.

Cuando se crea un pedido, puede devolverse como awaiting_payment con un bloque de pago y un vencimiento. Una vez que avanza la liquidación y el fulfilment, tu sistema necesita una forma fiable de recibir el resultado final.

Usa un callback de webhook para las actualizaciones normales de entrega y conserva el sondeo de estado como ruta de recuperación. Verifica que las solicitudes entrantes de webhook sean procesadas por tu backend, relaciónalas con el ID de pedido de MyStars y haz que el procesamiento de webhooks también sea idempotente. Un callback duplicado no debe conceder una recompensa duplicada, emitir un segundo recibo ni activar un segundo flujo de reembolso.

Liquidación de pagos: GRAM (TON) y USDT en TON

Los pedidos de la API de MyStars pueden liquidarse en GRAM (TON) o USDT (TON). Son operaciones de pago de backend, no campos que deban copiarse sin más a un checkout del cliente.

Para cada pedido, lee la moneda, cadena, dirección, importe, memo y vencimiento devueltos en la respuesta de la API. No reutilices los datos de pago de un pedido anterior. Un pago con importe, comentario, red o instrucción vencida incorrectos puede fallar en la conciliación.

Mantén la firma de cartera y las llamadas a la API del lado del servidor. Nunca distribuyas X-Api-Key, una semilla de cartera o credenciales de liquidación automatizada en un bundle de navegador, una Mini App de Telegram, un repositorio público o un registro del cliente.

Sin KYC del comprador: el significado preciso para B2B

"Sin KYC del comprador" es un término de búsqueda, pero requiere un lenguaje preciso. En este flujo, el checkout de fulfilment de MyStars no exige que el comprador cargue documentos de identidad. Esto puede reducir la fricción en la experiencia de producto.

Lista de comprobación de lanzamiento para una integración de API de revendedor de Telegram Stars

Antes de hacer visible la función a los clientes, verifica lo siguiente:

• La clave de API se almacena solo en gestión de secretos del lado del servidor y se puede rotar;
• las opciones de producto y moneda proceden de la API en vivo y no de valores codificados de forma fija;
• se ejecuta una comprobación de destinatario antes de crear el pedido y antes del cargo final al cliente;
• cada pedido tiene un ID interno estable y una clave de idempotencia;
• el pago usa la dirección, importe, memo, cadena y vencimiento exactos devueltos para ese pedido;
• USDT se etiqueta solo TON en todos los lugares donde aparece;
• el manejo de webhooks verifica, correlaciona, registra y deduplica eventos de forma segura;
• el sondeo cubre un webhook perdido o retrasado;
• tu equipo de soporte puede encontrar un pedido por tu ID, ID de pedido de MyStars, destinatario y hash de transacción;
• las reglas de reembolso, fraude, cumplimiento y comunicación con el cliente están definidas antes del lanzamiento.

Para los formatos de solicitud, campos de respuesta, opciones de SDK y el contrato de API en vivo, usa la documentación de la API de MyStars como fuente de verdad para la implementación.

Preguntas frecuentes

¿Puedo vender Telegram Stars mediante mi propio sitio web, bot o Mini App?

Sí. Tu producto puede recoger la selección del cliente y el nombre de usuario del destinatario, mientras tu backend usa la API de Fulfilment de MyStars para crear y seguir el pedido de Stars. Mantén la clave de API y las operaciones de liquidación del lado del servidor.

¿Puedo vender Telegram Premium mediante la misma API?

Sí. La API admite el fulfilment de Telegram Premium como un tipo de producto independiente con duración de Premium en meses. Comprueba la elegibilidad del destinatario antes de crear un pedido, porque las restricciones de regalo de Premium pueden diferir de las comprobaciones de destinatario de Stars.

¿La API ofrece una lista de precios fija para Stars y Premium?

Usa el endpoint de precios para una cotización en vivo en lugar de depender de una lista fija. La respuesta de la API es la fuente adecuada para el importe actual y la moneda de liquidación del pedido seleccionado.

¿Cómo evito pedidos duplicados de Telegram Stars?

Crea cada pedido con un Idempotency-Key estable vinculado a tu propio ID interno de pedido. Si un worker del servidor reintenta debido a un tiempo de espera, reutiliza la misma clave en lugar de generar una nueva.

¿Qué red de USDT es compatible?

USDT solo en TON / The Open Network. No envíes ni presentes USDT en otra red como método de liquidación compatible.

¿Que no haya KYC del comprador significa que mi negocio no tiene obligaciones de cumplimiento?

No. Describe la experiencia de checkout del comprador en MyStars, no las responsabilidades legales, financieras, antifraude, fiscales, de sanciones, de protección del consumidor o de reembolso de tu empresa.

Inicia tu integración B2B de fulfilment de Telegram

Si tu producto necesita vender Telegram Stars o Premium a escala, constrúyelo sobre un ciclo de vida de pedido verificable: cotización en vivo, comprobación de destinatario, creación idempotente del pedido, liquidación on-chain exacta y un webhook final o conciliación de estado.

Abre la documentación de la API de MyStars e inicia la integración →

Fuentes y evidencia

• MyStars FaaS: documentación de la API de Fulfilment: catálogo de productos, precios en vivo, comprobaciones de destinatario, creación de pedidos, autenticación de API, instrucciones de liquidación, seguimiento de estado y webhooks.