architect/_archive/2025-11-09-marketplace-old/marketplace-mvp/modules/delivery/QUICK_START.md

🚀 Быстрый старт - Модуль Доставки

Что умеет модуль

  1. Яндекс Доставка - полная интеграция
  2. Универсальный модуль - любая служба через YAML конфиг
  3. Работа с заказами - автоматическое создание доставки из Order
  4. Экспорт/Импорт - массовая отправка через CSV
  5. Синхронизация - автообновление трек-номеров и статусов

Примеры использования

1. Создать доставку для заказа из БД

from database.models import Order, get_session
from modules.delivery import DeliveryManager

session = get_session()
order = session.query(Order).filter_by(id=123).first()

# Создаем менеджер
manager = DeliveryManager("yandex", token="YOUR_YANDEX_TOKEN")

# Отправляем заказ в доставку
result = manager.create_delivery_from_order(
    order=order,
    pickup_address="Москва, ул. Ваш Склад, 1",
    session=session
)

if result['success']:
    print(f"✅ Доставка создана!")
    print(f"Трек-номер: {result['tracking_number']}")
else:
    print(f"❌ Ошибка: {result['error']}")

2. Экспорт заказов в CSV

# Получаем все заказы без доставки
orders = session.query(Order).filter(
    Order.tracking_number.is_(None),
    Order.status_internal == 'ready_to_ship'
).all()

# Экспортируем
manager = DeliveryManager("yandex", token="...")
count = manager.export_orders_to_csv(orders, "orders_to_ship.csv")
print(f"Экспортировано {count} заказов")

3. Массовая отправка из CSV

# Отправляем все заказы из файла
results = manager.import_and_create_from_csv(
    file_path="orders_to_ship.csv",
    pickup_address="Ваш склад"
)

# Анализируем результаты
success = [r for r in results if r['success']]
failed = [r for r in results if not r['success']]

print(f"✅ Успешно: {len(success)}")
print(f"❌ Ошибки: {len(failed)}")

4. Синхронизация статусов

# Обновить статус для одного заказа
result = manager.sync_tracking_status(order, session)
if result['success']:
    print(f"Статус: {result['status']}")

# Массовая синхронизация всех активных доставок
from modules.delivery import sync_all_active_deliveries

stats = sync_all_active_deliveries("yandex")
print(f"Обновлено: {stats['success']}/{stats['total']}")

5. Добавление новой службы доставки

Создайте файл config/delivery/my_service.yaml:

name: "My Delivery"
base_url: "https://api.mydelivery.com"
auth_type: "bearer"
auth:
  token: "${MY_DELIVERY_TOKEN}"

endpoints:
  create_order: "/orders"
  get_order: "/orders/{order_id}"
  track: "/tracking/{tracking_number}"

mapping:
  request:
    order_number: "external_id"
    recipient_name: "receiver.name"
  response:
    order_id: "id"
    tracking_number: "track_code"

Используйте:

manager = DeliveryManager("my_service")

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

Добавьте в .env:

YANDEX_DELIVERY_TOKEN=your_yandex_token_here
DPD_USERNAME=your_dpd_login
DPD_PASSWORD=your_dpd_password

Автоматизация (cron)

Добавьте в crontab для автоматической синхронизации:

# Синхронизация статусов каждые 30 минут
*/30 * * * * cd /path/to/project && python -c "from modules.delivery import sync_all_active_deliveries; sync_all_active_deliveries('yandex')"

Документация: См. README.md
Дата: 2025-11-08