Kuper API

Неофициальная Python библиотека для работы с внутренним API сервиса доставки Купер

Библиотека предоставляет высокоуровневый клиент и объектные модели для каталога (ретейлеры, магазины, товары, рестораны), адресов, корзины, заказов и оформления.

Особенности

• Синхронный клиент Client со всеми известными маршрутами API.
• Объектные модели данных вместо «сырых» словарей.
• Обход анти-бот защиты ServicePipe через подмену TLS-отпечатка браузера (под капотом — curl_cffi).
• Cookie-авторизация и автоматическое получение CSRF-токена.
• Поддержка сервиса оформления (checkout v3): инициализация, способы оплаты, завершение заказа.

Установка

pip install curl_cffi
pip install kuper_api

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

Чтение каталога (доступно без авторизации):

from kuper_api import Client

client = Client()

# Магазины по геолокации
for store in client.stores(lat=55.7558, lon=37.6173):
    print(store.id, store.retailer.slug, store.name)

# Поиск товаров в магазине (числовой Store ID)
for product in client.products(327, query='молоко'):
    print(product.id, product.price, product.name)

Для корзины, профиля и оформления нужна cookie из авторизованного браузера:

from kuper_api import Client

with open('.cookie.txt', encoding='utf-8') as f:
    cookie = f.read().strip()

client = Client(cookie=cookie)

session = client.shopping_session()
print(session.current_user.email)

# Добавление товара в корзину
cart = client.cart()
client.line_item_add(cart.number, store_id=327, product_id=39055067663, quantity=1)

Авторизация

API делит маршруты на два семейства:

• v2 (профиль, корзина, заказы) — авторизуются по cookie.
• checkout v3 (/api/v3/checkout/...) — отдельный сервис, в библиотеке заголовки авторизации (client-token, client-id, sbm-forward-tenant) проставляются автоматически.

Строку cookie нужно скопировать из авторизованного браузера (DevTools → Network → любой запрос к kuper.ru → заголовок cookie). Важно, чтобы в ней был свежий spsc (анти-бот) и авторизованный _Instamart_session.

Анти-бот

Купер закрыт анти-ботом ServicePipe, который распознаёт «голый» HTTP-клиент по TLS-отпечатку (JA3/JA4) и отдаёт 307, низводя сессию до анонимной. Поэтому библиотека использует curl_cffi с подменой отпечатка реального браузера (параметр impersonate). При срабатывании блокировки запрос автоматически повторяется.

Лицензия

LGPLv3

Автор

Если у вас возникли вопросы по бибилотеке можете написать создателю в Телеграм: @inmyuse