finance_bot/API_DOCUMENTATION_INDEX.md

📚 Bot API Integration - Documentation Index

🎯 Start Here

Выберите документ в зависимости от вашей роли:

👤 I'm a User/Tester

1. Start: API_QUICK_START.md - 5 минут
2. Testing: Follow Quick Tests section
3. Troubleshoot: See Troubleshooting section

👨‍💻 I'm a Developer

1. Overview: API_CHANGES_SUMMARY.md
2. API Reference: docs/API_ENDPOINTS.md
3. Integration: docs/API_INTEGRATION_GUIDE.md
4. Code Examples: examples/bot_api_usage.py

🚀 I'm Deploying to Production

1. Checklist: DEPLOYMENT_CHECKLIST_API.md - 13 phases
2. Migration: Phase 1 in checklist
3. Testing: Phase 4-7 in checklist
4. Monitoring: Phase 10 in checklist

🔧 I'm Maintaining/Debugging

1. Changes: API_CHANGES_SUMMARY.md
2. Endpoints: docs/API_ENDPOINTS.md
3. Integration: docs/API_INTEGRATION_GUIDE.md
4. Common Commands: API_QUICK_START.md

---

📖 Complete Documentation

Main Documentation Files

File	Purpose	Read Time
API_CHANGES_SUMMARY.md	Overview of all changes	5 min
API_QUICK_START.md	Quick deployment & testing	5 min
DEPLOYMENT_CHECKLIST_API.md	Full deployment guide (13 phases)	30 min
docs/API_ENDPOINTS.md	Complete API reference	15 min
docs/API_INTEGRATION_GUIDE.md	Integration guide with code	20 min
BOT_API_INTEGRATION_SUMMARY.md	Detailed implementation summary	15 min

Code & Examples

File	Purpose
examples/bot_api_usage.py	Python implementation examples
test_api.sh	Bash test script for all endpoints

---

🚀 Quick Reference

Most Common Tasks

1. Deploy Everything

# See API_QUICK_START.md → Deploy in 5 Minutes
docker compose down
docker compose up -d --build
docker exec finance_bot_migrations alembic upgrade head

2. Register a User

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

# Telegram quick registration
curl -X POST "http://localhost:8000/api/v1/auth/telegram/register" \
  -G --data-urlencode "chat_id=556399210" \
  --data-urlencode "username=john_doe"

3. Get Token

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

4. Make API Call

curl -X GET http://localhost:8000/api/v1/accounts \
  -H "Authorization: Bearer <token>"

5. Check Logs

docker logs -f finance_bot_web      # Web service
docker logs -f finance_bot_bot      # Bot service
docker logs -f finance_bot_postgres # Database

---

📋 What Was Added

API Endpoints

• ✅ 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 token
• ✅ POST /api/v1/auth/telegram/register - Quick Telegram registration

Bot Commands

• ✅ /start - Show registration options
• ✅ /register - One-tap Telegram registration
• ✅ /link - Link existing account
• ✅ /help - Updated help text

Database

• ✅ email field (unique, nullable)
• ✅ password_hash field
• ✅ telegram_id made nullable
• ✅ email_verified field

Documentation

• ✅ docs/API_ENDPOINTS.md - Full API reference
• ✅ docs/API_INTEGRATION_GUIDE.md - Integration guide
• ✅ examples/bot_api_usage.py - Code examples
• ✅ This file and 5 others

---

🔐 Authentication Flows

Quick Registration (1 command)

User /register → Bot API call → JWT Token → Ready!

Email Account Link (3 steps)

User /link → Get Code → User confirms → Get JWT → Ready!

Email Registration

User → Web → Register → Get Tokens → Make API calls

---

🧪 Testing Guide

Phase 1: Health Check

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

Phase 2: Email Registration

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"test123"}'
# Expected: 200 with access_token

Phase 3: Get Token

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

Phase 4: Quick Telegram Registration

curl -X POST "http://localhost:8000/api/v1/auth/telegram/register?chat_id=556399210&username=john"
# Expected: 200 with jwt_token

Phase 5: Authenticated Request

curl -X GET http://localhost:8000/api/v1/accounts \
  -H "Authorization: Bearer <token>"
# Expected: 200 or empty list

See DEPLOYMENT_CHECKLIST_API.md for full testing guide.

---

🛠️ Troubleshooting

Database Migration Failed

# Check status
docker exec finance_bot_migrations alembic current

# Rollback and retry
docker exec finance_bot_migrations alembic downgrade -1
docker exec finance_bot_migrations alembic upgrade head

Bot Can't Connect to Web

# Check network
docker network ls
docker network inspect finance_network

# Test connection
docker exec finance_bot_bot curl http://web:8000/health

Tokens Not Stored in Redis

# Check Redis
docker exec finance_bot_redis redis-cli ping

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

API Returns 500

# Check logs
docker logs finance_bot_web | grep ERROR

# Restart
docker restart finance_bot_web

See API_QUICK_START.md#-troubleshooting for more.

---

📊 File Structure

finance_bot/
├── docs/
│   ├── API_ENDPOINTS.md                    # Complete API reference
│   ├── API_INTEGRATION_GUIDE.md             # Integration guide
│   └── ARCHITECTURE.md                     # (existing)
├── examples/
│   └── bot_api_usage.py                    # Python examples
├── migrations/versions/
│   └── 003_add_email_auth.py               # Database migration
├── app/
│   ├── db/models/
│   │   └── user.py                         # Updated: email + password
│   ├── api/
│   │   └── auth.py                         # Added 3 new endpoints
│   └── bot/
│       └── client.py                       # Added 2 new commands
├── API_QUICK_START.md                      # Quick start (5 min)
├── API_CHANGES_SUMMARY.md                  # What changed
├── BOT_API_INTEGRATION_SUMMARY.md           # Detailed summary
├── DEPLOYMENT_CHECKLIST_API.md             # 13-phase checklist
├── test_api.sh                             # Test script
└── API_DOCUMENTATION_INDEX.md              # This file!

---

🎓 Learning Path

Beginner (15 minutes)

1. Read API_CHANGES_SUMMARY.md - What changed
2. Follow API_QUICK_START.md - Quick start
3. Run test script: bash test_api.sh

Intermediate (30 minutes)

1. Read docs/API_INTEGRATION_GUIDE.md
2. Study examples/bot_api_usage.py
3. Test each endpoint with cURL
4. Follow DEPLOYMENT_CHECKLIST_API.md phase 1-3

Advanced (60 minutes)

1. Complete all phases in DEPLOYMENT_CHECKLIST_API.md
2. Review database migration in migrations/versions/003_add_email_auth.py
3. Implement token refresh logic in your code
4. Set up monitoring and alerts

---

💼 For Teams

Frontend Team

• Read: docs/API_INTEGRATION_GUIDE.md
• Reference: docs/API_ENDPOINTS.md
• Endpoints: /api/v1/auth/register, /api/v1/auth/login, /api/v1/auth/telegram/confirm

Backend Team

• Read: BOT_API_INTEGRATION_SUMMARY.md
• Reference: docs/API_ENDPOINTS.md
• Files: app/api/auth.py, app/db/models/user.py, migrations/

DevOps Team

• Read: DEPLOYMENT_CHECKLIST_API.md
• Reference: API_QUICK_START.md
• Commands: Migration, rebuild, testing phases

QA Team

• Read: API_QUICK_START.md
• Follow: Phases 4-7 in DEPLOYMENT_CHECKLIST_API.md
• Use: test_api.sh script

---

🔗 External Resources

JWT Authentication

• jwt.io - JWT debugger and information
• FastAPI Security

Telegram Bot

• aiogram documentation
• Telegram Bot API

Docker & Compose

• Docker Compose Reference
• Docker Network Guide

Database

• PostgreSQL Documentation
• Alembic Documentation

---

✅ Verification Checklist

Before going live:

• All documentation read
• Database migration applied
• All API endpoints tested
• Bot commands working
• Tokens storing in Redis
• No errors in logs
• Load testing done
• Security review complete
• Monitoring configured
• Rollback plan ready

---

📞 Support & Troubleshooting

Getting Help

1. Check the relevant documentation file above
2. Search for your error in logs: docker logs
3. Run test script: bash test_api.sh
4. Check troubleshooting section in API_QUICK_START.md

Common Issues

• "Email already registered" → Use different email
• "User not found" → Register first, then get token
• "Cannot connect to host web" → Wait for web service to start
• Token not in Redis → Check Redis connection

---

🎉 Completion

You now have:

• ✅ 6 documentation files
• ✅ 2 code example files
• ✅ 1 test script
• ✅ 1 deployment checklist
• ✅ 5 modified application files
• ✅ 1 new database migration
• ✅ Complete API integration

Next Step: Choose your path above and start reading!

---

Last Updated: 2025-12-11
Status: ✅ Ready for Production
Version: 1.0.0