Документація API

Початок роботи

API Shiplyx дозволяє автоматично синхронізувати товари, керувати замовленнями та отримувати актуальну інформацію про залишки. Всі запити виконуються через HTTPS.

Base URL: https://api.shiplyx.ua/v1

Швидкий старт

Для початку роботи з API виконайте наступні кроки:

Зареєструйтесь на платформі Shiplyx
Отримайте API ключ в особистому кабінеті
Зробіть тестовий запит для перевірки

Приклад тестового запиту

curl -X GET "https://api.shiplyx.ua/v1/products" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
                    

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

API Shiplyx використовує Bearer Token для автентифікації. Додавайте ваш API ключ у заголовок кожного запиту.

Заголовок автентифікації

Authorization: Bearer YOUR_API_KEY

Важливо: Не публікуйте ваш API ключ у відкритому доступі. Зберігайте його в безпечному місці та не передавайте третім особам.

Отримання API ключа

1. Увійдіть в особистий кабінет
2. Перейдіть в розділ "API"
3. Натисніть "Створити новий ключ"
4. Скопіюйте згенерований ключ

Товари

Endpoints для роботи з каталогом товарів.

Отримати список товарів

GET /products

Параметри запиту

Параметр	Тип	Опис
`page`	integer	Номер сторінки (за замовчуванням: 1)
`limit`	integer	Кількість товарів на сторінці (макс: 100)
`category`	string	Фільтр по категорії
`search`	string	Пошук по назві або опису

Приклад запиту

curl -X GET "https://api.shiplyx.ua/v1/products?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
                    

Приклад відповіді

{
  "success": true,
  "data": {
    "products": [
      {
        "id": "prod_12345",
        "name": "Бездротові навушники TWS",
        "description": "Популярні бездротові навушники...",
        "category": "electronics",
        "price": 450.00,
        "currency": "UAH",
        "in_stock": true,
        "quantity": 150,
        "images": [
          "https://cdn.shiplyx.ua/images/prod_12345_1.jpg"
        ]
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 50,
      "total_items": 1000
    }
  }
}
                    

Отримати товар по ID

GET /products/{product_id}

Приклад запиту

curl -X GET "https://api.shiplyx.ua/v1/products/prod_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"
                    

Замовлення

Endpoints для створення та керування замовленнями.

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

POST /orders

Тіло запиту

Поле	Тип	Обов'язкове	Опис
`products`	array	Так	Масив товарів
`customer`	object	Так	Дані клієнта
`delivery`	object	Так	Дані доставки

Приклад запиту

curl -X POST "https://api.shiplyx.ua/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {
        "product_id": "prod_12345",
        "quantity": 2
      }
    ],
    "customer": {
      "name": "Іван Петренко",
      "phone": "+380501234567",
      "email": "ivan@example.com"
    },
    "delivery": {
      "type": "nova_poshta",
      "city": "Київ",
      "warehouse": "Відділення №1"
    }
  }'
                    

Успіх: Після створення замовлення ви отримаєте tracking ID для відстеження статусу.

Отримати статус замовлення

GET /orders/{order_id}

Приклад відповіді

{
  "success": true,
  "data": {
    "order_id": "ord_67890",
    "status": "processing",
    "tracking_number": "59001234567890",
    "created_at": "2025-11-01T10:30:00Z",
    "updated_at": "2025-11-01T11:15:00Z"
  }
}
                    

Залишки

Перевірка наявності товарів на складі.

Перевірити залишки

GET /inventory

Порада: Рекомендуємо синхронізувати залишки кожні 15 хвилин для актуальності даних у вашому магазині.

Webhooks

Налаштуйте webhooks для отримання сповіщень про події в реальному часі.

Доступні події

order.created - Створено нове замовлення
order.updated - Оновлено статус замовлення
order.shipped - Замовлення відправлено
product.updated - Оновлено дані товару
inventory.low - Товар закінчується

Приклад payload webhook

{
  "event": "order.shipped",
  "timestamp": "2025-11-01T14:30:00Z",
  "data": {
    "order_id": "ord_67890",
    "tracking_number": "59001234567890"
  }
}
                    

Обробка помилок

API використовує стандартні HTTP коди відповідей.

Код	Статус	Опис
`200`	OK	Запит успішно виконано
`400`	Bad Request	Невірні параметри запиту
`401`	Unauthorized	Невірний або відсутній API ключ
`404`	Not Found	Ресурс не знайдено
`429`	Too Many Requests	Перевищено ліміт запитів
`500`	Server Error	Внутрішня помилка сервера

Формат повідомлення про помилку

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Невірний формат параметра 'page'",
    "details": "Параметр 'page' має бути цілим числом"
  }
}
                    

Ліміти запитів

Для забезпечення стабільності API існують наступні ліміти:

Тариф	Запитів/хвилину	Запитів/день
Старт	60	5,000
Бізнес	120	15,000
Преміум	300	Необмежено

У відповідь на кожен запит включаються заголовки з інформацією про залишок лімітів:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1698836400