Listează — Comenzi
Citiți datele din „Comenzi”. Rezultatul depinde de parametrii acestei operațiuni.
GET/api/v1/orders
- Autentificare
Bearer- Disponibil începând cu
- BASIC
- Permisiuni necesare
orders.order:read
Exemple de cod
Exemplu de cerere
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))
Exemplu de răspuns 200
{
"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"
}
}
Cum funcționează
- Colecția oferă rezumate de comenzi și filtre pentru număr, stare, starea plății și data creării.
- Lista și detaliile comenzilor includ delivery.dates. Datele YYYY-MM-DD sunt planificate și nu confirmă expedierea. Datele curente au prioritate; comenzile vechi folosesc estimarea salvată. Valorile șterse sau necunoscute sunt null. Detaliile includ și toate pozițiile și imaginile produselor.
- Obțineți identificatorii valizi ai stărilor din /api/v1/order-statuses.
- Starea comenzii și starea plății folosesc endpointuri PATCH și permisiuni separate.
- Schimbarea stării de plată înregistrate nu debitează un card și nu execută o rambursare printr-un furnizor de plăți.
Comandă · Totaluri
Sumele și cotele provin din comanda salvată, inclusiv corecturile pozițiilor. Datele istorice lipsă sunt null și nu sunt înlocuite cu taxele actuale din catalog. Sumele rămân șiruri zecimale.
Lista returnează rezumate. Obține GET /api/v1/orders/{order_id} pentru fiecare rezultat pentru a exporta detaliile financiare complete. Reîncercările GET sunt limitate și respectă Retry-After. Exportul după data creării nu sincronizează corecturile ulterioare.
Parametri
Parametri de interogare
limitNumăr întregOpționalNumărul maxim de înregistrări pe această pagină.
minimum:1maximum:100cursorȘir de caractere nullOpționalValoare opacă de continuare returnată de pagina anterioară.
Șir de caractere:minLength:1maxLength:1024numberȘir de caractere nullOpționalNumărul comenzii sau al solicitării, destinat utilizatorilor.
Șir de caractere:minLength:1maxLength:48status_idȘir de caractere nullOpționalIdentificator obținut din dicționarul de stări corespunzător.
Restricții · Șir de caractere 1
pattern"^[a-z0-9][a-z0-9_-]{0,62}$"
payment_statusȘir de caractere nullOpționalStarea de plată înregistrată.
Restricții · Șir de caractere 1
enum["unpaid", "paid", "failed", "refunded"]
created_fromȘir de caractere nullOpționalÎnceputul intervalului de filtrare după momentul creării.
Șir de caractere:format:"date-time"created_toȘir de caractere nullOpționalSfârșitul intervalului de filtrare după momentul creării.
Șir de caractere:format:"date-time"
Această operație nu acceptă un corp JSON.
Răspunsuri
Răspuns 200
Model complet: ApiResponse_list_OrderSummaryData__
dataTablou <OrderSummaryData> ObligatoriuDatele unui răspuns reușit.
Câmpuri ·
dataModel complet:
OrderSummaryDatacreated_atȘir de caractereObligatoriuMomentul creării.
format:"date-time"customerCustomerDataObligatoriuDatele clientului înregistrate pentru această resursă.
deliveryShippingDataObligatoriuMetoda de livrare și informațiile asociate.
discount_amountMoneyDataObligatoriuSumă zecimală codificată ca șir JSON; null numai unde este permis.
idȘir de caractereObligatoriuIdentificatorul resursei; păstrați-l în forma returnată.
lifecycle_stateOrderLifecycleStateObligatoriuStarea din ciclul de viață comercial.
localeȘir de caractereObligatoriuLimba selectată pentru această cerere.
market_idȘir de caractereObligatoriuIdentificatorul pieței returnat de endpointul de context.
numberȘir de caractereObligatoriuNumărul comenzii sau al solicitării, destinat utilizatorilor.
paymentPaymentDataObligatoriuDetaliile de plată înregistrate pentru comandă.
prices_include_taxValoare booleanăObligatoriuIndică dacă prețurile afișate includ taxele.
shipping_discount_amountMoneyDataObligatoriuSumă zecimală codificată ca șir JSON; null numai unde este permis.
statusOrderStatusDataObligatoriuStarea acceptată de această operație specifică.
subtotalMoneyDataObligatoriuSuma înainte de componentele suplimentare prezentate în răspuns.
taxMoneyDataObligatoriuInformații despre taxe.
tax_country_codeȘir de caractere nullObligatoriuȚară fiscală · Datele salvate ale comenzii · ISO 3166-1 alpha-2; null.
totalMoneyDataObligatoriuSuma totală.
metaContextPageMetaContextMetaPageMetaRequestMetaObligatoriuMetadatele răspunsului.
Câmpuri ·
metaModel complet:
ContextPageMetalocaleȘir de caractereObligatoriuLimba selectată pentru această cerere.
market_codeȘir de caractereObligatoriuCodul pieței returnat de endpointul de context.
market_idȘir de caractereObligatoriuIdentificatorul pieței returnat de endpointul de context.
paginationPaginationObligatoriuMetadatele paginării prin cursor.
request_idȘir de caractereObligatoriuIdentificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.
minLength:1maxLength:100
localeȘir de caractereObligatoriuLimba selectată pentru această cerere.
market_codeȘir de caractereObligatoriuCodul pieței returnat de endpointul de context.
market_idȘir de caractereObligatoriuIdentificatorul pieței returnat de endpointul de context.
request_idȘir de caractereObligatoriuIdentificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.
minLength:1maxLength:100
paginationPaginationObligatoriuMetadatele paginării prin cursor.
request_idȘir de caractereObligatoriuIdentificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.
minLength:1maxLength:100
request_idȘir de caractereObligatoriuIdentificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.
minLength:1maxLength:100
Stare HTTP
200- Răspuns reușit Schemă
400- Cerere nevalidă
401- Autentificare necesară
403- Acces refuzat
404- Resursa nu a fost găsită
409- Conflict de versiune
422- Validare eșuată
429- Limită de cereri depășită
Alte stări HTTP (7)
405- Metodă nepermisă
413- Cerere prea mare
415- Format neacceptat
500- Eroare de server
502- Eroare de gateway API
503- Serviciu indisponibil
504- Timp de așteptare depășit
Catalog de erori: ErrorResponse
Antete
401
WWW-AuthenticateȘir de caractereOpționalSchema de autentificare cerută de server.
405
AllowȘir de caractereOpționalMetodele HTTP acceptate de această resursă.
429, 503
Retry-AfterNumăr întregOpționalÎntârzierea minimă înainte de reîncercare, în secunde.
minimum:0