finance_bot/API_QUICK_START.md

# Quick Start - Bot API Integration

## 🚀 Deploy in 5 Minutes

### 1. Apply Database Migration
```bash
docker compose down
docker compose up -d
docker exec finance_bot_migrations alembic upgrade head
```

### 2. Rebuild Containers
```bash
docker compose down
docker compose up -d --build
```

### 3. Test API Endpoint
```bash
# 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
```bash
# Send /register to your Telegram bot
# Expected: "Registration successful!" message
```

### 5. Verify Token in Redis
```bash
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
```bash
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
```bash
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
```bash
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
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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.