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.
Jak to działa
Dział zatytułowany „Jak to działa”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ń.
Lista zamówień
Dział zatytułowany „Lista 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 |
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}Synchronizacja przyrostowa
Dział zatytułowany „Synchronizacja przyrostowa”Zamiast cyklicznie pobierać wszystkie zamówienia, pobieraj tylko to, co zmieniło się od ostatniej synchronizacji.
-
Zapamiętaj moment startu. Przed zapytaniem zapisz bieżący czas UTC — po udanej synchronizacji stanie się on nowym punktem odniesienia.
-
Zapytaj o zmiany z filtrem
StatusUpdatedFrom= czas poprzedniej synchronizacji minus kilka minut zapasu. Zapas chroni przed zgubieniem zmian zapisanych w trakcie poprzedniego przebiegu. -
Przejdź przez wszystkie strony (
Offset+=Limit, ażOffset >= total). -
Zapisz zamówienia idempotentnie — po
id. Przez zapas czasowy to samo zamówienie może przyjść dwa razy. -
Pobierz pełne dane tylko dla zmienionych zamówień (sekcja niżej), jeśli potrzebujesz płatności, przesyłek lub załączników.
-
Zapisz nowy czas synchronizacji dopiero, gdy wszystko się powiodło.
import os, time, requestsfrom 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 bazystarted = 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)const BASE = `https://${process.env.SR_INSTANCE}-smerp-api.enterprise.sellrocket.pl`const headers = { Authorization: `Bearer ${process.env.SR_TOKEN}` }
async function* changedOrders(since) { const limit = 200 for (let offset = 0; ; ) { const qs = new URLSearchParams({ StatusUpdatedFrom: since.toISOString(), Limit: limit, Offset: offset }) const res = await fetch(`${BASE}/api/v5/Orders?${qs}`, { headers }) if (res.status === 429) { await new Promise((r) => setTimeout(r, 60_000)); continue } if (!res.ok) throw new Error(`HTTP ${res.status}`) const page = await res.json() yield* page.list offset += limit if (offset >= page.total) break }}
const lastSync = await loadLastSync()const started = new Date()for await (const order of changedOrders(new Date(lastSync.getTime() - 5 * 60_000))) { await saveOrder(order) // upsert po order.id}await saveLastSync(started)Pełne dane zamówienia
Dział zatytułowany „Pełne dane zamówienia”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:
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]'Z polami elastycznymi
Dział zatytułowany „Z polami elastycznymi”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 }]Na co uważać
Dział zatytułowany „Na co uważać”- 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.
Odpowiedniki w BaseLinker
Dział zatytułowany „Odpowiedniki w BaseLinker”getOrders→GET /api/v5/Orders(nagłówki) lubGET /api/v5/Orders/Full(pełne dane, filtryidFrom,gteConfirmed,getUnconfirmedOrders).getOrdersByEmail,getOrdersByPhone→GET /api/v5/Orders/FullzfilterEmail/filterPhone.date_confirmed_from→PlatformDateConfirmedFrom;status_id→OrderStatus;order_source_id→SourceConnectionId(ID połączenia Sellrocket; ID źródła z BaseLinkera jest wexternalSourceId— zobacz Identyfikatory z BaseLinkera).extra_field_1/2→additionalField1/2;custom_extra_fields→elasticFields.

