Przejdź do głównej zawartości

Automatyzacje

Automatyzacje w Sellrocket to skrypty automatyczne (AJS) — odpowiednik akcji automatycznych BaseLinkera. Reagują na zdarzenia w zamówieniach i zwrotach (np. nowe zamówienie, zmiana statusu, opłacenie) i wykonują akcje: zmieniają status, nadają przesyłkę, wysyłają e-mail, wywołują zewnętrzny adres. Z punktu widzenia integratora są ważne z dwóch powodów: możesz nimi zastąpić część logiki po swojej stronie oraz dostawać powiadomienia o zdarzeniach, wywołując z nich adres Twojej aplikacji.

  • Skrypt to kod JavaScript wykonywany po stronie Sellrocket, z nazwą, grupą (groupId), priorytetem (priority) i opcjonalnym opóźnieniem (delaySeconds). Skrypty grupuje się w grupy (np. „Wysyłka”, „Faktury”).
  • Skrypt nie musi być pisany ręcznie: w panelu jest kreator (wyzwalacz → warunki → akcje), który generuje skrypt. Pole type odróżnia skrypty pisane kodem (AutomaticScript) od zbudowanych w kreatorze (AutomaticAction).
  • Wyzwalacze — zdarzenia, m.in.: utworzenie zamówienia, zmiana statusu, opłacenie, utworzenie przesyłki, utworzenie zwrotu. Skrypt można też uruchomić ręcznie: z panelu, przez API albo przez zdarzenie użytkownika (przycisk, skrót klawiaturowy lub kod kreskowy w panelu).
  • Akcje — m.in.: zmiana statusu, edycja zamówienia, zmiana pól elastycznych, komentarz do zamówienia, utworzenie lub usunięcie przesyłki, wydruk dokumentu, wysłanie e-maila, wywołanie adresu URL, uruchomienie innego skryptu, podział zamówienia lub zestawów, utworzenie i zmiana zwrotu, wystawienie faktury.
  • Uruchomienie (run) — każde wykonanie skryptu jest zapisywane wraz z logami, czasem trwania i stanem.

Powiadomienia do Twojej aplikacji (akcja „Wywołaj URL”)

Dział zatytułowany „Powiadomienia do Twojej aplikacji (akcja „Wywołaj URL”)”

Akcja wywołania adresu URL wysyła żądanie GET pod wskazany adres. W adresie możesz użyć znaczników z danymi zamówienia w formacie {{order.*}}:

https://app.example.com/hooks/sellrocket?event=status-changed&order={{order.id}}

To najprostszy sposób na webhook: skrypt z wyzwalaczem „zmiana statusu” wywołuje Twój endpoint, a Twoja aplikacja pobiera szczegóły zamówienia z API. Akcja ma opcje ponawiania (useRetries) i przerwania skryptu przy błędzie (breakOnFail).

Szczegóły adresu (np. dostępne znaczniki) ustawiasz przy konfiguracji akcji w panelu. Inne sposoby śledzenia zmian opisuje Reagowanie na zmiany.

Serwis automatyzacji ma adres https://{instancja}-ajs-api.enterprise.sellrocket.pl.

  1. Pobierz skrypty i grupy

    Okno terminala
    curl "https://$SR_INSTANCE-ajs-api.enterprise.sellrocket.pl/api/v1/automaticScripts" \
    -H "Authorization: Bearer $SR_TOKEN"

    GET /api/v1/automaticScripts zwraca listę skryptów, GET /api/v1/automaticScripts/{id} — pełny skrypt z kodem, GET /api/groups — grupy.

  2. Utwórz lub zmień skrypt

    {
    "name": "Powiadom ERP o wysyłce",
    "groupId": 3,
    "priority": 10,
    "delaySeconds": 0,
    "body": "/* kod skryptu */"
    }

    POST /api/v3/automaticScripts tworzy skrypt, PATCH /api/v3/automaticScripts/{id} zmienia wybrane pola, PUT /api/v3/automaticScripts/{id} tworzy lub nadpisuje skrypt o podanym ID. Zapis jest asynchroniczny — dostajesz zadanie, którego stan sprawdzisz przez GET /api/jobs/get/{id} w serwisie automatyzacji.

    Obiekty i pola dostępne w kodzie skryptu zwraca GET /api/v3/dsl/getSupportedObjects.

  3. Uruchom skrypt dla zamówienia

    POST /api/v3/automaticScripts/start/{id} uruchamia skrypt dla wskazanego zamówienia (order.id, wymagane jest też pole context) niezależnie od jego wyzwalacza. Odpowiedź 202 Accepted zawiera identyfikator uruchomienia. Dla wielu zamówień użyj POST /api/v3/automaticScripts/start_batch, a postęp śledź przez GET /api/v3/runs/batchProgress/{id}.

    Jeśli w panelu skonfigurowano zdarzenie użytkownika (przycisk), możesz je wywołać z API OMS tak samo, jak użytkownik klikający przycisk:

    Okno terminala
    curl -X POST "https://$SR_INSTANCE-smerp-api.enterprise.sellrocket.pl/api/v3/UserEvents/12/Call" \
    -H "Authorization: Bearer $SR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "order": { "id": 204295 } }'

    Lista zdarzeń użytkownika: GET /api/v3/UserEvents/GetAll; wywołanie: POST /api/v3/UserEvents/{userEventId}/Call.

  4. Sprawdź wynik

POST /api/v1/automaticScripts/{id}/runAsHttpFunction (oraz wariant GET) uruchamia skrypt jak endpoint HTTP i przekazuje mu treść żądania (JSON). Dzięki temu zewnętrzny system może wywołać logikę zapisaną w Sellrocket — np. przyjąć powiadomienie i zaktualizować zamówienie — bez osobnego serwera po Twojej stronie. Wywołanie wymaga tokenu, jak każde żądanie do API.

  • Automatyzacje reagują też na zmiany z API. Zmiana statusu wykonana przez Twoją integrację uruchomi skrypty tak samo jak zmiana w panelu. Przy migracji lub korektach użyj nagłówka X-SR-ForceSilentChanges: true — zobacz Konwencje API.
  • Unikaj pętli. Skrypt, który zmienia status, może wyzwolić kolejny skrypt. Projektuj warunki tak, żeby łańcuch się kończył, a w swojej aplikacji nie odpowiadaj na webhook zmianą, która wywoła ten sam webhook.
  • Odpowiadaj szybko na wywołanie URL. Twój endpoint powinien od razu potwierdzić odbiór (limit to 20 s), a ciężką pracę wykonywać asynchronicznie. Zakładaj, że to samo powiadomienie może przyjść więcej niż raz (ponowienia) — przetwarzaj je idempotentnie.
  • Zapis skryptu jest asynchroniczny — po POST/PUT sprawdź zadanie, zanim uruchomisz skrypt.
  • Konfiguracja należy do sprzedawcy. Jeśli Twoja integracja zakłada istnienie konkretnych skryptów lub przycisków, opisz je w dokumentacji wdrożenia — administrator instancji może je zmienić lub wyłączyć.
BaseLinker Sellrocket
Akcje automatyczne Skrypty automatyczne (AJS) — /api/v3/automaticScripts
Akcja „Wywołaj adres URL” Akcja wywołania URL ze znacznikami {{order.*}}
Własne przyciski / makra Zdarzenia użytkownika — GET /api/v3/UserEvents/GetAll
runOrderMacroTrigger POST /api/v3/UserEvents/{userEventId}/Call, POST /api/v3/automaticScripts/start/{id}
Historia akcji dla zamówienia GET /api/v1/runs/history/{orderId}

Migracja akcji z BaseLinkera. Definicję akcji automatycznej z BaseLinkera (wyzwalacz, warunki, akcje) możesz przekonwertować na skrypt Sellrocket przez POST /api/v4/AjsAopsBuilder/ImportBeelConfig. Zanim zaczniesz, sprawdź, które wyzwalacze, warunki i akcje są obsługiwane: GET /api/v3/AjsAopsBuilder/ImportBeelConfig/ScopeCoverage/State.