Przejdź do głównej zawartości

Pobieranie zamówień

Pobieranie zamówień to podstawa większości integracji: ERP, WMS, systemu księgowego czy hurtowni danych. W Sellrocket zamówienia odczytujesz z serwisu OMS (https://{instancja}-smerp-api.enterprise.sellrocket.pl). Lista zwraca nagłówki z pozycjami, a pełne dane (płatności, przesyłki, załączniki, pola elastyczne) pobierasz osobnymi, masowymi wywołaniami.

Zamówienie (Order) składa się z:

Część Pola Uwagi
Nagłówek id, status (id, from), platformDateAddedUtc, platformDateConfirmedUtc, buyerComments, sellerComments, currency id to identyfikator w Sellrocket
Źródło source.connectionId, source.connectionType, source.platformOrderId, externalSourceType, externalSourceId Połączenie (kanał sprzedaży), numer zamówienia w systemie źródłowym oraz zewnętrzny typ i ID źródła (np. z BaseLinkera) — zobacz Identyfikatory z BaseLinkera
Kupujący buyer (e-mail, login, nazwa, firma, NIP, telefon, adres)
Odbiorca i dostawa delivery.recipient, delivery.pickupPoint, delivery.method, delivery.cost, delivery.isCod Punkt odbioru (paczkomat itp.) ma kod, nazwę i adres
Dane do faktury invoice.required, invoice.payer Płatnik może się różnić od kupującego
Pozycje lineItems[] — produkt (name, code, ean), quantity, price.unitPrice (brutto), tax
Płatności payments.paymentStatus (Unpaid, Paid, Incorrect), payments.payments[] Tylko w pełnych danych
Przesyłki shipments[] — kurier, numer śledzenia, status Tylko w pełnych danych, zobacz Przesyłki
Załączniki attachments[] — faktury, paragony, inne pliki Tylko w pełnych danych
Oznaczenia asteriskMarked, asteriskKindId (+ kolor i ikona) Odpowiednik gwiazdki z BaseLinkera
Pola dodatkowe additionalField1, additionalField2 Dwa stałe pola tekstowe
Pola elastyczne elasticFields[] Dowolne pola definiowane per instancja — zobacz Pola dodatkowe zamówień

Statusy są definiowane w każdej instancji osobno — zobacz Statusy zamówień.

GET /api/v5/Orders zwraca stronę nagłówków { list, pageNumber, total }. Najważniejsze filtry:

Parametr Znaczenie
CreatedFrom, CreatedTo Data utworzenia zamówienia w Sellrocket
StatusUpdatedFrom, StatusUpdatedTo Data ostatniej zmiany statusu
PlatformDateConfirmedFrom, PlatformDateConfirmedTo Data potwierdzenia w systemie źródłowym
OrderStatus ID statusu
SourceConnectionId ID połączenia (kanału sprzedaży)
OrderId ID w Sellrocket lub w systemie źródłowym, kilka wartości po przecinku
Limit, Offset Stronicowanie (Limit 1–1000), zobacz Konwencje API
Okno terminala
curl "https://$SR_INSTANCE-smerp-api.enterprise.sellrocket.pl/api/v5/Orders?OrderStatus=1&SourceConnectionId=12&Limit=100&Offset=0" \
-H "Authorization: Bearer $SR_TOKEN"
{
"list": [
{
"id": 204295,
"source": { "connectionId": 12, "platformOrderId": "WEB-100231" },
"status": { "id": 1, "from": "2026-10-05T08:15:00Z" },
"platformDateAddedUtc": "2026-10-05T08:12:00Z",
"buyer": { "email": "klient@example.com", "fullName": "Klient Przykładowy" },
"delivery": {
"method": { "platformName": "Kurier DPD" },
"cost": { "currency": "PLN", "amount": 14.99 },
"isCod": false
},
"lineItems": [
{
"id": 991,
"product": { "name": "Kubek ceramiczny 300 ml", "code": "KUB-300", "ean": "5901234123457" },
"quantity": 2,
"price": { "currency": "PLN", "unitPrice": 39.9 }
}
],
"summary": { "totalToPay": { "currency": "PLN", "amount": 94.79 } },
"additionalField1": null,
"asteriskMarked": false
}
],
"pageNumber": 0,
"total": 1
}

Zamiast cyklicznie pobierać wszystkie zamówienia, pobieraj tylko to, co zmieniło się od ostatniej synchronizacji.

  1. Zapamiętaj moment startu. Przed zapytaniem zapisz bieżący czas UTC — po udanej synchronizacji stanie się on nowym punktem odniesienia.

  2. Zapytaj o zmiany z filtrem StatusUpdatedFrom = czas poprzedniej synchronizacji minus kilka minut zapasu. Zapas chroni przed zgubieniem zmian zapisanych w trakcie poprzedniego przebiegu.

  3. Przejdź przez wszystkie strony (Offset += Limit, aż Offset >= total).

  4. Zapisz zamówienia idempotentnie — po id. Przez zapas czasowy to samo zamówienie może przyjść dwa razy.

  5. Pobierz pełne dane tylko dla zmienionych zamówień (sekcja niżej), jeśli potrzebujesz płatności, przesyłek lub załączników.

  6. Zapisz nowy czas synchronizacji dopiero, gdy wszystko się powiodło.

import os, time, requests
from datetime import datetime, timedelta, timezone
BASE = f"https://{os.environ['SR_INSTANCE']}-smerp-api.enterprise.sellrocket.pl"
HEADERS = {"Authorization": f"Bearer {os.environ['SR_TOKEN']}"}
def changed_orders(since):
offset, limit = 0, 200
while True:
r = requests.get(f"{BASE}/api/v5/Orders", headers=HEADERS, params={
"StatusUpdatedFrom": since.strftime("%Y-%m-%dT%H:%M:%SZ"),
"Limit": limit, "Offset": offset,
})
if r.status_code == 429: # limit zapytań — odczekaj i ponów
time.sleep(60)
continue
r.raise_for_status()
page = r.json()
yield from page["list"]
offset += limit
if offset >= page["total"]:
break
last_sync = load_last_sync() # Twoja funkcja, np. odczyt z bazy
started = datetime.now(timezone.utc)
for order in changed_orders(last_sync - timedelta(minutes=5)):
save_order(order) # upsert po order["id"]
save_last_sync(started)

Nagłówki z listy nie zawierają płatności, przesyłek ani załączników. Do pobrania kompletu masz kilka endpointów:

Potrzeba Endpoint
Jedno zamówienie (z płatnościami, przesyłkami, załącznikami) GET /api/v5/Orders/{orderId}
Wiele zamówień po ID — jedno wywołanie na stronę listy POST /api/v3/Orders/byIds — treść: tablica ID; opcje includePayments, withOrderEf, withLineItemEf
Zamówienie po numerze z systemu źródłowego GET /api/v5/Orders/{platformConnectionId}/{orderId}
Wiele zamówień po numerach źródłowych POST /api/v3/Orders/bySourceOrderIds
Pełne zamówienia stronicowane, filtry w stylu getOrders (idFrom, gteConfirmed, getUnconfirmedOrders) GET /api/v5/Orders/Full

Przykład — pełne dane trzech zamówień z płatnościami i polami elastycznymi:

Okno terminala
curl -X POST "https://$SR_INSTANCE-smerp-api.enterprise.sellrocket.pl/api/v3/Orders/byIds?includePayments=true&withOrderEf=true" \
-H "Authorization: Bearer $SR_TOKEN" \
-H "Content-Type: application/json" \
-d '[204295, 204296, 204301]'

Pojedyncze zamówienie razem z polami elastycznymi zamówienia i pozycji zwraca GET /api/v3/Orders/with-elastic-fields/{orderId} (parametry includeOrderElasticFields, includeLineItemElasticFields). Na liście możesz dołączyć pola elastyczne pozycji parametrem IncludeLineItemsElasticFields=true.

"elasticFields": [
{ "fieldName": "erp_document", "fieldType": "text", "fieldValue": "WZ/2026/10/0042", "objectId": 204295 }
]
  • Nie pobieraj pełnych danych pojedynczo dla każdego zamówienia z listy — użyj byIds, żeby zmieścić się w limicie zapytań.
  • Daty zawsze w UTC (ISO 8601). Przekazuj je z sufiksem Z.
  • Kolejność na liście może się zmienić w trakcie stronicowania, jeśli zamówienia zmieniają się w tym czasie. Zapas czasowy i idempotentny zapis rozwiązują problem.
  • Nie zakładaj stałych ID statusów i połączeń — pobierz je z instancji (GET /api/v3/Statuses, GET /api/v3/Connections).
  • Ceny pozycji (unitPrice) są brutto.
  • getOrders → GET /api/v5/Orders (nagłówki) lub GET /api/v5/Orders/Full (pełne dane, filtry idFrom, gteConfirmed, getUnconfirmedOrders).
  • getOrdersByEmail, getOrdersByPhone → GET /api/v5/Orders/Full z filterEmail / filterPhone.
  • date_confirmed_from → PlatformDateConfirmedFrom; status_id → OrderStatus; order_source_id → SourceConnectionId (ID połączenia Sellrocket; ID źródła z BaseLinkera jest w externalSourceId — zobacz Identyfikatory z BaseLinkera).
  • extra_field_1/2 → additionalField1/2; custom_extra_fields → elasticFields.