> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Обзор User API

> Создавайте заказы, синхронизируйте каталог, отправляйте физические товары и реагируйте на события из собственных систем.

> [!NOTE]
>
> Чтобы принимать оплату этих заказов картой на своем сайте, см. [PapelPay](https://developers.papelship.com/ru/papelpay/overview.md).

User API (в панели управления он называется Store API) дает вашим серверам те же возможности, что и панель управления магазином: заказы, товары, остатки, клиенты, поддержка, доставка и вебхуки.

**Базовый URL:** `https://app.papelship.com/api/v1`

> [!NOTE]
>
> Старые интеграции, которые обращаются к `https://app.papelship.com/api_user/api/v1`, продолжают работать. Для нового кода используйте `/api/v1`.

## Аутентификация

Создайте ключ в разделе **Разработчикам › API-ключи** и передавайте его вместе с ID магазина в каждом запросе:

```bash theme={"system"}
curl https://app.papelship.com/api/v1/me \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id"
```

`GET /me` работает с любым действительным ключом. Он возвращает магазин, разрешения ключа и ваши лимиты, поэтому используйте его для проверки настройки.

> [!WARNING]
>
> Ключи действуют от имени владельца магазина. Храните их на сервере и никогда не размещайте в браузерном или мобильном коде.

## Разрешения

При создании ключа выберите **Полный доступ**, **Только чтение** или **Настраиваемый**. В режиме «Настраиваемый» вы задаете доступ на чтение или запись для каждой области. Запись включает чтение.

| Область | Разрешение | Охватывает |
| :- | :- | :- |
| Заказы | `orders` | `/invoices` |
| Товары | `products` | `/products` и все вложенные пути |
| Категории и группы | `catalog` | `/categories`, `/groups` |
| Купоны | `coupons` | `/coupons` |
| Клиенты и черный список | `customers` | `/customers`, `/blacklist` |
| Доставка и исполнение | `fulfillment` | `/orders`, `/returns`, `/shipping` |
| Отзывы | `reviews` | `/reviews` |
| Вопросы о товарах | `questions` | `/questions` |
| Тикеты поддержки | `support` | `/tickets` |
| Подписки | `subscriptions` | `/subscriptions` |
| Партнеры | `affiliates` | `/affiliates` |
| Вебхуки | `webhooks` | `/webhooks`, `/events` |
| Аналитика | `analytics` | `/analytics` (только чтение) |
| Магазин | `store` | `/store`, `/payment-methods` (только чтение) |

Запросам `GET` нужен доступ на чтение; `POST`, `PATCH`, `PUT` и `DELETE` требуют доступа на запись. Ключ без нужного разрешения получает `403 INSUFFICIENT_SCOPE`, а недостающее разрешение указывается в `required_scope`.

Также можно ограничить ключ этим магазином, списком IP-адресов или датой истечения срока действия.

## Ответы

Каждый ответ представляет собой JSON с флагом `success`.

```json Успех theme={"system"}
{ "success": true, "invoice": { "id": "c35ffd-19a1b2c3d4e-8c7a20", "status": "pending" } }
```

```json Ошибка theme={"system"}
{
  "success": false,
  "code": "VALIDATION_FAILED",
  "error": "customer_email must be a valid email address",
  "details": { "field": "customer_email" },
  "request_id": "req_7YbK2mQ9xP1cRt4v"
}
```

Опирайтесь на `code`, а не на текст сообщения. Каждый ответ содержит заголовок `X-Request-Id`; указывайте его при обращении в поддержку. Все коды описаны в разделе [Ошибки](https://developers.papelship.com/ru/user-api/errors.md).

## Соглашения

* **Суммы** указываются целыми числами в минимальных единицах валюты: `price_cents: 2999` означает 29.99.
* **Даты** передаются в формате ISO 8601 в UTC.
* **ID** являются публичными идентификаторами: хеш-ID товаров, ID заказов вида `c35ffd-19a1b2c3d4e-8c7a20`. Для записей других магазинов возвращается `404`.
* **Созданные** записи возвращают `201`.

## Пагинация

Списки принимают `limit` (от 1 до 100, по умолчанию 25) и `offset` и возвращают объект `pagination`:

```bash theme={"system"}
curl "https://app.papelship.com/api/v1/invoices?status=completed&limit=50&offset=100" \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id"
```

```json theme={"system"}
{
  "success": true,
  "invoices": [ ... ],
  "pagination": { "total": 342, "limit": 50, "offset": 100, "has_more": true }
}
```

Списки партнеров используют курсор: передайте `next_cursor` обратно как `cursor`.

## Безопасные повторы

Передавайте заголовок `Idempotency-Key` в запросах на создание (заказы, возвраты, отправления, товары, вебхуки и другие, отмеченные в справочнике). При сбое сети повторите запрос с тем же ключом и телом: вы получите первый результат, а не дубликат.

```bash theme={"system"}
curl -X POST https://app.papelship.com/api/v1/invoices \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id" \
  -H "Idempotency-Key: 6f1c8a52-4f0e-4b8e-9a7c-2d1b3e5f7a90" \
  -H "Content-Type: application/json" \
  -d '{ "customer_email": "buyer@example.com", "items": [{ "product_id": "a1B2c3D4e5F6" }] }'
```

* Ключи хранятся 24 часа.
* Повторно отданный ответ содержит заголовок `Idempotent-Replayed: true`.
* Тот же ключ с другим телом возвращает `422 IDEMPOTENCY_KEY_REUSED`.

## Лимиты

| Лимит | Значение | Заголовки |
| :- | :- | :- |
| Запросов на ключ | 300 в минуту | `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (время Unix) |
| Вызовов в месяц | Зависит от тарифа | `X-Quota-Limit` |

При превышении лимита вы получите `429` с заголовком `Retry-After`. `RATE_LIMITED` снимается в течение минуты; `STORE_API_MONTHLY_QUOTA_EXCEEDED` сбрасывается в первый день следующего месяца (UTC).

Каждый запрос отображается в разделе **Разработчикам › API-запросы** со статусом и длительностью.

## Следующие шаги

> [card] [Создание заказов](https://developers.papelship.com/ru/user-api/orders.md)
>
> Принимайте заказы со своего сайта или из приложения и отправляйте клиентов на страницу оплаты.

> [card] [Вебхуки](https://developers.papelship.com/ru/user-api/webhooks.md)
>
> Получайте уведомления, когда заказы оплачены, отменены или возвращены.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.