Installation

composer require faustinopsy/ton-php

Requirements

PHP 8.2 or higher with extensions: sodium, gmp, bcmath, json, curl, pdo, pdo_sqlite

# Check extensions
php -m | grep -E "^(sodium|gmp|bcmath|json|curl|pdo|pdo_sqlite)$"

Quick Start

# Clone the workspace
git clone https://github.com/faustinopsy/ton_php_sdk
cd ton_php_sdk

# Install SDK dependencies
cd sdk/
composer install
vendor/bin/phpunit   # run all tests

# Run the TonBooks example store
cd ../TonBooks/
composer install
cp .env.example .env   # fill in TON variables
php -S localhost:8080 -t public/

SDK Usage

The SDK handles: - Ed25519 key pair generation - Cell/BOC serialization for TON transactions - TonCenter HTTP API calls (testnet and mainnet) - Signing and sending transactions

TonBooks Example App

A full ebook store demonstrating real TON payment integration: - Storefront with TON payments - Automatic payment detection (polling TonCenter every 10s) - SQLite order management - Email delivery after payment confirmation - Admin dashboard - Cron job for pending order processing

See WORKSPACE.md and TonBooks/OPERATOR_GUIDE.md for full configuration details.

TON PHP ? Workspace

Este diretório é o workspace do projeto. Contém dois projetos independentes que se integram para demonstrar o SDK em uma aplicação real.

TON_PHP_SDK/                     ? workspace (esta pasta)
?
??? sdk/                         ? pacote faustinopsy/ton-php (o SDK puro)
?   ??? src/                     ? código-fonte do SDK
?   ??? tests/                   ? testes unitários e de integração do SDK
?   ??? composer.json            ? name: faustinopsy/ton-php
?   ??? phpunit.xml
?   ??? HISTORY.md               ? histórico detalhado de implementação
?
??? TonBooks/                    ? mini-loja de ebooks (app de exemplo)
?   ??? public/                  ? document root (index.php, assets)
?   ??? src/                     ? controllers, services, views
?   ??? composer.json            ? require: faustinopsy/ton-php via path
?   ??? .env.example
?
??? WORKSPACE.md                 ? este arquivo

sdk/ ? faustinopsy/ton-php

SDK PHP puro para a blockchain TON. Não depende de nenhuma aplicação. Pode ser publicado no Packagist e instalado por qualquer projeto PHP:

composer require faustinopsy/ton-php

Para desenvolver o SDK:

cd sdk/
composer install
vendor/bin/phpunit          # rodar todos os testes
vendor/bin/phpunit tests/Unit   # apenas unitários

TonBooks/ ? Mini-loja de ebooks

Aplicação PHP real que usa o SDK como dependência local (Composer path). Serve como prova de conceito de integração e como suite de testes de ponta-a-ponta contra a testnet TON.

O composer.json do TonBooks referencia o SDK localmente:

{
    "repositories": [
        { "type": "path", "url": "../sdk" }
    ],
    "require": {
        "faustinopsy/ton-php": "*"
    }
}

Para rodar a loja:

cd TonBooks/
composer install
cp .env.example .env     # preencher as variáveis TON
php -S localhost:8080 -t public/

Separação de responsabilidades

| Responsabilidade | Projeto | |-----------------|---------| | Criptografia Ed25519 | sdk/ | | Serialização Cell/BOC | sdk/ | | Chamadas HTTP TonCenter | sdk/ | | Assinar e enviar transações | sdk/ | | Testes unitários do SDK | sdk/tests/Unit/ | | Testes de integração testnet | sdk/tests/Integration/ | | Interface de usuário (loja) | TonBooks/ | | Carrinho, pedidos, e-mail | TonBooks/ | | Testes E2E (compra completa) | TonBooks/tests/ |

Por que esta estrutura?

• O SDK não conhece a loja ? pode ser publicado de forma independente.
• A loja consome o SDK como qualquer outro desenvolvedor faria via Composer, apenas usando um `path` local em vez da versão do Packagist.
• Quando o SDK for publicado, trocar `"url": "../sdk"` por `"^1.0"` é a única mudança necessária no `composer.json` da loja.

TonBooks ? Guia de Configuração para Operadores

> Para quem: desenvolvedor ou empreendedor que quer rodar sua própria > instância da TonBooks ? seja para testes ou para vender de verdade. > > Pré-requisito de leitura: você não precisa entender blockchain. > Este guia explica cada passo do zero, inclusive o porquê de cada um.

Índice

1. Entendendo o que você vai configurar
2. Pré-requisitos de software
3. PASSO 1 ? Criar sua carteira TON
4. PASSO 2 ? Ativar modo testnet no Tonkeeper
5. PASSO 3 ? Obter TON de teste (faucet)
6. PASSO 4 ? Obter a API Key do TonCenter
7. PASSO 5 ? Instalar e configurar a loja
8. PASSO 6 ? Configurar o .env
9. PASSO 7 ? Adicionar seus ebooks
10. PASSO 8 ? Rodar em desenvolvimento (testnet)
11. PASSO 9 ? Fazer a primeira compra de teste
12. PASSO 10 ? Ir para produção (mainnet)
13. Configurar e-mail em produção
14. Configurar o cron job
15. Checklist final antes de vender de verdade
16. Perguntas frequentes
17. Referência rápida ? URLs e bots úteis

1. Entendendo o que você vai configurar

Antes de começar, vale entender o que cada peça faz:

Sua carteira TON é como uma conta bancária descentralizada. Ela tem um endereço público (como um número de conta que você pode mostrar para qualquer pessoa) e uma chave privada (como uma senha master que nunca deve ser compartilhada). Quando um cliente compra um ebook, ele envia TON diretamente para o endereço público da sua loja.

TonCenter é um serviço que funciona como uma "janela" para a blockchain TON. Em vez de rodar um nó próprio (o que seria complexo e caro), a loja usa a API do TonCenter para consultar transações recebidas. Você só precisa de uma chave de API gratuita.

Testnet vs Mainnet: - Testnet = ambiente de testes. Os TON usados aqui não têm valor real. Use para testar tudo antes de ativar de verdade. - Mainnet = ambiente de produção. TON de verdade, dinheiro de verdade. Só ative quando tudo estiver funcionando na testnet.

O fluxo de uma venda:

Cliente adiciona ebooks ao carrinho
? Informa o endereço TON dele (identificação)
? Vai para o checkout
? Recebe: endereço da SUA carteira + valor em TON + código do pedido
? Abre o Tonkeeper e envia o TON com o código no campo "comentário"
? A loja detecta o pagamento automaticamente (em até 30 segundos)
? Cliente recebe e-mail com links de download

2. Pré-requisitos de software

Verifique se você tem tudo instalado antes de começar:

# PHP 8.2 ou superior
php -v
# Deve mostrar: PHP 8.2.x ou 8.3.x

# Extensões PHP necessárias
php -m | grep -E "^(sodium|gmp|bcmath|json|curl|pdo|pdo_sqlite)$"
# Deve listar todas. Se faltar alguma:
# Ubuntu/Debian: sudo apt install php8.2-sodium php8.2-gmp php8.2-bcmath
# macOS com Homebrew: já vêm incluídas

# Composer (gerenciador de pacotes PHP)
composer --version
# Deve mostrar: Composer version 2.x

# Node.js (para compilar o frontend)
node -v
# Deve mostrar: v18.x ou superior

# npm (vem junto com Node.js)
npm -v
# Deve mostrar: 9.x ou superior

Se não tiver o PHP instalado: - Ubuntu/Debian: sudo apt install php8.2 php8.2-cli php8.2-sodium php8.2-gmp php8.2-bcmath php8.2-curl php8.2-pdo php8.2-sqlite3 - macOS: brew install php - Windows: usar o XAMPP ou Laragon

3. PASSO 1 ? Criar sua carteira TON

Você precisa de uma carteira TON para receber os pagamentos dos clientes.

3.1 Instalar o Tonkeeper

O Tonkeeper é a carteira TON mais usada e recomendada para este projeto.

• Android: Google Play ? Tonkeeper
• iOS: App Store ? Tonkeeper
• Desktop: tonkeeper.com (extensão Chrome)

3.2 Criar a carteira

1. Abrir o Tonkeeper
2. Tocar em "New Wallet" (criar nova carteira)
3. Anotar as 24 palavras do mnemônico que aparecem na tela

> ?? CRÍTICO: As 24 palavras são a única forma de recuperar sua carteira se > perder o celular. Anote em papel físico e guarde em local seguro. > Nunca fotografe, nunca envie por mensagem, nunca salve em nuvem.

4. Confirmar as palavras quando solicitado
5. Sua carteira está criada

3.3 Anotar seu endereço TON

Na tela principal do Tonkeeper, toque no endereço que aparece abaixo do nome da carteira. Ele vai para a área de transferência.

O endereço tem este formato: EQAbCd1234... (48 caracteres, começa com EQ)

Guarde este endereço ? você vai precisar dele no passo de configuração.

4. PASSO 2 ? Ativar modo testnet no Tonkeeper

> Este passo é necessário apenas para testes. Pule para o Passo 3 quando > for para produção.

O Tonkeeper por padrão opera na mainnet. Para testes, você precisa mudar para a testnet:

1. Abrir o Tonkeeper
2. Ir em "Settings" (Configurações) ? ícone de engrenagem
3. Rolar até o final da tela
4. Tocar no logo do Tonkeeper 5 vezes rapidamente
5. Um menu "Developer" vai aparecer
6. Tocar em "Switch to Testnet"
7. Confirmar a troca

> ?? Na testnet, o endereço da sua carteira muda. Anote o novo endereço > testnet separado do endereço mainnet.

Para voltar para mainnet: repita os mesmos passos e escolha "Switch to Mainnet".

5. PASSO 3 ? Obter TON de teste (faucet)

Na testnet, você precisa de TON de teste (sem valor real) para pagar o "deploy" da carteira e simular compras.

Opção A ? Bot do Telegram (mais simples)

1. Abrir o Telegram
2. Buscar pelo bot: @testgiver_ton_bot
3. Enviar: /start
4. Enviar o seu endereço TON da testnet (o que começa com EQ...)
5. Aguardar alguns segundos
6. Você vai receber 2 TON de teste automaticamente

Opção B ? Faucet web da Chainstack

Acesse: faucet.chainstack.com/ton-testnet-faucet

Cole seu endereço testnet e clique em "Send". Recebe até 1 TON por dia.

Verificar o recebimento

Abra o Tonkeeper na testnet e aguarde 10-30 segundos. O saldo deve aparecer.

Se quiser confirmar no explorer: acesse https://testnet.tonscan.org/address/SEU_ENDERECO

> Por que preciso de TON de teste? > Na TON, todo endereço precisa enviar pelo menos uma transação para "ativar" > o contrato da carteira. Sem isso, o endereço existe mas não pode enviar. > Para receber, não precisa de ativação.

6. PASSO 4 ? Obter a API Key do TonCenter

A loja consulta a blockchain TON através do serviço TonCenter. Você precisa de uma chave de API para isso. O plano gratuito é suficiente para começar.

Para testnet (testes)

1. Abrir o Telegram
2. Buscar: @tontestnetapibot
3. Enviar: /start
4. Enviar: /getcredentials
5. O bot vai te responder com uma chave no formato: abc123def456...
6. Copiar e guardar essa chave

Para mainnet (produção)

1. Abrir o Telegram
2. Buscar: @toncenterbot  (sem "testnet" no nome)
3. Enviar: /start
4. Enviar: /getcredentials
5. Copiar e guardar a chave

> Limites do plano gratuito: > - 1 requisição por segundo > - Suficiente para uma loja pequena/média > - Se precisar de mais: o plano Basic (10 req/s) custa aproximadamente 0.5 TON/mês

7. PASSO 5 ? Instalar e configurar a loja

# 1. Baixar o código
git clone https://github.com/faustinopsy/ton_php_sdk
cd tonbooks

# 2. Instalar dependências PHP
composer install

# 3. Instalar dependências do frontend
cd frontend
npm install
cd ..

# 4. Criar o banco de dados
php bin/migrate.php
# Deve mostrar: "Banco criado com sucesso em database/tonbooks.sqlite"

# 5. Verificar se tudo está ok
php bin/test-domain.php
# Deve mostrar: "? Todos os Models funcionando"

8. PASSO 6 ? Configurar o .env

Este é o passo mais importante. O arquivo .env contém todas as configurações da sua instância da loja.

# Copiar o template
cp .env.example .env

# Abrir para editar
nano .env
# ou: code .env  (VS Code)
# ou: vim .env

Preencha cada variável conforme as instruções abaixo:

# ????????????????????????????????????????????????
# CONFIGURAÇÕES DA APLICAÇÃO
# ????????????????????????????????????????????????

APP_NAME=TonBooks
# Nome da sua loja (aparece no título das páginas e nos e-mails)

APP_URL=http://localhost:8080
# Em desenvolvimento: http://localhost:8080
# Em produção: https://seudominio.com (com https, sem barra no final)

APP_ENV=development
# Em desenvolvimento: development
# Em produção: production

APP_DEBUG=true
# Em desenvolvimento: true (mostra erros detalhados)
# Em produção: false (OBRIGATÓRIO ? não expor erros para o público)

# ????????????????????????????????????????????????
# CONFIGURAÇÕES TON / BLOCKCHAIN
# ????????????????????????????????????????????????

TON_NETWORK=testnet
# Em desenvolvimento: testnet
# Em produção: mainnet

TONCENTER_API_KEY_TESTNET=COLE_AQUI_A_CHAVE_DO_tontestnetapibot
# A chave que você obteve no @tontestnetapibot

TONCENTER_API_KEY_MAINNET=COLE_AQUI_A_CHAVE_DO_toncenterbot
# A chave que você obteve no @toncenterbot
# Pode deixar vazio durante os testes

TON_STORE_ADDRESS=COLE_AQUI_SEU_ENDERECO_TON_DA_TESTNET
# O endereço da sua carteira Tonkeeper na TESTNET
# Formato: EQAbCd1234... (48 caracteres)
# ?? Use o endereço da TESTNET aqui durante os testes
# ?? Troque para o endereço da MAINNET quando for para produção

TON_STORE_MNEMONIC=palavra1 palavra2 palavra3 ... palavra24
# As 24 palavras da sua carteira Tonkeeper
# ?? Use as palavras da carteira TESTNET durante os testes
# ?? Troque para as palavras da MAINNET em produção
# ?? NUNCA commite este arquivo no git com as palavras preenchidas

# ????????????????????????????????????????????????
# CONFIGURAÇÕES DO PAINEL ADMIN
# ????????????????????????????????????????????????

ADMIN_PASSWORD_HASH=GERAR_CONFORME_INSTRUÇÃO_ABAIXO
# Para gerar o hash da sua senha de admin:
# Execute no terminal: php -r "echo password_hash('SUA_SENHA_AQUI', PASSWORD_BCRYPT);"
# Cole o resultado aqui (começa com $2y$...)
# Exemplo de geração:
#   php -r "echo password_hash('minhasenha123', PASSWORD_BCRYPT);"
#   Resultado: $2y$12$AbCdEf...

# ????????????????????????????????????????????????
# CONFIGURAÇÕES DE E-MAIL
# ????????????????????????????????????????????????

# Para TESTES, use o Mailtrap (intercepta e-mails sem enviar de verdade):
# 1. Criar conta gratuita em https://mailtrap.io
# 2. Ir em Email Testing ? My Inbox ? SMTP Settings
# 3. Copiar as credenciais

MAIL_HOST=smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=SEU_USUARIO_MAILTRAP
MAIL_PASSWORD=SUA_SENHA_MAILTRAP
MAIL_FROM=noreply@tonbooks.dev
MAIL_FROM_NAME=TonBooks
# ?? Em produção, trocar para as credenciais do seu servidor de e-mail real
# (ver Seção 13 ? Configurar e-mail em produção)

# ????????????????????????????????????????????????
# CONFIGURAÇÕES DE SESSÃO
# ????????????????????????????????????????????????

SESSION_NAME=tonbooks_session
SESSION_LIFETIME=86400
# 86400 segundos = 24 horas
# Tempo que a sessão do usuário dura sem atividade

# ????????????????????????????????????????????????
# BANCO DE DADOS
# ????????????????????????????????????????????????

DB_PATH=database/tonbooks.sqlite
# SQLite: caminho relativo à raiz do projeto
# Não mude isso a menos que queira usar MySQL (ver abaixo)

# Para MySQL em produção (opcional ? SQLite funciona bem para a maioria):
# DB_DRIVER=mysql
# DB_HOST=127.0.0.1
# DB_NAME=tonbooks
# DB_USER=seu_usuario_mysql
# DB_PASS=sua_senha_mysql

Verificar a configuração

php bin/test-sdk.php

Saída esperada:

=== Teste de integração com SDK TON ===
Rede: testnet
Endereço da loja: EQAbCd...
Saldo atual: 2.00 TON
Estado da conta: active
Últimas transações: 0 encontradas
? SDK funcionando corretamente

Se aparecer erro de API key inválida, verifique se copiou a chave corretamente no .env.

9. PASSO 7 ? Adicionar seus ebooks

9.1 Colocar os PDFs na pasta correta

Os arquivos PDF devem ficar em storage/ebooks/. Esta pasta fica fora do public/ para que ninguém consiga acessar os PDFs diretamente pela URL.

# Criar a pasta se não existir
mkdir -p storage/ebooks

# Copiar seus PDFs
cp /caminho/para/meu-ebook.pdf storage/ebooks/meu-ebook.pdf
cp /caminho/para/outro-ebook.pdf storage/ebooks/outro-ebook.pdf

9.2 Editar o catálogo

O arquivo storage/catalog.json define os ebooks à venda. Edite-o com seus produtos:

[
    {
        "id": "meu-ebook-unico",
        "title": "Título do Meu Ebook",
        "subtitle": "Subtítulo ou tagline",
        "description": "Descrição que aparece na vitrine. Pode ter até 2-3 frases.",
        "price_usd": 9.90,
        "pages": 120,
        "file": "meu-ebook.pdf",
        "cover_color": "#1D9E75",
        "topics": ["Tag1", "Tag2", "Tag3"]
    },
    {
        "id": "segundo-ebook",
        "title": "Segundo Ebook",
        "subtitle": "Subtítulo",
        "description": "Descrição do segundo ebook.",
        "price_usd": 14.90,
        "pages": 200,
        "file": "segundo-ebook.pdf",
        "cover_color": "#378ADD",
        "topics": ["Tag1", "Tag2"]
    }
]

Campos obrigatórios:

| Campo | O que é | Exemplo | |-------|---------|---------| | id | Identificador único, sem espaços | "php-avancado" | | title | Título que aparece na vitrine | "PHP Avançado" | | description | Texto de apresentação | "Aprenda..." | | price_usd | Preço em dólares (convertido para TON automaticamente) | 9.90 | | file | Nome exato do PDF em storage/ebooks/ | "php-avancado.pdf" | | cover_color | Cor do card na vitrine (hex) | "#1D9E75" |

> Por que o preço em USD? A cotação do TON muda todo dia. Se você colocar o > preço diretamente em TON, o valor em reais vai variar. Usando USD como base, > a loja converte automaticamente para TON na hora da compra com a cotação atual.

10. PASSO 8 ? Rodar em desenvolvimento (testnet)

# Terminal 1 ? Servidor PHP
php -S localhost:8080 -t public
# Deixar rodando

# Terminal 2 ? Frontend Vite (em outra aba/janela)
cd frontend
npm run dev
# Vai mostrar: "Local: http://localhost:5173"

Abrir no browser: http://localhost:5173

Você deve ver a vitrine da TonBooks com seus ebooks.

> Por que dois terminais? > O PHP serve a lógica e os dados. O Vite serve o JavaScript/CSS com > atualização automática (hot reload) quando você edita os arquivos. > Em produção, o Vite não é necessário ? você vai compilar uma vez e pronto.

11. PASSO 9 ? Fazer a primeira compra de teste

Siga este roteiro para verificar que tudo está funcionando:

11.1 Identificar-se na loja

1. Na vitrine, localize o campo "Sua carteira TON" no topo da página
2. Cole o endereço TON da sua carteira testnet (começa com `EQ...`)
3. Um ícone verde de confirmação deve aparecer
4. Clique em "Entrar"

11.2 Adicionar ao carrinho e fazer checkout

1. Clique em "Adicionar ao carrinho" em qualquer ebook
2. Clique no ícone do carrinho no topo
3. Na página do carrinho, clique em "Finalizar compra"
4. Informe um e-mail real (você vai receber o link de download aqui)
5. Clique em "Ir para pagamento"

11.3 Efetuar o pagamento no Tonkeeper

Na página de pagamento você vai ver:

Endereço da loja: EQAbCd... [botão copiar]
Valor:            1.35 TON
Comentário:       ORD-00001  ? OBRIGATÓRIO copiar exatamente
Timer:            14:59

Abra o Tonkeeper (certifique-se de estar na testnet):

1. Tocar em "Send" (Enviar)
2. Colar o endereço da loja no campo de destinatário
3. Digitar o valor exato (ex: `1.35`)
4. Obrigatório: no campo "Comment" ou "Memo", digitar exatamente `ORD-00001`
5. Confirmar o envio

> ?? O comentário é o que identifica o seu pedido. Se não colocar ou colocar > errado, o pagamento não vai ser detectado automaticamente.

11.4 Aguardar a confirmação

De volta ao browser, a página de pagamento faz uma verificação a cada 10 segundos. Em até 30 segundos após o envio no Tonkeeper, a página deve mudar para "Pagamento confirmado!".

11.5 Verificar a entrega

1. Verifique o e-mail que você informou no checkout
2. Um e-mail com o assunto "Seus ebooks ? TonBooks" deve ter chegado
3. Clique no link de download ? o PDF deve abrir/baixar

11.6 Verificar a biblioteca

1. Acesse `http://localhost:5173/biblioteca`
2. Informe o mesmo endereço TON que usou para comprar
3. O ebook comprado deve aparecer com opção de download

11.7 Verificar o painel admin

1. Acesse `http://localhost:5173/admin`
2. Faça login com a senha que você configurou no `.env`
3. O dashboard deve mostrar: - Saldo da carteira da loja (o TON que você enviou) - O pedido como "Entregue" - O e-mail e o hash da transação

Se tudo funcionou, sua loja está pronta para ir para produção.

12. PASSO 10 ? Ir para produção (mainnet)

> Atenção: Só faça isso depois de testar tudo na testnet. > Na mainnet, TON tem valor real.

12.1 Criar uma carteira mainnet separada

> Recomendado fortemente: use uma carteira diferente para a loja mainnet. > Não misture a carteira de testes com a de produção.

1. No Tonkeeper, vá em Settings ? logo 5x ? Switch to Mainnet
2. Criar uma nova carteira (ou usar a existente da mainnet)
3. Anotar as 24 palavras da carteira mainnet
4. Anotar o endereço mainnet (começa com `EQ...` mas é diferente do testnet)

12.2 Fazer deploy no servidor

# No servidor de produção (via SSH):

# 1. Clonar o repositório
git clone https://github.com/faustinopsy/ton_php_sdk /var/www/ton_php_sdk
cd /var/www/ton_php_sdk

# 2. Instalar dependências PHP (sem dev)
composer install --no-dev --optimize-autoloader

# 3. Compilar o frontend (gera os arquivos em public/assets/)
cd frontend
npm install
npm run build
cd ..
# Após este passo, você NÃO precisa mais do Node.js rodando
# O Vite só é necessário para compilar ? não para servir em produção

# 4. Criar o banco
php bin/migrate.php

# 5. Copiar os PDFs
mkdir -p storage/ebooks
# Copiar seus PDFs para cá (via scp, SFTP, etc.)

# 6. Configurar permissões
chmod 755 public/
chmod 644 public/index.php
chmod 700 storage/
chmod 700 database/
chmod 600 .env
# A pasta storage/ e database/ não devem ser acessíveis pelo webserver diretamente

12.3 Atualizar o .env para produção

APP_URL=https://seudominio.com
APP_ENV=production
APP_DEBUG=false

TON_NETWORK=mainnet
TON_STORE_ADDRESS=EQ_SEU_ENDERECO_MAINNET_AQUI
TON_STORE_MNEMONIC=palavra1 palavra2 ... palavra24 (da carteira mainnet)

TONCENTER_API_KEY_MAINNET=sua_chave_mainnet_aqui

12.4 Configurar o servidor web

Apache ? o .htaccess já está configurado. Certifique-se que mod_rewrite está ativo e que AllowOverride All está no VirtualHost:

<VirtualHost *:443>
    ServerName seudominio.com
    DocumentRoot /var/www/tonbooks/public

    <Directory /var/www/tonbooks/public>
        AllowOverride All
        Require all granted
    </Directory>

    # SSL (obrigatório em produção)
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/seudominio.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/seudominio.com/privkey.pem
</VirtualHost>

Nginx:

server {
    listen 443 ssl;
    server_name seudominio.com;
    root /var/www/tonbooks/public;
    index index.php;

    ssl_certificate /etc/letsencrypt/live/seudominio.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/seudominio.com/privkey.pem;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # Bloquear acesso direto aos PDFs e ao banco
    location ~ ^/(storage|database)/ {
        deny all;
        return 404;
    }
}

> SSL é obrigatório. Sem HTTPS, o Tonkeeper não consegue abrir o > deeplink de pagamento corretamente, e sessões PHP ficam vulneráveis. > Use o Let's Encrypt (gratuito): certbot --nginx -d seudominio.com

12.5 Verificar o deploy

# No servidor, verificar se o SDK consegue ler a mainnet
php bin/test-sdk.php

# Saída esperada:
# Rede: mainnet
# Endereço da loja: EQ...
# Saldo atual: 0.00 TON  (carteira nova, ainda sem saldo)
# ? SDK funcionando corretamente

13. Configurar e-mail em produção

Durante os testes, o Mailtrap intercepta os e-mails. Em produção, você precisa de um serviço de e-mail real.

Opção A ? Gmail (simples, mas com limites)

1. Criar uma conta Gmail dedicada para a loja (ex: loja@seudominio.com)
2. Ativar autenticação de dois fatores na conta
3. Criar uma "Senha de App":
   Google Account ? Security ? 2-Step Verification ? App passwords
   Selecionar "Mail" e "Other (Custom name)"
   Copiar a senha gerada (16 caracteres)

MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=sualoja@gmail.com
MAIL_PASSWORD=abcd efgh ijkl mnop   (senha de app, sem espaços)
MAIL_FROM=sualoja@gmail.com
MAIL_FROM_NAME=Nome da Sua Loja

> Limite: Gmail permite ~500 e-mails/dia com conta pessoal.

Opção B ? Brevo/Sendinblue (recomendado para produção)

Plano gratuito: 300 e-mails/dia. Ideal para começar.

1. Criar conta em https://brevo.com
2. Ir em Transactional ? Settings ? SMTP & API
3. Copiar as credenciais SMTP

MAIL_HOST=smtp-relay.brevo.com
MAIL_PORT=587
MAIL_USERNAME=seu@email.com
MAIL_PASSWORD=sua_chave_smtp_brevo
MAIL_FROM=noreply@seudominio.com
MAIL_FROM_NAME=TonBooks

Opção C ? Amazon SES (para volume alto)

Muito barato ($0.10 por 1.000 e-mails) mas requer verificação de domínio. Recomendado apenas se você espera mais de 1.000 vendas/mês.

14. Configurar o cron job

O cron job verifica automaticamente pedidos pendentes a cada minuto. Sem ele, a loja ainda funciona (o polling do frontend detecta o pagamento), mas pedidos que expiram sem o usuário na página não serão marcados como expirados.

Em servidor Linux (cPanel, VPS, etc.)

# Abrir o editor de cron
crontab -e

# Adicionar esta linha:
  * /usr/bin/php /var/www/tonbooks/app/Cron/ProcessPendingOrders.php >> /var/log/tonbooks-cron.log 2>&1

> Substitua /var/www/tonbooks pelo caminho real da sua instalação. > Substitua /usr/bin/php pelo caminho do seu PHP: which php

Em cPanel (hospedagem compartilhada)

1. Entrar no cPanel
2. Ir em "Cron Jobs"
3. Configurar frequência: Every Minute (` *`)
4. Comando: `/usr/local/bin/php /home/usuario/public_html/tonbooks/app/Cron/ProcessPendingOrders.php`

Verificar se o cron está funcionando

# Executar manualmente uma vez para testar
php app/Cron/ProcessPendingOrders.php

# Saída esperada (com pedidos pendentes):
# [14:32:01] Verificando 3 pedidos pendentes...
# [14:32:02] Pedido ORD-00001: sem pagamento detectado
# [14:32:03] Pedido ORD-00002: PAGO! TX: abc123...
# [14:32:03] Concluído.

# Saída esperada (sem pedidos):
# [14:32:01] Nenhum pedido pendente. Concluído.

15. Checklist final antes de vender de verdade

Antes de divulgar a loja e começar a receber pagamentos reais, confirme cada item desta lista:

Configuração básica

? APP_ENV=production no .env
? APP_DEBUG=false no .env
? APP_URL com https:// (não http://)
? TON_NETWORK=mainnet no .env
? TON_STORE_ADDRESS com endereço da MAINNET (não testnet)
? TON_STORE_MNEMONIC com palavras da carteira MAINNET
? TONCENTER_API_KEY_MAINNET preenchida
? ADMIN_PASSWORD_HASH com hash bcrypt (não a senha em texto)
? .env tem permissão 600 (chmod 600 .env)
? .gitignore inclui .env (nunca commitar o .env com dados reais)

SSL e servidor

? Certificado SSL ativo (https:// funciona sem aviso do browser)
? Redirecionamento http ? https configurado
? Pasta storage/ não acessível via URL (testar: curl https://seudominio.com/storage/)
? Pasta database/ não acessível via URL

E-mail

? Enviar e-mail de teste: php bin/test-email.php
? E-mail chega na caixa de entrada (não no spam)
? Links de download no e-mail apontam para https://

SDK e pagamentos

? php bin/test-sdk.php na MAINNET sem erros
? Saldo da carteira mainnet tem pelo menos 0.1 TON
  (para cobrir custos de transação futuros se precisar enviar algo)
? Fazer uma compra real de teste com valor pequeno (ex: ebook de $1)
? Pagamento detectado em menos de 60 segundos
? E-mail recebido com links funcionando
? PDF abre corretamente

Painel admin

? Login admin funciona em https://seudominio.com/admin
? Saldo da carteira aparece corretamente no dashboard
? Reenvio de e-mail funciona em um pedido de teste

Cron job

? Cron configurado e rodando
? Testar: criar pedido ? não pagar ? aguardar 15 min ? status deve ser EXPIRED

16. Perguntas frequentes

P: O cliente pode pagar em qualquer moeda? R: Não. Apenas TON nativo. Se quiser aceitar USDT (stablecoin), a lógica de detecção de pagamento precisa ser adaptada ? não está no escopo desta versão.

P: E se o cliente esquecer de colocar o comentário? R: O pagamento vai para a carteira da loja, mas não vai ser atribuído a nenhum pedido automaticamente. Você vai ver a transação no painel admin com "sem pedido correspondente" e pode fazer a entrega manual pelo painel.

P: E se o cliente pagar o valor errado? R: A loja aceita até 1% a menos (para variação de cotação). Se pagar muito menos, o pedido vai expirar. Se pagar a mais, o excesso fica na carteira da loja (não há devolução automática na v1).

P: Posso usar em hospedagem compartilhada? R: Sim, se a hospedagem tiver PHP 8.2+ e a extensão sodium habilitada. A maioria das hospedagens modernas tem. Verificar com: php -m | grep sodium.

P: Como faço backup? R: Faça backup do arquivo database/tonbooks.sqlite regularmente (ou configure MySQL e use o backup nativo do banco). As 24 palavras do mnemônico estão no .env ? guarde uma cópia segura offline.

P: Posso mudar os preços depois de publicar? R: Sim, basta editar o storage/catalog.json. O novo preço vale para os próximos pedidos. Pedidos já criados têm o preço travado no momento da compra.

P: O que acontece se o TonCenter ficar fora do ar? R: A loja continua funcionando para mostrar os ebooks e criar pedidos. Mas a detecção de pagamentos fica pausada até o serviço voltar. Os pedidos não expiram mais rápido por isso ? o timer de 15 minutos é baseado em quando o pedido foi criado, não em quando foi verificado.

P: Posso ter mais de uma instância da loja? R: Sim. Cada instância precisa de um endereço TON diferente para receber pagamentos, porque o sistema identifica pedidos pelo comentário + endereço. Duas lojas com o mesmo endereço causariam conflitos.

17. Referência rápida ? URLs e bots úteis

| Recurso | Testnet | Mainnet | |---------|---------|---------| | Explorer de transações | testnet.tonscan.org | tonscan.org | | API TonCenter | testnet.toncenter.com | toncenter.com | | Bot de API Key | @tontestnetapibot | @toncenterbot | | Faucet (TON grátis) | @testgiver_ton_bot | ? | | Verificar endereço | testnet.tonscan.org/address/EQ... | tonscan.org/address/EQ... | | Verificar transação | testnet.tonscan.org/tx/HASH | tonscan.org/tx/HASH |

Comandos úteis para diagnóstico

# Verificar SDK e conexão com a blockchain
php bin/test-sdk.php

# Verificar envio de e-mail
php bin/test-email.php

# Rodar o cron manualmente (para testar)
php app/Cron/ProcessPendingOrders.php

# Ver os últimos logs de erro PHP
tail -f /var/log/apache2/error.log   # Apache
tail -f /var/log/nginx/error.log     # Nginx

# Consultar pedidos pendentes diretamente no banco
sqlite3 database/tonbooks.sqlite \
  "SELECT id, comment_key, total_ton, status, datetime(created_at,'unixepoch') FROM orders WHERE status='PENDING';"

# Consultar saldo da loja via curl (sem precisar do PHP)
curl "https://testnet.toncenter.com/api/v2/getAddressBalance?address=SEU_ENDERECO" \
  -H "X-API-Key: SUA_API_KEY"
# Resultado em nanoTON (dividir por 1000000000 para obter TON)

*Documento de operação da TonBooks v2. Para dúvidas técnicas sobre o código, consulte o README principal do projeto. Para problemas com a blockchain TON, consulte docs.ton.org.*