Bitrix24 to PostgreSQL Sync Service

Сервис для синхронизации данных CRM из Bitrix24 в PostgreSQL с использованием Supabase для аутентификации.

📚 Документация:

SETUP.md - Подробная инструкция по установке и настройке
ARCHITECTURE.md - Архитектура системы
CHANGELOG.md - История изменений

Обзор

Этот сервис позволяет:

Синхронизировать сущности CRM (сделки, контакты, лиды, компании) из Bitrix24 в PostgreSQL
Поддерживать полную и инкрементальную синхронизацию
Получать webhook-уведомления от Bitrix24 для real-time обновлений
Автоматически создавать и обновлять схему БД на основе полей Bitrix24
Настраивать расписание синхронизации через API

Архитектура

┌─────────────┐     ┌─────────────────┐     ┌────────────────┐
│  Bitrix24   │────▶│  FastAPI Backend │────▶│   PostgreSQL   │
│   CRM API   │◀────│  + APScheduler   │     │   (Supabase)   │
└─────────────┘     └─────────────────┘     └────────────────┘
       │                    │
       │ webhooks           │
       └────────────────────┘

Требования

Docker и Docker Compose
Bitrix24 аккаунт с настроенным webhook
(Опционально) Внешний URL для получения webhooks

Быстрый старт

1. Клонирование репозитория

git clone <repository-url>
cd bitrix-to-postgres/new_version

2. Настройка переменных окружения

Создайте файл .env на основе примера:

cp .env.example .env

Отредактируйте .env:

# PostgreSQL
POSTGRES_PASSWORD=your_secure_password

# Supabase Auth
JWT_SECRET=your-super-secret-jwt-key-min-32-characters
SUPABASE_ANON_KEY=your-supabase-anon-key

# Bitrix24
BITRIX_WEBHOOK_URL=https://your-domain.bitrix24.ru/rest/1/your-webhook-code/

# Application
DEBUG=false
SITE_URL=http://localhost:3000
API_URL=http://localhost:8080
PUBLIC_SUPABASE_URL=http://localhost:8000

3. Получение Bitrix24 Webhook URL

Войдите в ваш Bitrix24
Перейдите в Приложения → Webhooks → Входящие вебхуки
Нажмите Добавить вебхук
Выберите необходимые права:
- crm - доступ к CRM
- crm.deal - работа со сделками
- crm.contact - работа с контактами
- crm.lead - работа с лидами
- crm.company - работа с компаниями
Скопируйте сгенерированный URL в BITRIX_WEBHOOK_URL

4. Запуск сервисов

docker compose up -d

⚠️ ВАЖНО: Используйте docker compose up -d для автоматического применения миграций. НЕ используйте docker compose restart - это только перезапускает контейнеры без применения миграций.

Автоматическое применение миграций: При запуске контейнера backend (docker compose up -d) автоматически выполняются:

Ожидание готовности PostgreSQL (до 30 попыток с интервалом 2 секунды)
Применение Alembic миграций (alembic upgrade head)
Запуск приложения

Сервисы будут доступны:

Backend API: http://localhost:8080
Frontend: http://localhost:3000
Supabase API: http://localhost:8000
Supabase Studio: http://localhost:3001
PostgreSQL: localhost:5432

5. Проверка работоспособности

curl http://localhost:8080/health

Проверка применения миграций:

# Просмотр логов backend при старте
docker-compose logs backend

# Вы должны увидеть:
# ✓ Waiting for PostgreSQL...
# ✓ PostgreSQL is ready!
# ✓ Running database migrations...
# ✓ Migrations completed successfully!
# ✓ Starting application...

Конфигурация

Переменные окружения

Переменная	Описание	По умолчанию
`DATABASE_URL`	PostgreSQL connection string	-
`BITRIX_WEBHOOK_URL`	Bitrix24 webhook URL	-
`SUPABASE_URL`	Supabase API URL	-
`SUPABASE_KEY`	Supabase anon key	-
`SUPABASE_JWT_SECRET`	JWT secret для валидации токенов	-
`DEBUG`	Режим отладки	`false`
`SYNC_BATCH_SIZE`	Размер пакета для синхронизации	`50`
`SYNC_DEFAULT_INTERVAL_MINUTES`	Интервал синхронизации по умолчанию	`30`

API Документация

Синхронизация

Запуск синхронизации

# Полная синхронизация сделок
curl -X POST http://localhost:8080/api/v1/sync/start/deal \
  -H "Content-Type: application/json" \
  -d '{"sync_type": "full"}'

# Инкрементальная синхронизация контактов
curl -X POST http://localhost:8080/api/v1/sync/start/contact \
  -H "Content-Type: application/json" \
  -d '{"sync_type": "incremental"}'

Поддерживаемые сущности: deal, contact, lead, company

Получение статуса синхронизации

curl http://localhost:8080/api/v1/sync/status

Конфигурация синхронизации

# Получить конфигурацию
curl http://localhost:8080/api/v1/sync/config

# Обновить конфигурацию
curl -X PUT http://localhost:8080/api/v1/sync/config \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "deal",
    "enabled": true,
    "sync_interval_minutes": 15,
    "webhook_enabled": true
  }'

Webhooks

Регистрация webhooks в Bitrix24

# Зарегистрировать webhooks
curl -X POST "http://localhost:8080/api/v1/webhooks/register?handler_base_url=https://your-public-url.com"

# Отменить регистрацию
curl -X DELETE "http://localhost:8080/api/v1/webhooks/unregister?handler_base_url=https://your-public-url.com"

# Получить список зарегистрированных webhooks
curl http://localhost:8080/api/v1/webhooks/registered

Endpoint для Bitrix24

Bitrix24 будет отправлять события на:

POST https://your-public-url.com/api/v1/webhooks/bitrix

Поддерживаемые события:

ONCRMDEALUPDATE, ONCRMDEALADD, ONCRMDEALDELETE
ONCRMCONTACTUPDATE, ONCRMCONTACTADD, ONCRMCONTACTDELETE
ONCRMLEADUPDATE, ONCRMLEADADD, ONCRMLEADDELETE
ONCRMCOMPANYUPDATE, ONCRMCOMPANYADD, ONCRMCOMPANYDELETE

Разработка

Настройка окружения для разработки

cd new_version/backend

# Создание виртуального окружения
python -m venv venv
source venv/bin/activate  # Linux/Mac
# или
.\venv\Scripts\activate  # Windows

# Установка зависимостей
pip install -e ".[dev]"

Запуск в режиме разработки

# Только база данных
docker-compose up -d db auth

# Backend с hot-reload
cd backend
DEBUG=true uvicorn app.main:app --reload --host 0.0.0.0 --port 8080

# Frontend с hot-reload
cd frontend
npm install
npm run dev

Структура проекта

new_version/
├── backend/
│   ├── app/
│   │   ├── api/v1/          # API endpoints
│   │   ├── core/            # Auth, logging, exceptions
│   │   ├── domain/          # Business logic
│   │   │   ├── entities/    # Pydantic models
│   │   │   └── services/    # Sync service
│   │   ├── infrastructure/  # External services
│   │   │   ├── bitrix/      # Bitrix24 client
│   │   │   ├── database/    # DB connection, models
│   │   │   └── scheduler/   # APScheduler
│   │   └── tests/           # Unit, integration, e2e tests
│   ├── alembic/             # Database migrations
│   │   ├── env.py           # Alembic environment (async)
│   │   └── versions/        # Migration files
│   ├── entrypoint.sh        # Auto-migration startup script
│   ├── alembic.ini          # Alembic configuration
│   ├── Dockerfile
│   └── pyproject.toml
├── frontend/                # React frontend
├── supabase/
│   └── db-init/             # Initial DB setup scripts (first run only)
├── docker-compose.yml
├── ARCHITECTURE.md          # Detailed architecture documentation
└── README.md

Тестирование

Запуск тестов

cd backend

# Все тесты
pytest

# Unit тесты
pytest app/tests/unit/

# Integration тесты
pytest app/tests/integration/

# E2E тесты
pytest app/tests/e2e/

# С покрытием
pytest --cov=app --cov-report=html

Типы тестов

Unit тесты (app/tests/unit/): Тестируют отдельные компоненты с моками
Integration тесты (app/tests/integration/): Тестируют API endpoints
E2E тесты (app/tests/e2e/): Тестируют полный flow синхронизации

Устранение неполадок

Проблемы с подключением к Bitrix24

Проверьте правильность BITRIX_WEBHOOK_URL
Убедитесь, что webhook имеет необходимые права
Проверьте логи: docker-compose logs backend

Проблемы с базой данных

Проверьте подключение: docker compose exec db pg_isready
Проверьте логи: docker compose logs db
Миграции применяются автоматически только при docker compose up -d (НЕ при restart)
Проверьте применение миграций:
```
docker compose logs backend | grep -i "migration"
```
При необходимости запустите миграции вручную:
```
docker compose exec backend alembic upgrade head
```
Проверьте текущую версию схемы БД:
```
docker compose exec backend alembic current
```
После изменения кода пересоздайте контейнер:
```
docker compose up -d --force-recreate --build backend
```
Создание новой миграции (для разработчиков):
```
docker compose exec backend alembic revision --autogenerate -m "description"
```

Webhooks не приходят

Убедитесь, что ваш сервер доступен из интернета
Проверьте, что webhooks зарегистрированы: curl http://localhost:8080/api/v1/webhooks/registered

Используйте ngrok для локальной разработки:

ngrok http 8080
# Используйте полученный URL для регистрации webhooks

Ошибки синхронизации

Проверьте статус: curl http://localhost:8080/api/v1/sync/status
Проверьте логи: docker-compose logs backend | grep -i error
Проверьте таблицу sync_logs в базе данных

Лицензия

MIT License напиши максимально подробный план по добавлению нового функционала в @new_version/ это создание чартов для дашбордов с помошью ai
gpt-4o-mini сами чарты должны будут брать данные из базы данных, также должен быть функционал который будет создавать описание полей
базы данных в формат markdown это должен быть отдельный endpoint. чарты должны быть в современном дизайне и иметь разные форматы

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Bitrix24 to PostgreSQL Sync Service

Обзор

Архитектура

Требования

Быстрый старт

1. Клонирование репозитория

2. Настройка переменных окружения

3. Получение Bitrix24 Webhook URL

4. Запуск сервисов

5. Проверка работоспособности

Конфигурация

Переменные окружения

API Документация

Синхронизация

Запуск синхронизации

Получение статуса синхронизации

Конфигурация синхронизации

Webhooks

Регистрация webhooks в Bitrix24

Endpoint для Bitrix24

Разработка

Настройка окружения для разработки

Запуск в режиме разработки

Структура проекта

Тестирование

Запуск тестов

Типы тестов

Устранение неполадок

Проблемы с подключением к Bitrix24

Проблемы с базой данных

Webhooks не приходят

Ошибки синхронизации

Лицензия

FilesExpand file tree

README2.md

Latest commit

History

README2.md

File metadata and controls

Bitrix24 to PostgreSQL Sync Service

Обзор

Архитектура

Требования

Быстрый старт

1. Клонирование репозитория

2. Настройка переменных окружения

3. Получение Bitrix24 Webhook URL

4. Запуск сервисов

5. Проверка работоспособности

Конфигурация

Переменные окружения

API Документация

Синхронизация

Запуск синхронизации

Получение статуса синхронизации

Конфигурация синхронизации

Webhooks

Регистрация webhooks в Bitrix24

Endpoint для Bitrix24

Разработка

Настройка окружения для разработки

Запуск в режиме разработки

Структура проекта

Тестирование

Запуск тестов

Типы тестов

Устранение неполадок

Проблемы с подключением к Bitrix24

Проблемы с базой данных

Webhooks не приходят

Ошибки синхронизации

Лицензия