Перейти до вмісту
ShopentlyLearn

Отримати список — Замовлення

Отримайте дані з «Замовлення». Результат залежить від параметрів цієї операції.

GET/api/v1/orders

Автентифікація
Bearer
Доступно починаючи з
BASIC
Потрібні дозволи
orders.order:read

Приклади коду

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

cURL

: "${SHOPENTLY_SHOP_URL:?}"

curl --disable --globoff --fail-with-body --silent --show-error \
  --proto '=https' --connect-timeout 5 --max-time 30 \
  --request GET \
  --header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \
  --url "${SHOPENTLY_SHOP_URL%/}"'/api/v1/orders?limit=20'

PHP

<?php
declare(strict_types=1);

$baseUrl = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/');
$origin = parse_url($baseUrl);
if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) ||
    isset($origin['user'], $origin['pass']) || isset($origin['user']) || isset($origin['path']) ||
    isset($origin['query']) || isset($origin['fragment'])) {
    throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin');
}
$credential = getenv('SHOPENTLY_ACCESS_TOKEN') ?: '';
if ($credential === '' || strpbrk($credential, "\r\n") !== false) {
    throw new RuntimeException('Invalid credential');
}
$headers = [];
$headers[] = 'Authorization: Bearer ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/orders?limit=20');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HEADERFUNCTION => static function ($handle, string $line) use (&$responseHeaders): int {
        if (str_contains($line, ':')) {
            [$name, $value] = explode(':', $line, 2);
            $responseHeaders[strtolower(trim($name))] = trim($value);
        }
        return strlen($line);
    },
]);
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
$error = curl_error($handle);
curl_close($handle);
if ($raw === false) {
    throw new RuntimeException('Transport error: ' . $error);
}
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP ' . $status . '; request_id=' .
        ($responseHeaders['x-request-id'] ?? '') . '; retry_after=' . ($responseHeaders['retry-after'] ?? ''));
}
$result = $raw === '' ? null : json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING);
echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), PHP_EOL;

Python

from contextlib import ExitStack
import json
import os
from urllib.parse import urlsplit

import requests  # python -m pip install requests

base_url = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/")
origin = urlsplit(base_url)
if origin.scheme != "https" or not origin.hostname or origin.username or origin.password or origin.path or origin.query or origin.fragment:
    raise ValueError("SHOPENTLY_SHOP_URL must be an HTTPS origin")
credential = os.environ['SHOPENTLY_ACCESS_TOKEN']
if not credential or "\r" in credential or "\n" in credential:
    raise ValueError("Invalid credential")
headers = {}
headers["Authorization"] = 'Bearer' + " " + credential
body = None
if body is not None:
    headers["Content-Type"] = "application/json"

with ExitStack() as stack:
    session = stack.enter_context(requests.Session())
    files = None
    if False:
        image = stack.enter_context(open(os.environ["SHOPENTLY_IMAGE_FILE"], "rb"))
        if os.fstat(image.fileno()).st_size > 5242880:
            raise ValueError("Image exceeds 5 MiB")
        files = {"file": ("article.png", image, "image/png")}
    response = session.request(
        'GET', base_url + '/api/v1/orders?limit=20', headers=headers,
        data=body.encode("utf-8") if body is not None else None, files=files,
        timeout=(5, 30), allow_redirects=False,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP {response.status_code}; request_id={response.headers.get('X-Request-ID', '')}; retry_after={response.headers.get('Retry-After', '')}")
    if False:
        if response.headers.get("Content-Type") != "image/webp" or len(response.content) > 5242880:
            raise ValueError("Unexpected image response")
        with open(os.environ["SHOPENTLY_OUTPUT_FILE"], "xb") as output:
            output.write(response.content)
    else:
        result = response.json() if response.content else None
        print(json.dumps(result, ensure_ascii=False, indent=2))

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

JSON
{
  "data": [
    {
      "created_at": "2026-10-19T10:00:00Z",
      "customer": {
        "email": "customer@example.invalid",
        "first_name": "Example",
        "last_name": "Example",
        "phone": null
      },
      "delivery": {
        "amount": {
          "amount": "0.00",
          "currency": "PLN",
          "minor_units": 2
        },
        "dates": {
          "dispatch_timezone": "Europe/Warsaw",
          "estimated_delivery_from": "2026-10-20",
          "estimated_delivery_to": "2026-10-21",
          "planned_dispatch_on": "2026-10-19"
        },
        "method_code": "shipping-old",
        "method_name": "Historic carrier",
        "pickup_point": null,
        "recipient_mode": "full_address"
      },
      "discount_amount": {
        "amount": "24.60",
        "currency": "PLN",
        "minor_units": 2
      },
      "id": "order-0000",
      "lifecycle_state": "placed",
      "locale": "pl",
      "market_id": "market-pl",
      "number": "0001",
      "payment": {
        "amount": {
          "amount": "329.40",
          "currency": "PLN",
          "minor_units": 2
        },
        "environment": "live",
        "method_code": "payment-old",
        "method_name": "Historic method",
        "paid_at": null,
        "status": "unpaid",
        "updated_at": "2026-10-19T10:00:00Z",
        "version": 0
      },
      "prices_include_tax": true,
      "shipping_discount_amount": {
        "amount": "24.60",
        "currency": "PLN",
        "minor_units": 2
      },
      "status": {
        "id": "status-0",
        "name": "Status 0",
        "updated_at": "2026-10-19T10:00:00Z",
        "version": 1
      },
      "subtotal": {
        "amount": "329.40",
        "currency": "PLN",
        "minor_units": 2
      },
      "tax": {
        "amount": "49.40",
        "currency": "PLN",
        "minor_units": 2
      },
      "tax_country_code": "PL",
      "total": {
        "amount": "329.40",
        "currency": "PLN",
        "minor_units": 2
      }
    }
  ],
  "meta": {
    "pagination": {
      "has_more": false,
      "limit": 20,
      "next_cursor": null
    },
    "request_id": "example"
  }
}

Як це працює

  • Список містить зведення замовлень і фільтри за номером, статусом, статусом оплати та часом створення.
  • Список і деталі замовлення містять delivery.dates. Заплановані дати YYYY-MM-DD не підтверджують відправлення. Поточні дати мають пріоритет; для старих замовлень використовується збережена оцінка. Очищені або невідомі значення — null. Деталі також містять усі позиції та зображення товарів.
  • Отримуйте допустимі ідентифікатори статусів через /api/v1/order-statuses.
  • Статус замовлення й статус оплати мають окремі кінцеві точки PATCH та дозволи.
  • Зміна записаного статусу оплати не списує кошти з картки й не виконує повернення через платіжного провайдера.

Замовлення · Підсумки

Суми й ставки походять зі збереженого замовлення, включно з виправленнями позицій. Відсутні історичні дані мають значення null і не замінюються поточними ставками каталогу. Суми залишаються десятковими рядками.

Список повертає підсумки. Для кожного результату отримайте GET /api/v1/orders/{order_id}, щоб експортувати повні фінансові дані. Повторні GET обмежені та враховують Retry-After. Експорт за датою створення не синхронізує пізніші виправлення.

Параметри

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

limitЦіле числоНеобов’язкове

Максимальна кількість записів на цій сторінці.

minimum: 1maximum: 100
За замовчуванням: 50Приклад: 20
cursorРядок nullНеобов’язкове

Непрозоре значення для продовження, повернуте попередньою сторінкою.

Рядок:minLength: 1maxLength: 1024
numberРядок nullНеобов’язкове

Зрозумілий користувачу номер замовлення або звернення.

Рядок:minLength: 1maxLength: 48
status_idРядок nullНеобов’язкове

Ідентифікатор із відповідного довідника статусів.

Обмеження · Рядок 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
payment_statusРядок nullНеобов’язкове

Записаний статус оплати.

Обмеження · Рядок 1
enum
["unpaid", "paid", "failed", "refunded"]
created_fromРядок nullНеобов’язкове

Початок фільтра за часом створення.

Рядок:format: "date-time"
created_toРядок nullНеобов’язкове

Кінець фільтра за часом створення.

Рядок:format: "date-time"

Ця операція не приймає тіло JSON.

Відповіді

Відповідь 200

dataМасив <OrderSummaryData > Обов’язкове

Дані успішної відповіді.

Поля · data

OrderSummaryData

created_atРядокОбов’язкове

Час створення.

format: "date-time"
customerCustomerData Обов’язкове

Відомості про клієнта, записані для цього ресурсу.

deliveryShippingData Обов’язкове

Спосіб доставки та пов’язані відомості.

discount_amountMoneyData Обов’язкове

Десяткова сума у вигляді рядка JSON; null лише там, де це дозволено.

idРядокОбов’язкове

Ідентифікатор ресурсу; зберігайте його в отриманому вигляді.

lifecycle_stateOrderLifecycleState Обов’язкове

Стан бізнесового життєвого циклу.

localeРядокОбов’язкове

Мова, вибрана для цього запиту.

market_idРядокОбов’язкове

Ідентифікатор ринку, повернутий кінцевою точкою контексту.

numberРядокОбов’язкове

Зрозумілий користувачу номер замовлення або звернення.

paymentPaymentData Обов’язкове

Відомості про оплату, записані для замовлення.

prices_include_taxЛогічне значенняОбов’язкове

Чи включають наведені ціни податок.

shipping_discount_amountMoneyData Обов’язкове

Десяткова сума у вигляді рядка JSON; null лише там, де це дозволено.

statusOrderStatusData Обов’язкове

Статус, допустимий для цієї конкретної операції.

subtotalMoneyData Обов’язкове

Сума до додавання інших складових, наведених у відповіді.

taxMoneyData Обов’язкове

Відомості про податок.

tax_country_codeРядок nullОбов’язкове

Країна оподаткування · Збережені дані замовлення · ISO 3166-1 alpha-2; null.

totalMoneyData Обов’язкове

Загальна сума.

metaContextPageMeta ContextMeta PageMeta RequestMeta Обов’язкове

Метадані відповіді.

Поля · meta

ContextPageMeta

localeРядокОбов’язкове

Мова, вибрана для цього запиту.

market_codeРядокОбов’язкове

Код ринку, повернутий кінцевою точкою контексту.

market_idРядокОбов’язкове

Ідентифікатор ринку, повернутий кінцевою точкою контексту.

paginationPagination Обов’язкове

Метадані пагінації за курсором.

request_idРядокОбов’язкове

Ідентифікатор звернення; у метаданих відповіді ідентифікує запит HTTP.

minLength: 1maxLength: 100

ContextMeta

localeРядокОбов’язкове

Мова, вибрана для цього запиту.

market_codeРядокОбов’язкове

Код ринку, повернутий кінцевою точкою контексту.

market_idРядокОбов’язкове

Ідентифікатор ринку, повернутий кінцевою точкою контексту.

request_idРядокОбов’язкове

Ідентифікатор звернення; у метаданих відповіді ідентифікує запит HTTP.

minLength: 1maxLength: 100

PageMeta

paginationPagination Обов’язкове

Метадані пагінації за курсором.

request_idРядокОбов’язкове

Ідентифікатор звернення; у метаданих відповіді ідентифікує запит HTTP.

minLength: 1maxLength: 100

RequestMeta

request_idРядокОбов’язкове

Ідентифікатор звернення; у метаданих відповіді ідентифікує запит HTTP.

minLength: 1maxLength: 100
Приклад відповіді

Статус HTTP

200
Успішна відповідь Схема
400
Некоректний запит
401
Потрібна автентифікація
403
Доступ заборонено
404
Ресурс не знайдено
409
Конфлікт версій
422
Помилка валідації
429
Перевищено ліміт запитів
Інші статуси HTTP (7)
405
Метод не дозволено
413
Завеликий запит
415
Непідтримуваний формат
500
Помилка сервера
502
Помилка шлюзу API
503
Сервіс недоступний
504
Перевищено час очікування

Каталог помилок: ErrorResponse

Заголовки

401

WWW-AuthenticateРядокНеобов’язкове

Схема автентифікації, потрібна серверу.

405

AllowРядокНеобов’язкове

Методи HTTP, підтримувані цим ресурсом.

429, 503

Retry-AfterЦіле числоНеобов’язкове

Мінімальна затримка перед повтором у секундах.

minimum: 0