Перейти к основному содержанию
Чтобы принимать оплату этих заказов картой на своем сайте, см. PapelPay.
User API (в панели управления он называется Store API) дает вашим серверам те же возможности, что и панель управления магазином: заказы, товары, остатки, клиенты, поддержка, доставка и вебхуки. Базовый URL: https://app.papelship.com/api/v1
Старые интеграции, которые обращаются к https://app.papelship.com/api_user/api/v1, продолжают работать. Для нового кода используйте /api/v1.

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

Создайте ключ в разделе Разработчикам › API-ключи и передавайте его вместе с ID магазина в каждом запросе:
GET /me работает с любым действительным ключом. Он возвращает магазин, разрешения ключа и ваши лимиты, поэтому используйте его для проверки настройки.
Ключи действуют от имени владельца магазина. Храните их на сервере и никогда не размещайте в браузерном или мобильном коде.

Разрешения

При создании ключа выберите Полный доступ, Только чтение или Настраиваемый. В режиме «Настраиваемый» вы задаете доступ на чтение или запись для каждой области. Запись включает чтение. Запросам GET нужен доступ на чтение; POST, PATCH, PUT и DELETE требуют доступа на запись. Ключ без нужного разрешения получает 403 INSUFFICIENT_SCOPE, а недостающее разрешение указывается в required_scope. Также можно ограничить ключ этим магазином, списком IP-адресов или датой истечения срока действия.

Ответы

Каждый ответ представляет собой JSON с флагом success.
Успех
Ошибка
Опирайтесь на code, а не на текст сообщения. Каждый ответ содержит заголовок X-Request-Id; указывайте его при обращении в поддержку. Все коды описаны в разделе Ошибки.

Соглашения

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

Пагинация

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

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

Передавайте заголовок Idempotency-Key в запросах на создание (заказы, возвраты, отправления, товары, вебхуки и другие, отмеченные в справочнике). При сбое сети повторите запрос с тем же ключом и телом: вы получите первый результат, а не дубликат.
  • Ключи хранятся 24 часа.
  • Повторно отданный ответ содержит заголовок Idempotent-Replayed: true.
  • Тот же ключ с другим телом возвращает 422 IDEMPOTENCY_KEY_REUSED.

Лимиты

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

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

Создание заказов

Принимайте заказы со своего сайта или из приложения и отправляйте клиентов на страницу оплаты.

Вебхуки

Получайте уведомления, когда заказы оплачены, отменены или возвращены.