Guia do SDK da Fragment API para apps e bots do Telegram

A maioria das ideias de comércio no Telegram encontra o mesmo obstáculo depois do protótipo: criar o bot ou Mini App é fácil, mas a entrega de Stars e Premium ainda exige um fluxo de backend confiável. É por isso que desenvolvedores procuram uma Fragment API.

O MyStars FaaS fornece essa camada que falta. FaaS significa Fragment as a Service: seu produto no Telegram mantém a experiência do usuário e o banco de dados de pedidos, enquanto a MyStars disponibiliza o fluxo de entrega por meio de uma API, SDKs oficiais e atualizações de status assinadas.

Use este guia quando quiser integrar um app, bot, marketplace, ferramenta para criadores ou fluxo de revenda real do Telegram — e não apenas ler mais uma visão geral de API.

A arquitetura limpa: Telegram API na frente, Fragment API por trás

Mantenha essa separação simples.

Sua camada de Telegram API cuida das partes que os usuários veem: comandos de bot, teclados inline, telas de Mini App, cartões de pedido, mensagens e respostas de suporte.

Sua camada de servidor é responsável pela lógica de negócio: pedidos locais, margem, regras de fraude, controles administrativos, gravações no banco de dados e evidências para suporte.

A camada MyStars FaaS cuida do fluxo Fragment as a Service: precificação, verificações de destinatário, criação de pedidos, instruções de pagamento e status de entrega.

Essa separação é importante para a segurança. Não coloque a chave de API da MyStars no frontend de um Telegram Mini App. O cliente deve falar com seu backend; seu backend deve falar com a MyStars.

Instale o SDK para sua stack

Para backends em Node.js e TypeScript, use o @mystars-tg/faas-sdk oficial:

npm install @mystars-tg/faas-sdk

Para backends em Python, use o pacote mystars-faas oficial:

pip install mystars-faas

Os dois pacotes são publicados como SDKs oficiais do MyStars FaaS e direcionam quem desenvolve de volta à documentação interativa da API. A documentação atual dos pacotes descreve compatibilidade com a FaaS API v1.9.0, útil para conferir exemplos dos SDKs em relação à referência da API.

Crie a primeira rota de backend em TypeScript

A primeira rota não deve tentar fazer tudo. Comece com uma ação executada somente no servidor, que cota o pedido, verifica o destinatário e cria uma ordem de entrega a partir do seu próprio ID local de pedido.

Antes do código, veja em linguagem simples o que ele faz:

• cria um cliente MyStars no backend com MYSTARS_API_KEY;
• pede à MyStars o preço atual da quantidade de Stars selecionada;
• verifica se o nome de usuário do Telegram pode receber o produto;
• interrompe cedo se o destinatário não for elegível, em vez de criar um pedido inválido;
• cria o pedido de entrega usando seu localOrderId estável como base para idempotência;
• retorna a cotação e o objeto de pedido da MyStars para que o app possa armazenar e mostrar a instrução de pagamento.

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 };
}

A parte importante é a chave de idempotência. Use algo estável do seu próprio sistema. Se a requisição HTTP expirar depois de o pedido ter sido criado no servidor, repita a tentativa com a mesma chave em vez de criar uma duplicata.

Algumas linhas merecem atenção especial:

• MyStarsClient.production(...) significa que a solicitação vai para a API MyStars em produção; portanto, use um pedido local/de teste em seu próprio sistema até estar pronto para tráfego real.
• getPricing(...) fornece uma cotação atual para seu backend. Não fixe preços na interface do bot.
• payment_currency: "ton" é o enum/nome da API para a rota de pagamento nativa neste exemplo de SDK. Na interface do produto, identifique essa rota como Gram ou Gram (ex. TON). Use TON para o nome da blockchain/rede.
• checkRecipient(...) protege o comprador contra pagar por um nome de usuário ou produto que não pode ser entregue.
• callback_url é o endereço em que a MyStars pode enviar atualizações de status do pedido depois da criação.
• idempotencyKey é a proteção contra pedidos duplicados. Ele deve vir do pedido no seu banco de dados, e não de um valor aleatório gerado no navegador.

Crie o mesmo fluxo em Python assíncrono

Equipes de Python geralmente querem código assíncrono porque o framework do bot no Telegram já é assíncrono. O SDK de Python oferece suporte direto a isso.

Este exemplo realiza a mesma tarefa da rota em TypeScript, mas em Python:

• abre um cliente MyStars assíncrono durante a requisição;
• solicita uma cotação de Premium em usdt_ton;
• verifica o destinatário antes de criar o pedido;
• retorna uma mensagem de erro segura se o destinatário não puder receber Premium;
• cria o pedido com uma URL de callback para atualizações de status;
• retorna a cotação e o pedido para que o bot possa armazená-los e mostrar o próximo passo ao usuário.

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}

Ao levar isso para produção, use um tratamento preciso de valores monetários, mantenha a chave de API em uma variável de ambiente e armazene a instrução de pagamento exatamente como ela for retornada. Se a instrução incluir memo/comentário, trate-o como dado, não como texto que você pode reescrever.

Para quem tem menos experiência em desenvolvimento, a ideia principal é esta: o exemplo de código não é um bot completo. Ele é a parte de backend que seu bot chama quando o usuário já escolheu um produto. O bot do Telegram ainda precisa dos próprios handlers, botões, gravações no banco de dados e mensagens ao usuário em torno dessa função.

Adicione a verificação de webhook antes do lançamento

Uma integração no estilo Fragment API não está concluída quando a criação do pedido funciona. Seu app também precisa de uma forma confiável de acompanhar o status.

Handler mínimo de webhook:

1. Receba o corpo bruto da requisição.
2. Leia o cabeçalho X-Faas-Signature.
3. Verifique a assinatura com seu segredo de webhook.
4. Elimine duplicatas pelo ID e status do pedido da MyStars.
5. Atualize seu pedido local somente se a transição for válida.
6. Notifique o usuário pelo seu bot ou Mini App do Telegram.

O SDK TypeScript documenta helpers de webhook como constructEvent, middleware para Express e suporte a Fastify. O SDK Python inclui WebhookVerifier e integrações com frameworks web Python comuns.

Mantenha uma tarefa de polling ou reconciliação como backup. Webhooks são o caminho rápido; a reconciliação é o que salva sua operação quando surge uma exceção de rede às 3 da manhã.

Use o bot blueprint como referência funcional

O bot blueprint em Python da MyStars é a melhor fonte quando você quer ver todas as partes em conjunto. Ele usa mystars-faas==0.1.3 para entrega, um servidor aiohttp para verificações de saúde e webhooks da MyStars, Postgres e Redis para estado, monitoramento do TON Center para pagamentos on-chain e comandos administrativos para margem e reconciliação.

Não trate o blueprint como um modelo de marca. Trate-o como um mapa de engenharia:

• onde criar o pedido local;
• onde chamar verificações de destinatário;
• onde aplicar margem;
• onde monitorar o pagamento;
• onde chamar a entrega;
• onde editar o cartão de pedido do Telegram após um status final.

A conta da MyStars no GitHub também publica os repositórios dos SDKs, para que você possa inspecionar código-fonte, exemplos e a estrutura dos pacotes quando precisar depurar algo além de um README.

Endpoints de backend para criar no seu app

Uma integração pequena, mas pronta para produção, geralmente começa com estas rotas:

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

O bot ou Mini App do Telegram deve chamar sua própria rota /api/orders, e não a MyStars diretamente. Sua rota pode então validar o usuário, criar um pedido local, chamar o SDK, armazenar o pedido de entrega retornado e devolver apenas os campos seguros de que o cliente precisa.

Detalhes de pagamento que os usuários não podem adivinhar

Se o produto mostrar uma tela de pagamento, seja preciso. Nos fluxos da MyStars, USDT significa USDT na TON. Outras redes de USDT não são intercambiáveis. Para a rota nativa, exemplos atuais de API ainda podem usar payment_currency: "ton"; o texto voltado ao comprador deve usar Gram / GRAM (ex. TON) para o token e TON para a rede.

Leia o campo expires_at do pedido em vez de fixar um prazo de pagamento. A documentação observa que a janela de pagamento foi ampliada para 1 hora, e expires_at continua sendo a fonte de verdade.

O que testar antes de receber tráfego real

Execute estas verificações antes de colocar usuários no fluxo:

• um pedido de Stars e um pedido de Premium;
• um caminho para destinatário inelegível;
• repetir a criação do pedido com a mesma chave de idempotência;
• assinaturas de webhook válidas e inválidas;
• entrega duplicada de evento de webhook;
• tratamento de pedido expirado;
• evidências de suporte: nome de usuário, ID local do pedido, ID do pedido MyStars, hash de pagamento, memo/comentário e status;
• acesso somente de administrador para comandos de margem, reconciliação, reembolso, broadcast e entrega manual.

Esta é a parte menos glamourosa, mas é o que faz um bot de Telegram Stars parecer confiável, e não experimental.

FAQ

Esta é uma Fragment API pública direta?

O MyStars FaaS é uma camada Fragment as a Service. Seu app se integra às APIs e SDKs da MyStars, enquanto a MyStars cuida do fluxo de entrega por trás dessa interface.

Posso usá-la em um Telegram Mini App?

Sim. Mantenha a chave de API no backend. O Mini App deve chamar seu servidor, e seu servidor deve chamar o MyStars FaaS.

Com qual pacote devo começar?

Use @mystars-tg/faas-sdk para Node.js e TypeScript. Use mystars-faas para Python e bots assíncronos do Telegram.

Preciso do bot blueprint?

Não, mas ele é útil se você estiver criando um bot no estilo revendedor com pagamentos, comandos administrativos, reconciliação e atualizações de status.

Qual é o primeiro marco mais seguro?

Crie um teste completo: cotação → verificação de destinatário → pedido local → pedido MyStars → webhook verificado ou atualização por polling. Depois que ele funcionar, adicione margem, política de reembolso, ferramentas administrativas e fluxos de suporte.

Para a referência da API, links dos SDKs e observações sobre o contrato atual, comece pela documentação da MyStars.