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

Автентифікація

Створіть ключ у розділі Developers › API keys і надсилайте його разом з ID магазину в кожному запиті:
GET /me працює з будь-яким дійсним ключем. Він повертає магазин, дозволи ключа та ваші ліміти, тож використовуйте його для перевірки налаштувань.
Ключі діють від імені власника магазину. Зберігайте їх на своєму сервері, ніколи не розміщуйте їх у браузерному чи мобільному коді.

Дозволи

Під час створення ключа оберіть Full access, Read only або Custom. У режимі Custom ви обираєте доступ на читання або запис для кожної області окремо. Запис включає читання. Запити 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). Кожен запит відображається в розділі Developers › API requests зі своїм статусом і тривалістю.

Наступні кроки

Створення замовлень

Приймайте замовлення зі свого сайту чи застосунку та перенаправляйте клієнтів на оформлення.

Вебхуки

Отримуйте сповіщення, коли замовлення оплачено, скасовано або за ним повернено кошти.