finance_bot/API_QUICK_START.md

Quick Start - Bot API Integration

🚀 Deploy in 5 Minutes

1. Apply Database Migration

docker compose down
docker compose up -d
docker exec finance_bot_migrations alembic upgrade head

2. Rebuild Containers

docker compose down
docker compose up -d --build

3. Test API Endpoint

# Register new user
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"test123","first_name":"Test"}'

# Expected: Returns access_token and user_id

4. Test Bot /register Command

# Send /register to your Telegram bot
# Expected: "Registration successful!" message

5. Verify Token in Redis

docker exec finance_bot_redis redis-cli get "chat_id:YOURCHATID:jwt"
# Expected: JWT token string

---

📋 What Was Added

New API Endpoints

Endpoint	Purpose
POST /api/v1/auth/register	Email registration
POST /api/v1/auth/token/get	Get token by chat_id
POST /api/v1/auth/token/refresh-telegram	Refresh Telegram token
POST /api/v1/auth/telegram/register	Quick Telegram registration

New Bot Commands

Command	Purpose
/start	Show registration options
/register	One-tap Telegram registration
/link	Link existing email account
/help	Updated help with new options

---

🧪 Quick Tests

Test 1: Email Registration

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123",
    "first_name": "John"
  }'

Test 2: Telegram User Token

curl -X POST http://localhost:8000/api/v1/auth/token/get \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 556399210}'

Test 3: Quick Telegram Register

curl -X POST "http://localhost:8000/api/v1/auth/telegram/register" \
  -H "Content-Type: application/json" \
  -d "" \
  -G \
  --data-urlencode "chat_id=556399210" \
  --data-urlencode "username=john_doe" \
  --data-urlencode "first_name=John"

Test 4: Health Check

curl http://localhost:8000/health
# Expected: {"status": "ok", "environment": "production"}

---

🔄 Authentication Flows

Quick Telegram Registration (1 step)

User /register
    ↓
Bot → POST /api/v1/auth/telegram/register
    ↓
Bot ← JWT Token
    ↓
User ready to use!

Email Account Link (3 steps)

User /link
    ↓
Bot → POST /api/v1/auth/telegram/start (get code)
    ↓
User clicks link, logs in with email
    ↓
Frontend → POST /api/v1/auth/telegram/confirm
    ↓
Bot → POST /api/v1/auth/token/get
    ↓
User ready to use!

---

📚 Full Documentation

1. API Endpoints: docs/API_ENDPOINTS.md
2. Integration Guide: docs/API_INTEGRATION_GUIDE.md
3. Complete Summary: BOT_API_INTEGRATION_SUMMARY.md
4. Deployment Checklist: DEPLOYMENT_CHECKLIST_API.md
5. Python Examples: examples/bot_api_usage.py

---

🛠️ Common Commands

Check Logs

# Web service
docker logs -f finance_bot_web

# Bot service
docker logs -f finance_bot_bot

# Database
docker logs -f finance_bot_postgres

Database Access

# List users
docker exec finance_bot_postgres psql -U finance_user -d finance_db \
  -c "SELECT id, email, telegram_id, created_at FROM users"

# Check table structure
docker exec finance_bot_postgres psql -U finance_user -d finance_db \
  -c "\d users"

Redis Access

# Check stored tokens
docker exec finance_bot_redis redis-cli keys "chat_id:*:jwt"

# Get specific token
docker exec finance_bot_redis redis-cli get "chat_id:556399210:jwt"

# Flush all (careful!)
docker exec finance_bot_redis redis-cli FLUSHALL

---

✅ Verification Checklist

• Database migration applied successfully
• Email registration endpoint works
• Telegram token endpoint works
• Bot /register command works
• Tokens stored in Redis
• No errors in logs
• Health check returns 200
• Documentation accessible

---

🚨 Troubleshooting

Migration Failed

# Check migration status
docker exec finance_bot_migrations alembic current

# Rollback
docker exec finance_bot_migrations alembic downgrade -1

# Reapply
docker exec finance_bot_migrations alembic upgrade head

Bot Can't Connect to Web

# Check network
docker network ls
docker network inspect finance_network

# Check web is running
docker exec finance_bot_web curl localhost:8000/health

Tokens Not Storing in Redis

# Check Redis is running
docker exec finance_bot_redis redis-cli ping

# Check connection string
docker compose config | grep REDIS_URL

API Returns 500 Error

# Check web logs
docker logs finance_bot_web | grep ERROR

# Restart web service
docker restart finance_bot_web

---

📞 Support

API Issues?

1. Check docs/API_ENDPOINTS.md
2. Review logs: docker logs finance_bot_web
3. Test with cURL first

Bot Issues?

1. Check bot is running: docker logs finance_bot_bot
2. Verify token storage: redis-cli keys "chat_id:*:jwt"
3. Check API connection: docker compose logs

Database Issues?

1. Check database is running: docker exec finance_bot_postgres psql -U finance_user -d finance_db -c "SELECT 1"
2. Check migration status: docker exec finance_bot_migrations alembic current

---

Status: 🟢 Ready to Deploy

See DEPLOYMENT_CHECKLIST_API.md for full deployment steps.