Metadata-Version: 2.4
Name: kuper_api
Version: 0.1.0
Summary: Неофициальная Python библиотека для работы с API Купер (бывш. СберМаркет)
Home-page: https://github.com/inmyuse/kuper-api
Keywords: kuper sbermarket api wrapper library delivery грузовик доставка
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: curl_cffi>=0.7
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Kuper API

Неофициальная Python библиотека для работы с внутренним API сервиса доставки
[Купер](https://kuper.ru)

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

## Особенности

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

## Установка

```bash
pip install curl_cffi
pip install kuper_api
```

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

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

```python
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 из авторизованного браузера:

```python
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](LICENSE)

## Автор

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