API de Telegram Stars para B2B: venda Stars e Premium

Se o seu produto já tem clientes, checkout ou uma audiência no Telegram, você não precisa criar uma operação de fulfillment separada para vender produtos digitais do Telegram. A API de Fulfilment da MyStars permite que o seu back-end crie e acompanhe pedidos de Telegram Stars e Telegram Premium entregues a um @username do Telegram.

Isso a torna uma opção prática para revendedores, bots do Telegram e Mini Apps, plataformas de criadores, serviços de presentes, programas de fidelidade, agências, marketplaces e produtos que querem adicionar uma compra do Telegram sem levar cada cliente a um fluxo de suporte manual.

Quem deve usar uma API de Telegram Stars?

Use uma API de Telegram Stars quando Stars ou Premium fizerem parte do produto que você vende — e não para uma compra manual pontual destinada à própria equipe.

Implementações B2B típicas incluem:

• Vitrines de revendedores que vendem pacotes de Stars ou durações de Premium junto com outros produtos digitais;
• Bots do Telegram e Mini Apps que coletam um nome de usuário, exibem uma cotação atual e enviam o pedido a um back-end;
• Plataformas de criadores e comunidades que ajudam a audiência a recarregar antes de uma publicação paga, ação de bot ou experiência Premium;
• Produtos de presentes e fidelidade que transformam uma recompensa de campanha em Telegram Stars ou Premium para um destinatário identificado;
• Agências e serviços gerenciados que precisam de um fluxo de fulfillment repetível em vez de processar manualmente cada solicitação de cliente;
• Marketplaces que precisam de um registro de pedido auditável e de um evento quando a entrega é concluída.

A API é uma camada de fulfillment, não um widget de front-end. Seu produto controla a experiência do cliente, o checkout e as regras comerciais. Seu servidor usa a MyStars para cotar, validar, criar, pagar e reconciliar o pedido de fulfillment no Telegram.

O que você pode vender pela API da MyStars?

O catálogo atual oferece dois tipos de produto:

• Telegram Stars — um pedido usa uma quantidade de Stars;
• Telegram Premium — um pedido usa uma duração de Premium em meses.

Stars e Premium resolvem necessidades diferentes do comprador, por isso apresente-os separadamente na sua interface. Stars são um saldo do Telegram utilizável para criadores, canais, bots e produtos digitais. Premium é uma assinatura presenteável para uma conta do Telegram. Se seu cliente estiver comparando planos de Premium em vez de integrar uma API, direcione-o ao checkout do Telegram Premium.

Não codifique tamanhos de pacote, durações de plano, moedas ou preços diretamente em um aplicativo cliente. A documentação da API MyStars expõe dados atualizados de produtos, moedas e preços para que o seu catálogo siga as regras vigentes da API.

Como vender Telegram Stars via API: o fluxo de fulfillment B2B

Uma integração confiável segue uma sequência curta, mas deliberada. O pedido é criado no seu back-end; o cliente nunca deve ver uma chave de API nem lidar com instruções de pagamento on-chain que pertencem ao seu serviço.

1. Carregue o catálogo atual e as moedas de pagamento. Consulte os produtos e as moedas disponíveis quando sua integração for iniciada e atualize-os em uma cadência sensata. Isso evita que uma versão antiga do app ofereça uma opção indisponível.
2. Solicite uma cotação em tempo real. Peça ao endpoint de preços a cotação do produto escolhido, da quantidade ou duração e da moeda de pagamento. Use o valor retornado como o valor a liquidar; não monte um preço a partir de suposições sobre taxas em cache.
3. Verifique o destinatário antes de cobrar ou criar o pedido. Envie o @username do Telegram do destinatário e o produto escolhido ao endpoint de verificação de destinatário. Uma verificação de destinatário para Stars e uma verificação de elegibilidade para Premium não são intercambiáveis.
4. Crie um único pedido idempotente. Envie o produto selecionado, o destinatário, a moeda de pagamento, uma URL de callback quando usar webhooks e um Idempotency-Key estável, gerado a partir do seu próprio ID interno de pedido.
5. Liquide exatamente a instrução de pagamento retornada. A resposta do pedido contém o endereço de destino, valor, memo, rede e expiração. Seu serviço de pagamentos deve usar esses valores exatamente como retornados, em vez de um endereço de carteira ou memo armazenado na configuração do aplicativo.
6. Reconcilie o status final de entrega. Consulte o endpoint de status do pedido como alternativa, ou receba o status final pelo webhook. Marque o pedido do seu cliente como concluído somente depois que suas regras de reconciliação forem atendidas.

Essa sequência é o que diferencia uma integração B2B da API de Telegram Stars de um simples link de compra: cada etapa pode ser armazenada, repetida com segurança, observada e atendida pela sua equipe de produto.

Os dados que seu back-end deve guardar

Seu banco de dados é a fonte de verdade para o pedido voltado ao cliente. Guarde informações suficientes para explicar um pedido ao suporte, repetir uma operação segura e reconciliar um pagamento em blockchain sem expor segredos.

No mínimo, mantenha:

• seu ID interno de pedido e o ID do pedido MyStars;
• a chave de idempotência usada para criar esse pedido;
• tipo de produto, quantidade de Stars ou duração de Premium e nome de usuário do destinatário;
• moeda cotada, valor, rede, expiração e memo de pagamento;
• o hash da transação on-chain após a liquidação;
• seu estado de pagamento, o estado do pedido MyStars, payload do webhook ou registro de data e hora do polling, e o resultado final do fulfillment.

Um Idempotency-Key é importante porque sistemas reais tentam novamente. Um timeout de rede após POST /v1/orders não prova que nada aconteceu. Repetir com a mesma chave estável permite que seu back-end se recupere sem criar um segundo pedido de fulfillment para a mesma compra do cliente.

Webhooks, polling e o ciclo de vida do pedido

Seu cliente pode primeiro pagar pelo seu produto, enquanto o seu serviço liquida a instrução da MyStars depois. Isso cria três estados operacionais que não devem ser confundidos:

1. o cliente pagou seu produto;
2. seu serviço enviou o pagamento on-chain para o pedido da MyStars;
3. a MyStars entregou Stars ou Premium ao destinatário no Telegram.

Quando um pedido é criado, ele pode retornar como awaiting_payment, com um bloco de pagamento e expiração. À medida que a liquidação e o fulfillment avançam, seu sistema precisa de uma forma confiável de receber o resultado final.

Use um callback de webhook para atualizações normais de entrega e mantenha o polling de status como caminho de recuperação. Verifique se as requisições de webhook recebidas são processadas pelo seu back-end, correlacione-as ao ID do pedido MyStars e torne também o processamento de webhook idempotente. Um callback duplicado não pode conceder uma recompensa duplicada, emitir um segundo recibo nem disparar um segundo fluxo de reembolso.

Liquidação de pagamento: GRAM (TON) e USDT na TON

Os pedidos da API MyStars podem ser liquidados em GRAM (TON) ou USDT (TON). São operações de pagamento de back-end, não campos para copiar cegamente em um checkout do lado do cliente.

Para cada pedido, leia a moeda, a rede, o endereço, o valor, o memo e a expiração retornados na resposta da API. Não reutilize os dados de pagamento de um pedido anterior. Um pagamento com valor, comentário, rede ou instrução expirada incorretos pode falhar na reconciliação.

Mantenha a assinatura de carteira e as chamadas à API no lado do servidor. Nunca inclua X-Api-Key, uma seed de carteira ou credenciais de liquidação automatizada em um bundle de navegador, Telegram Mini App, repositório público ou log de cliente.

Sem KYC do comprador: o significado B2B preciso

“Sem KYC do comprador” é um termo de busca, mas exige linguagem precisa. Neste fluxo, o checkout de fulfillment da MyStars não exige que o comprador envie documentos de identidade. Isso pode reduzir a fricção na experiência do produto.

Checklist de lançamento para uma integração de API de revenda de Telegram Stars

Antes de tornar o recurso visível aos clientes, confirme o seguinte:

• a chave de API fica apenas no gerenciamento de segredos do lado do servidor e pode ser rotacionada;
• as opções de produto e moeda vêm da API ativa, e não de valores codificados;
• uma verificação de destinatário é executada antes da criação do pedido e antes da cobrança final do cliente;
• cada pedido tem um ID interno estável e uma chave de idempotência;
• o pagamento usa o endereço, valor, memo, rede e expiração exatos retornados para aquele pedido;
• USDT é identificado como somente TON em todos os lugares onde aparece;
• o processamento de webhook verifica, correlaciona, registra e elimina eventos duplicados com segurança;
• o polling cobre um webhook perdido ou atrasado;
• sua equipe de suporte consegue localizar um pedido pelo seu ID, pelo ID MyStars, pelo destinatário e pelo hash da transação;
• regras de reembolso, fraude, conformidade e comunicação com o cliente são definidas antes do lançamento.

Para formatos de requisição, campos de resposta, opções de SDK e o contrato ativo da API, use a documentação da API MyStars como fonte de verdade da implementação.

FAQ

Posso vender Telegram Stars pelo meu próprio site, bot ou Mini App?

Sim. Seu produto pode coletar a escolha do cliente e o nome de usuário do destinatário, enquanto seu back-end usa a API de Fulfilment da MyStars para criar e acompanhar o pedido de Stars. Mantenha a chave de API e as operações de liquidação no lado do servidor.

Posso vender Telegram Premium pela mesma API?

Sim. A API oferece fulfillment de Telegram Premium como um tipo de produto separado, com duração de Premium em meses. Verifique a elegibilidade do destinatário antes de criar um pedido, pois as restrições para presentes Premium podem diferir das verificações de destinatário de Stars.

A API fornece uma lista de preços fixa para Stars e Premium?

Use o endpoint de preços para uma cotação em tempo real, em vez de depender de uma lista fixa. A resposta da API é a fonte adequada para o valor atual e a moeda de liquidação do pedido selecionado.

Como evitar pedidos duplicados de Telegram Stars?

Crie cada pedido com um Idempotency-Key estável vinculado ao seu próprio ID interno de pedido. Se um worker do servidor tentar novamente por causa de um timeout, reutilize a mesma chave em vez de gerar uma nova.

Qual rede de USDT é compatível?

USDT na TON / The Open Network somente. Não envie nem apresente USDT em outra rede como método de liquidação compatível.

Sem KYC do comprador significa que minha empresa não tem obrigações de conformidade?

Não. Isso descreve a experiência do comprador no checkout da MyStars, e não as responsabilidades da sua empresa em relação a obrigações legais, financeiras, de fraude, impostos, sanções, proteção ao consumidor ou reembolsos.

Inicie sua integração B2B de fulfillment no Telegram

Se o seu produto precisa vender Telegram Stars ou Premium em escala, estruture-o em torno de um ciclo de vida de pedido verificável: cotação em tempo real, verificação de destinatário, criação idempotente de pedido, liquidação on-chain exata e reconciliação final por webhook ou status.

Abra a documentação da API MyStars e inicie a integração →

Fontes e evidências

• Documentação da API FaaS — Fulfilment da MyStars: catálogo de produtos, preços em tempo real, verificações de destinatário, criação de pedidos, autenticação de API, instruções de liquidação, acompanhamento de status e webhooks.