Ritevo documentation. Short map of the product: https://ritevo.com/llms.txt Updated: 2026-10-18 # Pomoc (pl) Poradniki krok po kroku: podłączanie integracji, akcje automatyczne, zamówienia, wiadomości i API. Source: https://ritevo.com/pl/docs/orders/fetching-orders (updated 2026-10-10) ## Pobieranie zamówień Jak Ritevo pobiera zamówienia z marketplace'ów i sklepów, jak często to robi i co zrobić, gdy zamówienia nie widać. Ritevo samo sprawdza Twoje kanały sprzedaży i dopisuje nowe zamówienia do listy. Nie musisz nic importować ani odświeżać. > **Wymagana integracja:** Potrzebujesz co najmniej jednej integracji typu **marketplace** (np. Allegro) albo **sklep internetowy** (np. Shoper). E-mail i komunikatory to kanały wiadomości, zamówień z nich nie pobieramy. ### Włączanie i wyłączanie pobierania Pobieranie zamówień ustawiasz **osobno dla każdej integracji**. Po dodaniu nowej integracji jest ono **wyłączone** - dopóki go nie włączysz, z tego kanału nie pobieramy zamówień. Żeby je włączyć: 1. Wejdź w **Integracje** i otwórz integrację, z której chcesz pobierać zamówienia. 2. Włącz przełącznik **Pobieranie zamówień**. 3. Zapisz zmiany. ![Przełącznik „Pobieranie zamówień" w ustawieniach integracji](https://ritevo.com/docs/orders/pl-fetch-orders-toggle.webp) Od tej chwili sprawdzamy ten kanał mniej więcej co 10 minut. Pobieranie wyłączysz w każdej chwili tym samym przełącznikiem. Zamówienia pobrane wcześniej zostają w Ritevo, przestają tylko dochodzić nowe z tej integracji. ### Jak często sprawdzamy zamówienia Każdą integrację sprawdzamy mniej więcej **co 10 minut**. Nowe zamówienie zobaczysz więc na liście najpóźniej kilkanaście minut po jego złożeniu. Przy pierwszym pobraniu sięgamy **7 dni wstecz**, żeby lista nie startowała pusta. Starszych zamówień nie pobieramy. ### Gdzie zobaczysz pobrane zamówienie Pobrane zamówienie od razu pojawia się w **tabeli zamówień**. Stamtąd je otwierasz i dalej prowadzisz w Ritevo. > **Warto wiedzieć:** Wszystkie ceny, które widzisz w Ritevo - w zamówieniach, fakturach, paragonach i korektach - to ceny brutto. Wyjątkiem są produkty w magazynach, których ceny podajemy netto. Cenę netto liczymy z ceny brutto i stawki VAT: netto = brutto ÷ (1 + stawka VAT). Na przykład 123 zł brutto przy stawce 23% to 100 zł netto. ### Usługi dodatkowe Część kanałów przekazuje usługi, które kupujący dokupił do zamówienia, na przykład pakowanie na prezent, wniesienie czy montaż. Każda usługa pojawia się jako osobna pozycja zamówienia - także gdy kosztuje 0,00 - więc widzisz ją przy obsłudze zamówienia i masz ją na fakturze. - **Usługa przy produkcie** - zamiast zdjęcia ma ikonkę usługi i podpis **Usługa dodatkowa**, a produkt, z którym ją kupiono, ma znaczek z jej nazwą. - **Usługa do całego zamówienia** - dotyczy całej paczki, a nie jednego produktu, i ma podpis **Usługa do całego zamówienia**. - **Asystent pakowania** - usług nie pakujesz jako sztuk; widzisz je jako znaczki przy produkcie albo w osobnej karcie nad listą pozycji. Gdy kanał nie przekazuje usług, możesz wystawić usługę jako osobną ofertę albo produkt, na przykład **Pakowanie na prezent**. Przyjdzie wtedy jako zwykła pozycja zamówienia - Ritevo nie oznaczy jej jako usługi, bo dostaje ją tak samo jak każdy produkt. Czy dany kanał przekazuje usługi i które, sprawdzisz na stronie jego integracji, w części o zamówieniach. Usługa to pozycja z `lineItems[].additionalService.additionalService` = `true`. Pole `additionalService.forLineItemId` wskazuje `id` pozycji produktu, z którym ją kupiono; `null` oznacza usługę do całego zamówienia. Zwykła pozycja ma `additionalService` = `false` i `forLineItemId` = `null`. ### Kto zarządza zamówieniem po pobraniu To zależy od statusu zamówienia w Ritevo. **Zamówienie jeszcze niepotwierdzone** (na przykład **Ocz. na płatność** albo **Ocz. na potwierdzenie**): jeśli w kanale sprzedaży coś się zmieni, na przykład klient opłaci zamówienie, Ritevo zaktualizuje je przy kolejnym sprawdzeniu. Nie powstaje drugie zamówienie. **Zamówienie w statusie Potwierdzono**: od tej chwili zamówieniem zarządza Ritevo. Kolejne zmiany przychodzące z kanału sprzedaży **pomijamy**, żeby nie nadpisywały tego, co masz ustawione u siebie. Pomijamy między innymi: - zmianę statusu zamówienia po stronie kanału sprzedaży, - zmianę danych do faktury po stronie kanału sprzedaży, - list przewozowy wygenerowany po stronie kanału sprzedaży. Wszystko to prowadzisz już w Ritevo i to dane z Ritevo są obowiązujące. > **Warto wiedzieć:** Zamówienie, które przyszło do Ritevo od razu jako **Potwierdzono**, jest chronione w ten sam sposób od pierwszej chwili. ### Zamówienia pojawiają się mimo wyłączonego pobierania To nie błąd. Dzieje się tak, gdy dla integracji masz włączone [pobieranie wiadomości](https://ritevo.com/pl/docs/messages/fetching-messages). W części integracji wiadomość, dyskusja albo reklamacja odnosi się do konkretnego zamówienia. Gdy taka wiadomość przyjdzie, Ritevo **samo dociąga to jedno zamówienie**, żebyś przy rozmowie z klientem od razu widział, czego ona dotyczy. Dociągamy wtedy tylko zamówienia powiązane z wiadomościami. Pozostałe zamówienia z tego kanału nadal nie są pobierane, dopóki nie włączysz **Pobieranie zamówień**. ### Nie widzę zamówienia > **Warto wiedzieć:** Najczęstsza przyczyna: integracja pokazuje **Wymaga ponownego połączenia**. Zwykle oznacza to, że dostęp, którego udzieliłeś Ritevo w kanale sprzedaży, wygasł albo został cofnięty - na przykład po zmianie hasła lub po upływie ważności połączenia. Dopóki nie połączysz integracji ponownie, zamówienia z tego kanału nie są pobierane. Sprawdź po kolei: 1. Czy integracja jest **Aktywna**. 2. Czy ma włączone **Pobieranie zamówień** - po dodaniu integracji jest ono domyślnie wyłączone. 3. Czy minęło już kilkanaście minut od złożenia zamówienia. 4. Czy zamówienie nie jest starsze niż 7 dni sprzed dodania integracji. ### Statusy zamówienia i płatności przez API Status zamówienia (`status`) przyjmuje jedną z wartości: - **Potwierdzono** (API: "Potwierdzono" = `CONFIRMED`; wartość w `status`) - zamówienie przejęte przez Ritevo. - **Anulowano** (API: "Anulowano" = `CANCELLED`; wartość w `status`) - zamówienie anulowane. - **Ocz. na płatność** (API: "Ocz. na płatność" = `WAITING_FOR_PAYMENT`; wartość w `status`) - czeka na wpłatę. - **Ocz. na potwierdzenie** (API: "Ocz. na potwierdzenie" = `WAITING_FOR_CONFIRMATION`; wartość w `status`) - czeka na Twoją decyzję; tu trafia też status sklepu bez mapowania. Status płatności (`payment.paymentStatus`) jest osobny i Ritevo liczy go z kwot: brak kwoty zapłaconej (`paidAmount` = `null`) daje `WAITING_FOR_PAYMENT`; kwota równa sumie zamówienia daje `PAID`, wyższa `OVERPAID`, niższa `UNDERPAID`. Kwota `0.00` to wpłata zero, a nie brak wpłaty - przy niezerowej sumie daje `UNDERPAID`, przy sumie zero `PAID`. --- Source: https://ritevo.com/pl/docs/messages/fetching-messages (updated 2026-09-27) ## Pobieranie wiadomości Jak Ritevo pobiera wiadomości, dyskusje i reklamacje z kanałów sprzedaży, poczty i komunikatorów, jak często to robi i co zrobić, gdy wiadomości nie widać. Ritevo zbiera wiadomości od klientów ze wszystkich podłączonych kanałów w jednej skrzynce. Ta strona opisuje zasady wspólne dla każdej integracji - niezależnie od tego, czy to marketplace, sklep, poczta e-mail czy komunikator. > **Wymagana integracja:** Potrzebujesz co najmniej jednej integracji, która obsługuje wiadomości: **marketplace** (np. Allegro), **sklepu internetowego**, **poczty e-mail** albo **komunikatora** (np. Messenger). Nie każda integracja ma wiadomości - jeśli ich nie obsługuje, w jej ustawieniach nie ma przełącznika **Pobieranie wiadomości**. ### Włączanie i wyłączanie pobierania Pobieranie wiadomości ustawiasz **osobno dla każdej integracji**. Po dodaniu nowej integracji jest ono **wyłączone** - dopóki go nie włączysz, z tego kanału nie pobieramy wiadomości. Żeby je włączyć: 1. Wejdź w **Integracje** i otwórz integrację, z której chcesz pobierać wiadomości. 2. Włącz przełącznik **Pobieranie wiadomości**. 3. Zapisz zmiany. ![Przełącznik „Pobieranie wiadomości" w ustawieniach integracji](https://ritevo.com/docs/messages/pl-fetch-messages-toggle.webp) Pobieranie wyłączysz w każdej chwili tym samym przełącznikiem. Wiadomości pobrane wcześniej zostają w Ritevo, przestają tylko dochodzić nowe z tej integracji. Pobieranie wiadomości i [pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders) to dwa niezależne przełączniki. Możesz mieć włączone jedno, drugie albo oba. ### Jak często sprawdzamy wiadomości - **Marketplace'y, sklepy i poczta e-mail**: każdą integrację sprawdzamy mniej więcej **co 10 minut**. - **Komunikatory** (Messenger, WhatsApp): wiadomość trafia do Ritevo **od razu**, gdy klient ją wyśle. ### Co pobieramy Każdy wątek w Ritevo ma jeden z trzech typów: - **Wiadomość** (API: "Wiadomość" = `MESSAGE`; wartość w `threadType`) - zwykła rozmowa z klientem. Obsługuje ją każda integracja z wiadomościami. - **Dyskusja** (API: "Dyskusja" = `DISCUSSION`; wartość w `threadType`) - spór otwarty przez klienta w kanale sprzedaży. - **Reklamacja** (API: "Reklamacja" = `CLAIM`; wartość w `threadType`) - zgłoszenie reklamacyjne z kanału sprzedaży. Dyskusje i reklamacje pobieramy tylko z tych kanałów sprzedaży, które same je prowadzą. Poczta e-mail i komunikatory mają wyłącznie wiadomości. Które typy obsługuje konkretna integracja, przeczytasz na jej stronie. ### Gdzie zobaczysz pobrane wiadomości Wszystkie wątki trafiają do wspólnej skrzynki w zakładce **Wiadomości**. Przy każdym widać, z której integracji pochodzi i jakiego jest typu. ### Wiadomość a zamówienie W części integracji wiadomość, dyskusja albo reklamacja odnosi się do konkretnego zamówienia. Ritevo łączy wtedy wątek z tym zamówieniem, żebyś od razu widział, czego dotyczy rozmowa. > **Warto wiedzieć:** Jeśli takiego zamówienia nie ma jeszcze w Ritevo, **samo je dociągamy** - także wtedy, gdy pobieranie zamówień dla tej integracji jest wyłączone. Dociągamy tylko to jedno, powiązane zamówienie. Więcej w [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders#linked-orders). ### Nie widzę wiadomości > **Warto wiedzieć:** Najczęstsza przyczyna: integracja pokazuje **Wymaga ponownego połączenia**. Zwykle oznacza to, że dostęp, którego udzieliłeś Ritevo w tym kanale, wygasł albo został cofnięty - na przykład po zmianie hasła lub po upływie ważności połączenia. Dopóki nie połączysz integracji ponownie, wiadomości z tego kanału nie są pobierane. Sprawdź po kolei: 1. Czy integracja jest **Aktywna**. 2. Czy ma włączone **Pobieranie wiadomości** - po dodaniu integracji jest ono domyślnie wyłączone. 3. Czy ta integracja w ogóle obsługuje wiadomości - jeśli nie, przełącznika nie ma. 4. Czy minęło już kilkanaście minut od wysłania wiadomości (nie dotyczy komunikatorów). ### Typy i statusy wątków przez API Dyskusje i reklamacje mają dodatkowo status (`threadStatus`): - **Trwa**, **Zamknięta**, **Nierozwiązana** (API: "Trwa" = `DISPUTE_ONGOING`, "Zamknięta" = `DISPUTE_CLOSED`, "Nierozwiązana" = `DISPUTE_UNRESOLVED`; wartość w `threadStatus`) - statusy dyskusji. - **Złożona**, **Zaakceptowana**, **Odrzucona** (API: "Złożona" = `CLAIM_SUBMITTED`, "Zaakceptowana" = `CLAIM_ACCEPTED`, "Odrzucona" = `CLAIM_REJECTED`; wartość w `threadStatus`) - statusy reklamacji. Co potrafi każdy kanał (odpowiadanie, załączniki, limit znaków), zwraca `GET /integrations/messages/capabilities`. Aktualny kształt odpowiedzi jest w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/products/fetching-products (updated 2026-09-29) ## Pobieranie produktów Jak Ritevo pobiera produkty, ceny i stany z hurtowni, jak często, co dzieje się z usuniętymi produktami, kilka magazynów i reguły cen. Produkty trafiają do Ritevo z integracji z kategorii **Magazyny i hurtownie**: z hurtowni pobieramy je automatycznie, a do własnego magazynu dodajesz je sam. Wszystkie widzisz w jednym miejscu, z ceną i stanem. > **Wymagana integracja:** Potrzebujesz integracji z kategorii **Magazyny i hurtownie** - na przykład [Hurtowni Karm](https://ritevo.com/pl/docs/integrations/hurtownia-karm) albo [Własnego magazynu](https://ritevo.com/pl/docs/integrations/own-warehouse). ### Gdzie są produkty Wszystkie produkty są w menu **Produkty**. Lista pokazuje nazwę, producenta, cenę, stan, SKU i integrację, z której pochodzi produkt. Stan to suma wszystkich stanów produktu. Filtrujesz po integracji, nazwie, SKU, EAN, producencie, kategorii, cenie, stanie i po tym, czy produkt jest usunięty. ### Skąd biorą się produkty - **Hurtownia** - produkty, ceny i stany pobieramy z oferty hurtowni według ustawionego interwału. - **Własny magazyn** - produkty dodajesz sam przyciskiem **Dodaj produkt**, a cenę i stan wpisujesz w produkcie. ### Jak często pobieramy produkty Dla każdej hurtowni sam wybierasz w polu **Interwał synchronizacji** na stronie integracji, jak często pobieramy jej ofertę: - **Nigdy** (API: "Nigdy" = `NEVER`; wartość w `syncInterval`) - oferta pobiera się tylko raz, zaraz po dodaniu integracji. Domyślnie. - **LIVE** (API: "LIVE" = `LIVE`; wartość w `syncInterval`) - co godzinę. - **Co 2 godziny** (API: "Co 2 godziny" = `EVERY_2H`; wartość w `syncInterval`) - co dwie godziny. - **Co 6 godzin** (API: "Co 6 godzin" = `EVERY_6H`; wartość w `syncInterval`) - co sześć godzin. > **Warto wiedzieć:** Przy każdym pobraniu najpierw aktualizujemy produkty, a zaraz po nich ceny i stany. Własny magazyn niczego nie pobiera - zmienia się tylko wtedy, gdy sam coś zmienisz. ### Co jest w produkcie - **Dane podstawowe** - nazwa, SKU, EAN i dodatkowe EAN-y, opis, zdjęcia, producent, kategoria, waga i wymiary. - **Cena** - kwota netto, stawka VAT i waluta. Każdy produkt ma jedną cenę. - **Stan** - ilość w danym magazynie. Produkt może mieć kilka stanów, na przykład stan z hurtowni i Twój własny. - **Status** - przełączniki **Aktywny** i **Usunięty**. > **Warto wiedzieć:** Ceny produktów w magazynach są netto. Reguły cenowe też działają na cenę netto. Wszystkie pozostałe ceny w Ritevo, na przykład w zamówieniach, fakturach i paragonach, są brutto. ### Kilka magazynów i hurtowni Możesz mieć wiele integracji magazynowych naraz, także kilka własnych magazynów. Każdy produkt należy do jednej integracji - ten sam SKU albo EAN w dwóch magazynach to dwa osobne produkty, które nie są łączone. Z której integracji jest produkt, widzisz w kolumnie **Integracja** i w filtrze **Integracja**. ### Kiedy produkt jest usunięty - **Produkt zniknął z hurtowni** - przy najbliższym pobraniu oznaczamy go jako usunięty, a jego stan z hurtowni spada do 0. Jeśli wróci do oferty, przy kolejnym pobraniu znów będzie aktywny. - **Usuwasz produkt z hurtowni sam** - przełącznik **Usunięty** zadziała tylko do najbliższego pobrania, bo wtedy hurtownia znów nadpisze produkt. - **Usuwasz produkt z własnego magazynu** - włącz **Usunięty** w produkcie. Przywracasz go, wyłączając przełącznik. - **Na liście** - usunięte produkty nadal widać na liście **Produkty**. Ukryjesz je filtrem **Produkt usunięty**. ### Zmiany w produktach z hurtowni Produkt z hurtowni możesz edytować, ale przy najbliższym pobraniu hurtownia nadpisze nazwę, opis, cenę, EAN, wymiary i inne pola. Zostają tylko stany, które dodałeś sam przyciskiem **Dodaj stan**. Stany z hurtowni za każdym razem wracają do wartości od dostawcy. > **Warto wiedzieć:** W produkcie z hurtowni zobaczysz ostrzeżenie **Produkt pochodzi od zewnętrznego dostawcy**. Stałą zmianę ceny albo stanu dla całej hurtowni ustawisz regułami transformacji - opis niżej. ### Reguły cen i stanów Na stronie każdej integracji magazynowej są **Reguły transformacji**: osobno **Reguły cenowe** i **Reguły stanu**. Działają na każdą cenę i każdy stan tej integracji - pobrane z hurtowni i wpisane przez Ciebie. Każda reguła ma zakres **Wartość od** i **Wartość do**, **Operację** i **Operand**. Operacje: - **Mnożnik** (API: "Mnożnik" = `MULTIPLY`; wartość w `operation`) - mnoży wartość przez operand, na przykład 1.3 doliczy 30% marży. - **Dodaj** (API: "Dodaj" = `ADD`; wartość w `operation`) - dodaje operand do wartości. - **Odejmij** (API: "Odejmij" = `SUBTRACT`; wartość w `operation`) - odejmuje operand od wartości. - **Ustaw na** (API: "Ustaw na" = `SET_TO`; wartość w `operation`) - zastępuje wartość operandem, na przykład stan ustawia na 0. Reguły są sprawdzane po kolei od góry - zastosowana zostaje pierwsza, której zakres pasuje do wartości. Każda lista mieści maksymalnie 20 reguł, a dodajesz je przyciskiem **Dodaj regułę**. > **Warto wiedzieć:** Przykład: reguła cenowa od 0 do 100 z operacją **Mnożnik** i operandem 1.5 podnosi ceny tanich produktów o połowę, a następna, od 100 do 100000 z operandem 1.2, droższe o 20%. ### Produkty a zamówienia - **Powiązanie** - pozycji zamówienia nie łączymy z produktem automatycznie. W szczegółach zamówienia kliknij **Powiąż ofertę z produktem** i wybierz produkt. Powiązanie zostaje dla tej oferty także w kolejnych zamówieniach z tej samej integracji. - **Asystent pakowania** - korzysta z powiązanych produktów i porównuje skanowany kod z ich EAN-em. Pozycja bez powiązania ma oznaczenie **Brak powiązania z magazynem**. - **Stany** - sprzedaż nie zmienia stanów w Ritevo: nic nie jest zdejmowane ani rezerwowane. ### Usunięcie integracji magazynowej Usunięcie integracji zatrzymuje pobieranie, ale jej produkty, ceny i stany zostają na liście **Produkty**. Po przywróceniu integracji pobieranie rusza przy najbliższym terminie. ### Czego jeszcze nie ma - Nie łączy tych samych produktów z różnych magazynów w jeden. - Nie importuje produktów z pliku - produkty do własnego magazynu dodajesz w aplikacji albo przez API. - Nie zdejmuje ani nie rezerwuje stanów po sprzedaży. - Nie wysyła produktów do kanałów sprzedaży. ### Produkty przez API Lista: `GET /integrations/warehouses/products` (strona do 5000 pozycji), jeden produkt: `GET /integrations/warehouses/products/{id}`. Zapis jest asynchroniczny (202) i przyjmuje do 1000 pozycji w zapytaniu: `PUT /integrations/warehouses/{integrationId}/products` (pola `externalId`, `sku`, `name`, `description`, `ean`, `additionalEans`, `images`, `manufacturer`, `category`, `weight`, `width`, `height`, `length`, `active`, `deleted`, `price`), `PUT .../products/prices` (`productId`, `amount`, `currency`, `vatRate`) i `PUT .../products/stocks` (`productId`, `externalId`, `warehouse`, `quantity`, `deleted`). Produkt z tym samym `externalId` w danej integracji jest aktualizowany zamiast tworzony. W odpowiedzi `original` = `true` oznacza dane od dostawcy, `false` - zmienione ręcznie. Powiązania ofert z produktami: `GET` i `DELETE /integrations/warehouses/external-offer-assignments`, a powiązanie tworzysz przez `POST /orders/{orderId}/line-items/{lineItemId}/warehouse-link`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. Integracja hurtowni ma `syncInterval` = `NEVER`, `LIVE` (co godzinę), `EVERY_2H` albo `EVERY_6H`. `transformationRules` to `priceRules` i `stockRules` - listy do 20 obiektów `valueFrom`, `valueTo`, `operation` (`MULTIPLY`, `ADD`, `SUBTRACT`, `SET_TO`) i `operand`. Pierwsza reguła, której zakres pasuje, wygrywa. --- Source: https://ritevo.com/pl/docs/automations/how-it-works (updated 2026-09-30) ## Jak działają akcje automatyczne Akcje automatyczne w Ritevo: wyzwalacz, warunki i kroki, kolejność wykonania, ochrona przed zapętleniem i audyt wykonania. Akcja automatyczna to reguła: **gdy coś się wydarzy, a warunki są spełnione, Ritevo wykonuje ustalone kroki za Ciebie**. Wszystko, co robi akcja, możesz też zrobić ręcznie - akcja tylko Cię w tym wyręcza. > **Warto wiedzieć:** Bez utworzonej i włączonej akcji nic nie dzieje się samo. Ritevo nie ma żadnych ukrytych automatów. ### Dwa rodzaje akcji Akcje tworzysz osobno dla zamówień i osobno dla wiadomości. Działają tak samo, różnią się tym, na co reagują i co potrafią zrobić: - [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions) - reagują na zmiany w zamówieniu i potrafią zmienić status, wystawić dokument, utworzyć przesyłkę, wydrukować etykietę, zaktualizować dane zamówienia i wiele innych. - [Akcje dla wiadomości](https://ritevo.com/pl/docs/automations/message-actions) - reagują na wiadomości od klientów i potrafią odpowiedzieć za Ciebie, także z pomocą AI, przypisać wątek do użytkownika, ustawić status i wiele innych. ### Z czego składa się akcja - **Wyzwalacz** - jedno zdarzenie, które uruchamia akcję, na przykład **Zmiana statusu zamówienia** albo **Nowy wątek**. Każda akcja ma dokładnie jeden wyzwalacz. - **Warunki** - opcjonalne. Zawężają akcję, na przykład tylko do opłaconych zamówień albo tylko do wiadomości od klienta. Możesz dodać do 50 warunków. - **Kroki** - to, co Ritevo ma zrobić. Co najmniej jeden, najwyżej 50. Wykonują się po kolei. W formularzu to karty **Akcja #1**, **Akcja #2** i kolejne, dodawane przyciskiem **Dodaj krok**. - **Strefa czasowa wykonania** - według niej liczone są warunki z godziną i dniem tygodnia. - **Aktywna / Nie aktywna** - działają tylko akcje aktywne. Wyłączona akcja zostaje zapisana, ale nic nie robi. Wszystko ustawiasz w jednym formularzu: u góry ustawienia podstawowe, po lewej warunki, po prawej kroki. ![Pusty formularz nowej akcji: nazwa i opis, wyzwalacz, strefa czasowa wykonania, przełącznik Aktywna, karta warunku i karta kroku](https://ritevo.com/docs/automations/pl-action-form-empty.webp) ### Jak Ritevo wykonuje akcję 1. Dzieje się coś, co jest wyzwalaczem - niezależnie od tego, czy zmianę zrobiłeś Ty, przyszła z kanału sprzedaży, czy wykonała ją inna akcja. 2. Ritevo bierze wszystkie aktywne akcje z tym wyzwalaczem. 3. Dla każdej sprawdza warunki. Jeśli któryś nie jest spełniony, ta akcja się nie wykonuje. 4. Wykonuje kroki po kolei. Następny krok zaczyna się dopiero wtedy, gdy poprzedni się udał. 5. Każde wykonanie zapisuje w audycie. Jeśli do jednego zdarzenia pasuje kilka akcji, **wykonają się wszystkie**. Akcje nie mają priorytetów ani ustalanej kolejności, więc nie buduj akcji, które zależą od tego, która zadziała pierwsza. Gdy kolejność ma znaczenie, masz dwa sposoby - wybierz ten, który wolisz: - **Jedna akcja z kilkoma krokami.** Kroki zawsze wykonują się po kolei, a następny zaczyna się dopiero po udanym poprzednim. To najprostszy i najpewniejszy sposób. - **Łańcuch akcji.** Ostatni krok akcji A jest wyzwalaczem akcji B - na przykład A kończy się krokiem **Utwórz przesyłkę**, a B ma wyzwalacz **Stworzono przesyłkę**. Przydaje się, gdy drugą część chcesz mieć osobno: z własnymi warunkami albo do wyłączenia niezależnie od pierwszej. ### Jak działają warunki - Wszystkie warunki akcji muszą być spełnione **jednocześnie**. Nie ma warunku „albo" między warunkami. - W jednym warunku możesz wybrać kilka wartości - wtedy wystarczy **dowolna z nich**. Na przykład w warunku **Integracja jest** wybierasz z listy swoich integracji jedną albo kilka: Allegro i eBay oznacza „zamówienie z Allegro albo z eBay". - Przedział ustawiasz dwoma warunkami: **od** i **do**. Na przykład godziny pracy to **Godzina wykonania akcji od** 08:00 i **Godzina wykonania akcji do** 16:00. - Godziny i dni tygodnia liczone są w **strefie czasowej ustawionej w akcji**. Godzinę w formularzu wpisujesz jednak według czasu swojego komputera. Dlatego zostaw w akcji strefę, którą formularz ustawia sam - Twoją własną. Wtedy **Godzina wykonania akcji od** 08:00 oznacza po prostu 8:00 u Ciebie, także gdy klient jest w innym kraju. Jeśli zmienisz strefę akcji na inną niż Twoja, wpisana godzina przesunie się o różnicę między strefami. Zmiana czasu na letni i zimowy jest uwzględniana sama. - Przedział przechodzący przez północ (na przykład 22:00-05:00) wymaga **dwóch akcji**: jednej z warunkiem **od** 22:00 i drugiej z warunkiem **do** 05:00. Formularz pozwoli ustawić oba warunki w jednej akcji, ale taka akcja nigdy się nie wykona - każdy warunek jest sprawdzany osobno, a żadna godzina nie jest jednocześnie po 22:00 i przed 05:00. ### Rozgałęzienia w kroku Krok może mieć rozgałęzienia, czyli kilka wariantów z własnymi warunkami. Przydaje się, gdy ta sama akcja ma zrobić co innego zależnie od zamówienia lub wiadomości. - Ritevo sprawdza warianty po kolei i wykonuje **pierwszy**, którego warunki są spełnione. - Jeśli żaden wariant nie pasuje, wykonuje akcję domyślną kroku. - Jeśli krok nie ma akcji domyślnej, cała akcja się zatrzymuje, a w audycie zobaczysz **Akcja zatrzymana przez warunki**. - Rozgałęzienia mają jeden poziom - wariant zawiera jedną czynność, nie kolejne kroki. ### Ochrona przed zapętleniem Akcja zmienia dane, a zmiana danych może być wyzwalaczem. Ritevo pilnuje, żeby akcje nie nakręcały się w nieskończoność - na trzy sposoby: 1. **Akcja nigdy nie uruchamia samej siebie.** Jeśli akcja z wyzwalaczem **Zmiana statusu zamówienia** sama zmienia status, nie wystartuje przez to drugi raz. 2. **Akcje mogą uruchamiać inne akcje, ale nie w kółko.** Ostatni krok akcji A może uruchomić akcję B, a ta akcję C. Gdy jednak zapis lub włączenie akcji zamknęłoby koło (A uruchamia B, B uruchamia A - także przez więcej akcji), Ritevo tego nie zapisze i pokaże błąd o wykrytym nieskończonym cyklu. Liczą się tylko akcje aktywne. 3. **Bezpiecznik w trakcie działania.** Jeśli mimo wszystko akcje wykonują się na tym samym zamówieniu lub wątku zbyt wiele razy w krótkim czasie, Ritevo je wstrzymuje. W audycie zamówień albo wiadomości zobaczysz wtedy wpis **Wykryto nieskończoną pętlę** razem z akcją i krokiem, na którym to się stało. Twoje ręczne zmiany nigdy nie są w ten sposób blokowane. > **Warto wiedzieć:** Dopóki akcja jest w trakcie swoich kroków, jej zmiany **nie uruchamiają żadnej nowej akcji** - kolejne kroki tylko przesuwają tę samą akcję dalej. Nową akcję może uruchomić wyłącznie zdarzenie spoza akcji (wyzwalacz) albo **ostatni krok** innej akcji. ### Audyt wykonania Każde wykonanie akcji jest zapisywane w audycie: **Ustawienia → Audyt**, osobno dla zamówień i dla wiadomości. Wpisy możesz filtrować po akcji i po wyniku. Możliwe wyniki: - **Akcja trwa dalej** - krok się wykonał, są kolejne. - **Akcja zakończona** - wykonał się ostatni krok. - **Akcja zatrzymana przez warunki** - w kroku z rozgałęzieniami nie pasował żaden wariant. - **Wykryto nieskończoną pętlę** - zadziałał bezpiecznik. - **Błąd** - krok się nie udał, na przykład integracja odrzuciła żądanie. Wpis zawiera opis błędu. W akcjach dla zamówień po błędzie kroku z integracją - przesyłka, przesłanie dokumentu do księgowości, wydruk - akcja idzie dalej: [Kroki, które czekają na zewnętrzny system](https://ritevo.com/pl/docs/automations/order-actions#waiting-steps). Po błędzie pozostałych kroków kolejne kroki tej akcji już się nie wykonają. ### Czego akcje nie robią - Nie uruchamiają się o ustalonej porze. Nie ma wyzwalacza „codziennie o 8:00" - czas występuje tylko jako warunek. - Nie czekają. Nie ma kroku „odczekaj godzinę" ani „wyślij po 2 dniach". - Nie da się ich uruchomić ręcznie na wybranym zamówieniu lub wątku. Akcję możesz tylko włączyć albo wyłączyć. - Jedna akcja ma jeden wyzwalacz. Dla dwóch zdarzeń utwórz dwie akcje. - Limity: do 1000 akcji na firmę, do 50 kroków i 50 warunków w akcji. ### Zapis akcji przez API (dla AI i integratorów) Ta sekcja istnieje tylko w wersji Markdown. Przy nazwach wyzwalaczy, warunków i kroków na stronach szczegółowych dopisane są w nawiasie nazwy z API oraz pole, w którym podaje się wartość. Akcje dla zamówień zapisuje `POST /orders/automatic-actions`, akcje dla wiadomości `POST /messages/automatic-actions`; zmiana to `PATCH /{id}`, włączenie i wyłączenie `PATCH /{id}/toggle-active`, usunięcie `DELETE /{id}`. Adres bazowy API to `https://api.ritevo.com/api`. Pełna definicja wszystkich endpointów i pól: [Swagger UI](https://api.ritevo.com/api/webjars/swagger-ui/index.html), w wersji do odczytu maszynowego (OpenAPI) pod `https://api.ritevo.com/api/v1/api-docs`. Ścieżki podane przy wartościach (na przykład `GET /integrations/shippings`) są względem adresu bazowego. - Pola akcji: `name` i `description` (oba wymagane, do 255 znaków), `active`, `userTimezone` (wymagane, nazwa strefy IANA, na przykład `Europe/Warsaw`), `triggerType` (dokładnie jeden), `conditions` (0-50), `actionSteps` (1-50). - Krok: `stepOrder` numerowany od 1 bez przerw i powtórzeń oraz `action` albo `conditionalBranches` (albo oba - wtedy `action` jest akcją domyślną). Wariant: `branchOrder` od 1, `conditions` (co najmniej jeden) i `action`. - Warunek: `type` oraz **dokładnie to pole wartości**, które podano przy jego nazwie. Pozostałych pól nie wysyłaj. - Czynność kroku (`action`): `type` oraz pole wartości podane przy nazwie kroku. - Godzina i data: `offsetDateTimeValue` to pełna data z czasem i przesunięciem, na przykład `2026-01-10T08:00:00+01:00`. Dla warunków z godziną (`*_TIME_FROM`, `*_TIME_TO`) liczy się tylko godzina i minuta odczytana w `userTimezone`, więc podaj godzinę z przesunięciem tej strefy; data może być dowolna. Dla warunków z datą (`*_DATE_FROM`, `*_DATE_TO`) liczy się cały moment. - Dni tygodnia: `integerValues` z liczbami 1-7, gdzie 1 to poniedziałek, a 7 niedziela. - Warunki bez wartości („posiada fakturę", „od klienta"): `booleanValues` z jednym elementem `true`. Kroki wymagające potwierdzenia (usuwanie): `booleanValue` równe `true`. - Identyfikatory integracji, własnych statusów, szablonów wiadomości, użytkowników i szablonów ustawień dokumentu pobierz z list w API - to UUID. - Zapis zostanie odrzucony z kodem 409, jeśli aktywne akcje zamknęłyby koło. Wyzwalacz, który wywoła akcja, wynika z jej **ostatniego** kroku: `UPDATE_STATUS` → `STATUS_CHANGED`, `UPDATE_USER_DEFINED_STATUS` → `USER_DEFINED_STATUS_CHANGED`, `UPDATE_PAYMENT` → `PAYMENT_DATA_CHANGED`, `GENERATE_INVOICE` / `DELETE_INVOICE` → `INVOICE_CHANGED`, `GENERATE_RECEIPT` / `DELETE_RECEIPT` → `RECEIPT_CHANGED`, `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` → `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING`, `CREATE_SHIPMENT` → `CREATE_SHIPMENT`, `PRINT_SHIPMENT_LABEL` / `PRINT_RECEIPT` → `CREATE_PRINT_JOB`, `DELETE_ORDER` / `RESTORE_ORDER` → `ORDER`; w wiadomościach `SEND_MESSAGE_TO_THREAD` → `MESSAGE_RESPONSE`, `TEMPLATE_SEND_MESSAGE_TO_THREAD` → `TEMPLATE_MESSAGE_RESPONSE`, `AI_SEND_MESSAGE_TO_THREAD` → `AI_MESSAGE_RESPONSE`, `UPDATE_ASSIGNED_USER` → `ASSIGNED_USER_CHANGED`, `UPDATE_READ_STATUS` → `READ_STATUS_CHANGED`. Pozostałe: `UPDATE_OWN_NOTE` → `OWN_NOTE_CHANGED`, `UPDATE_FAVORITE_STATUS` → `FAVORITE_STATUS_CHANGED`, `UPDATE_ORDER_DATE` → `ORDER_DATE_CHANGED`, `UPDATE_BUYER` → `BUYER_DATA_CHANGED`, `UPDATE_COMPANY` / `USE_BUYER_AS_BILLING_RECIPIENT` → `COMPANY_DATA_CHANGED`, `UPDATE_DELIVERY_ADDRESS` → `DELIVERY_ADDRESS_CHANGED`, `UPDATE_DELIVERY_BASIC` → `DELIVERY_BASIC_CHANGED`, `UPDATE_DELIVERY_METHOD` → `DELIVERY_METHOD_CHANGED`, `UPDATE_DELIVERY_PICKUP_POINT` → `DELIVERY_PICKUP_POINT_CHANGED`, `UPDATE_DELIVERY_TIME` → `DELIVERY_TIME_CHANGED`, `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` → `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. --- Source: https://ritevo.com/pl/docs/automations/order-actions (updated 2026-09-30) ## Akcje automatyczne dla zamówień Akcje automatyczne dla zamówień w Ritevo: wyzwalacze, warunki i kroki - faktura, przesyłka, etykieta, status - z gotowymi przykładami. Akcja dla zamówień reaguje na zmianę w zamówieniu i wykonuje na nim ustalone kroki. Najczęściej zmienia status zamówienia albo Twój własny status, wystawia fakturę lub paragon, przesyła dokument do systemu księgowego, tworzy przesyłkę, drukuje etykietę lub paragon, aktualizuje dane zamówienia - kupującego, dane do faktury, dostawę, płatność - dopisuje notatkę, oznacza zamówienie jako ulubione i wiele innych. Ogólne zasady - warunki, rozgałęzienia, ochrona przed zapętleniem - opisuje strona [Jak działają akcje automatyczne](https://ritevo.com/pl/docs/automations/how-it-works). > **Wymagana integracja:** Same akcje nie wymagają żadnej integracji. Potrzebują jej konkretne kroki: **Utwórz przesyłkę** - integracji wysyłkowej, **Prześlij fakturę do zew. systemu księgowego** - integracji księgowej, **Wydrukuj etykietę przesyłki** - integracji drukarki. ### Gdzie znajdziesz akcje Akcje dla zamówień są w menu **Zamówienia → Akcje** (w lewym panelu). Lista pokazuje przy każdej akcji jej wyzwalacz, warunki i kroki oraz to, czy jest aktywna. Nową akcję dodajesz przyciskiem **Dodaj nowa akcję** w prawym górnym rogu. Okruszki u góry strony (**Pulpit → Zamówienia → Akcje**) zawsze pokazują, gdzie jesteś. ![Lista akcji automatycznych dla zamówień z podświetloną pozycją Akcje w lewym panelu; przycisk Dodaj nowa akcję w prawym górnym rogu jest zaznaczony ramką](https://ritevo.com/docs/automations/pl-order-actions-list.webp) Formularz akcji: u góry ustawienia podstawowe (nazwa, opis, wyzwalacz, strefa czasowa, **Aktywna**), po lewej warunki, po prawej kroki. ![Pusty formularz nowej akcji dla zamówień: ustawienia podstawowe, karta warunku i karta kroku](https://ritevo.com/docs/automations/pl-action-form-empty.webp) ### Wyzwalacze Wyzwalacz to zmiana, która zaszła w zamówieniu. Nie ma znaczenia, kto ją zrobił: Ty, kanał sprzedaży przy pobieraniu zamówienia, czy inna akcja. #### Zamówienie i statusy - **Zamówienie** (API: "Zamówienie" = `ORDER`) - do Ritevo trafiło nowe zamówienie albo istniejące zostało zaktualizowane przy pobraniu z kanału sprzedaży; także usunięcie i przywrócenie zamówienia. To wyzwalacz dla akcji typu „zrób coś z każdym nowym zamówieniem". - **Zmiana statusu zamówienia** (API: "Zmiana statusu zamówienia" = `STATUS_CHANGED`) - zmienił się status zamówienia, na przykład na **Potwierdzono**. - **Zmiana statusu** (API: "Zmiana statusu" = `USER_DEFINED_STATUS_CHANGED`) - zmienił się Twój własny status zamówienia. - **Zmiana danych płatności** (API: "Zmiana danych płatności" = `PAYMENT_DATA_CHANGED`) - zmieniła się płatność, na przykład zamówienie zostało opłacone. - **Zmiana daty zamówienia**, **Zmiana własnej notatki**, **Zmiana statusu ulubionych**. (API: "Zmiana daty zamówienia" = `ORDER_DATE_CHANGED`, "Zmiana własnej notatki" = `OWN_NOTE_CHANGED`, "Zmiana statusu ulubionych" = `FAVORITE_STATUS_CHANGED`) #### Dane zamówienia - **Zmiana pozycji zamówienia** (API: "Zmiana pozycji zamówienia" = `LINE_ITEM_CHANGED`) - dodano, zmieniono albo usunięto pozycję. - **Zmiana danych kupującego**, **Zmiana danych firmy**. (API: "Zmiana danych kupującego" = `BUYER_DATA_CHANGED`, "Zmiana danych firmy" = `COMPANY_DATA_CHANGED`) - **Zmiana adresu dostawy**, **Zmiana metody dostawy**, **Zmiana punktu odbioru**, **Zmiana czasu dostawy**, **Zmiana podstawowych danych dostawy**. (API: "Zmiana adresu dostawy" = `DELIVERY_ADDRESS_CHANGED`, "Zmiana metody dostawy" = `DELIVERY_METHOD_CHANGED`, "Zmiana punktu odbioru" = `DELIVERY_PICKUP_POINT_CHANGED`, "Zmiana czasu dostawy" = `DELIVERY_TIME_CHANGED`, "Zmiana podstawowych danych dostawy" = `DELIVERY_BASIC_CHANGED`) #### Dokumenty, przesyłki i wydruki - **Faktura(dodanie/usunięcie)**, **Paragon(dodanie/usunięcie)** (API: "Faktura(dodanie/usunięcie)" = `INVOICE_CHANGED`, "Paragon(dodanie/usunięcie)" = `RECEIPT_CHANGED`) - dokument został wystawiony albo usunięty. - **Przesłano fakturę w zew. systemie księgowym**, **Przesłano paragon w zew. systemie księgowym**. (API: "Przesłano fakturę w zew. systemie księgowym" = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING`, "Przesłano paragon w zew. systemie księgowym" = `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`) - **Stworzono przesyłkę** (API: "Stworzono przesyłkę" = `CREATE_SHIPMENT`) - do zamówienia powstała przesyłka. - **Zlecenie wydruku** (API: "Zlecenie wydruku" = `CREATE_PRINT_JOB`) - zlecono wydruk etykiety albo paragonu. ### Warunki Warunki sprawdzają zamówienie w chwili wykonania akcji. Poniżej nazwy dokładnie takie, jak na liście w formularzu akcji. #### Integracja i statusy - **Integracja jest** / **Integracja nie jest** (API: "Integracja jest" = `INTEGRATION_IS`, "Integracja nie jest" = `INTEGRATION_IS_NOT`; wartość w `uuidValues`: id integracji sprzedażowych: `GET /integrations/marketplaces`, `GET /integrations/shops`) - wybierasz z listy swoich integracji jedną albo kilka. Przy kilku wystarczy, że zamówienie pochodzi z dowolnej z nich. - **Status zamówienia jest** / **Status zamówienia nie jest** (API: "Status zamówienia jest" = `ORDER_STATUS_IS`, "Status zamówienia nie jest" = `ORDER_STATUS_IS_NOT`; wartość w `enumValues`: `CONFIRMED`, `CANCELLED`, `WAITING_FOR_PAYMENT`, `WAITING_FOR_CONFIRMATION`) - wybierasz jeden albo kilka statusów zamówienia, na przykład Potwierdzono. - **Status zamówienia zmienił się na** (API: "Status zamówienia zmienił się na" = `ORDER_STATUS_CHANGED_TO`; wartość w `enumValues`: `CONFIRMED`, `CANCELLED`, `WAITING_FOR_PAYMENT`, `WAITING_FOR_CONFIRMATION`) - używaj z wyzwalaczem **Zmiana statusu zamówienia**: warunek jest spełniony, gdy po zmianie zamówienie ma jeden z wybranych statusów. - **Status jest** / **Status nie jest** / **Status zmienił się na** (API: "Status jest" = `USER_DEFINED_STATUS_IS`, "Status nie jest" = `USER_DEFINED_STATUS_IS_NOT`, "Status zmienił się na" = `USER_DEFINED_STATUS_CHANGED_TO`; wartość w `uuidValues`: id własnych statusów zamówień: `GET /orders/statuses`) - to samo dla Twoich własnych statusów. #### Płatność - **Status płatności jest** / **Status płatności nie jest** (API: "Status płatności jest" = `PAYMENT_STATUS_IS`, "Status płatności nie jest" = `PAYMENT_STATUS_IS_NOT`; wartość w `enumValues`: `WAITING_FOR_PAYMENT`, `PAID`, `OVERPAID`, `UNDERPAID`) - na przykład Opłacone, Niedopłata, Nadpłata. - **Metoda płatności jest** / **Metoda płatności nie jest** (API: "Metoda płatności jest" = `PAYMENT_METHOD_IS`, "Metoda płatności nie jest" = `PAYMENT_METHOD_IS_NOT`; wartość w `enumValues`: `BANK_TRANSFER`, `CASH`, `CASH_ON_DELIVERY`, `COMPENSATION`, `CARD`, `PAYU`, `PAYPAL`, `P24`, `OTHER`) - jedna albo kilka metod. - **Zamówienie nieopłacone** (API: "Zamówienie nieopłacone" = `PAYMENT_NOT_PAID`; wartość w `booleanValues`: zawsze `[true]`) - nic jeszcze nie wpłynęło. - **Kwota zapłacona większa niż** / **mniejsza niż** / **równa** (API: "Kwota zapłacona większa niż" = `PAYMENT_PAID_AMOUNT_GREATER_THAN`, "mniejsza niż" = `PAYMENT_PAID_AMOUNT_LESS_THAN`, "równa" = `PAYMENT_PAID_AMOUNT_EQUALS`; wartość w `bigDecimalValue`: liczba, na przykład `500.00`) - porównanie z podaną kwotą. - **Kwota do zapłaty większa niż** / **mniejsza niż** / **równa** (API: "Kwota do zapłaty większa niż" = `PAYMENT_TOTAL_TO_PAY_AMOUNT_GREATER_THAN`, "mniejsza niż" = `PAYMENT_TOTAL_TO_PAY_AMOUNT_LESS_THAN`, "równa" = `PAYMENT_TOTAL_TO_PAY_AMOUNT_EQUALS`; wartość w `bigDecimalValue`: liczba, na przykład `500.00`) - na przykład inne kroki dla zamówień powyżej 500 zł. #### Dostawa i pozycje - **Kraj dostawy jest** / **Kraj dostawy nie jest** (API: "Kraj dostawy jest" = `DELIVERY_COUNTRY_IS`, "Kraj dostawy nie jest" = `DELIVERY_COUNTRY_IS_NOT`; wartość w `enumValues`: dwuliterowe kody krajów ISO, na przykład `PL`, `DE`) - jeden albo kilka krajów. - **Region dostawy jest** / **Region dostawy nie jest** (API: "Region dostawy jest" = `DELIVERY_REGION_IS`, "Region dostawy nie jest" = `DELIVERY_REGION_IS_NOT`; wartość w `enumValues`: `EUROPE`) - obecnie do wyboru Europa. - **Miasto dostawy zawiera** / **Miasto dostawy nie zawiera** (API: "Miasto dostawy zawiera" = `DELIVERY_CITY_CONTAINS`, "Miasto dostawy nie zawiera" = `DELIVERY_CITY_CONTAINS_NOT`; wartość w `stringValues`: lista słów lub fragmentów tekstu; wystarczy dowolny z nich, wielkość liter nie ma znaczenia) - fragment nazwy miasta. - **Liczba pozycji większa niż** / **mniejsza niż** / **równa** (API: "Liczba pozycji większa niż" = `LINE_ITEMS_COUNT_GREATER_THAN`, "mniejsza niż" = `LINE_ITEMS_COUNT_LESS_THAN`, "równa" = `LINE_ITEMS_COUNT_EQUALS`; wartość w `integerValue`: liczba całkowita) - ile różnych pozycji ma zamówienie. - **Ilość pozycji większa niż** / **mniejsza niż** / **równa** (API: "Ilość pozycji większa niż" = `LINE_ITEM_QUANTITY_GREATER_THAN`, "mniejsza niż" = `LINE_ITEM_QUANTITY_LESS_THAN`; wartość w `integerValue`: liczba całkowita | "równa" = `LINE_ITEM_QUANTITY_EQUALS`; wartość w `bigDecimalValue`: liczba, na przykład `500.00`) - ile sztuk ma pozycja. - **Nazwa pozycji zawiera** / **Nazwa pozycji nie zawiera** (API: "Nazwa pozycji zawiera" = `LINE_ITEM_NAME_CONTAINS`, "Nazwa pozycji nie zawiera" = `LINE_ITEM_NAME_NOT_CONTAINS`; wartość w `stringValues`: lista słów lub fragmentów tekstu; wystarczy dowolny z nich, wielkość liter nie ma znaczenia) - jedno albo kilka słów; wystarczy dowolne z nich. #### Dokumenty i przesyłka - **Posiada fakturę** / **Nie posiada faktury**, **Posiada paragon** / **Nie posiada paragonu**, **Posiada korektę** / **Nie posiada korekty**. (API: "Posiada fakturę" = `HAS_INVOICE`, "Nie posiada faktury" = `HAS_INVOICE_NOT`, "Posiada paragon" = `HAS_RECEIPT`, "Nie posiada paragonu" = `HAS_RECEIPT_NOT`, "Posiada korektę" = `HAS_CORRECTION`, "Nie posiada korekty" = `HAS_CORRECTION_NOT`; wartość w `booleanValues`: zawsze `[true]`) - **Ma udany transfer faktury do zew. systemu księgowego** / **Nie ma udanego transferu faktury do zew. systemu księgowego**, **Ma udany transfer paragonu do zew. systemu księgowego** / **Nie ma udanego transferu paragonu do zew. systemu księgowego** (API: "Ma udany transfer faktury do zew. systemu księgowego" = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING`, "Nie ma udanego transferu faktury do zew. systemu księgowego" = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`; wartość w `uuidValues`: id integracji księgowej: `GET /integrations/accountings` | "Ma udany transfer paragonu do zew. systemu księgowego" = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING`, "Nie ma udanego transferu paragonu do zew. systemu księgowego" = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT`; wartość w `uuidValues`: id integracji księgowej: `GET /integrations/accountings`) - wybierasz integrację księgową. - **Posiada przesyłkę** / **Nie posiada przesyłki**. (API: "Posiada przesyłkę" = `HAS_SHIPMENT`, "Nie posiada przesyłki" = `HAS_SHIPMENT_NOT`; wartość w `booleanValues`: zawsze `[true]`) - **Status przesyłki jest** / **Status przesyłki nie jest** (API: "Status przesyłki jest" = `SHIPMENT_STATUS_IS`, "Status przesyłki nie jest" = `SHIPMENT_STATUS_IS_NOT`; wartość w `enumValues`: `PENDING`, `SUCCESS`, `ERROR`) - jeden albo kilka statusów przesyłki. - **Przesyłka należy do integracji** / **Przesyłka nie należy do integracji** (API: "Przesyłka należy do integracji" = `SHIPMENT_SHIPPING_INTEGRATION_IS`, "Przesyłka nie należy do integracji" = `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT`; wartość w `uuidValues`: id integracji wysyłkowej: `GET /integrations/shippings`) - wybierasz integrację wysyłkową. #### Kupujący, notatka i ulubione - **Email kupującego zawiera** / **nie zawiera**, **Imię i nazwisko kupującego zawiera** / **nie zawiera**, **Firma kupującego zawiera** / **nie zawiera** (API: "Email kupującego zawiera" = `BUYER_EMAIL_CONTAINS`, "nie zawiera" = `BUYER_EMAIL_NOT_CONTAINS`, "Imię i nazwisko kupującego zawiera" = `BUYER_NAME_CONTAINS`, "nie zawiera" = `BUYER_NAME_NOT_CONTAINS`, "Firma kupującego zawiera" = `BUYER_COMPANY_CONTAINS`, "nie zawiera" = `BUYER_COMPANY_NOT_CONTAINS`; wartość w `stringValues`: lista słów lub fragmentów tekstu; wystarczy dowolny z nich, wielkość liter nie ma znaczenia) - fragment tekstu. - **Brak notatki** / **Posiada notatkę** / **Notatka została usunięta**. (API: "Brak notatki" = `OWN_NOTE_IS_EMPTY`, "Posiada notatkę" = `OWN_NOTE_IS_NOT_EMPTY`, "Notatka została usunięta" = `OWN_NOTE_CHANGED_TO_EMPTY`; wartość w `booleanValues`: zawsze `[true]`) - **Własna notatka zawiera słowa kluczowe** / **Własna notatka nie zawiera słów kluczowych**. (API: "Własna notatka zawiera słowa kluczowe" = `OWN_NOTE_CONTAINS_KEYWORDS`, "Własna notatka nie zawiera słów kluczowych" = `OWN_NOTE_NOT_CONTAINS_KEYWORDS`; wartość w `stringValues`: lista słów lub fragmentów tekstu; wystarczy dowolny z nich, wielkość liter nie ma znaczenia) - **Zamówienie jest w ulubionych** / **Zamówienie nie jest w ulubionych**, **Status ulubiony zmienił się z** / **na**. (API: "Zamówienie jest w ulubionych" = `FAVORITE_STATUS_IS`, "Zamówienie nie jest w ulubionych" = `FAVORITE_STATUS_IS_NOT`, "Status ulubiony zmienił się z" = `FAVORITE_STATUS_CHANGED_FROM`, "na" = `FAVORITE_STATUS_CHANGED_TO`; wartość w `booleanValue`: `true` albo `false`) #### Czas - **Godzina wykonania akcji od** / **do**, **Dzień wykonania akcji jest** / **nie jest**, **Data wykonania akcji od** / **do** (API: "Godzina wykonania akcji od" = `CURRENT_TIME_FROM`, "do" = `CURRENT_TIME_TO`; wartość w `offsetDateTimeValue`: data z czasem i przesunięciem strefy akcji; liczy się tylko godzina i minuta, na przykład `2026-01-10T16:00:00+01:00` | "Dzień wykonania akcji jest" = `CURRENT_DAY_OF_WEEK_IS`, "nie jest" = `CURRENT_DAY_OF_WEEK_IS_NOT`; wartość w `integerValues`: liczby 1-7, gdzie 1 to poniedziałek, a 7 niedziela | "Data wykonania akcji od" = `CURRENT_DATE_FROM`, "do" = `CURRENT_DATE_TO`; wartość w `offsetDateTimeValue`: data z czasem i przesunięciem; liczy się cały moment) - liczone od chwili, w której akcja się wykonuje. - **Godzina zamówienia od** / **do**, **Dzień zamówienia jest** / **nie jest**, **Data zamówienia od** / **do** (API: "Godzina zamówienia od" = `ORDER_TIME_FROM`, "do" = `ORDER_TIME_TO`; wartość w `offsetDateTimeValue`: data z czasem i przesunięciem strefy akcji; liczy się tylko godzina i minuta, na przykład `2026-01-10T16:00:00+01:00` | "Dzień zamówienia jest" = `ORDER_DAY_OF_WEEK_IS`, "nie jest" = `ORDER_DAY_OF_WEEK_IS_NOT`; wartość w `integerValues`: liczby 1-7, gdzie 1 to poniedziałek, a 7 niedziela | "Data zamówienia od" = `ORDER_DATE_FROM`, "do" = `ORDER_DATE_TO`; wartość w `offsetDateTimeValue`: data z czasem i przesunięciem; liczy się cały moment) - liczone od chwili złożenia zamówienia. - **Wiek zamówienia większy niż (dni)** / **Wiek zamówienia mniejszy niż (dni)** (API: "Wiek zamówienia większy niż (dni)" = `ORDER_AGE_DAYS_GREATER_THAN`, "Wiek zamówienia mniejszy niż (dni)" = `ORDER_AGE_DAYS_LESS_THAN`; wartość w `integerValue`: liczba całkowita) - ile dni minęło od złożenia zamówienia. > **Warto wiedzieć:** Warunki z „posiada" są najprostszą ochroną przed zdublowaniem: dodaj **Nie posiada faktury** do akcji, która wystawia fakturę, i **Nie posiada przesyłki** do akcji, która nadaje przesyłkę. ### Kroki - co akcja może zrobić #### Statusy i oznaczenia - **Zaktualizuj status zamówienia**, **Zaktualizuj status** (własny). (API: "Zaktualizuj status zamówienia" = `UPDATE_STATUS`; wartość w `enumValue`: `CONFIRMED`, `CANCELLED`, `WAITING_FOR_PAYMENT`, `WAITING_FOR_CONFIRMATION` | "Zaktualizuj status" = `UPDATE_USER_DEFINED_STATUS`; wartość w `uuidValue`: id własnych statusów zamówień: `GET /orders/statuses`) - **Zaktualizuj własną notatkę**, **Zaktualizuj status ulubione**. (API: "Zaktualizuj własną notatkę" = `UPDATE_OWN_NOTE`; wartość w `stringValue`: tekst do 255 znaków; `null` czyści notatkę | "Zaktualizuj status ulubione" = `UPDATE_FAVORITE_STATUS`; wartość w `booleanValue`: `true` albo `false`) #### Dokumenty - **Wygeneruj fakturę**, **Wygeneruj paragon** (API: "Wygeneruj fakturę" = `GENERATE_INVOICE`, "Wygeneruj paragon" = `GENERATE_RECEIPT`; wartość w `uuidValue`: id szablonu ustawień dokumentu: `GET /orders/billing/settings`) - według wybranego szablonu ustawień dokumentu. - **Usuń fakturę**, **Usuń paragon**. (API: "Usuń fakturę" = `DELETE_INVOICE`, "Usuń paragon" = `DELETE_RECEIPT`; wartość w `booleanValue`: zawsze `true` - potwierdzenie) - **Prześlij fakturę do zew. systemu księgowego**, **Prześlij paragon do zew. systemu księgowego** (API: "Prześlij fakturę do zew. systemu księgowego" = `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING`, "Prześlij paragon do zew. systemu księgowego" = `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING`; wartość w `uuidValue`: id integracji księgowej: `GET /integrations/accountings`) - wymaga integracji księgowej. - **Zaktualizuj dane firmy danymi kupującego** (API: "Zaktualizuj dane firmy danymi kupującego" = `USE_BUYER_AS_BILLING_RECIPIENT`; wartość w `booleanValue`: zawsze `true` - potwierdzenie) - przepisuje dane kupującego do danych na dokumencie. Przesyłanie dokumentów najlepiej zaplanować po kolei - najpierw wystawienie, potem przesłanie: - **Faktura** - pierwsza akcja kończy się krokiem **Wygeneruj fakturę**. Druga startuje wyzwalaczem **Faktura(dodanie/usunięcie)**, ma warunek **Posiada fakturę** i krok **Prześlij fakturę do zew. systemu księgowego**. - **Paragon** - tak samo: pierwsza akcja kończy się krokiem **Wygeneruj paragon**, a druga startuje wyzwalaczem **Paragon(dodanie/usunięcie)**, ma warunek **Posiada paragon** i krok **Prześlij paragon do zew. systemu księgowego**. - **Korekty** - do jednej faktury możesz wystawić wiele korekt. Każdą prześlij zaraz po wystawieniu, zanim wystawisz następną. > **Warto wiedzieć:** Krok przesłania wysyła zawsze tylko jeden dokument - najnowszy nieusunięty danego typu. Jeśli najpierw wystawisz wszystkie dokumenty, a dopiero potem włączysz przesyłanie, trafi tylko ostatni, a pozostałe prześlesz ręcznie. Usuniętego dokumentu nie prześlesz. #### Przesyłki i wydruki - **Utwórz przesyłkę** (API: "Utwórz przesyłkę" = `CREATE_SHIPMENT`; wartość w `uuidValue`: id integracji wysyłkowej: `GET /integrations/shippings`) - wymaga integracji wysyłkowej. - **Wydrukuj etykietę przesyłki** (API: "Wydrukuj etykietę przesyłki" = `PRINT_SHIPMENT_LABEL`; wartość w `uuidValue`: id integracji drukarki: `GET /integrations/printers`) - drukuje etykietę najnowszej udanej przesyłki zamówienia, wymaga integracji drukarki. - **Wydrukuj paragon** (API: "Wydrukuj paragon" = `PRINT_RECEIPT`; wartość w `uuidValue`: id integracji drukarki: `GET /integrations/printers`) - drukuje najnowszy paragon zamówienia. Druk etykiet najlepiej zaplanować po kolei, jako dwie akcje: - **Pierwsza akcja** - kończy się krokiem **Utwórz przesyłkę**. - **Druga akcja** - startuje wyzwalaczem **Stworzono przesyłkę**, ma warunek **Status przesyłki jest** z wartością **Utworzona pomyślnie** i jeden krok **Wydrukuj etykietę przesyłki**. Dzięki temu każda nowa przesyłka od razu drukuje swoją etykietę - także gdy zamówienie ma kilka paczek. > **Warto wiedzieć:** Krok **Wydrukuj etykietę przesyłki** drukuje zawsze tylko jedną etykietę - najnowszej udanej przesyłki. Jeśli najpierw utworzysz wszystkie przesyłki, a dopiero potem włączysz druk, wydrukuje się tylko ostatnia, a pozostałe wydrukujesz ręcznie przyciskiem **Drukuj**. Jeśli nowa przesyłka się nie uda, krok wydrukuje etykietę poprzedniej udanej. #### Dane zamówienia - **Zaktualizuj dane kupującego**, **Zaktualizuj dane firmy**, **Zaktualizuj adres dostawy**, **Zaktualizuj metodę dostawy**, **Zaktualizuj punkt odbioru**, **Zaktualizuj czas dostawy**, **Zaktualizuj podstawowe dane dostawy**, **Zaktualizuj dane płatności**, **Zaktualizuj datę zamówienia** (API: "Zaktualizuj dane kupującego" = `UPDATE_BUYER`; wartość w `buyerData`: obiekt z danymi do ustawienia; `useEntityWhenNull: true` zostawia bez zmian pola, których nie podasz | "Zaktualizuj dane firmy" = `UPDATE_COMPANY`; wartość w `companyData`: obiekt z danymi do ustawienia; `useEntityWhenNull: true` zostawia bez zmian pola, których nie podasz | "Zaktualizuj adres dostawy" = `UPDATE_DELIVERY_ADDRESS`; wartość w `deliveryAddressData`: obiekt z danymi do ustawienia; `useEntityWhenNull: true` zostawia bez zmian pola, których nie podasz | "Zaktualizuj metodę dostawy" = `UPDATE_DELIVERY_METHOD`; wartość w `deliveryMethodData`: obiekt z danymi do ustawienia; `useEntityWhenNull: true` zostawia bez zmian pola, których nie podasz | "Zaktualizuj punkt odbioru" = `UPDATE_DELIVERY_PICKUP_POINT`; wartość w `deliveryPickupPointData`: obiekt z danymi do ustawienia; `useEntityWhenNull: true` zostawia bez zmian pola, których nie podasz | "Zaktualizuj czas dostawy" = `UPDATE_DELIVERY_TIME`; wartość w `deliveryTimeData`: obiekt z danymi do ustawienia; `useEntityWhenNull: true` zostawia bez zmian pola, których nie podasz | "Zaktualizuj podstawowe dane dostawy" = `UPDATE_DELIVERY_BASIC`; wartość w `deliveryBasicData`: obiekt z danymi do ustawienia; `useEntityWhenNull: true` zostawia bez zmian pola, których nie podasz | "Zaktualizuj dane płatności" = `UPDATE_PAYMENT`; wartość w `paymentData`: obiekt z danymi do ustawienia; `useEntityWhenNull: true` zostawia bez zmian pola, których nie podasz | "Zaktualizuj datę zamówienia" = `UPDATE_ORDER_DATE`; wartość w `offsetDateTimeValue`: data z czasem i przesunięciem; liczy się cały moment) - ustawiają podane dane w zamówieniu. Opcja **Uzupełnij puste pola obecnymi danymi z zamówienia** zostawia bez zmian pola, których w kroku nie wypełnisz. - **Usuń zamówienie**, **Przywróć zamówienie**. (API: "Usuń zamówienie" = `DELETE_ORDER`, "Przywróć zamówienie" = `RESTORE_ORDER`; wartość w `booleanValue`: zawsze `true` - potwierdzenie) Kroki, które coś usuwają, wymagają wyraźnego potwierdzenia przy tworzeniu akcji. ### Kroki, które czekają na zewnętrzny system Część kroków nie kończy się od razu, bo odpowiedź musi przyjść z zewnątrz: - **Prześlij fakturę do zew. systemu księgowego** / **Prześlij paragon do zew. systemu księgowego** - niektóre systemy (na przykład KSeF) przyjmują dokument i potwierdzają go dopiero po chwili. Do tego czasu przesłanie ma stan „w trakcie". - **Utwórz przesyłkę** - przewoźnik przyjmuje zlecenie, a numer przesyłki i etykietę zwraca po chwili. Dopóki nie ma wyniku końcowego, akcja **czeka**: nie przechodzi do następnego kroku i nie uruchamia innych akcji. Dalej rusza dopiero wtedy, gdy zewnętrzny system odpowie - **powodzeniem** albo **błędem**. W obu przypadkach dzieje się to samo: - **Następny krok** - akcja przechodzi do kolejnego kroku, także po błędzie. Błąd nie zatrzymuje akcji, żebyś mógł na niego zareagować, na przykład ustawić własny status „Problem z przesyłką". - **Inne akcje** - jeśli był to ostatni krok akcji, mogą wystartować akcje z wyzwalaczem **Stworzono przesyłkę** lub **Przesłano fakturę w zew. systemie księgowym**. One też ruszają i po powodzeniu, i po błędzie. - **Audyt** - wynik, a przy błędzie także jego powód, zobaczysz w audycie zamówień. > **Warto wiedzieć:** Nie musisz dodawać warunków w rodzaju „poczekaj, aż będzie gotowe" - kolejny krok i tak ruszy dopiero po odpowiedzi. Sam decydujesz za to, co ma się stać po błędzie. Jeśli następny krok ma się wykonać tylko po powodzeniu, dodaj w nim [rozgałęzienie](https://ritevo.com/pl/docs/automations/how-it-works#branches) z warunkiem **Status przesyłki jest** Utworzona pomyślnie albo **Ma udany transfer faktury do zew. systemu księgowego** / **Ma udany transfer paragonu do zew. systemu księgowego** i nie ustawiaj akcji domyślnej. Po błędzie akcja zatrzyma się wtedy na tym kroku. Te warunki patrzą na wszystkie przesyłki i przesłania w zamówieniu, także wcześniejsze. ### Przykłady #### Przesyłka dla potwierdzonych zamówień z wybranej integracji - Wyzwalacz: **Zamówienie**. - Warunki: **Integracja jest** wybrana integracja sprzedażowa, **Status zamówienia jest** Potwierdzono. - Kroki: **Utwórz przesyłkę** z wybraną integracją wysyłkową, potem **Zaktualizuj status** na własny status, na przykład „Do spakowania". ![Formularz akcji: wyzwalacz Zamówienie, warunki Integracja jest i Status zamówienia jest, kroki Utwórz przesyłkę i Zaktualizuj status](https://ritevo.com/docs/automations/pl-order-action-shipment.webp) > **Warto wiedzieć:** Drugi krok wykona się, gdy przewoźnik odpowie - także wtedy, gdy przesyłka skończy się błędem. Jeśli status ma się zmienić tylko po udanej przesyłce, dodaj w drugim kroku rozgałęzienie z warunkiem **Status przesyłki jest** Utworzona pomyślnie, bez akcji domyślnej. Jeśli ta sama akcja mogłaby trafić na zamówienie więcej niż raz, dodaj warunek **Nie posiada przesyłki**. #### Faktura i przesyłka po opłaceniu - Wyzwalacz: **Zmiana danych płatności**. - Warunki: **Status płatności jest** Opłacone, **Nie posiada faktury**, **Nie posiada przesyłki**. - Kroki: **Wygeneruj fakturę**, potem **Utwórz przesyłkę**, potem **Wydrukuj etykietę przesyłki**. #### Oznaczenie zamówień zagranicznych - Wyzwalacz: **Zmiana statusu zamówienia**. - Warunki: **Status zamówienia zmienił się na** Potwierdzono, **Kraj dostawy nie jest** Polska. - Krok: **Zaktualizuj status** na własny status, na przykład „Zagranica". #### Jedna akcja, różni przewoźnicy - Wyzwalacz: **Zmiana statusu zamówienia**, warunek **Status zamówienia zmienił się na** Potwierdzono. - Krok **Utwórz przesyłkę** z rozgałęzieniami: wariant pierwszy z warunkiem **Kraj dostawy nie jest** Polska i integracją kuriera międzynarodowego, akcja domyślna z integracją krajową. ### Czego akcja dla zamówień nie zrobi - Nie wyśle wiadomości ani e-maila do klienta i nie użyje AI. Te kroki mają tylko [akcje dla wiadomości](https://ritevo.com/pl/docs/automations/message-actions). - Nie zadziała z opóźnieniem ani o ustalonej godzinie. Warunek **Wiek zamówienia większy niż (dni)** jest sprawdzany tylko wtedy, gdy w zamówieniu coś się zmieni - sam upływ czasu niczego nie uruchamia. - Nie wystawi dokumentu ani przesyłki bez ustawień, których te czynności wymagają także przy pracy ręcznej (szablon dokumentu, integracja wysyłkowa). ### Audyt wykonania Wykonania akcji dla zamówień znajdziesz w **Ustawienia → Audyt → Zamówienia**. Każdy wpis pokazuje akcję, numer kroku, wynik i ewentualny błąd. Znaczenie wyników opisuje strona [Jak działają akcje automatyczne](https://ritevo.com/pl/docs/automations/how-it-works#history). ### Przykład zapisu przez API Akcja „Faktura i przesyłka po opłaceniu" z sekcji Przykłady. Ogólne zasady zapisu są na stronie [Jak działają akcje automatyczne](https://ritevo.com/pl/docs/automations/how-it-works). ```json { "name": "Invoice and shipment after payment", "description": "Issues an invoice, creates a shipment and prints the label once the order is paid", "active": true, "userTimezone": "Europe/Warsaw", "triggerType": "PAYMENT_DATA_CHANGED", "conditions": [ { "type": "PAYMENT_STATUS_IS", "enumValues": [ "PAID" ] }, { "type": "HAS_INVOICE_NOT", "booleanValues": [ true ] }, { "type": "HAS_SHIPMENT_NOT", "booleanValues": [ true ] } ], "actionSteps": [ { "stepOrder": 1, "action": { "type": "GENERATE_INVOICE", "uuidValue": "" } }, { "stepOrder": 2, "action": { "type": "CREATE_SHIPMENT", "uuidValue": "" } }, { "stepOrder": 3, "action": { "type": "PRINT_SHIPMENT_LABEL", "uuidValue": "" } } ] } ``` --- Source: https://ritevo.com/pl/docs/automations/message-actions (updated 2026-09-26) ## Akcje automatyczne dla wiadomości Autoresponder i akcje automatyczne dla wiadomości w Ritevo: wyzwalacze, warunki z godzinami, odpowiedzi z szablonu i AI, ochrona przed pętlą. Akcja dla wiadomości reaguje na to, co dzieje się w skrzynce: nowy wątek, nową wiadomość, zmianę statusu. Najczęściej odpowiada klientowi - stałym tekstem, szablonem z danymi z wątku albo odpowiedzią napisaną przez AI - przypisuje wątek do konkretnego użytkownika, ustawia Twój własny status, oznacza wątek jako przeczytany lub ulubiony, dopisuje notatkę i wiele innych. Ogólne zasady opisuje strona [Jak działają akcje automatyczne](https://ritevo.com/pl/docs/automations/how-it-works). > **Wymagana integracja:** Potrzebujesz integracji z włączonym [pobieraniem wiadomości](https://ritevo.com/pl/docs/messages/fetching-messages). Krok **Wyślij wiadomość AI do wątku** wymaga dodatkowo integracji AI (OpenAI albo Claude), a **Wyślij wiadomość z szablonu do wątku** - zapisanego szablonu wiadomości. > **Warto wiedzieć:** Do każdej akcji, która odpowiada klientowi, dodaj warunek **Odebrano wiadomość od klienta**. Bez niego akcja zareaguje także na własne odpowiedzi i może się zapętlić - wyjaśnienie niżej. ### Gdzie znajdziesz akcje Akcje dla wiadomości są w menu **Wiadomości → Akcje** (w lewym panelu). Lista pokazuje przy każdej akcji jej wyzwalacz, warunki i kroki oraz to, czy jest aktywna. Nową akcję dodajesz przyciskiem **Dodaj nowa akcję** w prawym górnym rogu. Okruszki u góry strony (**Pulpit → Wiadomości → Akcje**) zawsze pokazują, gdzie jesteś. ![Lista akcji automatycznych dla wiadomości z podświetloną pozycją Akcje w lewym panelu; przycisk Dodaj nowa akcję w prawym górnym rogu jest zaznaczony ramką](https://ritevo.com/docs/automations/pl-message-actions-list.webp) Formularz akcji wygląda tak samo jak dla zamówień: u góry ustawienia podstawowe (nazwa, opis, wyzwalacz, strefa czasowa, **Aktywna**), po lewej warunki, po prawej kroki. ![Pusty formularz nowej akcji dla wiadomości: ustawienia podstawowe, karta warunku i karta kroku](https://ritevo.com/docs/automations/pl-message-action-form-empty.webp) ### Wyzwalacze - **Nowy wątek** (API: "Nowy wątek" = `NEW_THREAD`) - w Ritevo pojawił się wątek, którego wcześniej nie było. To zwykle pierwsza wiadomość klienta w danej sprawie. - **Odpowiedź w wątku** (API: "Odpowiedź w wątku" = `MESSAGE_RESPONSE`) - w istniejącym wątku pojawiła się nowa wiadomość. **Niezależnie od tego, kto ją napisał** - klient czy Ty. - **Odpowiedź z szablonu w wątku** (API: "Odpowiedź z szablonu w wątku" = `TEMPLATE_MESSAGE_RESPONSE`) - akcja automatyczna wysłała odpowiedź z szablonu. - **Odpowiedź AI w wątku** (API: "Odpowiedź AI w wątku" = `AI_MESSAGE_RESPONSE`) - akcja automatyczna wysłała odpowiedź AI. - **Zmiana statusu** (API: "Zmiana statusu" = `USER_DEFINED_STATUS_CHANGED`) - zmienił się Twój własny status wątku. - **Zmiana przypisania użytkownika**, **Zmiana statusu przeczytania**, **Zmiana statusu ulubionych**, **Zmiana własnej notatki**. (API: "Zmiana przypisania użytkownika" = `ASSIGNED_USER_CHANGED`, "Zmiana statusu przeczytania" = `READ_STATUS_CHANGED`, "Zmiana statusu ulubionych" = `FAVORITE_STATUS_CHANGED`, "Zmiana własnej notatki" = `OWN_NOTE_CHANGED`) Pierwsza wiadomość klienta uruchamia **Nowy wątek**, a każda następna w tej samej rozmowie - **Odpowiedź w wątku**. Wątek może być stary: klient, który kupował u Ciebie rok temu, często pisze w tej samej rozmowie i wtedy jest to **Odpowiedź w wątku**, a nie **Nowy wątek**. Dlatego autoresponder zawsze buduj jako **parę akcji** - jedną z wyzwalaczem **Nowy wątek** i drugą z wyzwalaczem **Odpowiedź w wątku**, z tymi samymi warunkami i krokami. ### Dlaczego warunek „od klienta" jest konieczny Wiadomości, które wysyłasz - ręcznie albo przez akcję - wracają do Ritevo przy kolejnym pobraniu z kanału i też są „nową wiadomością w wątku". Wyzwalacz **Odpowiedź w wątku** nie rozróżnia kierunku. Rozróżniają go dopiero warunki: - **Odebrano wiadomość od klienta** (API: "Odebrano wiadomość od klienta" = `MESSAGE_FROM_INTERLOCUTOR`; wartość w `booleanValues`: zawsze `[true]`) - ostatnia wiadomość w wątku jest od klienta. - **Wysłano wiadomość do klienta** (API: "Wysłano wiadomość do klienta" = `MESSAGE_FROM_SELF`; wartość w `booleanValues`: zawsze `[true]`) - ostatnia wiadomość jest od Ciebie. Akcja bez warunku **Odebrano wiadomość od klienta** **może się zapętlić**. Jej własna odpowiedź wraca przy kolejnym pobraniu wiadomości jako nowa wiadomość w wątku, akcja odpowiada na nią ponownie - i tak przy każdym pobraniu, bez końca. Bezpiecznik opisany na stronie ogólnej tego nie zatrzyma, bo między kolejnymi odpowiedziami mija kilka minut, a on reaguje na wiele wykonań w krótkim czasie. Klient dostawałby tę samą odpowiedź w kółko, dopóki nie wyłączysz akcji. Ten jeden warunek rozwiązuje problem u źródła, dlatego dodawaj go zawsze. ### Warunki #### Kto napisał i skąd - **Odebrano wiadomość od klienta** / **Wysłano wiadomość do klienta**. (API: "Odebrano wiadomość od klienta" = `MESSAGE_FROM_INTERLOCUTOR`, "Wysłano wiadomość do klienta" = `MESSAGE_FROM_SELF`; wartość w `booleanValues`: zawsze `[true]`) - **Integracja jest** / **Integracja nie jest** (API: "Integracja jest" = `INTEGRATION_IS`, "Integracja nie jest" = `INTEGRATION_IS_NOT`; wartość w `uuidValues`: id integracji z wiadomościami: `GET /integrations/marketplaces`, `GET /integrations/shops`, `GET /integrations/email`, `GET /integrations/messaging`) - z którego kanału pochodzi wątek. Wybierasz z listy swoich integracji - jedną albo kilka. Przy kilku wystarczy dowolna z nich. - **Typ konwersacji jest** / **Typ konwersacji nie jest** (API: "Typ konwersacji jest" = `THREAD_TYPE_IS`, "Typ konwersacji nie jest" = `THREAD_TYPE_IS_NOT`; wartość w `enumValues`: `MESSAGE`, `DISCUSSION`, `CLAIM`) - Wiadomość, Dyskusja albo Reklamacja; jedna albo kilka. - **Status konwersacji jest** / **Status konwersacji nie jest** (API: "Status konwersacji jest" = `THREAD_STATUS_IS`, "Status konwersacji nie jest" = `THREAD_STATUS_IS_NOT`; wartość w `enumValues`: `DISPUTE_ONGOING`, `DISPUTE_CLOSED`, `DISPUTE_UNRESOLVED`, `CLAIM_SUBMITTED`, `CLAIM_ACCEPTED`, `CLAIM_REJECTED`) - stan dyskusji lub reklamacji w kanale sprzedaży. #### Treść - **Wiadomość zawiera słowa kluczowe** / **Wiadomość nie zawiera słów kluczowych** (API: "Wiadomość zawiera słowa kluczowe" = `MESSAGE_CONTAINS_KEYWORDS`, "Wiadomość nie zawiera słów kluczowych" = `MESSAGE_NOT_CONTAINS_KEYWORDS`; wartość w `stringValues`: lista słów lub fragmentów tekstu; wystarczy dowolny z nich, wielkość liter nie ma znaczenia) - sprawdzana jest **ostatnia** wiadomość w wątku. Wystarczy jedno z podanych słów, wielkość liter nie ma znaczenia. - **Temat zawiera słowa kluczowe** / **Temat nie zawiera słów kluczowych**, **Własna notatka zawiera słowa kluczowe** / **Własna notatka nie zawiera słów kluczowych** (API: "Temat zawiera słowa kluczowe" = `TOPIC_CONTAINS_KEYWORDS`, "Temat nie zawiera słów kluczowych" = `TOPIC_NOT_CONTAINS_KEYWORDS`, "Własna notatka zawiera słowa kluczowe" = `OWN_NOTE_CONTAINS_KEYWORDS`, "Własna notatka nie zawiera słów kluczowych" = `OWN_NOTE_NOT_CONTAINS_KEYWORDS`; wartość w `stringValues`: lista słów lub fragmentów tekstu; wystarczy dowolny z nich, wielkość liter nie ma znaczenia) - działają tak samo. #### Godzina, dzień i data - **Godzina wykonania akcji od** / **do** (API: "Godzina wykonania akcji od" = `CURRENT_TIME_FROM`, "do" = `CURRENT_TIME_TO`; wartość w `offsetDateTimeValue`: data z czasem i przesunięciem strefy akcji; liczy się tylko godzina i minuta, na przykład `2026-01-10T16:00:00+01:00`) - która jest godzina w chwili, gdy akcja się wykonuje. - **Godzina wiadomości od** / **do** (API: "Godzina wiadomości od" = `MESSAGE_TIME_FROM`, "do" = `MESSAGE_TIME_TO`; wartość w `offsetDateTimeValue`: data z czasem i przesunięciem strefy akcji; liczy się tylko godzina i minuta, na przykład `2026-01-10T16:00:00+01:00`) - o której przyszła ostatnia wiadomość. - **Dzień wykonania akcji jest** / **nie jest**, **Dzień wiadomości jest** / **nie jest** (API: "Dzień wykonania akcji jest" = `CURRENT_DAY_OF_WEEK_IS`, "nie jest" = `CURRENT_DAY_OF_WEEK_IS_NOT`, "Dzień wiadomości jest" = `MESSAGE_DAY_OF_WEEK_IS`, "nie jest" = `MESSAGE_DAY_OF_WEEK_IS_NOT`; wartość w `integerValues`: liczby 1-7, gdzie 1 to poniedziałek, a 7 niedziela) - dni tygodnia. - **Data wykonania akcji od** / **do**, **Data wiadomości od** / **do** (API: "Data wykonania akcji od" = `CURRENT_DATE_FROM`, "do" = `CURRENT_DATE_TO`, "Data wiadomości od" = `MESSAGE_DATE_FROM`, "do" = `MESSAGE_DATE_TO`; wartość w `offsetDateTimeValue`: data z czasem i przesunięciem; liczy się cały moment) - na przykład na czas urlopu. > **Warto wiedzieć:** Godziny liczone są w strefie czasowej ustawionej w akcji. Przedział to dwa warunki (**od** i **do**), a granice się wliczają. Przedział przez północ wymaga dwóch akcji - [dlaczego](https://ritevo.com/pl/docs/automations/how-it-works#conditions). #### Stan wątku - **Status jest** / **Status nie jest** (API: "Status jest" = `USER_DEFINED_STATUS_IS`, "Status nie jest" = `USER_DEFINED_STATUS_IS_NOT`; wartość w `uuidValues`: id własnych statusów wątków: `GET /messages/statuses`) - Twoje własne statusy, jeden albo kilka. - **Przypisanym użytkownikiem jest** / **nie jest** (API: "Przypisanym użytkownikiem jest" = `ASSIGNED_USER_IS`, "nie jest" = `ASSIGNED_USER_IS_NOT`; wartość w `uuidValues`: id użytkowników firmy: `GET /company/users`) - jeden albo kilku użytkowników. - **Konwersacja jest przeczytana** / **Konwersacja nie jest przeczytana**, **Konwersacja jest w ulubionych** / **Konwersacja nie jest w ulubionych**. (API: "Konwersacja jest przeczytana" = `READ_STATUS_IS`, "Konwersacja nie jest przeczytana" = `READ_STATUS_IS_NOT`, "Konwersacja jest w ulubionych" = `FAVORITE_STATUS_IS`, "Konwersacja nie jest w ulubionych" = `FAVORITE_STATUS_IS_NOT`; wartość w `booleanValues`: lista z jedną wartością: `[true]` albo `[false]`) - **Brak notatki** / **Posiada notatkę** / **Notatka została usunięta**. (API: "Brak notatki" = `OWN_NOTE_IS_EMPTY`, "Posiada notatkę" = `OWN_NOTE_IS_NOT_EMPTY`, "Notatka została usunięta" = `OWN_NOTE_CHANGED_TO_EMPTY`; wartość w `booleanValues`: zawsze `[true]`) - **Status przeczytania zmienił się z** / **na**, **Status ulubiony zmienił się z** / **na** (API: "Status przeczytania zmienił się z" = `READ_STATUS_CHANGED_FROM`, "na" = `READ_STATUS_CHANGED_TO`, "Status ulubiony zmienił się z" = `FAVORITE_STATUS_CHANGED_FROM`, "na" = `FAVORITE_STATUS_CHANGED_TO`; wartość w `booleanValues`: lista z jedną wartością: `[true]` albo `[false]`) - reagują na samą zmianę. ### Kroki - co akcja może zrobić #### Odpowiedź do klienta - **Wyślij wiadomość do wątku** (API: "Wyślij wiadomość do wątku" = `SEND_MESSAGE_TO_THREAD`; wartość w `stringValue`: tekst do 2000 znaków) - stały tekst, do 2000 znaków. Wysyłany dosłownie, bez wstawianych wartości. - **Wyślij wiadomość z szablonu do wątku** (API: "Wyślij wiadomość z szablonu do wątku" = `TEMPLATE_SEND_MESSAGE_TO_THREAD`; wartość w `uuidValue`: id szablonu wiadomości: `GET /messages/templates`) - treść z zapisanego szablonu. Tylko w szablonie działają wstawiane wartości: **Rozmówca**, **Temat wątku**, **Status wątku**, **Numer zamówienia**, **Id zamówienia (zew.)**, **Id oferty (zew.)**. W edytorze szablonu klikasz wybraną wartość, a przy wysyłce podstawiają się dane z wątku. Jeśli wątek danej wartości nie ma (na przykład tematu albo id oferty), wstawia się ona jako pusta. - **Wyślij wiadomość AI do wątku** (API: "Wyślij wiadomość AI do wątku" = `AI_SEND_MESSAGE_TO_THREAD`; wartość w `uuidValue`: id integracji AI: `GET /integrations/ai`) - odpowiedź pisze wybrana integracja AI i Ritevo **od razu wysyła ją klientowi**. #### Jak działa odpowiedź AI - AI dostaje **treść ostatniej wiadomości klienta** oraz instrukcję, którą wpisałeś w ustawieniach integracji AI. Nie dostaje wcześniejszej historii wątku ani danych zamówienia. - Wszystko, co AI ma wiedzieć o Twojej firmie - godziny pracy, zasady zwrotów, ton odpowiedzi - wpisz w instrukcji integracji AI. - Nie ma trybu szkicu. Odpowiedź wychodzi do klienta bez Twojej akceptacji, więc zacznij od wąskich warunków, na przykład słów kluczowych albo jednego kanału. - Jeśli AI zwróci błąd, nic nie jest wysyłane, a błąd zobaczysz w audycie wiadomości. Koszt odpowiedzi rozlicza Twoje konto u dostawcy AI. #### Porządkowanie wątku - **Przypisz użytkownika** (API: "Przypisz użytkownika" = `UPDATE_ASSIGNED_USER`; wartość w `uuidValue`: id użytkownika z `GET /company/users`; `null` zdejmuje przypisanie) - także zdjęcie przypisania. - **Zaktualizuj status** (własny), **Zaktualizuj status przeczytania**, **Zaktualizuj status ulubione**, **Zaktualizuj własną notatkę**. (API: "Zaktualizuj status" = `UPDATE_USER_DEFINED_STATUS`; wartość w `uuidValue`: id własnych statusów wątków: `GET /messages/statuses` | "Zaktualizuj status przeczytania" = `UPDATE_READ_STATUS`, "Zaktualizuj status ulubione" = `UPDATE_FAVORITE_STATUS`; wartość w `booleanValue`: `true` albo `false` | "Zaktualizuj własną notatkę" = `UPDATE_OWN_NOTE`; wartość w `stringValue`: tekst do 255 znaków; `null` czyści notatkę) ### Przykład: autoresponder poza godzinami pracy Pracujesz od poniedziałku do piątku, 8:00-16:00. Klient, który napisze poza tym czasem, ma dostać informację, kiedy odpowiesz. > **Warto wiedzieć:** Każdą akcję poniżej tworzysz **dwa razy**: raz z wyzwalaczem **Nowy wątek** i raz z wyzwalaczem **Odpowiedź w wątku**. Warunki i krok są w obu takie same. Bez drugiej wersji autoresponder pominie klientów, którzy piszą w rozmowie istniejącej już w Ritevo - nawet jeśli poprzednia wiadomość była rok temu. #### Akcja 1 - weekend - Warunki: **Odebrano wiadomość od klienta**, **Dzień wykonania akcji jest** sobota, niedziela. - Krok: **Wyślij wiadomość z szablonu do wątku** z tekstem w rodzaju „Dziękujemy za wiadomość. Odpowiemy w najbliższy dzień roboczy." #### Akcja 2 - dni robocze po 16:00 - Warunki: **Odebrano wiadomość od klienta**, **Dzień wykonania akcji nie jest** sobota, niedziela, **Godzina wykonania akcji od** 16:00. - Krok: ten sam co w akcji 1. #### Akcja 3 - dni robocze przed 8:00 - Warunki: **Odebrano wiadomość od klienta**, **Dzień wykonania akcji nie jest** sobota, niedziela, **Godzina wykonania akcji do** 08:00. - Krok: ten sam co w akcji 1. Razem tworzysz sześć akcji: akcję 1, 2 i 3, każdą w dwóch wersjach - z wyzwalaczem **Nowy wątek** i z wyzwalaczem **Odpowiedź w wątku**. Akcje 2 i 3 są osobno, bo przedział 16:00-08:00 przechodzi przez północ. Warunek z dniem tygodnia w akcjach 2 i 3 pilnuje, żeby w weekend klient nie dostał dwóch odpowiedzi. ### Przykład: odpowiedź AI z przypisaniem pracownika Para akcji z aplikacji: na każdą wiadomość od klienta odpowiada AI, a wątek trafia do wybranego pracownika. Obie akcje mają te same warunki i kroki, różnią się tylko wyzwalaczem. #### Akcja 1 - wyzwalacz Nowy wątek - Wyzwalacz: **Nowy wątek**. - Warunek: **Odebrano wiadomość od klienta**. - Kroki: **Wyślij wiadomość AI do wątku** z wybraną integracją AI, potem **Przypisz użytkownika** do wybranej osoby. ![Formularz akcji: wyzwalacz Nowy wątek, warunek Odebrano wiadomość od klienta, kroki Wyślij wiadomość AI do wątku i Przypisz użytkownika](https://ritevo.com/docs/automations/pl-message-action-new-thread.webp) #### Akcja 2 - wyzwalacz Odpowiedź w wątku - To samo, tylko z wyzwalaczem **Odpowiedź w wątku** - dzięki temu AI odpowiada także na kolejne wiadomości klienta w tej samej rozmowie. ![Ta sama akcja z wyzwalaczem Odpowiedź w wątku](https://ritevo.com/docs/automations/pl-message-action-reply.webp) > **Warto wiedzieć:** Warunek **Odebrano wiadomość od klienta** jest tu konieczny: bez niego akcja 2 odpowiadałaby na własne odpowiedzi AI. Odpowiedź AI idzie do klienta od razu, więc zacznij od jednego kanału (warunek **Integracja jest**) i sprawdzaj wyniki w audycie. ### W których kanałach odpowiedź zadziała Akcja wysyła odpowiedź tą samą drogą, którą odpowiadasz ręcznie. Jeśli w danym kanale nie da się odpowiedzieć ręcznie, akcja też tego nie zrobi. Na stronie danej integracji sprawdzisz, czy możesz w niej odpowiadać na wiadomości, dyskusje i reklamacje. ### Czego akcja dla wiadomości nie zrobi - Nie wyśle załącznika. - Nie wstawi wartości z wątku w zwykłym tekście - tylko w szablonie. - Nie zamknie dyskusji ani reklamacji i nie zmieni ich stanu w kanale sprzedaży. - Nie odpowie z opóźnieniem ani „jeśli nikt nie odpisał przez godzinę". - Nie ma ograniczenia „raz na wątek" ani przerwy między odpowiedziami - zakres ustawiasz wyzwalaczem i warunkami. ### Audyt wykonania Wykonania znajdziesz w **Ustawienia → Audyt → Wiadomości**. Znaczenie wyników opisuje strona [Jak działają akcje automatyczne](https://ritevo.com/pl/docs/automations/how-it-works#history). ### Przykład zapisu przez API Akcja 2 z przykładu autorespondera (dni robocze po 16:00) w wersji z wyzwalaczem **Nowy wątek**. Drugą wersję tworzysz tak samo, zmieniając `triggerType` na `MESSAGE_RESPONSE`. Ogólne zasady zapisu są na stronie [Jak działają akcje automatyczne](https://ritevo.com/pl/docs/automations/how-it-works). ```json { "name": "Autoresponder - working days after 16:00 (new thread)", "description": "Tells the customer when we will reply", "active": true, "userTimezone": "Europe/Warsaw", "triggerType": "NEW_THREAD", "conditions": [ { "type": "MESSAGE_FROM_INTERLOCUTOR", "booleanValues": [ true ] }, { "type": "CURRENT_DAY_OF_WEEK_IS_NOT", "integerValues": [ 6, 7 ] }, { "type": "CURRENT_TIME_FROM", "offsetDateTimeValue": "2026-01-10T16:00:00+01:00" } ], "actionSteps": [ { "stepOrder": 1, "action": { "type": "TEMPLATE_SEND_MESSAGE_TO_THREAD", "uuidValue": "" } } ] } ``` --- Source: https://ritevo.com/pl/docs/general/errors (updated 2026-09-27) ## Błędy w aplikacji Komunikaty błędów w Ritevo: co oznacza każdy błąd przy zamówieniach, dokumentach, przesyłkach, magazynie, wiadomościach i integracjach, i co zrobić. Gdy operacja się nie uda, Ritevo pokazuje krótki komunikat. Poniżej wszystkie komunikaty pogrupowane według obszaru, z wyjaśnieniem, co oznaczają. #### Dane i zapytania - **Błąd walidacji** (API: "Błąd walidacji" = `VALIDATION_ERROR`) - wysłane dane są niepełne albo mają zły format, na przykład puste wymagane pole albo za długi tekst. Popraw zaznaczone pola i zapisz jeszcze raz. - **Nieprawidłowe żądanie** (API: "Nieprawidłowe żądanie" = `INVALID_REQUEST`) - zapytania nie da się odczytać, na przykład ma uszkodzoną treść. - **Nieprawidłowa wartość** (API: "Nieprawidłowa wartość" = `INVALID_ENUM`) - wybrana wartość nie należy do dozwolonej listy. - **Niewspierany format danych** (API: "Niewspierany format danych" = `UNSUPPORTED_MEDIA_TYPE`) - dane przyszły w formacie, którego Ritevo nie przyjmuje. - **Nieprawidłowy parametr** (API: "Nieprawidłowy parametr" = `INVALID_PARAMETER`) - parametr zapytania ma złą wartość, na przykład identyfikator w złym formacie. - **Brakujący parametr** (API: "Brakujący parametr" = `MISSING_PARAMETER`) - w zapytaniu brakuje wymaganego parametru. - **Błąd wewnętrzny** (API: "Błąd wewnętrzny" = `INTERNAL_ERROR`) - błąd po stronie Ritevo. Spróbuj ponownie za chwilę; jeśli się powtarza, napisz do nas. #### Limity - **Przekroczono limit** (API: "Przekroczono limit" = `LIMIT_EXCEPTION`) - osiągnięto limit, na przykład liczby integracji, akcji albo elementów w jednej operacji. #### Audyt - **Nie znaleziono loga audytu** (API: "Nie znaleziono loga audytu" = `AUDIT_LOG_NOT_FOUND`) - wpis historii zmian nie istnieje albo należy do innej firmy. #### Akcje automatyczne - **Błąd walidacji kroku akcji** (API: "Błąd walidacji kroku akcji" = `ACTION_STEP_VALIDATION`) - krok akcji jest niepełny albo ma niepoprawne ustawienia. - **Nie znaleziono automatycznej akcji** (API: "Nie znaleziono automatycznej akcji" = `AUTOMATIC_ACTION_NOT_FOUND`) - akcja nie istnieje albo została usunięta. - **Błąd walidacji warunku** (API: "Błąd walidacji warunku" = `CONDITION_VALIDATION`) - warunek akcji jest niepełny albo ma niepoprawną wartość. - **Wykryto cykliczną zależność** (API: "Wykryto cykliczną zależność" = `CYCLIC_DEPENDENCY`) - zapisanie akcji spowodowałoby pętlę - akcje uruchamiałyby się nawzajem bez końca. Zmień wyzwalacz albo kroki. #### Integracje - **Nie znaleziono integracji** (API: "Nie znaleziono integracji" = `INTEGRATION_NOT_FOUND`) - integracja nie istnieje, została usunięta albo należy do innej firmy. - **Nie znaleziono integracji AI** (API: "Nie znaleziono integracji AI" = `AI_INTEGRATION_NOT_FOUND`) - wskazana integracja AI nie istnieje albo została usunięta. - **Nieprawidłowy model** (API: "Nieprawidłowy model" = `INVALID_MODEL`) - wybrany model AI nie jest dostępny u tego dostawcy albo na Twoim koncie. - **Nieprawidłowy token** (API: "Nieprawidłowy token" = `INVALID_TOKEN`) - dostawca AI odrzucił podany klucz API. Sprawdź klucz w panelu dostawcy. #### Dokumenty - **Dokument rozliczeniowy już istnieje** (API: "Dokument rozliczeniowy już istnieje" = `BILLING_ALREADY_EXISTS`) - dla tego zamówienia jest już taki dokument. - **Dokument już został przeniesiony** (API: "Dokument już został przeniesiony" = `BILLING_ALREADY_TRANSFERRED`) - dokument został już wysłany do integracji księgowej i nie można go zmienić. - **Nie znaleziono zewnętrznego transferu** (API: "Nie znaleziono zewnętrznego transferu" = `BILLING_EXTERNAL_TRANSFER_NOT_FOUND`) - nie ma zapisu wysyłki tego dokumentu do integracji księgowej. - **Dokument ma już korektę** (API: "Dokument ma już korektę" = `BILLING_HAS_CORRECTION`) - do tego dokumentu wystawiono już korektę. - **Dokument nie ma korekty** (API: "Dokument nie ma korekty" = `BILLING_HAS_NO_CORRECTION`) - operacja wymaga korekty, a dokument jej nie ma. - **Nie znaleziono pozycji dokumentu** (API: "Nie znaleziono pozycji dokumentu" = `BILLING_LINE_ITEM_NOT_FOUND`) - wskazana pozycja nie istnieje w dokumencie. - **Nie znaleziono dokumentu rozliczeniowego** (API: "Nie znaleziono dokumentu rozliczeniowego" = `BILLING_NOT_FOUND`) - dokument nie istnieje albo należy do innej firmy. - **Nie znaleziono dokumentów rozliczeniowych** (API: "Nie znaleziono dokumentów rozliczeniowych" = `BILLINGS_NOT_FOUND`) - nie znaleziono żadnego z wybranych dokumentów. - **Nie znaleziono ustawień dla typu rozliczenia** (API: "Nie znaleziono ustawień dla typu rozliczenia" = `BILLING_SETTINGS_BY_BILLING_TYPE_NOT_FOUND`) - brakuje ustawień dla tego rodzaju dokumentu, na przykład numeracji dla paragonów. - **Nie znaleziono ustawień rozliczenia** (API: "Nie znaleziono ustawień rozliczenia" = `BILLING_SETTINGS_NOT_FOUND`) - wskazane ustawienia dokumentów nie istnieją. - **Błąd referencji ustawień rozliczenia** (API: "Błąd referencji ustawień rozliczenia" = `BILLING_SETTINGS_REFERENCE`) - tych ustawień nie da się usunąć, bo są już na nich wystawione dokumenty. - **Nie można usunąć domyślnych ustawień** (API: "Nie można usunąć domyślnych ustawień" = `DEFAULT_BILLING_SETTINGS_DELETION`) - domyślnych ustawień dokumentów nie da się usunąć. - **Podany dokument nie jest wspierany przez tę integrację** (API: "Podany dokument nie jest wspierany przez tę integrację" = `BILLING_TYPE_NOT_SUPPORTED`) - wybrana integracja nie wystawia tego rodzaju dokumentu, na przykład korekty albo paragonu. - **Stawka podatku nie jest wspierana** (API: "Stawka podatku nie jest wspierana" = `TAX_RATE_NOT_SUPPORTED`) - integracja nie obsługuje stawki VAT z tej pozycji. #### Zamówienia - **Nie znaleziono zamówień** (API: "Nie znaleziono zamówień" = `ORDERS_NOT_FOUND`) - nie znaleziono żadnego z wybranych zamówień. - **Nie znaleziono zamówienia** (API: "Nie znaleziono zamówienia" = `ORDER_NOT_FOUND`) - zamówienie nie istnieje albo należy do innej firmy. - **Nie znaleziono pozycji zamówienia** (API: "Nie znaleziono pozycji zamówienia" = `ORDER_LINE_ITEM_NOT_FOUND`) - wskazana pozycja nie istnieje w zamówieniu. - **Zamówienie nie jest kompatybilne z wybraną integracją lub metodą wysyłki** (API: "Zamówienie nie jest kompatybilne z wybraną integracją lub metodą wysyłki" = `ORDER_AND_SHIPPING_COMPATIBILITY`) - przesyłki nie da się utworzyć tą integracją, na przykład zamówienie z innego konta Allegro niż to podłączone do Wysyłam z Allegro. #### Przesyłki i paczki - **Nie znaleziono przesyłki** (API: "Nie znaleziono przesyłki" = `SHIPMENT_NOT_FOUND`) - przesyłka nie istnieje albo należy do innego zamówienia. - **Ilość w paczce przekracza ilość z zamówienia** (API: "Ilość w paczce przekracza ilość z zamówienia" = `PACKAGE_QUANTITY_EXCEEDED`) - do paczki dodano więcej sztuk, niż jest w zamówieniu. - **Etykieta nie pasuje do żadnej przesyłki zamówienia** (API: "Etykieta nie pasuje do żadnej przesyłki zamówienia" = `PACKAGE_LABEL_NOT_FOUND`) - zeskanowana etykieta nie należy do przesyłek tego zamówienia. - **Etykieta została już użyta w innej paczce** (API: "Etykieta została już użyta w innej paczce" = `PACKAGE_LABEL_ALREADY_USED`) - tę etykietę przypisano już do innej paczki. #### Produkty i magazyn - **Nie znaleziono produktu** (API: "Nie znaleziono produktu" = `PRODUCT_NOT_FOUND`) - produkt nie istnieje albo należy do innej firmy. - **Produkt o tym SKU już istnieje** (API: "Produkt o tym SKU już istnieje" = `PRODUCT_SKU_ALREADY_EXISTS`) - w magazynie jest już produkt z tym samym SKU. - **Nie znaleziono stanu magazynowego** (API: "Nie znaleziono stanu magazynowego" = `STOCK_NOT_FOUND`) - dla produktu nie ma zapisanego stanu. - **Stan magazynowy nie pasuje do produktu** (API: "Stan magazynowy nie pasuje do produktu" = `STOCK_PRODUCT_MISMATCH`) - wskazany stan należy do innego produktu. - **Nie znaleziono ceny** (API: "Nie znaleziono ceny" = `PRICE_NOT_FOUND`) - dla produktu nie ma zapisanej ceny. - **Cena już istnieje** (API: "Cena już istnieje" = `PRICE_ALREADY_EXISTS`) - produkt ma już cenę, którą próbujesz dodać. - **Pozycja nie ma identyfikatora oferty** (API: "Pozycja nie ma identyfikatora oferty" = `EXTERNAL_OFFER_ID_REQUIRED`) - pozycji zamówienia nie da się powiązać z produktem, bo kanał sprzedaży nie przekazał numeru oferty. - **Oferta jest już powiązana z innym produktem** (API: "Oferta jest już powiązana z innym produktem" = `EXTERNAL_OFFER_ALREADY_ASSIGNED`) - ta oferta jest już przypisana do innego produktu w magazynie. #### Statusy - **Nie znaleziono statusu** (API: "Nie znaleziono statusu" = `STATUS_NOT_FOUND`) - status nie istnieje albo został usunięty. - **Błąd operacji na statusie** (API: "Błąd operacji na statusie" = `STATUS_OPERATION`) - tej operacji nie da się wykonać, na przykład usunąć statusu domyślnego albo zastąpić statusu nim samym. #### Wiadomości - **Nie znaleziono wiadomości** (API: "Nie znaleziono wiadomości" = `MESSAGE_NOT_FOUND`) - wątek nie istnieje albo należy do innej firmy. - **Nie znaleziono wiadomości** (API: "Nie znaleziono wiadomości" = `MESSAGES_NOT_FOUND`) - nie znaleziono żadnego z wybranych wątków. - **Błąd operacji na wiadomości** (API: "Błąd operacji na wiadomości" = `MESSAGE_OPERATION`) - tej operacji nie da się wykonać dla tego typu wątku, na przykład zakończyć reklamacji w zwykłej wiadomości. - **Nie znaleziono szablonu wiadomości** (API: "Nie znaleziono szablonu wiadomości" = `MESSAGE_TEMPLATE_NOT_FOUND`) - szablon nie istnieje albo został usunięty. - **Integracja nie obsługuje wiadomości** (API: "Integracja nie obsługuje wiadomości" = `MESSAGES_NOT_SUPPORTED`) - ten kanał nie ma wiadomości. - **Wiadomości tej integracji obsługujesz przez e-mail** (API: "Wiadomości tej integracji obsługujesz przez e-mail" = `MESSAGES_SUPPORTED_BY_EMAIL`) - kupujący piszą e-mailem - obsłużysz ich przez integrację e-mail. - **Ta integracja nie wspiera odpowiadania na wiadomości** (API: "Ta integracja nie wspiera odpowiadania na wiadomości" = `MESSAGE_REPLY_NOT_SUPPORTED`) - w tym kanale albo typie wątku nie da się odpowiedzieć z Ritevo. - **Ta integracja nie wspiera dodawania załączników** (API: "Ta integracja nie wspiera dodawania załączników" = `MESSAGE_ATTACHMENT_UPLOAD_NOT_SUPPORTED`) - ten kanał nie przyjmuje załączników w odpowiedziach. - **Ta integracja nie wspiera pobierania załączników** (API: "Ta integracja nie wspiera pobierania załączników" = `MESSAGE_ATTACHMENT_DOWNLOAD_NOT_SUPPORTED`) - plik otworzysz tylko w panelu kanału sprzedaży. - **Wiadomość jest za długa** (API: "Wiadomość jest za długa" = `MESSAGE_LENGTH_EXCEEDED`) - odpowiedź przekracza 2000 znaków. #### Inne - **Błąd zewnętrznego dostawcy** (API: "Błąd zewnętrznego dostawcy" = `EXTERNAL_EXCEPTION`) - kanał sprzedaży, kurier albo inny dostawca odrzucił operację. Treść błędu od dostawcy zobaczysz w komunikacie. - **Nieoczekiwany błąd** (API: "Nieoczekiwany błąd" = `UNEXPECTED`) - coś poszło nie tak po stronie Ritevo. Spróbuj ponownie; jeśli się powtarza, napisz do nas. ### Błędy w API Błędy API mają format Problem Details (RFC 9457) i zwracają trzy pola: - `code` - jeden z kodów błędów opisanych wyżej. - `title` - krótki tytuł błędu. - `detail` - zwykle szczegółowy opis tego, co poszło nie tak w danym zapytaniu. --- Source: https://ritevo.com/pl/docs/integrations/allegro (updated 2026-10-10) ## Allegro Integracja Allegro z Ritevo: podłączenie konta przez logowanie, pobieranie zamówień i wiadomości, faktury, dyskusje i reklamacje, ponowne połączenie. Integracja z Allegro pobiera do Ritevo zamówienia oraz wiadomości, dyskusje i reklamacje z Twojego konta sprzedawcy. Podłączasz ją przez zwykłe logowanie w Allegro - bez kluczy i haseł wpisywanych w Ritevo. > **Wymagana integracja:** Potrzebujesz aktywnego konta sprzedawcy w Allegro. Jedno konto Allegro podłączasz raz; jeśli sprzedajesz z kilku kont, każde dodajesz jako osobną integrację. To samo konto Allegro podłączysz tylko raz. Gdy podłączysz je ponownie, Ritevo odświeży istniejącą integrację i włączy ją z powrotem, nawet jeśli była usunięta. Unikalność: integracja jest unikalna w ramach firmy po `externalId` i typie `ALLEGRO`. Ponowne utworzenie odświeża istniejącą integrację zamiast tworzyć nową: od razu ustawia `authError=false`, a jeśli integracja była nieaktywna - także `active=true`. Przy `authError` to jedyny sposób na przywrócenie połączenia. ### Podłączenie konta Całość zajmuje minutę. Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Marketplace** wybierz kafelek **Allegro**. 3. Kliknij **Dodaj integrację**. Ritevo przekieruje Cię na stronę logowania Allegro. 4. Zaloguj się na konto sprzedawcy i zatwierdź dostęp dla Ritevo. Allegro odeśle Cię z powrotem do Ritevo. 5. Wróć do Ritevo i chwilę poczekaj - nie zamykaj okna. Gdy dodawanie się zakończy, otworzą się ustawienia nowej integracji. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Allegro w sekcji Marketplace](https://ritevo.com/docs/integrations/allegro/pl-catalogue.webp) ![Ekran dodawania integracji Allegro z przyciskiem Dodaj integrację](https://ritevo.com/docs/integrations/allegro/pl-add.webp) ![Strona logowania Allegro, na którą przekierowuje Ritevo](https://ritevo.com/docs/integrations/allegro/pl-login.webp) > **Warto wiedzieć:** Ritevo nie widzi Twojego hasła do Allegro. Logujesz się na stronie Allegro, a Ritevo dostaje od Allegro tylko zgodę na dostęp do konta. Zgodę możesz w każdej chwili cofnąć w ustawieniach konta Allegro - integracja przestanie wtedy działać i pokaże **Wymaga ponownego połączenia**. ### Ustawienia integracji Po podłączeniu integracja jest **Aktywna**, ale pobieranie zamówień i wiadomości jest **wyłączone** - włączasz je sam, osobno: - **Nazwa konta** - login Twojego konta Allegro. Ritevo pobiera go z Allegro, nie da się go zmienić. - **Pobieranie zamówień** - po włączeniu Ritevo sprawdza nowe i zmienione zamówienia mniej więcej co 10 minut. Zasady wspólne dla wszystkich kanałów: [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders). - **Pobieranie wiadomości** - po włączeniu Ritevo pobiera wiadomości mniej więcej co 10 minut, przy pierwszym pobraniu sięgając 7 dni wstecz. Zasady wspólne: [Pobieranie wiadomości](https://ritevo.com/pl/docs/messages/fetching-messages). ![Szczegóły integracji Allegro: nazwa konta oraz przełączniki Pobieranie zamówień i Pobieranie wiadomości](https://ritevo.com/docs/integrations/allegro/pl-details.webp) ### Co daje ta integracja - **Zamówienia** - nowe i zaktualizowane zamówienia z Allegro trafiają do tabeli zamówień, z danymi kupującego, danymi do faktury, dostawą (także punktem odbioru) i pozycjami ze zdjęciami ofert. - **Wiadomości** - rozmowy z Centrum wiadomości oraz **dyskusje** i **reklamacje** trafiają do wspólnej skrzynki. Na wszystkie trzy odpowiadasz z Ritevo, także z załącznikami. - **Nadawanie przesyłek** przez Wysyłam z Allegro to osobna integracja, którą dodajesz po podłączeniu konta - korzysta z tego samego konta Allegro. ### Zamówienia z Allegro Ritevo pobiera z Allegro całe zamówienie: kupującego, płatność, dostawę razem z punktem odbioru, pozycje z cenami i zdjęciami ofert oraz wiadomość od kupującego. Allegro przekazuje przez API komplet tych danych, więc niczego nie trzeba uzupełniać ręcznie. - **Statusy i płatności** - statusy i metody płatności z Allegro są tłumaczone na statusy Ritevo w jeden, stały sposób; marketplace'y nie mają własnych mapowań, jak sklepy internetowe. Zamówienie za pobraniem przychodzi jako **Ocz. na płatność** z metodą **Płatność przy odbiorze**. - **Usługi dodatkowe** - obsługiwane. Gdy kupujący dokupi do produktu na przykład pakowanie na prezent albo wniesienie, zobaczysz je w zamówieniu jako osobną pozycję pod tym produktem - także gdy są darmowe. Więcej o [usługach dodatkowych](https://ritevo.com/pl/docs/orders/fetching-orders#additional-services). - **Faktura** - Allegro jawnie przekazuje, czy kupujący poprosił o fakturę. Takie zamówienie dostaje oznaczenie **Klient prosi o fakturę**, a dane firmy i numer podatkowy są wpisane. > **Warto wiedzieć:** Zamówienie ze statusem **Potwierdzono** przejmuje Ritevo - późniejsze zmiany po stronie kanału sprzedaży są pomijane. Więcej w [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders#who-manages). ### Wiadomości, dyskusje i reklamacje z Allegro - **Wiadomości** z Centrum wiadomości - do Ritevo trafiają tylko wiadomości, które Allegro już dostarczyło. Twoją odpowiedź Allegro najpierw sprawdza, więc potwierdzenie wysyłki może potrwać do pół minuty. - **Dyskusje** i **reklamacje** - z tematem, opisem, terminem na decyzję, żądaniem kupującego (naprawa, wymiana, zwrot pieniędzy, częściowy zwrot) i powiązanym zamówieniem. Odpowiadasz na nie z Ritevo, możesz też zakończyć dyskusję oraz rozpatrzyć reklamację - zaakceptować lub odrzucić z podaniem powodu. - Jeśli wiadomość dotyczy zamówienia, którego nie ma jeszcze w Ritevo, samo je dociągamy - także przy wyłączonym pobieraniu zamówień. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy zgoda udzielona Ritevo w Allegro wygasła albo została cofnięta - na przykład po zmianie hasła w Allegro lub po odłączeniu aplikacji w ustawieniach konta. Do czasu ponownego połączenia Ritevo nie pobiera ani nie wysyła żadnych danych na tym koncie. 1. Przejdź przez **Podłączenie konta** jeszcze raz, logując się na **to samo** konto Allegro. 2. Ritevo rozpozna konto po jego identyfikatorze i odświeży połączenie w istniejącej integracji. Ustawienia pobierania i historia zostają bez zmian - nie powstaje druga integracja. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie zarządza ofertami: nie wystawia, nie zmienia cen ani stanów magazynowych w Allegro. ### Integracja przez API Endpointy tej integracji są pod `/integrations/marketplaces/allegro`, a wspólne dla całego typu (lista, pobranie jednej, przełączniki pobierania, usunięcie, przywrócenie) pod `/integrations/marketplaces`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/ebay (updated 2026-10-10) ## eBay Integracja eBay z Ritevo: podłączenie konta przez logowanie w eBay, pobieranie zamówień i wiadomości, co eBay przekazuje przez API, ponowne połączenie. Integracja z eBay pobiera do Ritevo zamówienia i wiadomości od kupujących z Twojego konta sprzedawcy. Podłączasz ją przez zwykłe logowanie w eBay - bez kluczy i haseł wpisywanych w Ritevo. > **Wymagana integracja:** Potrzebujesz aktywnego konta sprzedawcy w eBay. Jedno konto eBay podłączasz raz; jeśli sprzedajesz z kilku kont, każde dodajesz jako osobną integrację. To samo konto eBay podłączysz tylko raz. Gdy podłączysz je ponownie, Ritevo odświeży istniejącą integrację i włączy ją z powrotem, nawet jeśli była usunięta. Unikalność: integracja jest unikalna w ramach firmy po `externalId` i typie `EBAY`. Ponowne utworzenie odświeża istniejącą integrację zamiast tworzyć nową: od razu ustawia `authError=false`, a jeśli integracja była nieaktywna - także `active=true`. Przy `authError` to jedyny sposób na przywrócenie połączenia. ### Podłączenie konta Całość zajmuje minutę. Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Marketplace** wybierz kafelek **Ebay**. 3. Kliknij **Dodaj integrację**. Ritevo przekieruje Cię na stronę logowania eBay. 4. Zaloguj się na konto sprzedawcy i zatwierdź dostęp dla Ritevo. eBay odeśle Cię z powrotem do Ritevo. 5. Wróć do Ritevo i chwilę poczekaj - nie zamykaj okna. Gdy dodawanie się zakończy, otworzą się ustawienia nowej integracji. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Ebay w sekcji Marketplace](https://ritevo.com/docs/integrations/ebay/pl-catalogue.webp) ![Ekran dodawania integracji eBay z przyciskiem Dodaj integrację](https://ritevo.com/docs/integrations/ebay/pl-add.webp) ![Strona logowania eBay, na którą przekierowuje Ritevo](https://ritevo.com/docs/integrations/ebay/pl-login.webp) > **Warto wiedzieć:** Ritevo nie widzi Twojego hasła do eBay. Logujesz się na stronie eBay, a Ritevo dostaje od eBay tylko zgodę na dostęp do konta. Zgodę możesz w każdej chwili cofnąć w ustawieniach konta eBay - integracja przestanie wtedy działać i pokaże **Wymaga ponownego połączenia**. ### Ustawienia integracji Po podłączeniu integracja jest **Aktywna**, ale pobieranie zamówień i wiadomości jest **wyłączone** - włączasz je sam, osobno: - **Nazwa konta** - login Twojego konta eBay. Ritevo pobiera go z eBay, nie da się go zmienić. - **Pobieranie zamówień** - po włączeniu Ritevo sprawdza nowe i zmienione zamówienia mniej więcej co 10 minut. Zasady wspólne dla wszystkich kanałów: [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders). - **Pobieranie wiadomości** - po włączeniu Ritevo pobiera wiadomości mniej więcej co 10 minut, przy pierwszym pobraniu sięgając 7 dni wstecz. Zasady wspólne: [Pobieranie wiadomości](https://ritevo.com/pl/docs/messages/fetching-messages). ![Szczegóły integracji eBay: nazwa konta oraz przełączniki Pobieranie zamówień i Pobieranie wiadomości](https://ritevo.com/docs/integrations/ebay/pl-details.webp) ### Co daje ta integracja - **Zamówienia** - nowe i zaktualizowane zamówienia z eBay trafiają do tabeli zamówień, z danymi kupującego, dostawą, pozycjami i zdjęciami ofert. - **Wiadomości** - rozmowy z kupującymi trafiają do wspólnej skrzynki. Odpowiadasz z Ritevo, także ze zdjęciami w załączniku. ### Zamówienia z eBay Ritevo pobiera z eBay całe zamówienie: kupującego, płatność, dostawę, pozycje z cenami (po rabatach) i zdjęciami ofert. eBay udostępnia przez API tylko zamówienia opłacone i gotowe do realizacji, więc każde przychodzi do Ritevo jako **Potwierdzono**. Anulowania, zwroty i spory rozstrzygasz po stronie eBay - nie zmieniają one statusu w Ritevo. - **Statusy i płatności** - statusy i metody płatności z eBay są tłumaczone na statusy Ritevo w jeden, stały sposób; marketplace'y nie mają własnych mapowań, jak sklepy internetowe. Zamówienie za pobraniem przychodzi jako **Ocz. na płatność** z metodą **Płatność przy odbiorze**. - **Punkty odbioru** - eBay nie przekazuje ich przez API; zamówienie przychodzi z adresem dostawy. - **Wysyłka międzynarodowa przez eBay** (eBay International Shipping) - jako adres dostawy widzisz magazyn eBay, do którego wysyłasz paczkę, a nie adres kupującego. - **Usługi dodatkowe** - nieobsługiwane. Ta integracja nie przekazuje usług takich jak pakowanie na prezent czy wniesienie. Jeśli chcesz je sprzedawać, wystaw je jako osobny produkt albo ofertę - w zamówieniu pojawią się wtedy jako zwykła pozycja. Więcej o [usługach dodatkowych](https://ritevo.com/pl/docs/orders/fetching-orders#additional-services). - **Faktura** - jeśli eBay przekaże numer podatkowy kupującego (na przykład NIP) albo jego odpowiednik, zamówienie dostaje oznaczenie **Klient prosi o fakturę**, a dane firmy i numer są wpisane. > **Warto wiedzieć:** Zamówienie ze statusem **Potwierdzono** przejmuje Ritevo - późniejsze zmiany po stronie kanału sprzedaży są pomijane. Więcej w [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders#who-manages). ### Wiadomości z eBay - Do Ritevo trafiają wiadomości od kupujących z Twojej skrzynki eBay. Odpowiadasz z Ritevo; w załączniku możesz wysłać **tylko obrazy** (zdjęcia), bo tak działa eBay. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy zgoda udzielona Ritevo w eBay wygasła albo została cofnięta - na przykład po zmianie hasła w eBay lub po odłączeniu aplikacji w ustawieniach konta. Do czasu ponownego połączenia Ritevo nie pobiera ani nie wysyła żadnych danych na tym koncie. 1. Przejdź przez **Podłączenie konta** jeszcze raz, logując się na **to samo** konto eBay. 2. Ritevo rozpozna konto po jego identyfikatorze i odświeży połączenie w istniejącej integracji. Ustawienia pobierania i historia zostają bez zmian - nie powstaje druga integracja. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie zarządza ofertami: nie wystawia, nie zmienia cen ani stanów magazynowych w eBay. ### Integracja przez API Endpointy tej integracji są pod `/integrations/marketplaces/ebay`, a wspólne dla całego typu (lista, pobranie jednej, przełączniki pobierania, usunięcie, przywrócenie) pod `/integrations/marketplaces`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. Usunięcie konta po stronie eBay: gdy eBay zgłosi usunięcie konta użytkownika (Marketplace Account Deletion), Ritevo od razu anonimizuje każdą integrację z tym kontem - ustawia `active=false`, zamienia nazwę konta na zastępczą i kasuje tokeny. Wcześniej pobrane zamówienia i wiadomości zostają. --- Source: https://ritevo.com/pl/docs/integrations/empik (updated 2026-10-10) ## Empik Integracja Empik Marketplace z Ritevo: podłączenie kluczem API, pobieranie zamówień i wiadomości, automatyczne przyjmowanie zamówień, dyskusje i incydenty. Integracja z Empik Marketplace pobiera do Ritevo zamówienia oraz wiadomości i dyskusje z Twojego konta sprzedawcy. Podłączasz ją kluczem API z panelu sprzedawcy Empik. > **Wymagana integracja:** Potrzebujesz aktywnego konta sprzedawcy w Empik i klucza API wygenerowanego w jego panelu. Jedno konto Empik podłączasz raz; jeśli sprzedajesz z kilku kont, każde dodajesz jako osobną integrację. To samo konto Empik podłączysz tylko raz. Gdy podłączysz je ponownie, Ritevo odświeży istniejącą integrację i włączy ją z powrotem, nawet jeśli była usunięta. Unikalność: integracja jest unikalna w ramach firmy po `externalId` i typie `EMPIK`. Ponowne utworzenie odświeża istniejącą integrację zamiast tworzyć nową: od razu ustawia `authError=false`, a jeśli integracja była nieaktywna - także `active=true`. Nowe dane podasz też przez `PATCH /integrations/marketplaces/empik/{id}/token` - w każdym stanie integracji, także gdy `authError=false` i `active=true`; ustawia `authError=false` i `active=true`. ### Jak wygenerować klucz API Klucz API tworzysz w panelu sprzedawcy Empik. Skopiuj go w całości - wkleisz go w Ritevo przy dodawaniu integracji. 1. Zaloguj się do panelu sprzedawcy Empik Marketplace. 2. Kliknij swoją nazwę użytkownika w prawym górnym rogu i przejdź do ustawień konta. 3. Wybierz **Klucz API**. 4. Kliknij **Wygeneruj nowy klucz**. Jeśli klucz już istnieje, po prostu go skopiuj. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Marketplace** wybierz kafelek **Empik**. 3. W polu **API Token** wklej klucz API z panelu sprzedawcy Empik. 4. Kliknij **Dodaj integrację**. Ritevo od razu sprawdza klucz w Empik: jeśli jest poprawny, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd zwrócony przez Empik i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Empik w sekcji Marketplace](https://ritevo.com/docs/integrations/empik/pl-catalogue.webp) ![Ekran dodawania integracji Empik z polem API Token i przyciskiem Dodaj integrację](https://ritevo.com/docs/integrations/empik/pl-add.webp) ### Ustawienia integracji Po podłączeniu integracja jest **Aktywna**, ale pobieranie zamówień i wiadomości jest **wyłączone** - włączasz je sam, osobno: - **Nazwa konta** - nazwa Twojego konta sprzedawcy, którą Ritevo pobiera z Empik. Nie da się jej zmienić. - **Pobieranie zamówień** - po włączeniu Ritevo sprawdza nowe i zmienione zamówienia mniej więcej co 10 minut. Zasady wspólne dla wszystkich kanałów: [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders). - **Pobieranie wiadomości** - po włączeniu Ritevo pobiera wiadomości mniej więcej co 10 minut, przy pierwszym pobraniu sięgając 7 dni wstecz. Zasady wspólne: [Pobieranie wiadomości](https://ritevo.com/pl/docs/messages/fetching-messages). ![Szczegóły integracji Empik: nazwa konta, przełączniki Pobieranie zamówień i Pobieranie wiadomości oraz przycisk Zaktualizuj dane logowania](https://ritevo.com/docs/integrations/empik/pl-details.webp) > **Warto wiedzieć:** Klucz możesz podmienić w każdej chwili tym samym przyciskiem **Zaktualizuj dane logowania**, nie tylko po błędzie. ### Co daje ta integracja - **Zamówienia** - nowe i zaktualizowane zamówienia z Empik trafiają do tabeli zamówień, z danymi kupującego, danymi do faktury, dostawą (także punktem odbioru) i pozycjami. - **Wiadomości i dyskusje** - rozmowy z kupującymi oraz zgłoszenia (incydenty) trafiają do wspólnej skrzynki. ### Zamówienia z Empik Ritevo pobiera z Empik całe zamówienie: kupującego, płatność, dostawę razem z punktem odbioru, pozycje i wiadomość od kupującego. Zamówienia czekające na przyjęcie Ritevo **przyjmuje automatycznie** - nie musisz ich akceptować w panelu Empik. - **Statusy i płatności** - statusy i metody płatności z Empik są tłumaczone na statusy Ritevo w jeden, stały sposób; marketplace'y nie mają własnych mapowań, jak sklepy internetowe. Zamówienie za pobraniem przychodzi jako **Ocz. na płatność** z metodą **Płatność przy odbiorze**. - **Usługi dodatkowe** - nieobsługiwane. Ta integracja nie przekazuje usług takich jak pakowanie na prezent czy wniesienie. Jeśli chcesz je sprzedawać, wystaw je jako osobny produkt albo ofertę - w zamówieniu pojawią się wtedy jako zwykła pozycja. Więcej o [usługach dodatkowych](https://ritevo.com/pl/docs/orders/fetching-orders#additional-services). - **Faktura** - jeśli Empik przekaże numer podatkowy kupującego (na przykład NIP) albo jego odpowiednik, zamówienie dostaje oznaczenie **Klient prosi o fakturę**, a dane firmy i numer są wpisane. > **Warto wiedzieć:** Zamówienie ze statusem **Potwierdzono** przejmuje Ritevo - późniejsze zmiany po stronie kanału sprzedaży są pomijane. Więcej w [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders#who-manages). ### Wiadomości i dyskusje z Empik - **Wiadomości** - rozmowy z kupującymi z panelu Empik. Odpowiadasz z Ritevo, także z załącznikami. - **Dyskusje** - to zgłoszenia (incydenty) do pozycji zamówienia. Empik nie pozwala odpowiadać wewnątrz zgłoszenia, dlatego przy dyskusji Ritevo pokazuje **istniejące konwersacje z tym kupującym dla tego zamówienia** - odpowiadasz w nich jak w zwykłej wiadomości - oraz przycisk **Napisz do kupującego w nowej konwersacji**, gdy takiej rozmowy jeszcze nie ma. Samo zgłoszenie zamykasz z tego miejsca przyciskiem **Rozwiąż incydent**, podając powód. - Jeśli wiadomość dotyczy zamówienia, którego nie ma jeszcze w Ritevo, samo je dociągamy - także przy wyłączonym pobieraniu zamówień. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy klucz API przestał działać - został unieważniony w panelu Empik albo stracił uprawnienia. Do czasu podania nowego klucza Ritevo nie pobiera ani nie wysyła żadnych danych na tym koncie. 1. W panelu sprzedawcy Empik wygeneruj nowy klucz API. 2. Na stronie integracji w Ritevo kliknij **Zaktualizuj dane logowania**, wklej nowy klucz i zatwierdź. Ritevo sprawdza go w Empik tak samo jak przy dodawaniu - zły klucz zwróci błąd, poprawny odświeży połączenie. Ustawienia pobierania i historia zostają bez zmian. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie zarządza ofertami: nie wystawia, nie zmienia cen ani stanów magazynowych w Empik. ### Integracja przez API Endpointy tej integracji są pod `/integrations/marketplaces/empik`, a wspólne dla całego typu (lista, pobranie jednej, przełączniki pobierania, usunięcie, przywrócenie) pod `/integrations/marketplaces`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/erli (updated 2026-10-10) ## Erli Integracja Erli z Ritevo: podłączenie konta kluczem API, pobieranie zamówień, punkty odbioru, wiadomości od kupujących przez e-mail, ponowne połączenie. Integracja z Erli pobiera do Ritevo zamówienia z Twojego konta sprzedawcy. Podłączasz ją kluczem API z panelu sprzedawcy Erli. Wiadomości od kupujących Erli wysyła e-mailem - obsługujesz je w Ritevo przez integrację e-mail. > **Wymagana integracja:** Potrzebujesz aktywnego konta sprzedawcy w Erli i klucza API wygenerowanego w jego panelu. Jedno konto Erli podłączasz raz; jeśli sprzedajesz z kilku kont, każde dodajesz jako osobną integrację. To samo konto Erli podłączysz tylko raz. Gdy podłączysz je ponownie, Ritevo odświeży istniejącą integrację i włączy ją z powrotem, nawet jeśli była usunięta. Unikalność: integracja jest unikalna w ramach firmy po `externalId` i typie `ERLI`. Ponowne utworzenie odświeża istniejącą integrację zamiast tworzyć nową: od razu ustawia `authError=false`, a jeśli integracja była nieaktywna - także `active=true`. Nowe dane podasz też przez `PATCH /integrations/marketplaces/erli/{id}/token` - w każdym stanie integracji, także gdy `authError=false` i `active=true`; ustawia `authError=false` i `active=true`. ### Jak wygenerować klucz API Klucz API tworzysz w panelu sprzedawcy Erli. Skopiuj go w całości - wkleisz go w Ritevo przy dodawaniu integracji. 1. Zaloguj się do panelu sprzedawcy Erli. 2. W prawym górnym rogu otwórz **Moje ERLI** i wybierz **Ustawienia sklepu**. 3. W menu po lewej wybierz **Metoda integracji**, a potem **Własna integracja po API**. 4. W polu **Opis klucza** wpisz dowolną nazwę, na przykład „Ritevo", i kliknij **Wygeneruj nowy klucz**. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Marketplace** wybierz kafelek **Erli**. 3. W polu **API Token** wklej klucz API z panelu sprzedawcy Erli. 4. Kliknij **Dodaj integrację**. Ritevo od razu sprawdza klucz w Erli: jeśli jest poprawny, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd zwrócony przez Erli i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Erli w sekcji Marketplace](https://ritevo.com/docs/integrations/erli/pl-catalogue.webp) ![Ekran dodawania integracji Erli z polem API Token i przyciskiem Dodaj integrację](https://ritevo.com/docs/integrations/erli/pl-add.webp) ### Ustawienia integracji Po podłączeniu integracja jest **Aktywna**, ale pobieranie zamówień i wiadomości jest **wyłączone** - włączasz je sam, osobno: - **Nazwa konta** - nazwa Twojego konta sprzedawcy, którą Ritevo pobiera z Erli. Nie da się jej zmienić. - **Pobieranie zamówień** - po włączeniu Ritevo sprawdza nowe i zmienione zamówienia mniej więcej co 10 minut. Zasady wspólne dla wszystkich kanałów: [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders). - **Pobieranie wiadomości** - zamiast przełącznika jest tu informacja, że wiadomości z Erli obsługujemy przez integrację e-mail, i przycisk **Dodaj integrację**, który prowadzi do jej dodania. ![Szczegóły integracji Erli: nazwa konta, przełącznik Pobieranie zamówień, karta wiadomości odsyłająca do integracji e-mail oraz przycisk Zaktualizuj dane logowania](https://ritevo.com/docs/integrations/erli/pl-details.webp) > **Warto wiedzieć:** Klucz możesz podmienić w każdej chwili tym samym przyciskiem **Zaktualizuj dane logowania**, nie tylko po błędzie. ### Co daje ta integracja - **Zamówienia** - nowe i zaktualizowane zamówienia z Erli trafiają do tabeli zamówień, z danymi kupującego, danymi do faktury, dostawą (także punktem odbioru) i pozycjami ze zdjęciami. - **Wiadomości** - przez integrację e-mail, patrz niżej. ### Zamówienia z Erli Ritevo pobiera z Erli całe zamówienie: kupującego, płatność, dostawę razem z punktem odbioru, pozycje z cenami i zdjęciami produktów. - **Statusy i płatności** - statusy i metody płatności z Erli są tłumaczone na statusy Ritevo w jeden, stały sposób; marketplace'y nie mają własnych mapowań, jak sklepy internetowe. Zamówienie za pobraniem przychodzi jako **Ocz. na płatność** z metodą **Płatność przy odbiorze**. - **Zwroty** - zamówienie, do którego kupujący zgłosił zwrot, Erli nadal pokazuje jako zakupione; w Ritevo zostaje **Potwierdzono**. - **Usługi dodatkowe** - nieobsługiwane. Ta integracja nie przekazuje usług takich jak pakowanie na prezent czy wniesienie. Jeśli chcesz je sprzedawać, wystaw je jako osobny produkt albo ofertę - w zamówieniu pojawią się wtedy jako zwykła pozycja. Więcej o [usługach dodatkowych](https://ritevo.com/pl/docs/orders/fetching-orders#additional-services). - **Faktura** - jeśli Erli przekaże numer podatkowy kupującego (na przykład NIP) albo jego odpowiednik, zamówienie dostaje oznaczenie **Klient prosi o fakturę**, a dane firmy i numer są wpisane. > **Warto wiedzieć:** Zamówienie ze statusem **Potwierdzono** przejmuje Ritevo - późniejsze zmiany po stronie kanału sprzedaży są pomijane. Więcej w [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders#who-manages). ### Wiadomości od kupujących z Erli Erli nie ma własnej skrzynki wiadomości - kupujący piszą do Ciebie **e-mailem** na adres podany w Twoim koncie Erli. Żeby te wiadomości widzieć i odpowiadać na nie w Ritevo, dodaj [integrację e-mail](https://ritevo.com/pl/docs/messages/fetching-messages) dla tej skrzynki. Wiadomości pojawią się wtedy w Ritevo jak zwykłe e-maile; nie są powiązane z integracją Erli ani z jej zamówieniami. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy klucz API przestał działać - został unieważniony w panelu Erli albo stracił uprawnienia. Do czasu podania nowego klucza Ritevo nie pobiera ani nie wysyła żadnych danych na tym koncie. 1. W panelu sprzedawcy Erli wygeneruj nowy klucz API. 2. Na stronie integracji w Ritevo kliknij **Zaktualizuj dane logowania**, wklej nowy klucz i zatwierdź. Ritevo sprawdza go w Erli tak samo jak przy dodawaniu - zły klucz zwróci błąd, poprawny odświeży połączenie. Ustawienia pobierania i historia zostają bez zmian. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie zarządza ofertami: nie wystawia, nie zmienia cen ani stanów magazynowych w Erli. - Nie pobiera wiadomości ani dyskusji - Erli nie udostępnia ich przez API. ### Integracja przez API Endpointy tej integracji są pod `/integrations/marketplaces/erli`, a wspólne dla całego typu (lista, pobranie jednej, przełączniki pobierania, usunięcie, przywrócenie) pod `/integrations/marketplaces`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/own-sales-channel (updated 2026-09-27) ## Własny kanał sprzedaży Własny kanał sprzedaży w Ritevo: integracja dla zamówień spoza marketplace'ów i sklepów - telefon, e-mail, sprzedaż stacjonarna - które dodajesz ręcznie. Własny kanał sprzedaży to integracja bez zewnętrznego systemu. Najczęściej służy jako **POS - szybka sprzedaż na miejscu**: klient kupuje w sklepie stacjonarnym lub na stoisku, a Ty od razu dodajesz zamówienie w Ritevo. Sprawdzi się też przy zamówieniach przyjmowanych przez telefon, e-mailem czy na komunikatorze. Dzięki temu takie zamówienia mają swoje źródło, tak jak zamówienia z Allegro czy eBay, i działają na nich te same akcje automatyczne, dokumenty i przesyłki. > **Wymagana integracja:** Nie potrzebujesz żadnego konta ani klucza. Własnych kanałów możesz utworzyć dowolnie wiele - na przykład osobny dla każdego punktu sprzedaży (POS): sklepu stacjonarnego, stoiska na targach czy sprzedaży telefonicznej. Każdy jest osobną integracją, więc zamówienia z każdego miejsca odfiltrujesz osobno i ustawisz dla nich osobne akcje automatyczne. Unikalność: dla typu `OWN` nie jest sprawdzana - każde utworzenie daje nowy kanał. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Marketplace** wybierz kafelek **Własny kanał sprzedaży**. 3. W polu **Nazwa konta** wpisz dowolną nazwę, pod którą będziesz widzieć ten kanał, na przykład „Sprzedaż telefoniczna". 4. Kliknij **Utwórz integrację**. Otworzą się ustawienia nowego kanału. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Własny kanał sprzedaży w sekcji Marketplace](https://ritevo.com/docs/integrations/own/pl-catalogue.webp) ![Ekran dodawania własnego kanału sprzedaży z polem Nazwa konta i przyciskiem Utwórz integrację](https://ritevo.com/docs/integrations/own/pl-add.webp) ### Ustawienia kanału Własny kanał ma tylko pole **Nazwa konta**, które możesz w każdej chwili zmienić i zapisać przyciskiem **Zaktualizuj integrację**. Nie ma pobierania zamówień ani wiadomości - nie ma skąd ich pobierać. ![Szczegóły własnego kanału sprzedaży: nazwa konta i przycisk Zaktualizuj integrację](https://ritevo.com/docs/integrations/own/pl-details.webp) ### Zamówienia we własnym kanale Zamówienie dodajesz ręcznie w tabeli zamówień, wybierając ten kanał jako źródło. Wypełniasz w nim to, co potrzebujesz: kupującego, dane do faktury, dostawę, pozycje i płatność. Od tej chwili działa jak każde inne zamówienie w Ritevo - możesz wystawić do niego dokument, nadać przesyłkę, zmienić status, a akcje automatyczne z warunkiem **Integracja jest** ustawionym na ten kanał zadziałają tak samo jak dla marketplace'ów. ### Usunięcie integracji **Usuń integrację** oznacza kanał jako wyłączony na liście integracji; zamówienia dodane wcześniej zostają, a kanał nadal można wybrać przy ręcznym dodawaniu zamówienia. **Przywróć integrację** włącza go z powrotem. ### Czego integracja nie robi - Nie pobiera zamówień ani wiadomości i nie aktualizuje żadnych ofert - to tylko źródło dla zamówień dodanych ręcznie. ### Integracja przez API Endpointy tej integracji są pod `/integrations/marketplaces/own`, a wspólne dla całego typu (lista, pobranie jednej, przełączniki pobierania, usunięcie, przywrócenie) pod `/integrations/marketplaces`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/woocommerce (updated 2026-10-17) ## WooCommerce Integracja WooCommerce z Ritevo: klucze REST API, podłączenie sklepu, mapowanie statusów, płatności i pól wtyczek (NIP, paczkomat), pobieranie zamówień. Integracja z WooCommerce pobiera do Ritevo zamówienia z Twojego sklepu na WordPressie. Podłączasz ją kluczami REST API wygenerowanymi w panelu WooCommerce. Ponieważ sklepy na WooCommerce różnią się wtyczkami, sam ustawiasz, jak statusy, metody płatności i pola dodane przez wtyczki (NIP, punkt odbioru) mają być czytane w Ritevo. > **Wymagana integracja:** Potrzebujesz działającego sklepu WooCommerce i dostępu do jego panelu administracyjnego, żeby wygenerować klucze API. Ten sam sklep WooCommerce podłączysz tylko raz. Gdy dodasz go ponownie, Ritevo odświeży istniejącą integrację i włączy ją z powrotem, nawet jeśli była usunięta. Unikalność: integracja jest unikalna w ramach firmy po `externalId` i typie `WOOCOMMERCE`; `externalId` to adres sklepu bez końcowego `/` (adres z `/` na końcu jest zapisywany bez niego). Ponowne utworzenie z tym samym adresem odświeża istniejącą integrację zamiast tworzyć nową: podmienia dane logowania, ustawia `authError=false` i `active=true` i zwraca tę integrację. Nowe dane logowania podasz też przez `PATCH /integrations/shops/woocommerce/{integrationId}/credentials` - w każdym stanie integracji, także gdy `authError=false` i `active=true`; ustawia `authError=false` i `active=true`. ### Jak wygenerować klucz API Klucze tworzysz w panelu WordPress swojego sklepu. Skopiuj oba od razu - wkleisz je w Ritevo przy dodawaniu integracji. 1. Zaloguj się do panelu WordPress i w menu po lewej wybierz **WooCommerce**, potem **Ustawienia**. 2. Otwórz zakładkę **Zaawansowane**, a w niej **REST API**. Kliknij **Dodaj klucz**. 3. W polu **Opis** wpisz dowolną nazwę, na przykład „Ritevo". W polu **Użytkownik** wybierz konto administratora sklepu. 4. W polu **Uprawnienia** wybierz **Odczyt/Zapis** - najwyższe dostępne - i kliknij **Wygeneruj klucz API**. 5. Skopiuj **Klucz klienta** (Consumer Key) i **Sekret klienta** (Consumer Secret). > **Warto wiedzieć:** Sekret klienta WooCommerce pokazuje tylko raz, zaraz po wygenerowaniu. Jeśli zamkniesz stronę bez skopiowania, wygeneruj nowy klucz. Klucz z uprawnieniem tylko **Odczyt** nie zadziała - Ritevo odrzuci go przy dodawaniu. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Sklepy internetowe** wybierz kafelek **WooCommerce**. 3. W polu **Nazwa konta** wpisz własną nazwę integracji, na przykład nazwę sklepu. 4. W polu **Adres sklepu** wpisz pełny adres sklepu razem z `https://`, bez końcowego ukośnika i bez `/wp-admin` - na przykład `https://mojsklep.pl`. 5. W polach **Consumer Key** i **Consumer Secret** wklej klucze z panelu WooCommerce. 6. Kliknij **Dodaj integrację**. Ritevo od razu łączy się ze sklepem i sprawdza dane: jeśli są poprawne, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd zwrócony przez sklep i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem WooCommerce w sekcji Sklepy internetowe](https://ritevo.com/docs/integrations/woocommerce/pl-catalogue.webp) ![Ekran dodawania integracji WooCommerce z polami Nazwa konta, Adres sklepu, Consumer Key i Consumer Secret](https://ritevo.com/docs/integrations/woocommerce/pl-add.webp) ### Ustawienia integracji Po podłączeniu integracja jest **Aktywna**, ale pobieranie zamówień jest **wyłączone** - włączasz je sam. Na stronie integracji znajdziesz: - **Nazwa konta** - Twoja własna nazwa tej integracji, na przykład nazwa sklepu. Możesz ją zmienić w każdej chwili. - **Adres sklepu** - adres podany przy dodawaniu. Tutaj nie da się go zmienić; nowy adres lub nowe klucze podajesz przez **Zaktualizuj dane logowania**. - **Pobieranie zamówień** - po włączeniu Ritevo sprawdza nowe i zmienione zamówienia mniej więcej co 10 minut. Zasady wspólne dla wszystkich kanałów: [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders). - **Mapowanie statusów zamówień**, **Mapowanie metod płatności** i **Zaawansowane mapowanie** - opisane niżej. ![Szczegóły integracji WooCommerce: nazwa konta, adres sklepu, przełącznik Pobieranie zamówień i karta Mapowanie statusów zamówień](https://ritevo.com/docs/integrations/woocommerce/pl-details.webp) > **Warto wiedzieć:** Klucz możesz podmienić w każdej chwili tym samym przyciskiem **Zaktualizuj dane logowania**, nie tylko po błędzie. ### Mapowanie statusów i płatności Każdy sklep nazywa statusy zamówień i metody płatności po swojemu, dlatego przy sklepach internetowych sam decydujesz, jak mają być tłumaczone na statusy i metody Ritevo. Mapowanie ustawiasz raz, na stronie integracji, i dotyczy ono każdego zamówienia pobieranego od tej chwili. > **Warto wiedzieć:** Mapowanie możesz w każdej chwili dowolnie zmienić według swoich potrzeb - także przypisania wpisane z góry, które są tylko ustawieniami startowymi. #### Mapowanie statusów zamówień Listę statusów Ritevo pobiera z Twojego sklepu, razem ze statusami dodanymi przez wtyczki, więc widzisz je pod takimi nazwami jak w panelu WooCommerce. **Na start** przypisane są standardowe statusy WooCommerce. **Sam przypisujesz** statusy dodane przez wtyczki. Przypisanie startowe: - **Potwierdzono** (API: "Potwierdzono" = `CONFIRMED`; wartość w `orderStatusMappings[].status`) - W trakcie realizacji, Zrealizowane, Zwrócone. Zwrócone zamówienie było prawdziwą sprzedażą, dlatego zostaje potwierdzone - zwrot rozliczasz osobno. - **Anulowano** (API: "Anulowano" = `CANCELLED`; wartość w `orderStatusMappings[].status`) - Anulowano. - **Ocz. na płatność** (API: "Ocz. na płatność" = `WAITING_FOR_PAYMENT`; wartość w `orderStatusMappings[].status`) - Oczekujące na płatność, Nieudane. - **Ocz. na potwierdzenie** (API: "Ocz. na potwierdzenie" = `WAITING_FOR_CONFIRMATION`; wartość w `orderStatusMappings[].status`) - Wstrzymane (oczekujące na płatność). Jeden status Ritevo może mieć przypisanych kilka statusów sklepu, ale jeden status sklepu tylko jeden status Ritevo. Zamówienie ze statusem, którego nigdzie nie przypisałeś, trafia jako **Ocz. na potwierdzenie** - zobaczysz je i zdecydujesz, co dalej. #### Mapowanie metod płatności Listę metod Ritevo pobiera z bramek płatności włączonych w Twoim sklepie. **Na start** przypisane są metody wbudowane w WooCommerce. **Sam przypisujesz** bramki z wtyczek (PayU, Przelewy24, Stripe i inne), bo każdy sklep ma inne. Przypisanie startowe: - **Przelew** (API: "Przelew" = `BANK_TRANSFER`; wartość w `paymentMethodMappings[].paymentMethod`) - Przelew bankowy, Płatność czekiem. - **Płatność przy odbiorze** (API: "Płatność przy odbiorze" = `CASH_ON_DELIVERY`; wartość w `paymentMethodMappings[].paymentMethod`) - Za pobraniem. Płatność metodą, której nigdzie nie przypisałeś, trafia jako **Inne**. ![Karta Mapowanie metod płatności integracji WooCommerce z przypisanymi metodami Przelew bankowy, Płatność czekiem i Za pobraniem](https://ritevo.com/docs/integrations/woocommerce/pl-payments.webp) #### Zaawansowane mapowanie - pola z wtyczek WooCommerce nie ma standardowych pól na NIP, prośbę o fakturę ani punkt odbioru - dodają je wtyczki, każda pod własną nazwą pola. W tej karcie wskazujesz, z którego pola zamówienia Ritevo ma czytać każdą z tych danych. **Na start** wpisane są nazwy pól popularnych wtyczek. **Sam dopisujesz** nazwy pól innych wtyczek, a niepotrzebne usuwasz. - **NIP / numer VAT** (API: "NIP / numer VAT" = `TAX_ID`; wartość w `fieldMappings[].field`) - pole z numerem podatkowym kupującego. Gdy ma wartość, zamówienie dostaje dane firmy i numer do faktury. - **Żądanie faktury** (API: "Żądanie faktury" = `INVOICE_REQUESTED`; wartość w `fieldMappings[].field`) - pole, z którego Ritevo odczytuje, czy kupujący chce fakturę. Liczy się sama wartość w polu: jeśli jest tam „0", „nie", „no", „false" albo „off", prośby o fakturę nie ma; każda inna wartość (na przykład „1", „tak", „yes") to prośba o fakturę. Gdy pole jest puste, prośba o fakturę jest wtedy, gdy kupujący podał NIP. - **Identyfikator punktu odbioru** (API: "Identyfikator punktu odbioru" = `PICKUP_POINT_ID`; wartość w `fieldMappings[].field`) - pole z kodem paczkomatu lub punktu (na przykład `WAW123`). - **Nazwa punktu odbioru** i **Opis punktu odbioru** (API: "Nazwa punktu odbioru" = `PICKUP_POINT_NAME`, "Opis punktu odbioru" = `PICKUP_POINT_DESCRIPTION`; wartość w `fieldMappings[].field`) - pola z nazwą i adresem punktu, jeśli wtyczka je zapisuje. - **Kraj punktu odbioru** (API: "Kraj punktu odbioru" = `PICKUP_POINT_COUNTRY`; wartość w `fieldMappings[].field`) - zwykle zostaje puste; wtedy Ritevo bierze kraj z adresu dostawy. Nazwę pola znajdziesz w ustawieniach wtyczki albo w szczegółach zamówienia testowego. Wpisz ją dokładnie - wielkość liter i podkreślenie na początku mają znaczenie. W jednym polu możesz podać kilka nazw (na przykład po zmianie wtyczki): Ritevo użyje pierwszej, która w zamówieniu ma wartość. ![Karta Zaawansowane mapowanie integracji WooCommerce z polami NIP / numer VAT, Żądanie faktury i polami punktu odbioru oraz przyciski Zaktualizuj dane logowania i Zaktualizuj integrację](https://ritevo.com/docs/integrations/woocommerce/pl-advanced.webp) > **Warto wiedzieć:** Zmiany mapowania zapisujesz przyciskiem **Zaktualizuj integrację** na dole strony. Działają od następnego pobrania - zamówienia pobrane wcześniej nie zmieniają statusu wstecz. Mapowania zapisujesz przez `PATCH /integrations/shops/woocommerce/{integrationId}` razem z `accountName`: `orderStatusMappings` (`{ status, externalIds }`), `paymentMethodMappings` (`{ paymentMethod, externalIds }`) i `fieldMappings` (`{ field, keys }`) z każdą wartością z listy wyżej. Każda lista musi zawierać wszystkie wartości swojego enuma - nieprzypisaną wartość wysyłasz z pustą listą. `externalIds` to slugi statusów i identyfikatory bramek płatności z WooCommerce. Aktualny kształt jest w Swaggerze. ### Co daje ta integracja - **Zamówienia** - nowe i zmienione zamówienia z WooCommerce trafiają do tabeli zamówień, z danymi kupującego, danymi do faktury, dostawą (także punktem odbioru z wtyczki) i pozycjami ze zdjęciami produktów. ### Zamówienia z WooCommerce Ritevo pobiera z WooCommerce całe zamówienie: kupującego, adres rozliczeniowy i dostawy, metodę dostawy, płatność, pozycje z cenami brutto i zdjęciami produktów. Zamówienie zmienione w sklepie (na przykład nowy status) jest pobierane ponownie. - **Statusy i płatności** - tłumaczone według Twojego mapowania, opisanego wyżej. - **Faktura** - dane firmy i NIP są czytane z pól wskazanych w sekcji **Zaawansowane mapowanie**; bez nazwy firmy i bez NIP-u zamówienie nie ma danych do faktury. Prośba o fakturę wynika z pola **Żądanie faktury** i daje oznaczenie **Klient prosi o fakturę**. - **Punkt odbioru** - kod i nazwa punktu są czytane z pól wskazanych w sekcji **Zaawansowane mapowanie**; bez nich zamówienie ma tylko adres dostawy. - **Uwagi kupującego** - uwaga do zamówienia wpisana w koszyku trafia do zamówienia jako wiadomość od kupującego. - **Usługi dodatkowe** - obsługiwane. Opłaty doliczone w sklepie do zamówienia, na przykład za pakowanie na prezent albo wniesienie, zobaczysz jako osobne pozycje dla całego zamówienia. Rabat dodany jako opłata pojawi się z kwotą na minusie. Więcej o [usługach dodatkowych](https://ritevo.com/pl/docs/orders/fetching-orders#additional-services). - **Zakup bez konta** - zamówienie gościa pobiera się normalnie; kupujący nie ma wtedy identyfikatora klienta sklepu. > **Warto wiedzieć:** Zamówienie ze statusem **Potwierdzono** przejmuje Ritevo - późniejsze zmiany po stronie kanału sprzedaży są pomijane. Więcej w [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders#who-manages). ### Wymaga ponownego połączenia Ten stan pojawia się, gdy sklep przestał akceptować dane logowania - klucz został usunięty w panelu sklepu, stracił uprawnienia albo zmienił się adres sklepu. Do czasu podania nowych danych Ritevo nie pobiera ani nie wysyła żadnych danych z tego sklepu. 1. W panelu sklepu wygeneruj nowe klucze - tak samo jak przy pierwszym podłączeniu. 2. Na stronie integracji w Ritevo kliknij **Zaktualizuj dane logowania**, podaj adres sklepu i nowe klucze i zatwierdź. Ritevo sprawdza je w sklepie tak samo jak przy dodawaniu - błędne dane zwrócą błąd, poprawne odświeżą połączenie. Mapowania, ustawienia pobierania i historia zostają bez zmian. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie zarządza ofertami: nie wystawia, nie zmienia cen ani stanów magazynowych w WooCommerce. - Nie pobiera wiadomości - WooCommerce nie ma skrzynki wiadomości od kupujących. Klienci piszą e-mailem, więc dodaj [integrację e-mail](https://ritevo.com/pl/docs/messages/fetching-messages) dla skrzynki sklepu. - Nie przesyła nic z powrotem do WooCommerce: gdy w Ritevo zmienisz status zamówienia, nadasz przesyłkę albo wystawisz fakturę, zamówienie w WooCommerce zostaje bez zmian. ### Integracja przez API Endpointy tej integracji są pod `/integrations/shops/woocommerce`, a wspólne dla całego typu (lista, pobranie jednej, przełączniki pobierania, usunięcie, przywrócenie) pod `/integrations/shops`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/prestashop (updated 2026-10-17) ## PrestaShop Integracja PrestaShop z Ritevo: klucz webservice, podłączenie sklepu, mapowanie statusów i modułów płatności, zamówienia i wiadomości z obsługi klienta. Integracja z PrestaShop pobiera do Ritevo zamówienia i wiadomości z obsługi klienta Twojego sklepu. Podłączasz ją kluczem webservice wygenerowanym w panelu PrestaShop. Statusy i moduły płatności sklepu tłumaczysz na statusy Ritevo w mapowaniu na stronie integracji. > **Wymagana integracja:** Potrzebujesz działającego sklepu PrestaShop i dostępu do jego panelu administracyjnego, żeby wygenerować klucze API. Ten sam sklep PrestaShop podłączysz tylko raz. Gdy dodasz go ponownie, Ritevo odświeży istniejącą integrację i włączy ją z powrotem, nawet jeśli była usunięta. Unikalność: integracja jest unikalna w ramach firmy po `externalId` i typie `PRESTASHOP`; `externalId` to adres sklepu bez końcowego `/` (adres z `/` na końcu jest zapisywany bez niego). Ponowne utworzenie z tym samym adresem odświeża istniejącą integrację zamiast tworzyć nową: podmienia dane logowania, ustawia `authError=false` i `active=true` i zwraca tę integrację. Nowe dane logowania podasz też przez `PATCH /integrations/shops/prestashop/{integrationId}/credentials` - w każdym stanie integracji, także gdy `authError=false` i `active=true`; ustawia `authError=false` i `active=true`. ### Jak wygenerować klucz API Klucz tworzysz w panelu administracyjnym PrestaShop. Skopiuj go w całości - wkleisz go w Ritevo przy dodawaniu integracji. 1. Zaloguj się do panelu PrestaShop i w menu po lewej wybierz **Zaawansowane**, potem **Webservice**. 2. W sekcji **Konfiguracja** ustaw **Włącz webservice PrestaShop** na **Tak** i zapisz. 3. Kliknij **Dodaj nowy klucz webservice**. Kliknij **Generuj**, a w polu **Opis klucza** wpisz dowolną nazwę, na przykład „Ritevo". 4. W tabeli **Uprawnienia** zaznacz **wszystko**: każdy zasób i każde działanie (Widok, Dodaj, Modyfikuj, Usuń). Ustaw **Status** na **Tak** i zapisz. Klucz skopiuj z pola **Klucz**. > **Warto wiedzieć:** Zaznacz pełne uprawnienia, nawet jeśli dziś Ritevo korzysta tylko z części - klucz z brakującym dostępem daje niepełne zamówienia albo nie pobiera wiadomości, a nowe funkcje Ritevo zadziałają wtedy bez zmian w kluczu. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Sklepy internetowe** wybierz kafelek **PrestaShop**. 3. W polu **Nazwa konta** wpisz własną nazwę integracji, na przykład nazwę sklepu. 4. W polu **Adres sklepu** wpisz pełny adres sklepu razem z `https://`, bez końcowego ukośnika i bez `/api` - na przykład `https://mojsklep.pl`. 5. W polu **Klucz webservice** wklej klucz z panelu PrestaShop. 6. Kliknij **Dodaj integrację**. Ritevo od razu łączy się ze sklepem i sprawdza dane: jeśli są poprawne, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd zwrócony przez sklep i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem PrestaShop w sekcji Sklepy internetowe](https://ritevo.com/docs/integrations/prestashop/pl-catalogue.webp) ![Ekran dodawania integracji PrestaShop z polami Nazwa konta, Adres sklepu i Klucz webservice](https://ritevo.com/docs/integrations/prestashop/pl-add.webp) ### Ustawienia integracji Po podłączeniu integracja jest **Aktywna**, ale pobieranie zamówień jest **wyłączone** - włączasz je sam. Na stronie integracji znajdziesz: - **Nazwa konta** - Twoja własna nazwa tej integracji, na przykład nazwa sklepu. Możesz ją zmienić w każdej chwili. - **Adres sklepu** - adres podany przy dodawaniu. Tutaj nie da się go zmienić; nowy adres lub nowe klucze podajesz przez **Zaktualizuj dane logowania**. - **Pobieranie zamówień** - po włączeniu Ritevo sprawdza nowe i zmienione zamówienia mniej więcej co 10 minut. Zasady wspólne dla wszystkich kanałów: [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders). - **Pobieranie wiadomości** - po włączeniu Ritevo pobiera wątki z obsługi klienta mniej więcej co 10 minut, przy pierwszym pobraniu sięgając 7 dni wstecz. Zasady wspólne: [Pobieranie wiadomości](https://ritevo.com/pl/docs/messages/fetching-messages). - **Mapowanie statusów zamówień** i **Mapowanie metod płatności** - opisane niżej. ![Szczegóły integracji PrestaShop: informacja o punktach odbioru, nazwa konta, adres sklepu oraz przełączniki Pobieranie zamówień i Pobieranie wiadomości](https://ritevo.com/docs/integrations/prestashop/pl-details.webp) > **Warto wiedzieć:** Klucz możesz podmienić w każdej chwili tym samym przyciskiem **Zaktualizuj dane logowania**, nie tylko po błędzie. ### Mapowanie statusów i płatności Każdy sklep nazywa statusy zamówień i metody płatności po swojemu, dlatego przy sklepach internetowych sam decydujesz, jak mają być tłumaczone na statusy i metody Ritevo. Mapowanie ustawiasz raz, na stronie integracji, i dotyczy ono każdego zamówienia pobieranego od tej chwili. > **Warto wiedzieć:** Mapowanie możesz w każdej chwili dowolnie zmienić według swoich potrzeb - także przypisania wpisane z góry, które są tylko ustawieniami startowymi. #### Mapowanie statusów zamówień Listę statusów Ritevo pobiera z Twojego sklepu, więc widzisz je pod takimi nazwami jak w panelu PrestaShop. **Na start** przypisane są statusy, z którymi PrestaShop jest instalowany. **Sam przypisujesz** statusy dodane przez moduły płatności lub ręcznie. Przypisanie startowe: - **Potwierdzono** (API: "Potwierdzono" = `CONFIRMED`; wartość w `orderStatusMappings[].status`) - Płatność zaakceptowana, Przygotowanie w toku, Dostarczane, Dostarczone, Zwróconych pieniędzy, Zamówienie oczekujące (opłacone), Płatność przyjęta. Zamówienie ze zwróconymi pieniędzmi było prawdziwą sprzedażą, dlatego zostaje potwierdzone. - **Anulowano** (API: "Anulowano" = `CANCELLED`; wartość w `orderStatusMappings[].status`) - Anulowane. - **Ocz. na płatność** (API: "Ocz. na płatność" = `WAITING_FOR_PAYMENT`; wartość w `orderStatusMappings[].status`) - Oczekiwanie na płatność czekiem, Błąd płatności, Oczekiwanie na płatność przelewem, Zamówienie oczekujące (nieopłacone), Oczekiwanie na płatność przy odbiorze. - **Ocz. na potwierdzenie** (API: "Ocz. na potwierdzenie" = `WAITING_FOR_CONFIRMATION`; wartość w `orderStatusMappings[].status`) - z góry nic; tu trafiają też zamówienia ze statusem bez przypisania. Jeden status Ritevo może mieć przypisanych kilka statusów sklepu, ale jeden status sklepu tylko jeden status Ritevo. Zamówienie ze statusem, którego nigdzie nie przypisałeś, trafia jako **Ocz. na potwierdzenie** - zobaczysz je i zdecydujesz, co dalej. ![Karta Mapowanie statusów zamówień integracji PrestaShop z domyślnie przypisanymi statusami sklepu](https://ritevo.com/docs/integrations/prestashop/pl-statuses.webp) #### Mapowanie metod płatności PrestaShop nie udostępnia listy modułów płatności, dlatego tu wpisujesz **nazwy modułów** ręcznie - takie, jakie widzisz w panelu PrestaShop w szczegółach zamówienia albo w **Moduły → Płatności** (na przykład `ps_wirepayment`, `payu`). **Na start** wpisane są najczęstsze moduły. **Sam dopisujesz** inne moduły, a niepotrzebne usuwasz. Przypisanie startowe: - **Przelew** (API: "Przelew" = `BANK_TRANSFER`; wartość w `paymentMethodMappings[].paymentMethod`) - ps_wirepayment, ps_checkpayment. - **Płatność przy odbiorze** (API: "Płatność przy odbiorze" = `CASH_ON_DELIVERY`; wartość w `paymentMethodMappings[].paymentMethod`) - ps_cashondelivery. - **Karta płatnicza** (API: "Karta płatnicza" = `CARD`; wartość w `paymentMethodMappings[].paymentMethod`) - stripe_official. - **PayU** (API: "PayU" = `PAYU`; wartość w `paymentMethodMappings[].paymentMethod`) - payu. - **PayPal** (API: "PayPal" = `PAYPAL`; wartość w `paymentMethodMappings[].paymentMethod`) - ps_checkout, paypal. - **P24** (API: "P24" = `P24`; wartość w `paymentMethodMappings[].paymentMethod`) - przelewy24. Płatność metodą, której nigdzie nie przypisałeś, trafia jako **Inne**. ![Karta Mapowanie metod płatności integracji PrestaShop z domyślnie wpisanymi nazwami modułów płatności](https://ritevo.com/docs/integrations/prestashop/pl-payments.webp) > **Warto wiedzieć:** Zmiany mapowania zapisujesz przyciskiem **Zaktualizuj integrację** na dole strony. Działają od następnego pobrania - zamówienia pobrane wcześniej nie zmieniają statusu wstecz. Mapowania zapisujesz przez `PATCH /integrations/shops/prestashop/{integrationId}` razem z `accountName`: `orderStatusMappings` (`{ status, externalIds }`), `paymentMethodMappings` (`{ paymentMethod, externalIds }`) i `fieldMappings` jako pustą listę - ten sklep nie ma pól do mapowania. Każda lista musi zawierać wszystkie wartości swojego enuma - nieprzypisaną wartość wysyłasz z pustą listą. `externalIds` to identyfikatory statusów PrestaShop i nazwy modułów płatności. Aktualny kształt jest w Swaggerze. ### Co daje ta integracja - **Zamówienia** - nowe i zmienione zamówienia z PrestaShop trafiają do tabeli zamówień, z danymi kupującego, danymi do faktury, dostawą i pozycjami ze zdjęciami produktów. - **Wiadomości** - wątki z obsługi klienta PrestaShop trafiają do skrzynki wiadomości; odpowiadasz na nie z Ritevo. ### Zamówienia z PrestaShop Ritevo pobiera z PrestaShop całe zamówienie: konto klienta z adresem do faktury, adres i przewoźnika dostawy, wpłaty, pozycje z cenami brutto i zdjęciami produktów. Zamówienie zmienione w sklepie (na przykład nowy status) jest pobierane ponownie. - **Statusy i płatności** - tłumaczone według Twojego mapowania, opisanego wyżej. Kwota zapłacona to suma wpłat zarejestrowanych w PrestaShop. - **Uwagi kupującego** - komentarz wpisany w koszyku trafia do zamówienia jako wiadomość od kupującego. - **Usługi dodatkowe** - obsługiwane. Gdy kupujący wybierze pakowanie na prezent albo opakowanie z recyklingu, zobaczysz je w zamówieniu jako osobne pozycje dla całego zamówienia, także gdy są darmowe. Obsługiwana jest też wiadomość na prezent, czyli tekst, który kupujący chce dołączyć do paczki - zobaczysz ją razem z wiadomością od kupującego, w ramce **Wiadomość na prezent**. Więcej o [usługach dodatkowych](https://ritevo.com/pl/docs/orders/fetching-orders#additional-services). - **Rabaty** - reguły koszyka (kody rabatowe) pojawiają się jako osobne pozycje z ujemną kwotą, żeby suma pozycji zgadzała się z kwotą zamówienia. - **Zakup bez konta** - zamówienie gościa pobiera się normalnie. - **Faktura** - jeśli PrestaShop przekaże numer podatkowy kupującego (na przykład NIP) albo jego odpowiednik, zamówienie dostaje oznaczenie **Klient prosi o fakturę**, a dane firmy i numer są wpisane. Treść bileciku jest w `messageFromBuyer`, otoczona znacznikami `[GIFT_MESSAGE]` i `[/GIFT_MESSAGE]`, przed komentarzem kupującego. Wszystko poza znacznikami to wiadomość kupującego. > **Warto wiedzieć:** Zamówienie ze statusem **Potwierdzono** przejmuje Ritevo - późniejsze zmiany po stronie kanału sprzedaży są pomijane. Więcej w [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders#who-manages). ### Wiadomości z PrestaShop Ritevo pobiera wątki z **Obsługi klienta** PrestaShop - zarówno te z formularza kontaktowego, jak i te przypięte do zamówienia. Każdy wątek jest w Ritevo rozmową: - **Odpowiedź** - odpowiadasz z Ritevo; w PrestaShop odpowiedź jest zapisana jako wiadomość pracownika sklepu. Nie ma dyskusji ani reklamacji - PrestaShop ich nie ma. - **Powiązanie z zamówieniem** - wątek dotyczący zamówienia jest w Ritevo podpięty pod to zamówienie. - **Wiadomości prywatne** - notatki pracowników oznaczone w PrestaShop jako prywatne nie są pobierane. - **Załączniki** - PrestaShop podaje tylko nazwę załączonego pliku, nie sam plik. W Ritevo widzisz nazwę; plik otworzysz w panelu PrestaShop. Załączników też nie wyślesz. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy sklep przestał akceptować dane logowania - klucz został usunięty w panelu sklepu, stracił uprawnienia albo zmienił się adres sklepu. Do czasu podania nowych danych Ritevo nie pobiera ani nie wysyła żadnych danych z tego sklepu. 1. W panelu sklepu wygeneruj nowe klucze - tak samo jak przy pierwszym podłączeniu. 2. Na stronie integracji w Ritevo kliknij **Zaktualizuj dane logowania**, podaj adres sklepu i nowe klucze i zatwierdź. Ritevo sprawdza je w sklepie tak samo jak przy dodawaniu - błędne dane zwrócą błąd, poprawne odświeżą połączenie. Mapowania, ustawienia pobierania i historia zostają bez zmian. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie zarządza ofertami: nie wystawia, nie zmienia cen ani stanów magazynowych w PrestaShop. - Nie obsługuje punktów odbioru (na przykład paczkomatów). PrestaShop nie ma na nie standardowego pola - każdy moduł przewoźnika zapisuje wybrany punkt u siebie, poza zasięgiem webservice. Zamówienie z taką dostawą pobierze się normalnie, ale bez informacji o punkcie; ostrzeżenie o tym widzisz u góry strony integracji. - Nie przesyła nic z powrotem do PrestaShop: gdy w Ritevo zmienisz status zamówienia, nadasz przesyłkę albo wystawisz fakturę, zamówienie w PrestaShop zostaje bez zmian. ### Integracja przez API Endpointy tej integracji są pod `/integrations/shops/prestashop`, a wspólne dla całego typu (lista, pobranie jednej, przełączniki pobierania, usunięcie, przywrócenie) pod `/integrations/shops`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/shoper (updated 2026-10-17) ## Shoper Integracja Shoper z Ritevo: Client ID i Token API, podłączenie sklepu, mapowanie własnych statusów i płatności, zamówienia, wiadomości przez e-mail. Integracja z Shoper pobiera do Ritevo zamówienia z Twojego sklepu. Podłączasz ją danymi dostępu do API wygenerowanymi w panelu Shoper. Ponieważ statusy i metody płatności w Shoperze każdy sklep ustawia sam, po podłączeniu przypisujesz je do statusów Ritevo w mapowaniu. Wiadomości od kupujących Shoper wysyła e-mailem - obsługujesz je w Ritevo przez integrację e-mail. > **Wymagana integracja:** Potrzebujesz działającego sklepu Shoper i dostępu do jego panelu administracyjnego, żeby wygenerować klucze API. Ten sam sklep Shoper podłączysz tylko raz. Gdy dodasz go ponownie, Ritevo odświeży istniejącą integrację i włączy ją z powrotem, nawet jeśli była usunięta. Unikalność: integracja jest unikalna w ramach firmy po `externalId` i typie `SHOPER`; `externalId` to adres sklepu bez końcowego `/` (adres z `/` na końcu jest zapisywany bez niego). Ponowne utworzenie z tym samym adresem odświeża istniejącą integrację zamiast tworzyć nową: podmienia dane logowania, ustawia `authError=false` i `active=true` i zwraca tę integrację. Nowe dane logowania podasz też przez `PATCH /integrations/shops/shoper/{integrationId}/credentials` - w każdym stanie integracji, także gdy `authError=false` i `active=true`; ustawia `authError=false` i `active=true`. ### Jak wygenerować klucz API Dane dostępu tworzysz w panelu administracyjnym Shoper. Skopiuj je od razu - wkleisz je w Ritevo przy dodawaniu integracji. 1. Zaloguj się do panelu Shoper i wybierz **Aplikacje i integracje**, potem **Zewnętrzne aplikacje**. 2. Kliknij **Dodaj integrację** i wpisz dowolną nazwę, na przykład „Ritevo". 3. Zaznacz **wszystkie** obszary dostępu z pełnymi uprawnieniami - nawet jeśli dziś Ritevo korzysta tylko z części, nowe funkcje zadziałają wtedy bez zmian w panelu Shoper. 4. Zapisz i skopiuj **Client ID** oraz **Token API**. > **Warto wiedzieć:** Token Shoper pokazuje tylko raz, zaraz po utworzeniu. Jeśli zamkniesz okno bez skopiowania, utwórz integrację w panelu Shoper jeszcze raz. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Sklepy internetowe** wybierz kafelek **Shoper**. 3. W polu **Nazwa konta** wpisz własną nazwę integracji, na przykład nazwę sklepu. 4. W polu **Adres sklepu** wpisz pełny adres sklepu razem z `https://`, bez końcowego ukośnika - na przykład `https://mojsklep.shoparena.pl`. 5. W polach **Client ID** i **Token API** wklej dane z panelu Shoper. 6. Kliknij **Dodaj integrację**. Ritevo od razu łączy się ze sklepem i sprawdza dane: jeśli są poprawne, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd zwrócony przez sklep i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Shoper w sekcji Sklepy internetowe](https://ritevo.com/docs/integrations/shoper/pl-catalogue.webp) ![Ekran dodawania integracji Shoper z polami Nazwa konta, Adres sklepu, Client ID i Token API](https://ritevo.com/docs/integrations/shoper/pl-add.webp) ### Ustawienia integracji Po podłączeniu integracja jest **Aktywna**, ale pobieranie zamówień jest **wyłączone** - włączasz je sam. Na stronie integracji znajdziesz: - **Nazwa konta** - Twoja własna nazwa tej integracji, na przykład nazwa sklepu. Możesz ją zmienić w każdej chwili. - **Adres sklepu** - adres podany przy dodawaniu. Tutaj nie da się go zmienić; nowy adres lub nowe klucze podajesz przez **Zaktualizuj dane logowania**. - **Client ID** - identyfikator z panelu Shoper, podany przy dodawaniu. Zmienisz go razem z tokenem przez **Zaktualizuj dane logowania**. - **Pobieranie zamówień** - po włączeniu Ritevo sprawdza nowe zamówienia i zmiany statusów mniej więcej co 10 minut. Zasady wspólne dla wszystkich kanałów: [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders). - **Pobieranie wiadomości** - zamiast przełącznika jest tu informacja, że wiadomości z Shoper obsługujemy przez integrację e-mail, i przycisk **Dodaj integrację**, który prowadzi do jej dodania. - **Mapowanie statusów zamówień** i **Mapowanie metod płatności** - opisane niżej. ![Szczegóły integracji Shoper: nazwa konta, adres sklepu, Client ID, przełącznik Pobieranie zamówień i karta wiadomości odsyłająca do integracji e-mail](https://ritevo.com/docs/integrations/shoper/pl-details.webp) > **Warto wiedzieć:** Klucz możesz podmienić w każdej chwili tym samym przyciskiem **Zaktualizuj dane logowania**, nie tylko po błędzie. ### Mapowanie statusów i płatności Każdy sklep nazywa statusy zamówień i metody płatności po swojemu, dlatego przy sklepach internetowych sam decydujesz, jak mają być tłumaczone na statusy i metody Ritevo. Mapowanie ustawiasz raz, na stronie integracji, i dotyczy ono każdego zamówienia pobieranego od tej chwili. > **Warto wiedzieć:** Mapowanie możesz w każdej chwili dowolnie zmienić według swoich potrzeb - także przypisania wpisane z góry, które są tylko ustawieniami startowymi. > **Warto wiedzieć:** W Shoperze statusy i metody płatności tworzysz sam w panelu sklepu, dlatego **nic nie jest przypisane z góry**. Ustaw mapowanie zaraz po podłączeniu, zanim włączysz pobieranie zamówień - inaczej każde zamówienie trafi jako **Ocz. na potwierdzenie** z płatnością **Inne**. #### Mapowanie statusów zamówień Listę statusów Ritevo pobiera z Twojego sklepu, więc widzisz je pod takimi nazwami, jakie nadałeś im w panelu Shoper. **Na start** nic nie jest przypisane. **Sam przypisujesz** wszystkie statusy, bo każdy sklep tworzy własne. Przykładowe przypisanie dla standardowych statusów Shopera: - **Potwierdzono** (API: "Potwierdzono" = `CONFIRMED`; wartość w `orderStatusMappings[].status`) - przyjęte do realizacji, oczekiwanie na dostawę, w trakcie kompletowania, gotowe do wysłania, przesyłka wysłana. - **Anulowano** (API: "Anulowano" = `CANCELLED`; wartość w `orderStatusMappings[].status`) - anulowane. - **Ocz. na płatność** (API: "Ocz. na płatność" = `WAITING_FOR_PAYMENT`; wartość w `orderStatusMappings[].status`) - złożone, oczekiwanie na płatność, odrzucone. - **Ocz. na potwierdzenie** (API: "Ocz. na potwierdzenie" = `WAITING_FOR_CONFIRMATION`; wartość w `orderStatusMappings[].status`) - zwrócone, reklamowane - zamówienia, którym chcesz się przyjrzeć, zanim coś z nimi zrobisz. Jeden status Ritevo może mieć przypisanych kilka statusów sklepu, ale jeden status sklepu tylko jeden status Ritevo. Zamówienie ze statusem, którego nigdzie nie przypisałeś, trafia jako **Ocz. na potwierdzenie** - zobaczysz je i zdecydujesz, co dalej. ![Karta Mapowanie statusów zamówień integracji Shoper z przykładowym przypisaniem statusów sklepu](https://ritevo.com/docs/integrations/shoper/pl-statuses.webp) #### Mapowanie metod płatności Listę metod Ritevo pobiera z płatności skonfigurowanych w Twoim sklepie, pod nazwami z panelu Shoper. **Na start** nic nie jest przypisane. **Sam przypisujesz** wszystkie metody, bo każdy sklep ma własne. Przykładowe przypisanie: - **Przelew** (API: "Przelew" = `BANK_TRANSFER`; wartość w `paymentMethodMappings[].paymentMethod`) - mBank mRaty, Przelewy24.pl, Klarna, InPost Pay, Stripe - operatorzy płatności online, które chcesz rozliczać jak przelew. - **Gotówka** (API: "Gotówka" = `CASH`; wartość w `paymentMethodMappings[].paymentMethod`) - Gotówka. - **Płatność przy odbiorze** (API: "Płatność przy odbiorze" = `CASH_ON_DELIVERY`; wartość w `paymentMethodMappings[].paymentMethod`) - Pobranie. - **P24** (API: "P24" = `P24`; wartość w `paymentMethodMappings[].paymentMethod`) - Autopay lub inny operator, którego chcesz widzieć osobno. Płatność metodą, której nigdzie nie przypisałeś, trafia jako **Inne**. ![Karta Mapowanie metod płatności integracji Shoper z przykładowym przypisaniem metod sklepu](https://ritevo.com/docs/integrations/shoper/pl-payments.webp) > **Warto wiedzieć:** Zmiany mapowania zapisujesz przyciskiem **Zaktualizuj integrację** na dole strony. Działają od następnego pobrania - zamówienia pobrane wcześniej nie zmieniają statusu wstecz. Mapowania zapisujesz przez `PATCH /integrations/shops/shoper/{integrationId}` razem z `accountName`: `orderStatusMappings` (`{ status, externalIds }`), `paymentMethodMappings` (`{ paymentMethod, externalIds }`) i `fieldMappings` jako pustą listę - ten sklep nie ma pól do mapowania. Każda lista musi zawierać wszystkie wartości swojego enuma - nieprzypisaną wartość wysyłasz z pustą listą. `externalIds` to liczbowe identyfikatory statusów i płatności z Shopera. Aktualny kształt jest w Swaggerze. ### Co daje ta integracja - **Zamówienia** - nowe i zmienione zamówienia z Shoper trafiają do tabeli zamówień, z danymi kupującego, danymi do faktury, dostawą i pozycjami ze zdjęciami produktów. - **Wiadomości** - przez integrację e-mail, patrz niżej. ### Zamówienia z Shoper Ritevo pobiera z Shoper całe zamówienie: kupującego, adres rozliczeniowy i dostawy, płatność, pozycje z cenami brutto i głównym zdjęciem produktu. Zamówienie, któremu w sklepie zmienił się status, jest pobierane ponownie. - **Statusy i płatności** - tłumaczone według Twojego mapowania, opisanego wyżej. Kwota zapłacona to to, co kupujący faktycznie wpłacił - także częściowo. - **Adres dostawy** - gdy kupujący nie podał osobnego adresu dostawy, Ritevo używa adresu rozliczeniowego. - **Termin wysyłki** - data wysyłki zadeklarowana przez sklep (z czasów realizacji produktów) trafia do zamówienia jako termin wysyłki. - **Warianty i pola własne** - wybrany wariant i to, co kupujący wpisał w polach produktu (na przykład grawer), są dopisane do nazwy pozycji. - **Zamówienia scalone** - jeśli w Shoperze połączyłeś kilka zamówień w jedno, Ritevo pobiera oryginalne zamówienia, a zbiorcze pomija, żeby nie liczyć towaru dwa razy. - **Usługi dodatkowe** - nieobsługiwane. Ta integracja nie przekazuje usług takich jak pakowanie na prezent czy wniesienie. Jeśli chcesz je sprzedawać, wystaw je jako osobny produkt albo ofertę - w zamówieniu pojawią się wtedy jako zwykła pozycja. Więcej o [usługach dodatkowych](https://ritevo.com/pl/docs/orders/fetching-orders#additional-services). - **Faktura** - jeśli Shoper przekaże numer podatkowy kupującego (na przykład NIP) albo jego odpowiednik, zamówienie dostaje oznaczenie **Klient prosi o fakturę**, a dane firmy i numer są wpisane. > **Warto wiedzieć:** Zamówienie ze statusem **Potwierdzono** przejmuje Ritevo - późniejsze zmiany po stronie kanału sprzedaży są pomijane. Więcej w [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders#who-manages). ### Wiadomości od kupujących z Shoper Shoper nie udostępnia skrzynki wiadomości przez API - kupujący piszą do Ciebie **e-mailem** na adres sklepu. Żeby te wiadomości widzieć i odpowiadać na nie w Ritevo, dodaj [integrację e-mail](https://ritevo.com/pl/docs/messages/fetching-messages) dla tej skrzynki. Wiadomości pojawią się wtedy w Ritevo jak zwykłe e-maile; nie są powiązane z integracją Shoper ani z jej zamówieniami. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy sklep przestał akceptować dane logowania - klucz został usunięty w panelu sklepu, stracił uprawnienia albo zmienił się adres sklepu. Do czasu podania nowych danych Ritevo nie pobiera ani nie wysyła żadnych danych z tego sklepu. 1. W panelu sklepu wygeneruj nowe klucze - tak samo jak przy pierwszym podłączeniu. 2. Na stronie integracji w Ritevo kliknij **Zaktualizuj dane logowania**, podaj adres sklepu i nowe klucze i zatwierdź. Ritevo sprawdza je w sklepie tak samo jak przy dodawaniu - błędne dane zwrócą błąd, poprawne odświeżą połączenie. Mapowania, ustawienia pobierania i historia zostają bez zmian. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie zarządza ofertami: nie wystawia, nie zmienia cen ani stanów magazynowych w Shoper. - Nie obsługuje jeszcze dostaw do punktów odbioru (na przykład paczkomatów). Zamówienie z taką dostawą pobierze się normalnie, ale bez informacji o wybranym punkcie. - Nie pobiera wiadomości - Shoper nie udostępnia ich przez API. - Nie przesyła nic z powrotem do Shoper: gdy w Ritevo zmienisz status zamówienia, nadasz przesyłkę albo wystawisz fakturę, zamówienie w Shoper zostaje bez zmian. ### Integracja przez API Endpointy tej integracji są pod `/integrations/shops/shoper`, a wspólne dla całego typu (lista, pobranie jednej, przełączniki pobierania, usunięcie, przywrócenie) pod `/integrations/shops`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/shopify (updated 2026-10-18) ## Shopify Integracja Shopify z Ritevo: podłączenie sklepu przez aplikację, mapowanie statusów, płatności i pól dodatkowych (NIP, paczkomat), pobieranie zamówień. Integracja z Shopify pobiera do Ritevo zamówienia z Twojego sklepu. Podłączasz ją, zatwierdzając aplikację Ritevo w panelu Shopify - bez kopiowania kluczy. Statusy płatności, metody płatności i dodatkowe pola zamówienia (NIP, punkt odbioru) tłumaczysz na dane Ritevo w mapowaniu. Wiadomości od kupujących Shopify wysyła e-mailem - obsługujesz je w Ritevo przez integrację e-mail. > **Wymagana integracja:** Potrzebujesz działającego sklepu Shopify i konta w jego panelu administracyjnym, które może instalować aplikacje. Ten sam sklep Shopify podłączysz tylko raz. Gdy dodasz go ponownie, Ritevo odświeży istniejącą integrację i włączy ją z powrotem, nawet jeśli była usunięta. Unikalność: integracja jest unikalna w ramach firmy po `externalId` i typie `SHOPIFY`; `externalId` to adres sklepu `https://.myshopify.com`. Integracja powstaje tylko po zatwierdzeniu aplikacji w Shopify: `POST /integrations/shops/shopify` przyjmuje w `callbackQuery` parametry przekierowania od Shopify, więc przez samo API jej nie utworzysz. Ponowne podłączenie tego samego sklepu odświeża istniejącą integrację zamiast tworzyć nową: podmienia dostęp i nazwę sklepu, ustawia `authError=false` i `active=true` i zwraca tę integrację. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Sklepy internetowe** wybierz kafelek **Shopify** i kliknij **Dodaj integrację**. 3. Ritevo przeniesie Cię do Shopify - zaloguj się, jeśli trzeba, wybierz sklep i zainstaluj aplikację Ritevo. 4. Shopify od razu poprosi o zgodę na dostęp do sklepu - zatwierdź ją. 5. Wróć do Ritevo i chwilę poczekaj - nie zamykaj okna. Gdy dodawanie się zakończy, otworzą się ustawienia nowej integracji. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran dodawania integracji Shopify z przyciskiem Dodaj integrację, który prowadzi do instalacji w Shopify](https://ritevo.com/docs/integrations/shopify/pl-add.webp) > **Warto wiedzieć:** Ritevo nie widzi Twojego hasła do Shopify i nie potrzebuje kluczy API. Shopify przekazuje Ritevo tylko zgodę na dostęp do sklepu. Zgodę cofasz, odinstalowując aplikację Ritevo w panelu Shopify - integracja przestanie wtedy działać i pokaże **Wymaga ponownego połączenia**. ### Ustawienia integracji Po podłączeniu integracja jest **Aktywna**, ale pobieranie zamówień jest **wyłączone** - włączasz je sam. Na stronie integracji znajdziesz: - **Nazwa konta** - nazwa sklepu z Shopify. Ritevo pobiera ją z Shopify, nie da się jej tu zmienić; odświeża się przy ponownym połączeniu. - **Adres sklepu** - adres `.myshopify.com` sklepu, w którym zainstalowałeś aplikację. Nie da się go zmienić. - **Pobieranie zamówień** - po włączeniu Ritevo sprawdza nowe i zmienione zamówienia mniej więcej co 10 minut. Najnowsze zamówienia mogą pojawić się z kilkuminutowym opóźnieniem. Zasady wspólne dla wszystkich kanałów: [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders). - **Pobieranie wiadomości** - zamiast przełącznika jest tu informacja, że wiadomości z Shopify obsługujemy przez integrację e-mail, i przycisk **Dodaj integrację**, który prowadzi do jej dodania. - **Mapowanie statusów zamówień**, **Mapowanie metod płatności** i **Zaawansowane mapowanie** - opisane niżej. ![Szczegóły integracji Shopify: nazwa konta, adres sklepu, przełącznik Pobieranie zamówień i karta wiadomości odsyłająca do integracji e-mail](https://ritevo.com/docs/integrations/shopify/pl-details.webp) ### Mapowanie statusów i płatności Każdy sklep nazywa statusy zamówień i metody płatności po swojemu, dlatego przy sklepach internetowych sam decydujesz, jak mają być tłumaczone na statusy i metody Ritevo. Mapowanie ustawiasz raz, na stronie integracji, i dotyczy ono każdego zamówienia pobieranego od tej chwili. > **Warto wiedzieć:** Mapowanie możesz w każdej chwili dowolnie zmienić według swoich potrzeb - także przypisania wpisane z góry, które są tylko ustawieniami startowymi. #### Mapowanie statusów zamówień Status zamówienia w Ritevo wynika ze statusu płatności zamówienia w Shopify. Te statusy są takie same w każdym sklepie, więc **na start** przypisane są wszystkie - na liście widzisz je pod nazwami z Shopify. Przypisanie startowe: - **Potwierdzono** (API: "Potwierdzono" = `CONFIRMED`; wartość w `orderStatusMappings[].status`) - PAID (opłacone), PARTIALLY_REFUNDED (częściowo zwrócone), REFUNDED (zwrócone). Zwrócone zamówienie było prawdziwą sprzedażą, dlatego zostaje potwierdzone - zwrot rozliczasz osobno. - **Anulowano** (API: "Anulowano" = `CANCELLED`; wartość w `orderStatusMappings[].status`) - VOIDED (płatność unieważniona), EXPIRED (płatność wygasła). - **Ocz. na płatność** (API: "Ocz. na płatność" = `WAITING_FOR_PAYMENT`; wartość w `orderStatusMappings[].status`) - PENDING (czeka na płatność), PARTIALLY_PAID (opłacone częściowo). - **Ocz. na potwierdzenie** (API: "Ocz. na potwierdzenie" = `WAITING_FOR_CONFIRMATION`; wartość w `orderStatusMappings[].status`) - AUTHORIZED (płatność zatwierdzona, ale pieniądze nie zostały jeszcze pobrane). Jeden status Ritevo może mieć przypisanych kilka statusów sklepu, ale jeden status sklepu tylko jeden status Ritevo. Zamówienie ze statusem, którego nigdzie nie przypisałeś, trafia jako **Ocz. na potwierdzenie** - zobaczysz je i zdecydujesz, co dalej. ![Karta Mapowanie statusów zamówień integracji Shopify z domyślnie przypisanymi statusami płatności Shopify](https://ritevo.com/docs/integrations/shopify/pl-statuses.webp) > **Warto wiedzieć:** Zamówienie anulowane w Shopify zawsze trafia jako **Anulowano**, niezależnie od mapowania statusów. Anulowanie jest ważniejsze od statusu płatności, bo anulowane zamówienie zachowuje w Shopify swój status płatności (na przykład PAID albo REFUNDED). #### Mapowanie metod płatności Shopify nie udostępnia listy metod płatności sklepu, dlatego nazwy metod wpisujesz ręcznie - tak, jak Shopify zapisuje je w zamówieniu. Nazwę znajdziesz w panelu Shopify w szczegółach zamówienia. **Na start** wpisane są Shopify Payments, PayPal i metody ręczne wbudowane w Shopify. **Sam dopisujesz** metody z aplikacji płatniczych, a niepotrzebne usuwasz. Przypisanie startowe: - **Karta płatnicza** (API: "Karta płatnicza" = `CARD`; wartość w `paymentMethodMappings[].paymentMethod`) - `shopify_payments`. - **PayPal** (API: "PayPal" = `PAYPAL`; wartość w `paymentMethodMappings[].paymentMethod`) - `paypal`. - **Płatność przy odbiorze** (API: "Płatność przy odbiorze" = `CASH_ON_DELIVERY`; wartość w `paymentMethodMappings[].paymentMethod`) - `Cash on Delivery (COD)`. - **Przelew** (API: "Przelew" = `BANK_TRANSFER`; wartość w `paymentMethodMappings[].paymentMethod`) - `Bank Deposit`, `Money Order`. Płatność metodą, której nigdzie nie przypisałeś, trafia jako **Inne**. #### Zaawansowane mapowanie - dodatkowe pola zamówienia Shopify nie ma standardowych pól na NIP, prośbę o fakturę ani punkt odbioru - dodają je aplikacje, każda pod własną nazwą, jako dodatkowe informacje zamówienia. W tej karcie wskazujesz, z którego pola Ritevo ma czytać każdą z tych danych. **Na start** pola są puste. **Sam wpisujesz** nazwy pól aplikacji, z których korzysta Twój sklep. - **NIP / numer VAT** (API: "NIP / numer VAT" = `TAX_ID`; wartość w `fieldMappings[].field`) - pole z numerem podatkowym kupującego. Gdy ma wartość, zamówienie dostaje dane firmy i numer do faktury. - **Żądanie faktury** (API: "Żądanie faktury" = `INVOICE_REQUESTED`; wartość w `fieldMappings[].field`) - pole, z którego Ritevo odczytuje, czy kupujący chce fakturę. Liczy się sama wartość w polu: jeśli jest tam „0", „no", „false" albo „off", prośby o fakturę nie ma; każda inna wartość (na przykład „1", „yes") to prośba o fakturę. Gdy pole jest puste, prośba o fakturę jest wtedy, gdy kupujący podał NIP. - **Identyfikator punktu odbioru** (API: "Identyfikator punktu odbioru" = `PICKUP_POINT_ID`; wartość w `fieldMappings[].field`) - pole z kodem paczkomatu lub punktu (na przykład `WAW123`). - **Nazwa punktu odbioru** i **Opis punktu odbioru** (API: "Nazwa punktu odbioru" = `PICKUP_POINT_NAME`, "Opis punktu odbioru" = `PICKUP_POINT_DESCRIPTION`; wartość w `fieldMappings[].field`) - pola z nazwą i adresem punktu, jeśli aplikacja je zapisuje. - **Kraj punktu odbioru** (API: "Kraj punktu odbioru" = `PICKUP_POINT_COUNTRY`; wartość w `fieldMappings[].field`) - zwykle zostaje puste; wtedy Ritevo bierze kraj z adresu dostawy. Nazwę pola znajdziesz w panelu Shopify w szczegółach zamówienia testowego, w sekcji z dodatkowymi informacjami. Wpisz ją dokładnie - wielkość liter ma znaczenie. W jednym polu możesz podać kilka nazw (na przykład po zmianie aplikacji): Ritevo użyje pierwszej, która w zamówieniu ma wartość. ![Karta Zaawansowane mapowanie integracji Shopify z przykładowymi nazwami pól NIP, Faktura, paczkomat_id i paczkomat_nazwa](https://ritevo.com/docs/integrations/shopify/pl-advanced.webp) > **Warto wiedzieć:** Zmiany mapowania zapisujesz przyciskiem **Zaktualizuj integrację** na dole strony. Działają od następnego pobrania - zamówienia pobrane wcześniej nie zmieniają statusu wstecz. Mapowania zapisujesz przez `PATCH /integrations/shops/shopify/{integrationId}`: `orderStatusMappings` (`{ status, externalIds }`), `paymentMethodMappings` (`{ paymentMethod, externalIds }`) i `fieldMappings` (`{ field, keys }`) z każdą wartością z listy wyżej. Każda lista musi zawierać wszystkie wartości swojego enuma - nieprzypisaną wartość wysyłasz z pustą listą. `externalIds` statusów to statusy płatności Shopify: `PENDING`, `AUTHORIZED`, `PARTIALLY_PAID`, `PAID`, `PARTIALLY_REFUNDED`, `REFUNDED`, `VOIDED`, `EXPIRED`; `externalIds` płatności to nazwy bramek z zamówienia Shopify. Aktualny kształt jest w Swaggerze. ### Co daje ta integracja - **Zamówienia** - nowe i zmienione zamówienia z Shopify trafiają do tabeli zamówień, z danymi kupującego, danymi do faktury, dostawą i pozycjami ze zdjęciami produktów. - **Wiadomości** - przez integrację e-mail, patrz niżej. ### Zamówienia z Shopify Ritevo pobiera z Shopify całe zamówienie: kupującego, adres rozliczeniowy i dostawy, sposób dostawy, płatność oraz pozycje ze zdjęciami produktów. Zamówienie zmienione w sklepie (na przykład po opłaceniu) jest pobierane ponownie. Pobierane są wszystkie zamówienia - także ze sprzedaży stacjonarnej (Shopify POS) i zamówienia testowe. - **Statusy i płatności** - tłumaczone według Twojego mapowania, opisanego wyżej. Numer płatności i data opłacenia pochodzą z ostatniej udanej transakcji pobrania pieniędzy, a kwota zapłacona to to, co kupujący faktycznie wpłacił. - **Kwoty i VAT** - kwoty są w walucie, w której płacił kupujący. Stawki VAT pochodzą z podatków, które Shopify naliczył przy każdej pozycji; pozycja bez podatku ma VAT 0%. - **Napiwek** - jest pozycją zamówienia, bo tak przesyła go Shopify, ze stawką VAT z Shopify. - **Usługi dodatkowe** - obsługiwane. Dodatkowe opłaty doliczone do zamówienia w Shopify zobaczysz jako osobne pozycje dla całego zamówienia, pod nazwą ze sklepu. Cło, jeśli nie jest wliczone w ceny, trafia jako pozycja **Duties** - osobna dla każdej stawki VAT naliczonej przez Shopify. Więcej o [usługach dodatkowych](https://ritevo.com/pl/docs/orders/fetching-orders#additional-services). - **Dostawa** - gdy zamówienie ma kilka sposobów dostawy, ich nazwy są połączone przecinkiem, a koszty zsumowane. Termin wysyłki i szacowany termin dostawy trafiają do zamówienia, jeśli Shopify je podaje. - **Kupujący** - dane kupującego pochodzą z adresu rozliczeniowego, a gdy go brak - z adresu dostawy. - **Faktura** - nazwa firmy pochodzi z adresu rozliczeniowego, a NIP z pola wskazanego w sekcji **Zaawansowane mapowanie**; bez nazwy firmy i bez NIP-u zamówienie nie ma danych do faktury. Prośba o fakturę wynika z pola **Żądanie faktury** i daje oznaczenie **Klient prosi o fakturę**. - **Punkt odbioru** - kod i nazwa punktu są czytane z pól wskazanych w sekcji **Zaawansowane mapowanie**; bez nich zamówienie ma tylko adres dostawy. - **Kraj pochodzenia** - wynika z języka i regionu, w którym kupujący składał zamówienie (na przykład `de-DE` to Niemcy). Gdy Shopify nie poda regionu, Ritevo bierze kraj sklepu. Kraj kupującego jest osobno, w jego adresie. - **Uwagi kupującego** - uwaga do zamówienia wpisana w koszyku trafia do zamówienia jako wiadomość od kupującego. > **Warto wiedzieć:** Gdy wyłączysz **Pobieranie zamówień** i włączysz je ponownie, Ritevo pobiera zamówienia od chwili wyłączenia. Shopify udostępnia jednak tylko zamówienia z ostatnich 60 dni, więc po dłuższej przerwie starszych zamówień nie da się już pobrać. Zamówienia z czasu przerwy trafią do Ritevo jako nowe i mogą uruchomić akcje automatyczne - przed ponownym włączeniem sprawdź swoje akcje. Po ponad 90 dniach bez pobierania połączenie wygasa i trzeba podłączyć sklep ponownie. > **Warto wiedzieć:** Zamówienie ze statusem **Potwierdzono** przejmuje Ritevo - późniejsze zmiany po stronie kanału sprzedaży są pomijane. Więcej w [Pobieranie zamówień](https://ritevo.com/pl/docs/orders/fetching-orders#who-manages). ### Wiadomości od kupujących z Shopify Shopify nie udostępnia skrzynki wiadomości (Shopify Inbox) przez API - kupujący piszą do Ciebie **e-mailem** na adres sklepu. Żeby te wiadomości widzieć i odpowiadać na nie w Ritevo, dodaj [integrację e-mail](https://ritevo.com/pl/docs/messages/fetching-messages) dla tej skrzynki. Wiadomości pojawią się wtedy w Ritevo jak zwykłe e-maile; nie są powiązane z integracją Shopify ani z jej zamówieniami. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy aplikacja Ritevo została odinstalowana w panelu Shopify albo połączenie wygasło - na przykład gdy integracja przez ponad 90 dni nie łączyła się ze sklepem, bo pobieranie zamówień było wyłączone. Do czasu ponownego połączenia Ritevo nie pobiera ani nie wysyła żadnych danych z tego sklepu. 1. Wejdź w **Integracje**, kliknij **Dodaj integrację** i wybierz kafelek **Shopify**. 2. Wybierz w Shopify **ten sam** sklep i zatwierdź aplikację Ritevo - tak samo jak przy pierwszym podłączeniu. 3. Ritevo rozpozna sklep po adresie i odświeży połączenie w istniejącej integracji. Mapowania, ustawienia pobierania i historia zostają bez zmian - druga integracja nie powstaje. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie zarządza ofertami: nie wystawia, nie zmienia cen ani stanów magazynowych w Shopify. - Nie pobiera wiadomości - Shopify nie udostępnia ich przez API. - Nie przenosi anulowania ani zwrotu zrobionego w Shopify po potwierdzeniu zamówienia - zamówienie w Ritevo zostaje bez zmian. - Nie przesyła nic z powrotem do Shopify: gdy w Ritevo zmienisz status zamówienia, nadasz przesyłkę albo wystawisz fakturę, zamówienie w Shopify zostaje bez zmian. ### Integracja przez API Endpointy tej integracji są pod `/integrations/shops/shopify`, a wspólne dla całego typu (lista, pobranie jednej, przełączniki pobierania, usunięcie, przywrócenie) pod `/integrations/shops`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/email (updated 2026-09-27) ## E-mail Integracja e-mail z Ritevo: podłączenie skrzynki IMAP/SMTP, hasło aplikacji, pobieranie maili jako wątków i odpowiadanie klientom z Ritevo. Integracja e-mail podłącza do Ritevo zwykłą skrzynkę pocztową - firmową, Gmail, Outlook albo dowolną inną, która obsługuje IMAP i SMTP. Maile od klientów trafiają do wspólnej skrzynki **Wiadomości** obok rozmów z marketplace'ów i sklepów, a odpowiadasz na nie z Ritevo. Przez e-mail obsłużysz też kanały sprzedaży, które nie mają własnej skrzynki wiadomości - na stronie takiej integracji jest to zaznaczone. > **Wymagana integracja:** Potrzebujesz adresu e-mail, hasła do skrzynki (albo hasła aplikacji) i skrzynki, która pozwala łączyć się przez IMAP i SMTP. Jedną skrzynkę podłączasz raz; jeśli obsługujesz kilka adresów, każdy dodajesz jako osobną integrację. W ramach jednego konta firmowego dany adres podłączysz tylko raz: gdy Ty albo ktoś z Twoich współpracowników doda go ponownie, odświeży się istniejąca integracja - także wtedy, gdy wcześniej została usunięta - a druga nie powstanie. Nowe hasło i ustawienia serwera zastąpią poprzednie. Unikalność: integracja jest unikalna w ramach firmy po `email` i typie `EMAIL`. Ponowne utworzenie odświeża istniejącą integrację zamiast tworzyć nową: od razu ustawia `authError=false`, a jeśli integracja była nieaktywna - także `active=true`. Nowe dane podasz też przez `PATCH /integrations/email/{integrationId}/credentials` - w każdym stanie integracji, także gdy `authError=false` i `active=true`; ustawia `authError=false` i `active=true`. ### Hasło aplikacji Część dostawców poczty nie wpuszcza programów zewnętrznych na zwykłe hasło do logowania. Wtedy w ustawieniach konta pocztowego generujesz **hasło aplikacji** i to ono trafia do Ritevo: - **Gmail** - hasło aplikacji tworzysz w ustawieniach konta Google, w sekcji bezpieczeństwa. Wymaga włączonej weryfikacji dwuetapowej. - **Outlook, Yahoo, iCloud** - podobnie: hasło aplikacji w ustawieniach bezpieczeństwa konta. - **Poczta firmowa u hostingu** - zwykle wystarczy zwykłe hasło do skrzynki. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Poczta e-mail** wybierz kafelek **Email**. 3. W polu **Nazwa konta** wpisz własną nazwę integracji, na przykład „Obsługa klienta". 4. W polu **Adres e-mail** wpisz adres skrzynki. Ritevo od razu uzupełni dane serwera na podstawie tego adresu - opis niżej. 5. W polu **Hasło** wpisz hasło do skrzynki albo hasło aplikacji. 6. Kliknij **Dodaj integrację**. Ritevo od razu łączy się z serwerem poczty - osobno z odbieraniem (IMAP) i wysyłaniem (SMTP). Jeśli oba połączenia się udadzą, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd zwrócony przez serwer i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z wybranym filtrem Poczta e-mail i zaznaczonym kafelkiem Email](https://ritevo.com/docs/integrations/email/pl-catalogue.webp) ![Ekran dodawania integracji e-mail z polami Nazwa konta, Adres e-mail i Hasło, informacją o haśle aplikacji i przyciskiem Pokaż ustawienia zaawansowane](https://ritevo.com/docs/integrations/email/pl-add.webp) ### Ustawienia serwera (IMAP / SMTP) Ustawienia serwera są schowane pod **Pokaż ustawienia zaawansowane**. Zwykle nie musisz ich ruszać - rozwiń je, gdy dodanie integracji się nie powiedzie: - **Login (opcjonalnie)** - zostaw puste, jeśli logujesz się adresem e-mail. Uzupełnij tylko wtedy, gdy serwer wymaga innego loginu. - **Serwer IMAP (odbieranie)** i **Port IMAP** - skąd Ritevo pobiera maile. - **Serwer SMTP (wysyłanie)** i **Port SMTP** - przez który serwer Ritevo wysyła Twoje odpowiedzi. - **Szyfrowanie** - **SSL/TLS** albo **STARTTLS**. Najczęściej: port 993 dla IMAP, port 465 z SSL/TLS albo 587 ze STARTTLS dla SMTP. ![Rozwinięta karta Ustawienia serwera (IMAP / SMTP) z polami Login, Serwer IMAP, Port IMAP, Serwer SMTP, Port SMTP i Szyfrowanie](https://ritevo.com/docs/integrations/email/pl-advanced.webp) Dane serwera Ritevo podpowiada na podstawie adresu: - **Gmail** - serwery Google, porty 993 i 465, SSL/TLS. - **Outlook, Hotmail, Live** - serwery Microsoft, porty 993 i 587, STARTTLS. - **Każdy inny adres** - `imap.` i `smtp.` z domeny adresu (dla `kontakt@mojsklep.pl` to `imap.mojsklep.pl` i `smtp.mojsklep.pl`), porty 993 i 465, SSL/TLS. > **Warto wiedzieć:** Jeśli Twoja poczta ma inne serwery niż podpowiedź (częste przy hostingu), właściwe dane znajdziesz w panelu hostingu albo w instrukcji dostawcy, w części o konfiguracji programu pocztowego. ### Ustawienia integracji Po podłączeniu integracja jest **Aktywna**, ale pobieranie wiadomości jest **wyłączone** - włączasz je sam. Na stronie integracji znajdziesz: - **Nazwa konta** - Twoja własna nazwa integracji. Możesz ją zmienić w każdej chwili. - **Adres e-mail** - adres podany przy dodawaniu. Nie da się go zmienić; inny adres dodajesz jako nową integrację. - **Pobieranie wiadomości** - po włączeniu Ritevo sprawdza skrzynkę mniej więcej co 10 minut, przy pierwszym pobraniu sięgając 7 dni wstecz. Zasady wspólne: [Pobieranie wiadomości](https://ritevo.com/pl/docs/messages/fetching-messages). - **Ustawienia serwera (IMAP / SMTP)** - te same pola co przy dodawaniu, opisane wyżej. ![Szczegóły integracji e-mail: nazwa konta, adres e-mail, przełącznik Pobieranie wiadomości, ustawienia serwera oraz przyciski Zaktualizuj dane logowania i Zaktualizuj integrację](https://ritevo.com/docs/integrations/email/pl-details.webp) > **Warto wiedzieć:** Zmianę ustawień serwera zapisujesz przyciskiem **Zaktualizuj integrację** - Ritevo najpierw sprawdza nowe dane na serwerze i zapisuje je tylko wtedy, gdy połączenie się uda. Hasło zmieniasz osobno, przyciskiem **Zaktualizuj dane logowania**. ### Jakie maile trafiają do Ritevo Ritevo czyta dwa foldery skrzynki: **odebrane** i **wysłane**. Maile z tej samej korespondencji łączy w jeden wątek, tak jak robi to program pocztowy: - **Wątki** - odpowiedzi są dopinane do rozmowy, której dotyczą. Gdy program pocztowy klienta tego nie oznaczył, Ritevo łączy maile po temacie. - **Wysłane z innych programów** - odpowiedź napisana na przykład z telefonu też pojawi się w wątku, bo trafia do folderu wysłanych. - **Pozostałe foldery** - spam, archiwum i własne foldery nie są pobierane. Mail przeniesiony tam przez regułę pocztową nie trafi do Ritevo. - **Typ wątku** - każdy wątek z e-maila jest **Wiadomością**; poczta nie ma dyskusji ani reklamacji. - **Zamówienia** - wątki z e-maila nie są automatycznie łączone z zamówieniami, nawet jeśli klient podał w treści numer zamówienia. - **Załączniki** - załączniki od klienta widzisz w wątku i pobierasz je z Ritevo. ### Odpowiadanie z Ritevo - **Nadawca** - odpowiedź wychodzi z adresu podłączonej skrzynki, przez jej serwer SMTP. Klient widzi zwykły mail od Ciebie. - **Wątek u klienta** - odpowiedź trafia do tej samej rozmowy w skrzynce klienta, nie jako nowy mail. - **Folder wysłanych** - odpowiedź zapisuje się w folderze wysłanych Twojej skrzynki, więc widzisz ją też w swoim programie pocztowym. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy serwer poczty odrzucił login albo hasło - najczęściej po zmianie hasła do skrzynki albo po usunięciu hasła aplikacji. Na liście integracji taka skrzynka ma czerwoną ramkę i napis **Wymaga ponownego połączenia**. Do czasu podania nowego hasła Ritevo nie pobiera maili i nie wysyła odpowiedzi z tej skrzynki. ![Dwie skrzynki na liście integracji: jedna z czerwoną ramką i napisem Wymaga ponownego połączenia, druga ze statusem Aktywna](https://ritevo.com/docs/integrations/email/pl-status.webp) 1. Jeśli używasz hasła aplikacji, wygeneruj nowe w ustawieniach konta pocztowego. 2. Na stronie integracji w Ritevo kliknij **Zaktualizuj dane logowania**, wpisz hasło i zatwierdź. Ritevo sprawdza je na serwerze tak samo jak przy dodawaniu - złe hasło zwróci błąd, poprawne odświeży połączenie. Ustawienia pobierania i historia zostają bez zmian. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie wysyła nowych maili do klientów z własnej inicjatywy - odpowiadasz w istniejących wątkach. - Nie pobiera maili ze spamu, archiwum ani własnych folderów. - Nie przenosi, nie oznacza i nie usuwa maili w Twojej skrzynce - skrzynka zostaje taka, jaka była. ### Integracja e-mail przez API (dla AI i integratorów) Ta sekcja istnieje tylko w wersji Markdown. Integracja e-mail ma typ `EMAIL` i własny zestaw endpointów pod `/integrations/email`. Każdy zapis, który zmienia dane serwera albo hasło, najpierw łączy się z serwerem poczty (IMAP i SMTP) i przy błędzie zwraca `424`. - `POST /integrations/email` - dodanie skrzynki. Pola: `accountName` (wymagane, do 255 znaków), `email` (wymagane, adres), `username` (opcjonalne - login, gdy inny niż adres), `password` (wymagane, do 1000 znaków), `imapHost`, `imapPort`, `smtpHost`, `smtpPort` (porty 1-65535), `security` (`SSL_TLS` albo `STARTTLS`). `409`, gdy ten adres jest już podłączony. - `GET /integrations/email` i `GET /integrations/email/{integrationId}` - lista i jedna skrzynka. Odpowiedź nie zawiera hasła; ma `active`, `authError` (true = **Wymaga ponownego połączenia**) i `messageConfig.fetchMessages`. - `PATCH /integrations/email/{integrationId}` - zmiana `accountName`, `username` i ustawień serwera (te same pola co przy dodawaniu, bez `email` i `password`). - `PATCH /integrations/email/{integrationId}/credentials` - nowe hasło: `{ "password": "..." }`. Czyści `authError`. - `PATCH /integrations/email/{integrationId}/fetch-messages` - włączenie lub wyłączenie pobierania: `{ "fetchMessages": true }`. - `DELETE /integrations/email/{integrationId}` - **Usuń integrację** (ustawia `active=false`), `PATCH /integrations/email/{integrationId}/restore` - **Przywróć integrację**. - Wątki z e-maila mają `threadType` = `MESSAGE` i nie mają powiązanego zamówienia. Endpointy tej integracji są pod `/integrations/email`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. ```json { "accountName": "Sklep - obsługa klienta", "email": "kontakt@mojsklep.pl", "username": null, "password": "haslo-aplikacji", "imapHost": "imap.mojsklep.pl", "imapPort": 993, "smtpHost": "smtp.mojsklep.pl", "smtpPort": 465, "security": "SSL_TLS" } ``` --- Source: https://ritevo.com/pl/docs/integrations/whatsapp (updated 2026-09-27) ## WhatsApp Integracja WhatsApp z Ritevo: podłączenie numeru WhatsApp Business przez Meta, PIN weryfikacji, wiadomości od klientów na żywo i odpowiadanie na nie. Integracja WhatsApp podłącza do Ritevo numer WhatsApp Business. Wiadomości od klientów trafiają do wspólnej skrzynki **Wiadomości** od razu, gdy klient je wyśle, i stamtąd na nie odpowiadasz. > **Wymagana integracja:** Potrzebujesz konta na Facebooku z dostępem do konta firmowego Meta i numeru telefonu, który podłączysz jako WhatsApp Business. Konto WhatsApp Business i numer możesz utworzyć w trakcie podłączania. Jedna integracja to jeden numer - okno Meta zawsze kończy się wyborem jednego numeru. Kilka numerów podłączasz po kolei, każdy jako osobną integrację. W ramach jednego konta firmowego dany numer podłączysz tylko raz: gdy Ty albo ktoś z Twoich współpracowników podłączy go ponownie, odświeży się istniejąca integracja - także wtedy, gdy wcześniej została usunięta - a druga nie powstanie. Unikalność: integracja jest unikalna w ramach firmy po `externalId` i typie `WHATSAPP`. Ponowne utworzenie odświeża istniejącą integrację zamiast tworzyć nową: od razu ustawia `authError=false`, a jeśli integracja była nieaktywna - także `active=true`. Przy `authError` to jedyny sposób na przywrócenie połączenia. WhatsApp podłączasz przez okno logowania Facebooka. Nie podajesz nam hasła - Meta przekazuje tylko ten dostęp, na który zgodzisz się w tym oknie. ### PIN weryfikacji dwuetapowej Przy podłączaniu wpisujesz 6-cyfrowy PIN weryfikacji dwuetapowej numeru. Meta wymaga go przy rejestracji numeru do wysyłania wiadomości: - **Numer bez PIN-u** - wpisz nowy PIN; zostanie ustawiony dla tego numeru. Zapisz go, przyda się przy ponownym podłączeniu. - **Numer z PIN-em** - wpisz ten sam PIN, który numer już ma. Inny PIN Meta odrzuci. - **Nie pamiętasz PIN-u** - zresetuj weryfikację dwuetapową numeru w panelu Meta i wpisz nowy PIN przy podłączaniu. ### Podłączenie konta Zacznij od listy integracji: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Komunikatory** wybierz kafelek **WhatsApp**. 3. W polu **PIN weryfikacyjny (6 cyfr)** wpisz PIN numeru - opis wyżej. 4. Kliknij **Połącz WhatsApp**. Otworzy się okno Meta. 5. W oknie Meta postępuj według kroków: zaloguj się, wybierz albo utwórz konto WhatsApp Business, wybierz albo dodaj numer telefonu i potwierdź udostępnienie danych przyciskiem **Kontynuuj**. 6. Wróć do okna z integracjami. Sprawdzamy w Meta, czy masz dostęp do wybranego konta i numeru, podłączamy numer do odbierania wiadomości i otwieramy ustawienia nowej integracji. Jeśli coś się nie zgadza, zobaczysz błąd zwrócony przez Meta i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran dodawania integracji WhatsApp z polem PIN weryfikacyjny (6 cyfr), podpowiedzią o PIN-ie i przyciskiem Połącz WhatsApp](https://ritevo.com/docs/integrations/whatsapp/pl-add.webp) ![Okno logowania do Facebooka dla firm z opisem połączenia konta WhatsApp Business i przyciskiem Kontynuuj](https://ritevo.com/docs/integrations/whatsapp/pl-meta.webp) > **Warto wiedzieć:** Jeśli okno Facebooka zostanie białe albo się zawiesi, zamknij je i kliknij przycisk połączenia jeszcze raz - to błąd po stronie Facebooka. Potem postępuj według kroków w oknie Facebooka. ### Ustawienia integracji Integracja od razu jest **Aktywna** i odbiera wiadomości - nie ma tu przełącznika pobierania, bo WhatsApp przekazuje wiadomości na bieżąco. Na stronie integracji znajdziesz, tylko do odczytu: - **Nazwa konta** - podłączony numer telefonu. - **Identyfikator WABA** - identyfikator konta WhatsApp Business w Meta. - **Identyfikator numeru telefonu** - identyfikator numeru w Meta. ![Szczegóły integracji WhatsApp: nazwa konta, identyfikator WABA i identyfikator numeru telefonu, tylko do odczytu](https://ritevo.com/docs/integrations/whatsapp/pl-details.webp) ![Sekcja Komunikatory na liście integracji z kafelkami WhatsApp i Messenger oznaczonymi jako Aktywna](https://ritevo.com/docs/integrations/whatsapp/pl-list.webp) ### Wiadomości z WhatsAppa - **Historia rozmów** - WhatsApp nie udostępnia historii, więc wiadomości i załączniki zapisujemy u siebie od chwili podłączenia. Masz do nich dostęp także wtedy, gdy integracja wymaga ponownego połączenia - bez połączenia nie wyślesz tylko odpowiedzi. - **Na żywo** - wiadomość od klienta pojawia się w skrzynce od razu, bez czekania na kolejne sprawdzenie. - **Wątki** - każda rozmowa z jednym numerem klienta to jeden wątek typu **Wiadomość**. Nie jest automatycznie łączony z zamówieniem. - **Odpowiedzi z innych programów** - jeśli na tym numerze odpisujesz klientom także z innego programu, w wątku zobaczysz tylko, że o tej godzinie wysłano wiadomość - bez jej treści. To ograniczenie WhatsAppa: nie przekazuje treści wiadomości wysłanych z innych programów. Żeby mieć całą rozmowę, odpowiadaj klientom tylko w Ritevo. ### Odpowiadanie klientom - **Od razu w wątku** - wysłaną odpowiedź widać w wątku od razu, a jej status zmienia się, gdy WhatsApp potwierdzi dostarczenie. - **24 godziny** - WhatsApp pozwala odpowiadać swobodnie przez 24 godziny od ostatniej wiadomości klienta. Później odrzuci zwykłą odpowiedź i zobaczysz błąd. Po tym czasie rozmowę można zacząć tylko zatwierdzonym szablonem WhatsApp - takich szablonów jeszcze nie wysyłamy, więc napiszesz dopiero, gdy klient odezwie się pierwszy. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy Meta przestała akceptować nasz dostęp do numeru - na przykład po odebraniu uprawnień aplikacji w ustawieniach konta firmowego Meta. Do czasu ponownego połączenia nie wyślesz odpowiedzi z tego numeru. 1. Przejdź przez **Podłączenie konta** jeszcze raz i wybierz w oknie Meta **ten sam** numer. 2. Wpisz **ten sam PIN**, który numer już ma. Połączenie odświeży się w istniejącej integracji - historia zostaje, druga integracja nie powstanie. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie pobiera rozmów sprzed podłączenia numeru. - Nie wysyła zatwierdzonych szablonów WhatsApp, więc nie zacznie rozmowy po upływie 24 godzin. - Nie pokazuje treści wiadomości wysłanych z innego programu podłączonego do tego numeru. ### Integracja WhatsApp przez API (dla AI i integratorów) Ta sekcja istnieje tylko w wersji Markdown. Integracja ma typ `MESSAGING` i dostawcę `WHATSAPP`. Podłączenie wymaga okna Meta (Embedded Signup) w przeglądarce, więc samo API nie utworzy integracji bez udziału człowieka. - `POST /integrations/messaging/whatsapp` - utworzenie integracji z wyniku okna Meta: `code` (jednorazowy kod autoryzacji), `wabaId`, `phoneNumberId` i `verificationPin` (6 cyfr). Backend sprawdza w Meta, że kod daje dostęp do tego konta i numeru; ponowne podłączenie tego samego numeru odświeża istniejącą integrację. - `GET /integrations/messaging/{integrationId}` - integracja: `accountName` (numer), `externalId` (`wabaId::-::phoneNumberId`), `phoneNumberId`, `displayPhoneNumber`, `active`, `authError` (true = **Wymaga ponownego połączenia**). Bez tokenu dostępu. - `DELETE /integrations/messaging/{integrationId}` - **Usuń integrację**, `PATCH /integrations/messaging/{integrationId}/restore` - **Przywróć integrację**. - Wątki mają `threadType` = `MESSAGE` i nie mają powiązanego zamówienia. Odpowiedź wysyłasz tak samo jak w innych kanałach. Endpointy tej integracji są pod `/integrations/messaging/whatsapp`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/messaging`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. Odłączenie aplikacji po stronie Meta: Meta nie powiadamia Ritevo o odebraniu dostępu. Nowe wiadomości przestają wtedy przychodzić, a integracja dostaje `authError=true` przy pierwszym zapytaniu do Meta, na przykład przy próbie wysłania odpowiedzi. Zapisana historia rozmów zostaje. --- Source: https://ritevo.com/pl/docs/integrations/messenger (updated 2026-09-27) ## Messenger Integracja Messenger z Ritevo: podłączenie strony na Facebooku, wiadomości od klientów na żywo, odpowiadanie, załączniki i ponowne połączenie. Integracja Messenger podłącza do Ritevo stronę na Facebooku. Wiadomości, które klienci wysyłają do strony przez Messengera, trafiają do wspólnej skrzynki **Wiadomości** od razu, i stamtąd na nie odpowiadasz. > **Wymagana integracja:** Potrzebujesz strony na Facebooku i konta, które ma do niej pełny dostęp. Jedna integracja to jedna strona. W oknie Facebooka zaznacz dokładnie **jedną** stronę - jeśli zaznaczysz kilka, zobaczysz błąd i nic nie zostanie zapisane. Kilka stron podłączasz po kolei, każdą jako osobną integrację. W ramach jednego konta firmowego daną stronę podłączysz tylko raz: gdy Ty albo ktoś z Twoich współpracowników podłączy ją ponownie, odświeży się istniejąca integracja - także wtedy, gdy wcześniej została usunięta - a druga nie powstanie. Unikalność: integracja jest unikalna w ramach firmy po `externalId` i typie `MESSENGER`. Ponowne utworzenie odświeża istniejącą integrację zamiast tworzyć nową: od razu ustawia `authError=false`, a jeśli integracja była nieaktywna - także `active=true`. Przy `authError` to jedyny sposób na przywrócenie połączenia. Messenger podłączasz przez okno logowania Facebooka. Nie podajesz nam hasła - Meta przekazuje tylko ten dostęp, na który zgodzisz się w tym oknie. ### Podłączenie konta Zacznij od listy integracji: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Komunikatory** wybierz kafelek **Messenger**. 3. Kliknij **Połącz z Facebookiem**. Otworzy się okno Facebooka. 4. Zaloguj się i zaznacz **jedną** stronę, którą chcesz podłączyć. Jeśli łączyłeś już wcześniej konto z Facebookiem, okno zapyta, czy kontynuować z wcześniejszymi ustawieniami - kliknij **Edytuj ustawienia**, żeby wybrać inną stronę, albo **Kontynuuj**. 5. Wróć do okna z integracjami i chwilę poczekaj - nie zamykaj go. Podłączamy stronę do odbierania wiadomości i otwieramy ustawienia nowej integracji. Jeśli coś się nie uda, zobaczysz błąd zwrócony przez Facebooka i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran dodawania integracji Messenger z informacją o wyborze jednej strony i przyciskiem Połącz z Facebookiem](https://ritevo.com/docs/integrations/messenger/pl-add.webp) ![Okno logowania do Facebooka dla firm z pytaniem, czy kontynuować z wcześniejszymi ustawieniami, i przyciskami Edytuj ustawienia oraz Kontynuuj](https://ritevo.com/docs/integrations/messenger/pl-facebook.webp) > **Warto wiedzieć:** Jeśli okno Facebooka zostanie białe albo się zawiesi, zamknij je i kliknij przycisk połączenia jeszcze raz - to błąd po stronie Facebooka. Potem postępuj według kroków w oknie Facebooka. ### Ustawienia integracji Integracja od razu jest **Aktywna** i odbiera wiadomości - nie ma tu przełącznika pobierania, bo Messenger przekazuje wiadomości na bieżąco. Na stronie integracji znajdziesz, tylko do odczytu: - **Nazwa strony** - nazwa podłączonej strony na Facebooku. - **Identyfikator strony** - identyfikator strony w Facebooku. ![Szczegóły integracji Messenger: nazwa strony i identyfikator strony, tylko do odczytu](https://ritevo.com/docs/integrations/messenger/pl-details.webp) ![Sekcja Komunikatory na liście integracji z kafelkami WhatsApp i Messenger oznaczonymi jako Aktywna](https://ritevo.com/docs/integrations/messenger/pl-list.webp) ### Wiadomości z Messengera - **Historia rozmów** - Messenger nie udostępnia historii, więc wiadomości i załączniki zapisujemy u siebie od chwili podłączenia. Masz do nich dostęp także wtedy, gdy integracja wymaga ponownego połączenia - bez połączenia nie wyślesz tylko odpowiedzi. - **Na żywo** - wiadomość od klienta pojawia się w skrzynce od razu, bez czekania na kolejne sprawdzenie. - **Wątki** - każda rozmowa z jedną osobą to jeden wątek typu **Wiadomość**, podpisany imieniem i nazwiskiem z jej profilu. Nie jest automatycznie łączony z zamówieniem. - **Przyciski strony** - gdy klient zamiast pisać kliknie przycisk ustawiony na Twojej stronie w Messengerze (na przykład „Rozpocznij" albo pozycję menu), w wątku zobaczysz wiadomość z nazwą tego przycisku. ### Odpowiadanie klientom - **Od razu w wątku** - wysłaną odpowiedź widać w wątku od razu, a jej status zmienia się, gdy Messenger potwierdzi wysyłkę. - **Załącznik i tekst** - Messenger nie wysyła pliku i tekstu w jednej wiadomości, więc klient dostanie dwie: najpierw plik, potem tekst. - **24 godziny** - Messenger pozwala odpowiadać swobodnie przez 24 godziny od ostatniej wiadomości klienta. Później odrzuci zwykłą odpowiedź i zobaczysz błąd. Po tym czasie można pisać tylko wiadomościami ze specjalnym oznaczeniem Meta (na przykład odpowiedzią konsultanta do 7 dni) - takich wiadomości jeszcze nie wysyłamy, więc napiszesz dopiero, gdy klient odezwie się pierwszy. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy Facebook przestał akceptować nasz dostęp do strony - na przykład po zmianie hasła, utracie uprawnień do strony albo odłączeniu aplikacji w ustawieniach Facebooka. Do czasu ponownego połączenia nie wyślesz odpowiedzi z tej strony. 1. Przejdź przez **Podłączenie konta** jeszcze raz i wybierz w oknie Facebooka **tę samą** stronę. 2. Połączenie odświeży się w istniejącej integracji - historia zostaje, druga integracja nie powstanie. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie pobiera rozmów sprzed podłączenia strony. - Nie zaczyna rozmów z klientami - odpowiadasz w rozmowach otwartych przez klienta. - Nie wysyła wiadomości ze specjalnym oznaczeniem Meta, więc nie napisze do klienta po upływie 24 godzin. - Nie obsługuje komentarzy pod postami ani wiadomości z Instagrama. ### Integracja Messenger przez API (dla AI i integratorów) Ta sekcja istnieje tylko w wersji Markdown. Integracja ma typ `MESSAGING` i dostawcę `MESSENGER`. Podłączenie wymaga okna logowania Facebooka w przeglądarce, więc samo API nie utworzy integracji bez udziału człowieka. - `POST /integrations/messaging/messenger` - utworzenie integracji z wyniku okna Facebooka: `code` (jednorazowy kod autoryzacji) i `redirectUri` (adres strony, która otworzyła okno - musi być identyczny). Ponowne podłączenie tej samej strony odświeża istniejącą integrację. - `GET /integrations/messaging/{integrationId}` - integracja: `accountName` (nazwa strony), `externalId` (identyfikator strony), `active`, `authError` (true = **Wymaga ponownego połączenia**). Bez tokenu dostępu. - `DELETE /integrations/messaging/{integrationId}` - **Usuń integrację**, `PATCH /integrations/messaging/{integrationId}/restore` - **Przywróć integrację**. - Wątki mają `threadType` = `MESSAGE` i nie mają powiązanego zamówienia. Odpowiedź wysyłasz tak samo jak w innych kanałach. Endpointy tej integracji są pod `/integrations/messaging/messenger`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/messaging`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. Odłączenie aplikacji po stronie Meta: Meta nie powiadamia Ritevo o odebraniu dostępu. Nowe wiadomości przestają wtedy przychodzić, a integracja dostaje `authError=true` przy pierwszym zapytaniu do Meta, na przykład przy próbie wysłania odpowiedzi. Zapisana historia rozmów zostaje. --- Source: https://ritevo.com/pl/docs/integrations/wfirma (updated 2026-09-29) ## wFirma Integracja wFirma z Ritevo: podłączenie kluczami API, przesyłanie faktur i paragonów, ustawienia VAT i kontrahentów, ponowne połączenie. Integracja z wFirma przesyła do wFirma faktury i paragony wystawione w Ritevo. Podłączasz ją kluczami API z panelu wFirma i wybierasz firmę, do której mają trafiać dokumenty. > **Wymagana integracja:** Potrzebujesz konta w wFirma i kluczy API wygenerowanych w jego panelu: klucza dostępu (Access Key) i klucza tajnego (Secret Key). Integracji wFirma możesz dodać dowolnie wiele, także kilka dla tego samego konta - na przykład z innymi danymi albo innymi ustawieniami wystawiania dokumentów. Każda działa osobno. Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami. `externalId` to ID firmy w wFirma. Listę firm dostępnych dla kluczy zwraca `POST /integrations/accountings/wfirma/companies`. Nowe klucze podasz przez `PATCH /integrations/accountings/wfirma/{id}/credentials` - w każdym stanie integracji. Sprawdza, czy klucze widzą firmę z `externalId`, i ustawia `authError=false` i `active=true`. ### Jakie dokumenty przesyła - **Faktura VAT** (API: "Faktura VAT" = `INVOICE`; wartość w `billingType`) - trafia do wFirma jako faktura VAT albo faktura bez VAT, zależnie od ustawienia **Faktura z VAT** na stronie integracji. - **Paragon** (API: "Paragon" = `RECEIPT`; wartość w `billingType`) - trafia do wFirma jako paragon z VAT albo bez VAT, zależnie od ustawienia **Paragon z VAT** na stronie integracji. - **Korekta faktury** (API: "Korekta faktury" = `CORRECTION`; wartość w `billingType`) - nie jest obsługiwana. ### Jak wygenerować klucz API Klucze API tworzysz w panelu wFirma. Secret Key wFirma pokazuje tylko raz, więc skopiuj oba klucze od razu - wkleisz je w Ritevo przy dodawaniu integracji. 1. Zaloguj się do wFirma. 2. Przejdź do **Ustawienia** → **Bezpieczeństwo** → **Aplikacje** → **Klucze API** i kliknij **Dodaj**. 3. Wpisz nazwę, na przykład „Ritevo", i potwierdź hasłem do wFirma. 4. Skopiuj **Access Key** i **Secret Key**. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Księgowość** wybierz kafelek **wFirma**. 3. Wklej **Klucz dostępu (Access Key)** i **Klucz tajny (Secret Key)** i kliknij **Kolejny krok**. Sprawdzamy klucze w wFirma - jeśli są błędne, zobaczysz błąd zwrócony przez wFirma. 4. Z listy **Wybierz firmę** wybierz firmę z Twojego konta wFirma i kliknij **Utwórz integrację**. Otworzą się ustawienia nowej integracji. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem wFirma w sekcji Księgowość](https://ritevo.com/docs/integrations/wfirma/pl-catalogue.webp) ![Ekran dodawania integracji wFirma z polami Klucz dostępu i Klucz tajny oraz przyciskiem Kolejny krok](https://ritevo.com/docs/integrations/wfirma/pl-add.webp) ### Ustawienia integracji Nazwą integracji jest nazwa firmy pobrana z wFirma - nie da się jej zmienić. Na stronie integracji znajdziesz: - **Ustawienia integracji** - stałe zasady: przesyłamy tylko kwoty brutto, numer dokumentu nadaje wFirma według swojej numeracji, a wFirma przyjmuje tylko polskie stawki VAT - więcej niżej. - **Twórz kontrahentów** - po włączeniu wFirma dopisuje kupującego do listy kontrahentów, jeśli jeszcze go tam nie ma. Domyślnie wyłączone. - **Faktura z VAT** / **Faktura bez VAT** - rodzaj faktury tworzonej w wFirma. Domyślnie z VAT. - **Paragon z VAT** / **Paragon bez VAT** - rodzaj paragonu tworzonego w wFirma. Domyślnie z VAT. - **Zaktualizuj dane logowania** - podajesz nowe klucze API tej samej firmy. Tworzenie: `accessKey`, `secretKey` i `externalId` - ID firmy z listy `POST /integrations/accountings/wfirma/companies`, która zwraca pozycje `id:nazwa`. Ustawienia zmieniasz osobnymi `PATCH`: `/{id}/invoice-with-vat` z `invoiceWithVat` (**Faktura z VAT** = `true`), `/{id}/receipt-with-vat` z `receiptWithVat` (**Paragon z VAT** = `true`) i `/{id}/auto-create-contractors` z `autoCreateContractors` (**Twórz kontrahentów** = `true`). > **Warto wiedzieć:** Przełączniki zapisują się od razu i działają dla dokumentów przesyłanych od tej chwili. ### Przesyłanie dokumentów > **Warto wiedzieć:** Na jednym zamówieniu może być tylko jedna aktywna faktura i jeden aktywny paragon. Kolejny dokument tego typu wystawisz dopiero po usunięciu poprzedniego. Korekt do faktury możesz wystawić dowolnie wiele. Dokumenty wystawiasz w zamówieniu. Do wFirma przesyłasz je na dwa sposoby: - **Ręcznie** - w szczegółach dokumentu, w karcie **Zew. systemy księgowe**, kliknij przycisk z nazwą konta wFirma. Przycisk pojawia się tylko przy dokumentach, które ta integracja obsługuje. - **Automatycznie** - krokiem **Prześlij fakturę do zew. systemu księgowego** albo **Prześlij paragon do zew. systemu księgowego** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Przesyłanie dokumentów najlepiej zaplanować po kolei - najpierw wystawienie, potem przesłanie: - **Faktura** - pierwsza akcja kończy się krokiem **Wygeneruj fakturę**. Druga startuje wyzwalaczem **Faktura(dodanie/usunięcie)**, ma warunek **Posiada fakturę** i krok **Prześlij fakturę do zew. systemu księgowego**. - **Paragon** - tak samo: pierwsza akcja kończy się krokiem **Wygeneruj paragon**, a druga startuje wyzwalaczem **Paragon(dodanie/usunięcie)**, ma warunek **Posiada paragon** i krok **Prześlij paragon do zew. systemu księgowego**. - **Korekty** - do jednej faktury możesz wystawić wiele korekt. Każdą prześlij zaraz po wystawieniu, zanim wystawisz następną. > **Warto wiedzieć:** Krok przesłania wysyła zawsze tylko jeden dokument - najnowszy nieusunięty danego typu. Jeśli najpierw wystawisz wszystkie dokumenty, a dopiero potem włączysz przesyłanie, trafi tylko ostatni, a pozostałe prześlesz ręcznie. Usuniętego dokumentu nie prześlesz. W tej samej karcie każde przesłanie ma swoją ikonę. Po najechaniu na nią widzisz konto, stan i datę: - **W trakcie przesyłania** (API: "W trakcie przesyłania" = `PENDING`; wartość w `externalTransfers[].status`) - dokument jest wysłany, czekamy na potwierdzenie od wFirma. - **Przesłano pomyślnie** (API: "Przesłano pomyślnie" = `SUCCESS`; wartość w `externalTransfers[].status`) - dokument jest w wFirma. Kliknij ikonę, żeby go pobrać albo otworzyć. - **Błąd podczas przesyłania** (API: "Błąd podczas przesyłania" = `FAILED`; wartość w `externalTransfers[].status`) - dokument nie trafił do wFirma. Pod stanem widzisz powód błędu. > **Warto wiedzieć:** Jeden dokument ma do danej integracji tylko jedno przesłanie: prześlesz go tam raz. Jeśli przesłanie skończy się błędem, możesz je ponowić tym samym przyciskiem. Do innej integracji księgowej ten sam dokument prześlesz osobno. Akcje dla zamówień: kroki **Prześlij fakturę do zew. systemu księgowego** i **Prześlij paragon do zew. systemu księgowego** to `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` w `actionSteps[].action.type`, z `uuidValue` = id integracji księgowej (`GET /integrations/accountings`). Wyzwalacze **Przesłano fakturę w zew. systemie księgowym** i **Przesłano paragon w zew. systemie księgowym** to `triggerType` = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. Warunki **Ma udany transfer faktury do zew. systemu księgowego** / **Nie ma udanego transferu faktury do zew. systemu księgowego** = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`, a dla paragonu `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT` (`uuidValues` = id integracji księgowych). Liczy się tylko przesłanie `SUCCESS`. Krok bierze ostatni dokument z `billings[]` zamówienia o danym `billingType` (`INVOICE` albo `RECEIPT`) z `deleted` = `false`. Na zamówieniu jest najwyżej jeden dokument danego `billingType` z `deleted` = `false` - próba wystawienia drugiego zwraca `BILLING_ALREADY_EXISTS`. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). #### Jak dokument trafia do wFirma - **Od razu** - wFirma odpowiada od razu, więc dokument ma stan **Przesłano pomyślnie** albo **Błąd podczas przesyłania** zaraz po wysłaniu. - **Numer i daty** - numer nadaje wFirma. Datę wystawienia, datę sprzedaży i termin płatności bierzemy z dokumentu w Ritevo. - **PDF** - kliknięcie ikony pobiera PDF wygenerowany przez wFirma. - **Stawki VAT** - wFirma przyjmuje od nas 23%, 8%, 5%, 0%, WDT, Zw. i O.o, a stawki OSS dobieramy według kraju kupującego. Dokument z inną stawką nie zostanie przesłany - zobaczysz błąd **Stawka podatku nie jest wspierana**. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy wFirma przestała akceptować klucze API - na przykład po ich usunięciu w panelu wFirma. Do czasu podania nowych kluczy dokumenty nie trafią do wFirma. 1. W panelu wFirma wygeneruj nowe klucze API - tak samo jak przy pierwszym podłączeniu. 2. Na stronie integracji kliknij **Zaktualizuj dane logowania**, wklej oba klucze i zatwierdź. Sprawdzamy je w wFirma - klucze muszą mieć dostęp do tej samej firmy. Poprawne odświeżą połączenie, a ustawienia i historia przesłanych dokumentów zostają bez zmian. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo. Dokumenty przesłane wcześniej zostają w wFirma. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie przesyła korekt faktur. - Nie zmienia ani nie usuwa w wFirma dokumentów, które już tam trafiły. - Nie pobiera dokumentów z wFirma do Ritevo. ### Integracja przez API Endpointy tej integracji są pod `/integrations/accountings/wfirma`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/accountings`. Dokument przesyłasz przez `POST /orders/billings/{billingId}/transfer-to-external-accounting/{integrationId}`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/ksef (updated 2026-09-29) ## KSeF Integracja KSeF z Ritevo: podłączenie certyfikatem KSeF, wysyłanie faktur i korekt w trybie online, numer KSeF, ponowne połączenie. Integracja z KSeF wysyła faktury i korekty wystawione w Ritevo do Krajowego Systemu e-Faktur. Podłączasz ją certyfikatem KSeF, a faktury trafiają do KSeF w trybie online. > **Wymagana integracja:** Potrzebujesz NIP-u firmy i certyfikatu KSeF do uwierzytelniania: pliku klucza prywatnego (.key), hasła do tego klucza i pliku certyfikatu (.pem albo .crt). Integracji KSeF możesz dodać dowolnie wiele, także kilka dla tego samego konta - na przykład z innymi danymi albo innymi ustawieniami wystawiania dokumentów. Każda działa osobno. Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami. `externalId` to NIP. Nowy certyfikat podasz przez `PUT /integrations/accountings/ksef/{id}/certificate` - w każdym stanie integracji. Po udanym logowaniu do KSeF ustawia `authError=false` i `active=true`. ### Jakie dokumenty przesyła - **Faktura VAT** (API: "Faktura VAT" = `INVOICE`; wartość w `billingType`) - trafia do KSeF jako faktura podstawowa. - **Korekta faktury** (API: "Korekta faktury" = `CORRECTION`; wartość w `billingType`) - trafia do KSeF jako faktura korygująca. - **Paragon** (API: "Paragon" = `RECEIPT`; wartość w `billingType`) - nie jest obsługiwany. ### Jak zdobyć certyfikat KSeF Certyfikat generujesz w Aplikacji Podatnika KSeF Ministerstwa Finansów. Hasła do klucza prywatnego nie da się odzyskać, więc zapisz je razem z oboma plikami - podasz je w Ritevo przy dodawaniu integracji. Jeśli zgubisz hasło albo plik klucza, jedyne wyjście to wygenerować nowy certyfikat z nową parą kluczy. 1. Zaloguj się do Aplikacji Podatnika KSeF, na przykład profilem zaufanym. 2. W sekcji certyfikatów wybierz **Wnioskuj o certyfikat**. 3. Wybierz certyfikat do uwierzytelniania, wpisz jego nazwę i ustaw hasło do klucza prywatnego. 4. Kliknij **Generuj**. Plik klucza prywatnego (.key) zapisze się na Twoim komputerze. 5. Gdy wniosek zostanie zatwierdzony, pobierz plik certyfikatu (.crt). ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Księgowość** wybierz kafelek **KSeF**. 3. W polu **Nazwa konta** wpisz własną nazwę integracji, a w polu **Nip** - NIP firmy, dla której wystawiasz faktury. 4. Dodaj **Plik klucza prywatnego (.key)**, wpisz **Hasło klucza** i dodaj **Plik certyfikatu (.pem/.crt)**. 5. Kliknij **Utwórz integrację**. Od razu logujemy się tym certyfikatem do KSeF: jeśli się uda, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem KSeF w sekcji Księgowość](https://ritevo.com/docs/integrations/ksef/pl-catalogue.webp) ![Ekran dodawania integracji KSeF z polami Nazwa konta, Nip, plikami certyfikatu i hasłem klucza](https://ritevo.com/docs/integrations/ksef/pl-add.webp) ### Ustawienia integracji Na stronie integracji znajdziesz: - **Faktury są wysyłane w trybie online** - każda faktura trafia do KSeF od razu po przesłaniu. - **Nazwa konta** - Twoja własna nazwa integracji. Zmieniasz ją i zapisujesz przyciskiem **Zaktualizuj integrację**. - **Zaktualizuj dane logowania** - podajesz nowe pliki i hasło, na przykład gdy certyfikat wygasa. Sprawdzamy je w KSeF tak samo jak przy dodawaniu. Tworzenie: `accountName`, `nip`, `certificateBase64` (plik .key w Base64), `certificatePassword` i `certificatePemBase64` (plik .pem albo .crt w Base64). Nazwę zmieniasz przez `PATCH /integrations/accountings/ksef/{id}` z `accountName`, a certyfikat przez `PUT /integrations/accountings/ksef/{id}/certificate` z tymi samymi trzema polami certyfikatu. ![Szczegóły integracji KSeF: informacja o trybie online, nazwa konta i przycisk Zaktualizuj dane logowania](https://ritevo.com/docs/integrations/ksef/pl-details.webp) ### Przesyłanie dokumentów > **Warto wiedzieć:** Na jednym zamówieniu może być tylko jedna aktywna faktura i jeden aktywny paragon. Kolejny dokument tego typu wystawisz dopiero po usunięciu poprzedniego. Korekt do faktury możesz wystawić dowolnie wiele. Dokumenty wystawiasz w zamówieniu. Do KSeF przesyłasz je na dwa sposoby: - **Ręcznie** - w szczegółach dokumentu, w karcie **Zew. systemy księgowe**, kliknij przycisk z nazwą konta KSeF. Przycisk pojawia się tylko przy dokumentach, które ta integracja obsługuje. - **Automatycznie** - krokiem **Prześlij fakturę do zew. systemu księgowego** albo **Prześlij paragon do zew. systemu księgowego** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Przesyłanie dokumentów najlepiej zaplanować po kolei - najpierw wystawienie, potem przesłanie: - **Faktura** - pierwsza akcja kończy się krokiem **Wygeneruj fakturę**. Druga startuje wyzwalaczem **Faktura(dodanie/usunięcie)**, ma warunek **Posiada fakturę** i krok **Prześlij fakturę do zew. systemu księgowego**. - **Paragon** - tak samo: pierwsza akcja kończy się krokiem **Wygeneruj paragon**, a druga startuje wyzwalaczem **Paragon(dodanie/usunięcie)**, ma warunek **Posiada paragon** i krok **Prześlij paragon do zew. systemu księgowego**. - **Korekty** - do jednej faktury możesz wystawić wiele korekt. Każdą prześlij zaraz po wystawieniu, zanim wystawisz następną. > **Warto wiedzieć:** Krok przesłania wysyła zawsze tylko jeden dokument - najnowszy nieusunięty danego typu. Jeśli najpierw wystawisz wszystkie dokumenty, a dopiero potem włączysz przesyłanie, trafi tylko ostatni, a pozostałe prześlesz ręcznie. Usuniętego dokumentu nie prześlesz. W tej samej karcie każde przesłanie ma swoją ikonę. Po najechaniu na nią widzisz konto, stan i datę: - **W trakcie przesyłania** (API: "W trakcie przesyłania" = `PENDING`; wartość w `externalTransfers[].status`) - dokument jest wysłany, czekamy na potwierdzenie od KSeF. - **Przesłano pomyślnie** (API: "Przesłano pomyślnie" = `SUCCESS`; wartość w `externalTransfers[].status`) - dokument jest w KSeF. Kliknij ikonę, żeby go pobrać albo otworzyć. - **Błąd podczas przesyłania** (API: "Błąd podczas przesyłania" = `FAILED`; wartość w `externalTransfers[].status`) - dokument nie trafił do KSeF. Pod stanem widzisz powód błędu. > **Warto wiedzieć:** Jeden dokument ma do danej integracji tylko jedno przesłanie: prześlesz go tam raz. Jeśli przesłanie skończy się błędem, możesz je ponowić tym samym przyciskiem. Do innej integracji księgowej ten sam dokument prześlesz osobno. Akcje dla zamówień: kroki **Prześlij fakturę do zew. systemu księgowego** i **Prześlij paragon do zew. systemu księgowego** to `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` w `actionSteps[].action.type`, z `uuidValue` = id integracji księgowej (`GET /integrations/accountings`). Wyzwalacze **Przesłano fakturę w zew. systemie księgowym** i **Przesłano paragon w zew. systemie księgowym** to `triggerType` = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. Warunki **Ma udany transfer faktury do zew. systemu księgowego** / **Nie ma udanego transferu faktury do zew. systemu księgowego** = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`, a dla paragonu `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT` (`uuidValues` = id integracji księgowych). Liczy się tylko przesłanie `SUCCESS`. Krok bierze ostatni dokument z `billings[]` zamówienia o danym `billingType` (`INVOICE` albo `RECEIPT`) z `deleted` = `false`. Na zamówieniu jest najwyżej jeden dokument danego `billingType` z `deleted` = `false` - próba wystawienia drugiego zwraca `BILLING_ALREADY_EXISTS`. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). #### Jak faktura trafia do KSeF - **Potwierdzenie** - KSeF przetwarza fakturę po otrzymaniu, więc najpierw ma ona stan **W trakcie przesyłania**. Sprawdzamy odpowiedź KSeF co kilka sekund. Jeśli KSeF nie potwierdzi faktury w ciągu 24 godzin, przesłanie kończy się błędem. - **Numery i data** - na fakturze jest numer nadany w Ritevo. Po przyjęciu KSeF nadaje jej numer KSeF. Datą wystawienia w KSeF jest dzień przesłania. - **PDF** - kliknięcie ikony pobiera PDF przygotowany z faktury zapisanej w KSeF, z numerem KSeF. - **Korekty** - przesyłasz je ręcznie. Akcje automatyczne przesyłają tylko faktury i paragony. - **Stawki VAT** - KSeF przyjmuje od nas 23%, 8%, 5%, 0%, WDT, Zw. i O.o, a także dawne 22% i 7%. Stawki OSS przesyłamy jako sprzedaż OSS. Faktura z inną stawką nie zostanie przesłana - zobaczysz błąd **Stawka podatku nie jest wspierana**. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy KSeF przestał akceptować certyfikat - na przykład po jego wygaśnięciu albo unieważnieniu. Do tego czasu faktury nie trafią do KSeF. 1. Wygeneruj nowy certyfikat KSeF - tak samo jak przy pierwszym podłączeniu. 2. Na stronie integracji kliknij **Zaktualizuj dane logowania**, dodaj nowe pliki, wpisz hasło i zatwierdź. Poprawny certyfikat odświeży połączenie, a historia przesłanych faktur zostaje bez zmian. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ![Okno Zaktualizuj dane logowania w integracji KSeF z polami na plik klucza prywatnego, hasło klucza i plik certyfikatu](https://ritevo.com/docs/integrations/ksef/pl-update.webp) ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo. Dokumenty przesłane wcześniej zostają w KSeF. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie przesyła paragonów. - Nie wysyła faktur w trybie offline - tylko online. - Nie zmienia faktur, które już trafiły do KSeF - zmianę wprowadzasz korektą. - Nie pobiera z KSeF faktur zakupowych ani innych dokumentów. ### Integracja przez API Endpointy tej integracji są pod `/integrations/accountings/ksef`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/accountings`. Dokument przesyłasz przez `POST /orders/billings/{billingId}/transfer-to-external-accounting/{integrationId}`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/eparagony (updated 2026-09-29) ## eparagony.pl Integracja eparagony.pl z Ritevo: podłączenie danymi API, przesyłanie paragonów, fiskalizacja i druk, sekret webhooka, ponowne połączenie. Integracja z eparagony.pl przesyła do eParagony paragony wystawione w Ritevo. Podłączasz ją danymi dostępowymi do API z panelu eParagony i wskazujesz punkt sprzedaży. > **Wymagana integracja:** Potrzebujesz konta w eParagony z punktem sprzedaży i danych dostępowych do API: Client ID, Client Secret, sekretu webhooka i ID punktu sprzedaży (posId). Integracji eparagony.pl możesz dodać dowolnie wiele, także kilka dla tego samego konta - na przykład z innymi danymi albo innymi ustawieniami wystawiania dokumentów. Każda działa osobno. Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami. `externalId` to `posId`. Nowe dane dostępowe podasz przez `PATCH /integrations/accountings/eparagony/{id}/credentials` - w każdym stanie integracji. Sprawdza Client ID i Client Secret w eParagony i ustawia `authError=false` i `active=true`. ### Jakie dokumenty przesyła - **Paragon** (API: "Paragon" = `RECEIPT`; wartość w `billingType`) - trafia do eParagony jako e-paragon. - **Faktura VAT** i **Korekta faktury** (API: "Faktura VAT" = `INVOICE`, "Korekta faktury" = `CORRECTION`; wartość w `billingType`) - nie są obsługiwane. ### Skąd wziąć dane dostępowe Dane dostępowe do API eParagony udostępnia po rejestracji w usłudze, razem z dokumentacją API. Przygotuj je przed dodaniem integracji: 1. Załóż konto w eparagony.pl, jeśli jeszcze go nie masz. 2. Przygotuj **Client ID**, **Client Secret** i sekret webhooka. 3. Przygotuj ID punktu sprzedaży (posId), do którego mają trafiać paragony. 4. Jeśli nie możesz znaleźć tych danych, napisz do pomocy eParagony: pomoc@eparagony.pl. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Księgowość** wybierz kafelek **eParagony**. 3. W karcie **Ustawienia podstawowe** wpisz **Nazwa konta** - własną nazwę integracji - i **ID punktu sprzedaży (posId)**. 4. W karcie **Dane dostępowe** wklej **Client ID**, **Client Secret** i **Sekret webhooka**. 5. W karcie **Ustawienia integracji** ustaw **Fiskalizuj dokumenty** i **Drukuj paragon** - opis niżej. 6. Kliknij **Utwórz integrację**. Client ID i Client Secret sprawdzamy od razu w eParagony: jeśli są poprawne, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem eParagony w sekcji Księgowość](https://ritevo.com/docs/integrations/eparagony/pl-catalogue.webp) ![Ekran dodawania integracji eParagony z kartami Ustawienia podstawowe, Dane dostępowe i Ustawienia integracji](https://ritevo.com/docs/integrations/eparagony/pl-add.webp) ### Ustawienia integracji Na stronie integracji znajdziesz poniższe pola. Zmiany nazwy i przełączników zapisujesz przyciskiem **Zaktualizuj integrację**: - **Nazwa konta** - Twoja własna nazwa integracji. Możesz ją zmienić w każdej chwili. - **ID punktu sprzedaży (posId)** - punkt podany przy dodawaniu. Nie da się go zmienić - inny punkt dodajesz jako nową integrację. - **Fiskalizuj dokumenty** - po włączeniu eParagony fiskalizuje paragon. Wymaga to działającej u Ciebie usługi drukowania dokumentów eParagony. Domyślnie włączone. - **Drukuj paragon** - po włączeniu eParagony drukuje paragon. Tylko dla stacjonarnego punktu sprzedaży. Domyślnie wyłączone. - **Zaktualizuj dane logowania** - podajesz nowe Client ID, Client Secret i sekret webhooka. Tworzenie: `accountName`, `posId`, `clientId`, `clientSecret`, `webhookSecret`, `fiscalize` (**Fiskalizuj dokumenty**) i `print` (**Drukuj paragon**) - oba `true` albo `false`. Ustawienia zmieniasz przez `PATCH /integrations/accountings/eparagony/{id}` z `accountName`, `fiscalize` i `print`. > **Warto wiedzieć:** Sekretu webhooka nie da się sprawdzić przy zapisie. Jeśli jest błędny, paragon trafi do eParagony, ale nie dostaniemy potwierdzenia i przesłanie zostanie **W trakcie przesyłania**. Wpisz go dokładnie tak, jak jest w panelu eParagony. ### Przesyłanie dokumentów > **Warto wiedzieć:** Na jednym zamówieniu może być tylko jedna aktywna faktura i jeden aktywny paragon. Kolejny dokument tego typu wystawisz dopiero po usunięciu poprzedniego. Korekt do faktury możesz wystawić dowolnie wiele. Dokumenty wystawiasz w zamówieniu. Do eparagony.pl przesyłasz je na dwa sposoby: - **Ręcznie** - w szczegółach dokumentu, w karcie **Zew. systemy księgowe**, kliknij przycisk z nazwą konta eparagony.pl. Przycisk pojawia się tylko przy dokumentach, które ta integracja obsługuje. - **Automatycznie** - krokiem **Prześlij fakturę do zew. systemu księgowego** albo **Prześlij paragon do zew. systemu księgowego** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Przesyłanie dokumentów najlepiej zaplanować po kolei - najpierw wystawienie, potem przesłanie: - **Faktura** - pierwsza akcja kończy się krokiem **Wygeneruj fakturę**. Druga startuje wyzwalaczem **Faktura(dodanie/usunięcie)**, ma warunek **Posiada fakturę** i krok **Prześlij fakturę do zew. systemu księgowego**. - **Paragon** - tak samo: pierwsza akcja kończy się krokiem **Wygeneruj paragon**, a druga startuje wyzwalaczem **Paragon(dodanie/usunięcie)**, ma warunek **Posiada paragon** i krok **Prześlij paragon do zew. systemu księgowego**. - **Korekty** - do jednej faktury możesz wystawić wiele korekt. Każdą prześlij zaraz po wystawieniu, zanim wystawisz następną. > **Warto wiedzieć:** Krok przesłania wysyła zawsze tylko jeden dokument - najnowszy nieusunięty danego typu. Jeśli najpierw wystawisz wszystkie dokumenty, a dopiero potem włączysz przesyłanie, trafi tylko ostatni, a pozostałe prześlesz ręcznie. Usuniętego dokumentu nie prześlesz. W tej samej karcie każde przesłanie ma swoją ikonę. Po najechaniu na nią widzisz konto, stan i datę: - **W trakcie przesyłania** (API: "W trakcie przesyłania" = `PENDING`; wartość w `externalTransfers[].status`) - dokument jest wysłany, czekamy na potwierdzenie od eparagony.pl. - **Przesłano pomyślnie** (API: "Przesłano pomyślnie" = `SUCCESS`; wartość w `externalTransfers[].status`) - dokument jest w eparagony.pl. Kliknij ikonę, żeby go pobrać albo otworzyć. - **Błąd podczas przesyłania** (API: "Błąd podczas przesyłania" = `FAILED`; wartość w `externalTransfers[].status`) - dokument nie trafił do eparagony.pl. Pod stanem widzisz powód błędu. > **Warto wiedzieć:** Jeden dokument ma do danej integracji tylko jedno przesłanie: prześlesz go tam raz. Jeśli przesłanie skończy się błędem, możesz je ponowić tym samym przyciskiem. Do innej integracji księgowej ten sam dokument prześlesz osobno. Akcje dla zamówień: kroki **Prześlij fakturę do zew. systemu księgowego** i **Prześlij paragon do zew. systemu księgowego** to `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` w `actionSteps[].action.type`, z `uuidValue` = id integracji księgowej (`GET /integrations/accountings`). Wyzwalacze **Przesłano fakturę w zew. systemie księgowym** i **Przesłano paragon w zew. systemie księgowym** to `triggerType` = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING` i `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. Warunki **Ma udany transfer faktury do zew. systemu księgowego** / **Nie ma udanego transferu faktury do zew. systemu księgowego** = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`, a dla paragonu `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT` (`uuidValues` = id integracji księgowych). Liczy się tylko przesłanie `SUCCESS`. Krok bierze ostatni dokument z `billings[]` zamówienia o danym `billingType` (`INVOICE` albo `RECEIPT`) z `deleted` = `false`. Na zamówieniu jest najwyżej jeden dokument danego `billingType` z `deleted` = `false` - próba wystawienia drugiego zwraca `BILLING_ALREADY_EXISTS`. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). #### Jak paragon trafia do eParagony - **Bez fiskalizacji** - eParagony przyjmuje paragon od razu, więc ma on stan **Przesłano pomyślnie** zaraz po wysłaniu. - **Z fiskalizacją** - paragon ma stan **W trakcie przesyłania**, dopóki eParagony nie potwierdzi fiskalizacji. Potem zmienia się na **Przesłano pomyślnie** albo na **Błąd podczas przesyłania** z powodem od eParagony. - **Numer** - w eParagony paragon ma numer nadany w Ritevo. - **Podgląd** - kliknięcie ikony otwiera paragon na stronie eParagony. - **Stawki VAT** - eParagony przyjmuje od nas 23%, 8%, 5%, 0% i Zw., a także dawne 22%, 7% i 3%. Paragon z inną stawką nie zostanie przesłany - zobaczysz błąd **Stawka podatku nie jest wspierana**. ### Wymaga ponownego połączenia Ten stan pojawia się, gdy eParagony przestało akceptować Client ID i Client Secret - na przykład po ich zmianie w panelu eParagony. Do tego czasu paragony nie trafią do eParagony. 1. W panelu eParagony skopiuj aktualne dane dostępowe. 2. Na stronie integracji kliknij **Zaktualizuj dane logowania**, wklej Client ID, Client Secret i sekret webhooka i zatwierdź. Sprawdzamy je w eParagony tak samo jak przy dodawaniu - poprawne odświeżą połączenie. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo. Dokumenty przesłane wcześniej zostają w eparagony.pl. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie przesyła faktur ani korekt. - Nie zmienia ani nie anuluje paragonów, które już trafiły do eParagony. ### Integracja przez API Endpointy tej integracji są pod `/integrations/accountings/eparagony`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/accountings`. Dokument przesyłasz przez `POST /orders/billings/{billingId}/transfer-to-external-accounting/{integrationId}`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/send-with-allegro (updated 2026-10-07) ## Wysyłam z Allegro Integracja Wysyłam z Allegro w Ritevo: przypisanie konta Allegro, ustawienia paczki i punktów nadania, tworzenie przesyłek i etykiet dla zamówień z Allegro. Integracja Wysyłam z Allegro tworzy przesyłki dla zamówień z Allegro przez usługę Wysyłam z Allegro. Nie ma własnego logowania - korzysta z konta Allegro, które masz już podłączone w Ritevo. > **Wymagana integracja:** Potrzebujesz konta Allegro podłączonego w Ritevo jako [integracja Allegro](https://ritevo.com/pl/docs/integrations/allegro). Integracji Wysyłam z Allegro możesz dodać dowolnie wiele, także kilka dla tego samego konta - na przykład z innym formatem etykiety, inną paczką albo innym adresem nadawcy. Każda działa osobno. Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami. `externalId` nie jest używany. Integracja wskazuje konto Allegro przez `marketplaceAccountId`. Nie ma endpointu danych logowania - błąd autoryzacji dotyczy integracji Allegro pod `/integrations/marketplaces`, a zapis ustawień tej integracji zawsze ustawia `authError=false` i `active=true`. ### Jakie przesyłki tworzy - **Tylko zamówienia z Allegro** - z tego konta Allegro, które wybierzesz w integracji. Przy innych zamówieniach nie zobaczysz przycisku, a akcja skończy się błędem **Zamówienie nie jest kompatybilne z wybraną integracją lub metodą wysyłki**. - **Przewoźnik** - ten, którego kupujący wybrał na Allegro. Nie wybierasz go w Ritevo. - **Punkt odbioru** - gdy kupujący wybrał paczkomat albo punkt, przesyłka trafia właśnie tam. - **Pobranie** - gdy zamówienie jest za pobraniem, a wybrana dostawa Allegro obsługuje pobranie. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Przesyłki** wybierz kafelek **Wysyłam z Allegro**. 3. W polu **Konto marketplace Allegro** wybierz konto, z którego zamówienia chcesz wysyłać, a w polu **Nazwa konta** wpisz własną nazwę integracji. 4. Uzupełnij pozostałe ustawienia opisane niżej i kliknij **Utwórz integrację**. Otworzą się ustawienia nowej integracji. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Wysyłam z Allegro w sekcji Przesyłki](https://ritevo.com/docs/integrations/send-with-allegro/pl-catalogue.webp) ![Ekran dodawania konta Wysyłam z Allegro z polami Konto marketplace Allegro, Nazwa konta, Rozmiar strony i Format etykiety](https://ritevo.com/docs/integrations/send-with-allegro/pl-add.webp) ### Ustawienia integracji Na stronie integracji znajdziesz poniższe pola. Zmiany zapisujesz przyciskiem **Zaktualizuj integrację**: - **Konto marketplace Allegro** - konto Allegro, dla którego zamówień tworzysz przesyłki. - **Nazwa konta** - Twoja własna nazwa integracji. - **Rozmiar strony** - A4 albo A6. Domyślnie A4. - **Format etykiety** - PDF albo ZPL. Domyślnie PDF. - **Punkty odbioru** - numery punktów, w których nadajesz paczki poszczególnych przewoźników: DPD, Poczta Polska, Allegro One, Allegro International i InPost. Puste pole oznacza, że paczkę odbiera kurier, a uzupełnione - że nadajesz ją w tym punkcie. **Numer punktu UPS** dziś nie jest wykorzystywany. - **Szczegóły paczki** - typ (**Paczka**, **List**, **Paleta** albo **Inne**), wymiary w centymetrach i waga w kilogramach. Te dane trafiają do każdej przesyłki. - **Płatność za pobraniem** - **Numer konta IBAN** i **Właściciel konta**. Przekazujemy je tylko wtedy, gdy wybrana dostawa Allegro ich wymaga. - **Adres nadawcy na etykiecie** - dane nadawcy, które przewoźnik drukuje na etykiecie. - **Adres odbioru przesyłek przez kuriera** - adres, spod którego kurier odbiera paczki. Może być inny niż adres nadawcy na etykiecie - na przykład przy dropshippingu: na etykiecie jest Twój sklep, a kurier odbiera paczkę z hurtowni. - **Dodatkowe ubezpieczenie** - kwota ubezpieczenia każdej przesyłki: **Brak**, **Wartość zamówienia z dostawą**, **Wartość zamówienia bez dostawy** albo **Stała kwota**. W **Źródło waluty** wybierasz walutę zamówienia, walutę kraju dostawy albo stałą walutę. Pola integracji: `accountName`, `marketplaceAccountId` (id integracji Allegro z `GET /integrations/marketplaces`), `pageSize` = `A4` albo `A6`, `labelFormat` = `PDF` albo `ZPL`, numery punktów `dpdPickupPointNumber`, `upsPickupPointNumber`, `pocztaPolskaPickupPointNumber`, `allegroOnePickupPointNumber`, `allegroInternationalPickupPointNumber`, `inPostPickupPointNumber`, `packageDetails` z `packageType` (**Paczka** = `PACKAGE`, **List** = `DOX`, **Paleta** = `PALLET`, **Inne** = `OTHER`) oraz `length`, `width`, `height` w cm i `weight` w kg, a także `cashOnDeliveryBankDetails` z `iban` i `ownerName`. Pola wspólne dla przesyłek: `senderAddress` i `pickupAddress` (`companyName`, `firstName`, `lastName`, `street`, `city`, `zipCode`, `countryCode`, `phoneNumber`, `email`) oraz `additionalInsurance`. W nim `insuranceType`: **Brak** = `NONE`, **Wartość zamówienia z dostawą** = `ORDER_AMOUNT_WITH_DELIVERY`, **Wartość zamówienia bez dostawy** = `ORDER_AMOUNT_WITHOUT_DELIVERY`, **Stała kwota** = `FIXED_AMOUNT` (kwota w `fixedAmount`), a `currencySource`: **Waluta zamówienia** = `ORDER_CURRENCY`, **Waluta kraju dostawy** = `DELIVERY_COUNTRY_CURRENCY`, **Stała waluta** = `FIXED` (waluta w `fixedCurrency`, wymagana przy `FIXED`). ![Szczegóły integracji Wysyłam z Allegro: ustawienia podstawowe z kontem Allegro i adres nadawcy na etykiecie](https://ritevo.com/docs/integrations/send-with-allegro/pl-details.webp) ![Karta Punkty odbioru z numerami punktów DPD, UPS, Poczta Polska, Allegro One, Allegro International i InPost](https://ritevo.com/docs/integrations/send-with-allegro/pl-pickup-points.webp) ![Karty Szczegóły paczki i Płatność za pobraniem z typem paczki, wymiarami, wagą, numerem IBAN i właścicielem konta](https://ritevo.com/docs/integrations/send-with-allegro/pl-package.webp) ![Karta Adres nadawcy na etykiecie z polami firmy, imienia i nazwiska, adresu, kraju, telefonu i e-maila](https://ritevo.com/docs/integrations/shipping/pl-sender.webp) ![Karta Adres odbioru przesyłek przez kuriera z polami firmy, imienia i nazwiska, adresu, kraju, telefonu i e-maila](https://ritevo.com/docs/integrations/shipping/pl-pickup-address.webp) ![Karta Dodatkowe ubezpieczenie z polami Typ ubezpieczenia i Źródło waluty](https://ritevo.com/docs/integrations/shipping/pl-insurance.webp) > **Warto wiedzieć:** Integracja nie zamawia podjazdu kuriera. Podjazd zamawiasz bezpośrednio u przewoźnika albo ustawiasz u niego stały harmonogram odbiorów. > **Warto wiedzieć:** Gdy zamówienie ma metodę płatności **Płatność przy odbiorze**, przesyłka dostaje pobranie automatycznie - w kwocie i walucie zamówienia. ### Tworzenie przesyłek Przesyłkę tworzysz z zamówienia na dwa sposoby: - **Ręcznie** - w szczegółach zamówienia, w karcie **Przesyłki**, kliknij przycisk z nazwą integracji Wysyłam z Allegro. Przyciski widzisz tylko dla aktywnych integracji, które pasują do zamówienia. - **Automatycznie** - krokiem **Utwórz przesyłkę** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Dane przesyłki bierzemy z zamówienia: - **Odbiorca** - adres dostawy z zamówienia oraz telefon i e-mail kupującego. - **Punkt odbioru** - punkt wybrany przez kupującego, jeśli zamówienie go ma. - **Pobranie** - kwota do zapłaty z zamówienia, gdy metoda płatności to **Płatność przy odbiorze**. - **Paczka** - jedna przesyłka to zawsze jedna paczka. W tej samej karcie każda przesyłka ma numer śledzenia, stan i datę utworzenia. Stany: - **W trakcie tworzenia** (API: "W trakcie tworzenia" = `PENDING`; wartość w `shipments[].status`) - przewoźnik jeszcze tworzy przesyłkę. Sprawdzamy ją co kilka sekund. Jeśli przewoźnik nie potwierdzi przesyłki w ciągu 24 godzin, kończy się ona błędem. - **Utworzona pomyślnie** (API: "Utworzona pomyślnie" = `SUCCESS`; wartość w `shipments[].status`) - przesyłka jest u przewoźnika i ma numer śledzenia. - **Błąd podczas tworzenia** (API: "Błąd podczas tworzenia" = `ERROR`; wartość w `shipments[].status`) - przewoźnik nie przyjął przesyłki. Przy stanie widzisz powód, a przy błędzie przewoźnika także jego komunikat. Etykietę utworzonej przesyłki pobierzesz przyciskiem **Pobierz** w karcie **Przesyłki**. Drukujesz ją na dwa sposoby - na komputerze z drukarką musi wtedy działać aplikacja [Ritevo Printer](https://ritevo.com/pl/docs/integrations/ritevo-printer): - **Ręcznie** - w karcie **Przesyłki** kliknij **Drukuj** i wybierz drukarkę. - **Automatycznie** - krokiem **Wydrukuj etykietę przesyłki** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Krok drukuje etykietę ostatniej przesyłki ze stanem **Utworzona pomyślnie** - przesyłki w trakcie tworzenia i z błędem pomija. Druk etykiet najlepiej zaplanować po kolei, jako dwie akcje: - **Pierwsza akcja** - kończy się krokiem **Utwórz przesyłkę**. - **Druga akcja** - startuje wyzwalaczem **Stworzono przesyłkę**, ma warunek **Status przesyłki jest** z wartością **Utworzona pomyślnie** i jeden krok **Wydrukuj etykietę przesyłki**. Dzięki temu każda nowa przesyłka od razu drukuje swoją etykietę - także gdy zamówienie ma kilka paczek. > **Warto wiedzieć:** Krok **Wydrukuj etykietę przesyłki** drukuje zawsze tylko jedną etykietę - najnowszej udanej przesyłki. Jeśli najpierw utworzysz wszystkie przesyłki, a dopiero potem włączysz druk, wydrukuje się tylko ostatnia, a pozostałe wydrukujesz ręcznie przyciskiem **Drukuj**. Jeśli nowa przesyłka się nie uda, krok wydrukuje etykietę poprzedniej udanej. > **Warto wiedzieć:** Każde kliknięcie przycisku i każde uruchomienie kroku **Utwórz przesyłkę** tworzy nową przesyłkę u przewoźnika. Przesyłki nie da się anulować w Ritevo - anulujesz ją w panelu przewoźnika. #### Jak przesyłka trafia do Allegro - **Potwierdzenie** - Allegro tworzy przesyłkę w tle, więc najpierw ma ona stan **W trakcie tworzenia**. - **Numer śledzenia** - numer przesyłki nadany przez Allegro. - **Pobranie bez numeru konta** - gdy dostawa wymaga numeru konta do pobrania, a nie podałeś go w integracji, przesyłka skończy się błędem. - **Dostawa bez pobrania** - zamówienie za pobraniem z dostawą, która nie obsługuje pobrania, też skończy się błędem. Przesyłkę tworzysz przez `POST /orders/{orderId}/create-shipments/{shipmentIntegrationId}` - odpowiedź 202, a wynik pojawia się później w `shipments[]` zamówienia (`status`, `trackingNumber`, `errorType`, `errorMessage`). Etykietę pobierasz przez `GET /orders/{orderId}/shipments/{shipmentId}/label`, a wydruk zlecasz przez `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}`. Akcje dla zamówień: krok **Utwórz przesyłkę** to `CREATE_SHIPMENT`, a **Wydrukuj etykietę przesyłki** to `PRINT_SHIPMENT_LABEL` - oba w `actionSteps[].action.type`, z `uuidValue` = id integracji wysyłkowej (`GET /integrations/shippings`) albo id drukarki (`GET /integrations/printers`). Wyzwalacz **Stworzono przesyłkę** to `triggerType` = `CREATE_SHIPMENT`. Warunki: **Posiada przesyłkę** / **Nie posiada przesyłki** = `HAS_SHIPMENT` / `HAS_SHIPMENT_NOT` (`booleanValues` = `[true]`), **Status przesyłki jest** / **Status przesyłki nie jest** = `SHIPMENT_STATUS_IS` / `SHIPMENT_STATUS_IS_NOT` (`enumValues`: `PENDING`, `SUCCESS`, `ERROR`), **Przesyłka należy do integracji** / **Przesyłka nie należy do integracji** = `SHIPMENT_SHIPPING_INTEGRATION_IS` / `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT` (`uuidValues` = id integracji wysyłkowych). Druk etykiety w akcji bierze najnowszą przesyłkę z `status` = `SUCCESS` (po `createdAt`); ręczny druk przez `POST /orders/{orderId}/print-shipment-label/...` też przyjmuje tylko przesyłkę `SUCCESS`, inaczej zwraca `SHIPMENT_NOT_FOUND`. `SHIPMENT_STATUS_IS` jest spełniony, gdy dowolna przesyłka zamówienia ma podany status, nie tylko ostatnia. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). ### Wymaga ponownego połączenia Wysyłam z Allegro nie ma własnego logowania, więc sama nie wymaga ponownego połączenia. Gdy konto Allegro przestanie działać, połącz je ponownie na stronie [integracji Allegro](https://ritevo.com/pl/docs/integrations/allegro#reconnect) - przesyłki zaczną działać bez zmian w tej integracji. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo. Przesyłki utworzone wcześniej zostają w zamówieniach i u przewoźnika. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie zamawia podjazdu kuriera. - Nie anuluje przesyłek. - Nie śledzi przesyłki po jej utworzeniu - stan doręczenia sprawdzasz u przewoźnika. - Nie przekazuje numeru śledzenia do kanału sprzedaży. - Nie tworzy przesyłek z kilkoma paczkami. - Nie tworzy przesyłek dla zamówień spoza wybranego konta Allegro. ### Integracja przez API Endpointy tej integracji są pod `/integrations/shippings/send-with-allegro`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/shippings`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/inpost (updated 2026-10-07) ## InPost Integracja InPost ShipX z Ritevo: token API i ID organizacji, gabaryt i sposób nadania, przesyłki do paczkomatów z pobraniem, etykiety, ponowne połączenie. Integracja z InPost tworzy przesyłki do paczkomatów InPost przez API ShipX. Podłączasz ją tokenem API i ID organizacji z Managera Paczek InPost. > **Wymagana integracja:** Potrzebujesz konta w Managerze Paczek InPost z uzupełnionymi danymi firmy i danymi do faktury. Integracji InPost możesz dodać dowolnie wiele, także kilka dla tego samego konta - na przykład z innym formatem etykiety, inną paczką albo innym adresem nadawcy. Każda działa osobno. Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami. `externalId` nie jest używany. Nowy token podasz przez `PATCH /integrations/shippings/inpost-locker-x/{id}/token` - w każdym stanie integracji. Sprawdza token w InPost i ustawia `authError=false` i `active=true`. ### Jakie przesyłki tworzy - **Paczkomat** - przesyłka zawsze jedzie do paczkomatu wybranego przez kupującego. Zamówienie musi mieć punkt odbioru - bez niego InPost odrzuci przesyłkę. - **Kurier** - przesyłki kurierskie nie są obsługiwane. - **Zamówienia z Allegro** - dostają usługę Paczkomat Allegro, a pozostałe zwykłą usługę Paczkomat. - **Pobranie i ubezpieczenie** - pobranie z zamówienia, ubezpieczenie z ustawień integracji. - **Dowolny kanał sprzedaży** - przesyłkę utworzysz dla zamówienia z każdego kanału. ### Skąd wziąć token i ID organizacji Oba znajdziesz w Managerze Paczek InPost. Przygotuj je przed dodaniem integracji: 1. Zaloguj się do Managera Paczek InPost na manager.paczkomaty.pl. 2. Przejdź do **Moje konto** → **API** i w zakładce **API ShipX** kliknij **Generuj**. Skopiuj token. 3. W zakładce **Ustawienia organizacji** skopiuj ID organizacji. Pojawi się ono dopiero po wygenerowaniu tokenu. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Przesyłki** wybierz kafelek **Inpost paczkomat ShipX**. 3. Wpisz **Nazwa konta** - własną nazwę integracji - oraz wklej **Token API ShipX** i **ID organizacji ShipX**. 4. Uzupełnij pozostałe ustawienia opisane niżej i kliknij **Dodaj integrację**. Token sprawdzamy od razu w InPost: jeśli jest błędny, zobaczysz błąd zwrócony przez InPost i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Inpost paczkomat ShipX w sekcji Przesyłki](https://ritevo.com/docs/integrations/inpost/pl-catalogue.webp) ![Ekran dodawania integracji InPost z polami Nazwa konta, Token API ShipX, ID organizacji ShipX, gabarytem, formatem etykiety, sposobem nadania i kodem punktu](https://ritevo.com/docs/integrations/inpost/pl-add.webp) ### Ustawienia integracji Na stronie integracji znajdziesz poniższe pola. Zmiany zapisujesz przyciskiem **Zaktualizuj integrację**: - **Nazwa konta** - Twoja własna nazwa integracji. - **Domyślny gabaryt paczki** - **Gabaryt A**, **Gabaryt B** albo **Gabaryt C**. Domyślnie A. - **Format etykiety** - A4 PDF, A6 PDF, A6 ZPL, A6 ZPL 300dpi albo A6 EPL. Domyślnie A6 PDF. - **Sposób nadania** - jak przekazujesz paczki InPost: **Odbiór przez kuriera**, **Nadanie w automacie Paczkomat**, **Nadanie w oddziale InPost**, **Nadanie w POK**, **Nadanie w POP (PaczkoPunkt)** albo **Nadanie w dowolnym punkcie**. Domyślnie odbiór przez kuriera. - **Kod punktu nadawczego** - kod punktu, w którym nadajesz paczki. Pole jest wymagane przy każdym sposobie nadania. - **Zaktualizuj token** - podajesz nowy token API ShipX. - **Adres nadawcy na etykiecie** - dane nadawcy, które przewoźnik drukuje na etykiecie. - **Adres odbioru przesyłek przez kuriera** - adres, spod którego kurier odbiera paczki. Może być inny niż adres nadawcy na etykiecie - na przykład przy dropshippingu: na etykiecie jest Twój sklep, a kurier odbiera paczkę z hurtowni. - **Dodatkowe ubezpieczenie** - kwota ubezpieczenia każdej przesyłki: **Brak**, **Wartość zamówienia z dostawą**, **Wartość zamówienia bez dostawy** albo **Stała kwota**. W **Źródło waluty** wybierasz walutę zamówienia, walutę kraju dostawy albo stałą walutę. Pola integracji: `accountName`, `apiToken`, `organizationId`, `defaultTemplate` (**Gabaryt A** = `SMALL`, **Gabaryt B** = `MEDIUM`, **Gabaryt C** = `LARGE`), `labelFormat` (`A4_PDF`, `A6_PDF`, `A6_ZPL`, `A6_ZPL_300`, `A6_EPL`), `sendingMethod` (**Odbiór przez kuriera** = `DISPATCH_ORDER`, **Nadanie w automacie Paczkomat** = `PARCEL_LOCKER`, **Nadanie w oddziale InPost** = `BRANCH`, **Nadanie w POK** = `POK`, **Nadanie w POP (PaczkoPunkt)** = `POP`, **Nadanie w dowolnym punkcie** = `ANY_POINT`) i `dropoffPoint`. Pola wspólne dla przesyłek: `senderAddress` i `pickupAddress` (`companyName`, `firstName`, `lastName`, `street`, `city`, `zipCode`, `countryCode`, `phoneNumber`, `email`) oraz `additionalInsurance`. W nim `insuranceType`: **Brak** = `NONE`, **Wartość zamówienia z dostawą** = `ORDER_AMOUNT_WITH_DELIVERY`, **Wartość zamówienia bez dostawy** = `ORDER_AMOUNT_WITHOUT_DELIVERY`, **Stała kwota** = `FIXED_AMOUNT` (kwota w `fixedAmount`), a `currencySource`: **Waluta zamówienia** = `ORDER_CURRENCY`, **Waluta kraju dostawy** = `DELIVERY_COUNTRY_CURRENCY`, **Stała waluta** = `FIXED` (waluta w `fixedCurrency`, wymagana przy `FIXED`). ![Szczegóły integracji InPost: ustawienia podstawowe z gabarytem, formatem etykiety, sposobem nadania i kodem punktu oraz adres nadawcy](https://ritevo.com/docs/integrations/inpost/pl-details.webp) ![Karta Adres nadawcy na etykiecie z polami firmy, imienia i nazwiska, adresu, kraju, telefonu i e-maila](https://ritevo.com/docs/integrations/shipping/pl-sender.webp) ![Karta Adres odbioru przesyłek przez kuriera z polami firmy, imienia i nazwiska, adresu, kraju, telefonu i e-maila](https://ritevo.com/docs/integrations/shipping/pl-pickup-address.webp) ![Karta Dodatkowe ubezpieczenie z polami Typ ubezpieczenia i Źródło waluty](https://ritevo.com/docs/integrations/shipping/pl-insurance.webp) > **Warto wiedzieć:** Integracja nie zamawia podjazdu kuriera. Podjazd zamawiasz bezpośrednio u przewoźnika albo ustawiasz u niego stały harmonogram odbiorów. > **Warto wiedzieć:** Gdy zamówienie ma metodę płatności **Płatność przy odbiorze**, przesyłka dostaje pobranie automatycznie - w kwocie i walucie zamówienia. ### Tworzenie przesyłek Przesyłkę tworzysz z zamówienia na dwa sposoby: - **Ręcznie** - w szczegółach zamówienia, w karcie **Przesyłki**, kliknij przycisk z nazwą integracji InPost. Przyciski widzisz tylko dla aktywnych integracji, które pasują do zamówienia. - **Automatycznie** - krokiem **Utwórz przesyłkę** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Dane przesyłki bierzemy z zamówienia: - **Odbiorca** - adres dostawy z zamówienia oraz telefon i e-mail kupującego. - **Punkt odbioru** - punkt wybrany przez kupującego, jeśli zamówienie go ma. - **Pobranie** - kwota do zapłaty z zamówienia, gdy metoda płatności to **Płatność przy odbiorze**. - **Paczka** - jedna przesyłka to zawsze jedna paczka. W tej samej karcie każda przesyłka ma numer śledzenia, stan i datę utworzenia. Stany: - **W trakcie tworzenia** (API: "W trakcie tworzenia" = `PENDING`; wartość w `shipments[].status`) - przewoźnik jeszcze tworzy przesyłkę. Sprawdzamy ją co kilka sekund. Jeśli przewoźnik nie potwierdzi przesyłki w ciągu 24 godzin, kończy się ona błędem. - **Utworzona pomyślnie** (API: "Utworzona pomyślnie" = `SUCCESS`; wartość w `shipments[].status`) - przesyłka jest u przewoźnika i ma numer śledzenia. - **Błąd podczas tworzenia** (API: "Błąd podczas tworzenia" = `ERROR`; wartość w `shipments[].status`) - przewoźnik nie przyjął przesyłki. Przy stanie widzisz powód, a przy błędzie przewoźnika także jego komunikat. Etykietę utworzonej przesyłki pobierzesz przyciskiem **Pobierz** w karcie **Przesyłki**. Drukujesz ją na dwa sposoby - na komputerze z drukarką musi wtedy działać aplikacja [Ritevo Printer](https://ritevo.com/pl/docs/integrations/ritevo-printer): - **Ręcznie** - w karcie **Przesyłki** kliknij **Drukuj** i wybierz drukarkę. - **Automatycznie** - krokiem **Wydrukuj etykietę przesyłki** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Krok drukuje etykietę ostatniej przesyłki ze stanem **Utworzona pomyślnie** - przesyłki w trakcie tworzenia i z błędem pomija. Druk etykiet najlepiej zaplanować po kolei, jako dwie akcje: - **Pierwsza akcja** - kończy się krokiem **Utwórz przesyłkę**. - **Druga akcja** - startuje wyzwalaczem **Stworzono przesyłkę**, ma warunek **Status przesyłki jest** z wartością **Utworzona pomyślnie** i jeden krok **Wydrukuj etykietę przesyłki**. Dzięki temu każda nowa przesyłka od razu drukuje swoją etykietę - także gdy zamówienie ma kilka paczek. > **Warto wiedzieć:** Krok **Wydrukuj etykietę przesyłki** drukuje zawsze tylko jedną etykietę - najnowszej udanej przesyłki. Jeśli najpierw utworzysz wszystkie przesyłki, a dopiero potem włączysz druk, wydrukuje się tylko ostatnia, a pozostałe wydrukujesz ręcznie przyciskiem **Drukuj**. Jeśli nowa przesyłka się nie uda, krok wydrukuje etykietę poprzedniej udanej. > **Warto wiedzieć:** Każde kliknięcie przycisku i każde uruchomienie kroku **Utwórz przesyłkę** tworzy nową przesyłkę u przewoźnika. Przesyłki nie da się anulować w Ritevo - anulujesz ją w panelu przewoźnika. #### Jak przesyłka trafia do InPost - **Potwierdzenie** - InPost tworzy przesyłkę w tle, więc najpierw ma ona stan **W trakcie tworzenia**. Gdy InPost nada numer śledzenia, zmienia się na **Utworzona pomyślnie**. - **Numer śledzenia** - numer przesyłki InPost. Ten sam numer jest na etykiecie. - **Anulowanie w InPost** - przesyłka anulowana w InPost w trakcie tworzenia kończy się błędem. Przesyłkę tworzysz przez `POST /orders/{orderId}/create-shipments/{shipmentIntegrationId}` - odpowiedź 202, a wynik pojawia się później w `shipments[]` zamówienia (`status`, `trackingNumber`, `errorType`, `errorMessage`). Etykietę pobierasz przez `GET /orders/{orderId}/shipments/{shipmentId}/label`, a wydruk zlecasz przez `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}`. Akcje dla zamówień: krok **Utwórz przesyłkę** to `CREATE_SHIPMENT`, a **Wydrukuj etykietę przesyłki** to `PRINT_SHIPMENT_LABEL` - oba w `actionSteps[].action.type`, z `uuidValue` = id integracji wysyłkowej (`GET /integrations/shippings`) albo id drukarki (`GET /integrations/printers`). Wyzwalacz **Stworzono przesyłkę** to `triggerType` = `CREATE_SHIPMENT`. Warunki: **Posiada przesyłkę** / **Nie posiada przesyłki** = `HAS_SHIPMENT` / `HAS_SHIPMENT_NOT` (`booleanValues` = `[true]`), **Status przesyłki jest** / **Status przesyłki nie jest** = `SHIPMENT_STATUS_IS` / `SHIPMENT_STATUS_IS_NOT` (`enumValues`: `PENDING`, `SUCCESS`, `ERROR`), **Przesyłka należy do integracji** / **Przesyłka nie należy do integracji** = `SHIPMENT_SHIPPING_INTEGRATION_IS` / `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT` (`uuidValues` = id integracji wysyłkowych). Druk etykiety w akcji bierze najnowszą przesyłkę z `status` = `SUCCESS` (po `createdAt`); ręczny druk przez `POST /orders/{orderId}/print-shipment-label/...` też przyjmuje tylko przesyłkę `SUCCESS`, inaczej zwraca `SHIPMENT_NOT_FOUND`. `SHIPMENT_STATUS_IS` jest spełniony, gdy dowolna przesyłka zamówienia ma podany status, nie tylko ostatnia. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). ### Wymaga ponownego połączenia Ten stan pojawia się, gdy InPost przestał akceptować token - na przykład po wygenerowaniu nowego tokenu w Managerze Paczek. Do czasu podania nowego tokenu nie utworzysz przesyłek ani nie pobierzesz etykiet. 1. W Managerze Paczek InPost skopiuj aktualny token z zakładki **API ShipX**. 2. Na stronie integracji kliknij **Zaktualizuj token**, wklej go w polu **Nowy token API ShipX** i zatwierdź. Sprawdzamy go w InPost tak samo jak przy dodawaniu - poprawny odświeży połączenie, a ustawienia zostają bez zmian. ![Dół strony integracji InPost z przyciskami Zaktualizuj token i Zaktualizuj integrację](https://ritevo.com/docs/integrations/inpost/pl-token.webp) ![Okno Zaktualizuj token w integracji InPost z polem Nowy token API ShipX](https://ritevo.com/docs/integrations/inpost/pl-update-token.webp) > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo. Przesyłki utworzone wcześniej zostają w zamówieniach i u przewoźnika. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie zamawia podjazdu kuriera. - Nie anuluje przesyłek. - Nie śledzi przesyłki po jej utworzeniu - stan doręczenia sprawdzasz u przewoźnika. - Nie przekazuje numeru śledzenia do kanału sprzedaży. - Nie tworzy przesyłek z kilkoma paczkami. - Nie tworzy przesyłek kurierskich - tylko do paczkomatów. ### Integracja przez API Endpointy tej integracji są pod `/integrations/shippings/inpost-locker-x`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/shippings`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/dpd (updated 2026-10-07) ## DPD Integracja DPD Polska z Ritevo: dane do API i Numkat, paczka i dodatkowe serwisy, przesyłki kurierskie i do punktów DPD Pickup, etykiety, ponowne połączenie. Integracja z DPD Polska tworzy przesyłki kurierskie DPD i przesyłki do punktów DPD Pickup. Podłączasz ją danymi do API DPD i numerami klienta Numkat. > **Wymagana integracja:** Potrzebujesz umowy z DPD Polska oraz loginu i hasła do API DPD. To inne dane niż login do panelu DPD - dostaniesz je od opiekuna konta DPD. Integracji DPD możesz dodać dowolnie wiele, także kilka dla tego samego konta - na przykład z innym formatem etykiety, inną paczką albo innym adresem nadawcy. Każda działa osobno. Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami. `externalId` nie jest używany. Nowe dane logowania podasz przez `PATCH /integrations/shippings/dpd-pl/{id}/credentials` - w każdym stanie integracji. Sprawdza je w DPD i ustawia `authError=false` i `active=true`. ### Jakie przesyłki tworzy - **Kurier** - domyślnie przesyłka jedzie kurierem pod adres z zamówienia. - **Punkt DPD Pickup** - po zaznaczeniu usługi **Dostawa do punktu PUDO (DPD_PICKUP)** przesyłka jedzie do punktu wybranego w zamówieniu. Zamówienie bez punktu odbioru skończy się błędem. - **Pobranie i ubezpieczenie** - pobranie z zamówienia, a ubezpieczenie z ustawień integracji jako wartość deklarowana, zaokrąglona do pełnych złotych. - **Przesyłki krajowe** - etykiety pobieramy jako krajowe, więc przesyłki zagraniczne mogą się nie udać. ### Skąd wziąć dane do API Login i hasło do API oraz numery Numkat dostaniesz od DPD. Przygotuj je przed dodaniem integracji: 1. Poproś opiekuna konta DPD o dostęp do API DPD. 2. Zapisz login i hasło do API oraz swój Numkat (MasterFID). 3. Jeśli nadajesz z kilku lokalizacji, poproś też o Numkat lokalizacji nadania. Przy jednej lokalizacji to ten sam numer. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Przesyłki** wybierz kafelek **Dpd PL**. 3. Wpisz **Nazwa konta** - własną nazwę integracji - oraz **Login** i **Hasło** do API DPD. 4. Wpisz **Numkat (MasterFID)**, **Numkat (MasterFID) nadawcy** i **Numkat (MasterFID) DPDInfoServices (śledzenie paczek)**. 5. Uzupełnij pozostałe ustawienia opisane niżej i kliknij **Dodaj integrację**. Login i hasło sprawdzamy od razu w DPD: jeśli są błędne, zobaczysz błąd zwrócony przez DPD i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Dpd PL w sekcji Przesyłki](https://ritevo.com/docs/integrations/dpd/pl-catalogue.webp) ![Ekran dodawania integracji DPD z polami Nazwa konta, Login, Hasło, trzema numerami Numkat i formatem etykiety](https://ritevo.com/docs/integrations/dpd/pl-add.webp) ### Ustawienia integracji Na stronie integracji znajdziesz poniższe pola. Zmiany zapisujesz przyciskiem **Zaktualizuj integrację**: - **Nazwa konta** - Twoja własna nazwa integracji. - **Numkat (MasterFID)** - główny numer klienta DPD. - **Numkat (MasterFID) nadawcy** - numer lokalizacji nadania. Na ten numer DPD rozlicza przesyłki. Przy jednej lokalizacji wpisz ten sam numer co wyżej. - **Numkat (MasterFID) DPDInfoServices (śledzenie paczek)** - numer do śledzenia paczek w DPD. Pole jest wymagane, ale dziś nie śledzimy przesyłek DPD. - **Format etykiety** - A4 PDF, A6 PDF, A6 ZPL albo A6 EPL. Domyślnie A4 PDF. - **Szczegóły paczki** - wymiary w centymetrach i waga w kilogramach każdej przesyłki. Wymiary zaokrąglamy do pełnych centymetrów. - **Dodatkowe serwisy** - usługi DPD dodawane do każdej przesyłki, na przykład doręczenie w sobotę, doręczenie do 12:00 czy dokumenty zwrotne. **Etykieta cyfrowa (DIGITAL_LABEL)** i **Nadanie w punkcie PUDO (PUDO_TO_SEND)** działają tylko zaznaczone razem. - **Zaktualizuj dane logowania** - podajesz nowy login i hasło do API DPD. - **Adres nadawcy na etykiecie** - dane nadawcy, które przewoźnik drukuje na etykiecie. - **Adres odbioru przesyłek przez kuriera** - adres, spod którego kurier odbiera paczki. Może być inny niż adres nadawcy na etykiecie - na przykład przy dropshippingu: na etykiecie jest Twój sklep, a kurier odbiera paczkę z hurtowni. - **Dodatkowe ubezpieczenie** - kwota ubezpieczenia każdej przesyłki: **Brak**, **Wartość zamówienia z dostawą**, **Wartość zamówienia bez dostawy** albo **Stała kwota**. W **Źródło waluty** wybierasz walutę zamówienia, walutę kraju dostawy albo stałą walutę. Pola integracji: `accountName`, `apiLogin`, `apiPassword`, `masterFid`, `senderFid`, `infoServicesFid` (liczby), `labelFormat` (`A4_PDF`, `A6_PDF`, `A6_ZPL`, `A6_EPL`), `packageDetails` z `length`, `width`, `height` w cm i `weight` w kg oraz `additionalServices` - lista wartości: `CARRY_IN`, `CUD`, `ROD`, `HAND_DELIVERY`, `SELF_COLLECTION`, `PRIVATE_PERSON`, `DEDICATED_DELIVERY`, `PALETTE`, `DOX`, `DPD_EXPRESS`, `DOCUMENTS_INTERNATIONAL`, `DPD_LQ`, `DPD_NEXT_DAY`, `DPD_PICKUP`, `DPD_TODAY`, `INTERNATIONAL`, `SATURDAY`, `TIME0930`, `TIME1200`, `TIRES`, `TIRES_EXPORT`, `DIGITAL_LABEL`, `PUDO_TO_SEND`. Wartość w API to nazwa w nawiasie przy usłudze w aplikacji. Pola wspólne dla przesyłek: `senderAddress` i `pickupAddress` (`companyName`, `firstName`, `lastName`, `street`, `city`, `zipCode`, `countryCode`, `phoneNumber`, `email`) oraz `additionalInsurance`. W nim `insuranceType`: **Brak** = `NONE`, **Wartość zamówienia z dostawą** = `ORDER_AMOUNT_WITH_DELIVERY`, **Wartość zamówienia bez dostawy** = `ORDER_AMOUNT_WITHOUT_DELIVERY`, **Stała kwota** = `FIXED_AMOUNT` (kwota w `fixedAmount`), a `currencySource`: **Waluta zamówienia** = `ORDER_CURRENCY`, **Waluta kraju dostawy** = `DELIVERY_COUNTRY_CURRENCY`, **Stała waluta** = `FIXED` (waluta w `fixedCurrency`, wymagana przy `FIXED`). ![Karta Dodatkowe serwisy z listą usług DPD do zaznaczenia](https://ritevo.com/docs/integrations/dpd/pl-services.webp) ![Karta Adres nadawcy na etykiecie z polami firmy, imienia i nazwiska, adresu, kraju, telefonu i e-maila](https://ritevo.com/docs/integrations/shipping/pl-sender.webp) ![Karta Adres odbioru przesyłek przez kuriera z polami firmy, imienia i nazwiska, adresu, kraju, telefonu i e-maila](https://ritevo.com/docs/integrations/shipping/pl-pickup-address.webp) ![Karta Dodatkowe ubezpieczenie z polami Typ ubezpieczenia i Źródło waluty](https://ritevo.com/docs/integrations/shipping/pl-insurance.webp) > **Warto wiedzieć:** Integracja nie zamawia podjazdu kuriera. Podjazd zamawiasz bezpośrednio u przewoźnika albo ustawiasz u niego stały harmonogram odbiorów. > **Warto wiedzieć:** Gdy zamówienie ma metodę płatności **Płatność przy odbiorze**, przesyłka dostaje pobranie automatycznie - w kwocie i walucie zamówienia. ### Tworzenie przesyłek Przesyłkę tworzysz z zamówienia na dwa sposoby: - **Ręcznie** - w szczegółach zamówienia, w karcie **Przesyłki**, kliknij przycisk z nazwą integracji DPD. Przyciski widzisz tylko dla aktywnych integracji, które pasują do zamówienia. - **Automatycznie** - krokiem **Utwórz przesyłkę** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Dane przesyłki bierzemy z zamówienia: - **Odbiorca** - adres dostawy z zamówienia oraz telefon i e-mail kupującego. - **Punkt odbioru** - punkt wybrany przez kupującego, jeśli zamówienie go ma. - **Pobranie** - kwota do zapłaty z zamówienia, gdy metoda płatności to **Płatność przy odbiorze**. - **Paczka** - jedna przesyłka to zawsze jedna paczka. W tej samej karcie każda przesyłka ma numer śledzenia, stan i datę utworzenia. Stany: - **W trakcie tworzenia** (API: "W trakcie tworzenia" = `PENDING`; wartość w `shipments[].status`) - przewoźnik jeszcze tworzy przesyłkę. Sprawdzamy ją co kilka sekund. Jeśli przewoźnik nie potwierdzi przesyłki w ciągu 24 godzin, kończy się ona błędem. - **Utworzona pomyślnie** (API: "Utworzona pomyślnie" = `SUCCESS`; wartość w `shipments[].status`) - przesyłka jest u przewoźnika i ma numer śledzenia. - **Błąd podczas tworzenia** (API: "Błąd podczas tworzenia" = `ERROR`; wartość w `shipments[].status`) - przewoźnik nie przyjął przesyłki. Przy stanie widzisz powód, a przy błędzie przewoźnika także jego komunikat. Etykietę utworzonej przesyłki pobierzesz przyciskiem **Pobierz** w karcie **Przesyłki**. Drukujesz ją na dwa sposoby - na komputerze z drukarką musi wtedy działać aplikacja [Ritevo Printer](https://ritevo.com/pl/docs/integrations/ritevo-printer): - **Ręcznie** - w karcie **Przesyłki** kliknij **Drukuj** i wybierz drukarkę. - **Automatycznie** - krokiem **Wydrukuj etykietę przesyłki** w [akcjach dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Krok drukuje etykietę ostatniej przesyłki ze stanem **Utworzona pomyślnie** - przesyłki w trakcie tworzenia i z błędem pomija. Druk etykiet najlepiej zaplanować po kolei, jako dwie akcje: - **Pierwsza akcja** - kończy się krokiem **Utwórz przesyłkę**. - **Druga akcja** - startuje wyzwalaczem **Stworzono przesyłkę**, ma warunek **Status przesyłki jest** z wartością **Utworzona pomyślnie** i jeden krok **Wydrukuj etykietę przesyłki**. Dzięki temu każda nowa przesyłka od razu drukuje swoją etykietę - także gdy zamówienie ma kilka paczek. > **Warto wiedzieć:** Krok **Wydrukuj etykietę przesyłki** drukuje zawsze tylko jedną etykietę - najnowszej udanej przesyłki. Jeśli najpierw utworzysz wszystkie przesyłki, a dopiero potem włączysz druk, wydrukuje się tylko ostatnia, a pozostałe wydrukujesz ręcznie przyciskiem **Drukuj**. Jeśli nowa przesyłka się nie uda, krok wydrukuje etykietę poprzedniej udanej. > **Warto wiedzieć:** Każde kliknięcie przycisku i każde uruchomienie kroku **Utwórz przesyłkę** tworzy nową przesyłkę u przewoźnika. Przesyłki nie da się anulować w Ritevo - anulujesz ją w panelu przewoźnika. #### Jak przesyłka trafia do DPD - **Od razu** - DPD odpowiada od razu, więc przesyłka ma stan **Utworzona pomyślnie** albo **Błąd podczas tworzenia** zaraz po wysłaniu. - **Numer śledzenia** - numer listu przewozowego DPD. Ten sam numer jest na etykiecie. Przesyłkę tworzysz przez `POST /orders/{orderId}/create-shipments/{shipmentIntegrationId}` - odpowiedź 202, a wynik pojawia się później w `shipments[]` zamówienia (`status`, `trackingNumber`, `errorType`, `errorMessage`). Etykietę pobierasz przez `GET /orders/{orderId}/shipments/{shipmentId}/label`, a wydruk zlecasz przez `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}`. Akcje dla zamówień: krok **Utwórz przesyłkę** to `CREATE_SHIPMENT`, a **Wydrukuj etykietę przesyłki** to `PRINT_SHIPMENT_LABEL` - oba w `actionSteps[].action.type`, z `uuidValue` = id integracji wysyłkowej (`GET /integrations/shippings`) albo id drukarki (`GET /integrations/printers`). Wyzwalacz **Stworzono przesyłkę** to `triggerType` = `CREATE_SHIPMENT`. Warunki: **Posiada przesyłkę** / **Nie posiada przesyłki** = `HAS_SHIPMENT` / `HAS_SHIPMENT_NOT` (`booleanValues` = `[true]`), **Status przesyłki jest** / **Status przesyłki nie jest** = `SHIPMENT_STATUS_IS` / `SHIPMENT_STATUS_IS_NOT` (`enumValues`: `PENDING`, `SUCCESS`, `ERROR`), **Przesyłka należy do integracji** / **Przesyłka nie należy do integracji** = `SHIPMENT_SHIPPING_INTEGRATION_IS` / `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT` (`uuidValues` = id integracji wysyłkowych). Druk etykiety w akcji bierze najnowszą przesyłkę z `status` = `SUCCESS` (po `createdAt`); ręczny druk przez `POST /orders/{orderId}/print-shipment-label/...` też przyjmuje tylko przesyłkę `SUCCESS`, inaczej zwraca `SHIPMENT_NOT_FOUND`. `SHIPMENT_STATUS_IS` jest spełniony, gdy dowolna przesyłka zamówienia ma podany status, nie tylko ostatnia. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). ### Wymaga ponownego połączenia Ten stan pojawia się, gdy DPD przestało akceptować login i hasło do API - na przykład po ich zmianie przez DPD. Do czasu podania nowych danych nie utworzysz przesyłek ani nie pobierzesz etykiet. 1. Poproś opiekuna konta DPD o aktualne dane do API. 2. Na stronie integracji kliknij **Zaktualizuj dane logowania**, wpisz **Login** i **Hasło** i zatwierdź. Sprawdzamy je w DPD tak samo jak przy dodawaniu - poprawne odświeżą połączenie, a ustawienia zostają bez zmian. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo. Przesyłki utworzone wcześniej zostają w zamówieniach i u przewoźnika. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie zamawia podjazdu kuriera. - Nie anuluje przesyłek. - Nie śledzi przesyłki po jej utworzeniu - stan doręczenia sprawdzasz u przewoźnika. - Nie przekazuje numeru śledzenia do kanału sprzedaży. - Nie tworzy przesyłek z kilkoma paczkami. - Nie śledzi przesyłek przez DPDInfoServices, mimo że numer do śledzenia jest w ustawieniach. ### Integracja przez API Endpointy tej integracji są pod `/integrations/shippings/dpd-pl`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/shippings`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/openai (updated 2026-09-29) ## OpenAI Integracja OpenAI z Ritevo: klucz API, model, prompt systemowy i limit tokenów, automatyczne odpowiedzi AI w wiadomościach, ponowne połączenie. Integracja z OpenAI pozwala odpowiadać klientom w wiadomościach tekstem napisanym przez model OpenAI. Podłączasz ją własnym kluczem API z OpenAI Platform - za użycie płacisz bezpośrednio u dostawcy. > **Wymagana integracja:** Potrzebujesz konta w OpenAI Platform z doładowanym saldem i klucza API. Integracji OpenAI możesz dodać dowolnie wiele, także kilka z tym samym kluczem API - na przykład z innym modelem albo innym promptem systemowym dla różnych kanałów. Każda działa osobno. Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami. Nowy klucz podasz przez `PATCH /integrations/ai/openai/{id}/token` - w każdym stanie integracji. Wysyła do dostawcy zapytanie próbne i ustawia `authError=false` i `active=true`. Błędny klucz przy tworzeniu albo zmianie klucza zwraca `INVALID_TOKEN`, inny błąd dostawcy `EXTERNAL_EXCEPTION`. ### Jak wygenerować klucz API Klucz tworzysz w OpenAI Platform. Skopiuj go od razu - klucz jest pokazywany tylko raz. 1. Zaloguj się na platform.openai.com. 2. Przejdź do **API Keys** i kliknij **Create new secret key**. 3. Skopiuj klucz. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Sztuczna inteligencja** wybierz kafelek **OpenAI**. 3. W polu **Nazwa konta** wpisz własną nazwę integracji, wklej **API Token** i wybierz **Model**. 4. W karcie **Ustawienia Zaawansowane** wpisz **Prompt systemowy** i ustaw **Maks. ilość tokenów** - opis niżej. 5. Kliknij **Utwórz integrację**. Od razu wysyłamy do OpenAI krótkie zapytanie próbne z tym kluczem i modelem: jeśli się uda, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem OpenAI w sekcji Sztuczna inteligencja](https://ritevo.com/docs/integrations/openai/pl-catalogue.webp) ![Ekran dodawania integracji OpenAI z polami Nazwa konta, API Token, Model, Prompt systemowy i Maks. ilość tokenów](https://ritevo.com/docs/integrations/openai/pl-add.webp) ### Ustawienia integracji Na stronie integracji znajdziesz poniższe pola. Zmiany zapisujesz przyciskiem **Zaktualizuj integrację**: - **Nazwa konta** - Twoja własna nazwa integracji. Pod nią wybierasz integrację w akcji automatycznej. - **Model** - model OpenAI, który pisze odpowiedzi: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4 albo gpt-3.5-turbo. - **Prompt systemowy** - instrukcja dla AI dołączana do każdej odpowiedzi: kim jesteś, jakim tonem odpisywać, godziny pracy, zasady zwrotów, w jakim języku odpowiadać. To jedyne miejsce, w którym przekazujesz AI wiedzę o firmie. - **Maks. ilość tokenów** - górny limit długości odpowiedzi. Domyślnie 1000. Za niski limit utnie odpowiedź w połowie i klient dostanie ją uciętą. - **Zaktualizuj token** - podajesz nowy klucz API. ![Szczegóły integracji OpenAI: nazwa konta, model, prompt systemowy, maks. ilość tokenów oraz przyciski Zaktualizuj token i Zaktualizuj integrację](https://ritevo.com/docs/integrations/openai/pl-details.webp) Pola integracji: `accountName`, `apiToken` (tylko przy tworzeniu), `model` = `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`, `gpt-4`, `gpt-3.5-turbo`, `systemPrompt` (do 10000 znaków) i `maxTokens`. Zmiana ustawień: `PUT /integrations/ai/openai/{id}` z tymi polami bez `apiToken` - zapis ustawia też `active=true`. ### Odpowiedzi AI w wiadomościach Integracja AI działa w akcjach dla wiadomości, w kroku **Wyślij wiadomość AI do wątku**. Szczegóły kroku i gotowy przykład znajdziesz w [Akcjach dla wiadomości](https://ritevo.com/pl/docs/automations/message-actions#ai-reply-example). - **Co dostaje AI** - treść ostatniej wiadomości w wątku oraz **Prompt systemowy**. Nie dostaje wcześniejszej historii rozmowy ani danych zamówienia. - **Wysyłka** - odpowiedź od razu trafia do klienta, bez zatwierdzania. - **Błąd** - gdy dostawca AI zwróci błąd, nic nie jest wysyłane, a akcja się zatrzymuje. Błąd zobaczysz w audycie wiadomości. - **Koszty** - każda odpowiedź rozlicza się na Twoim koncie u dostawcy AI. Dodanie integracji i zmiana klucza wysyłają jedno krótkie zapytanie próbne. > **Warto wiedzieć:** W akcji z krokiem **Wyślij wiadomość AI do wątku** ustaw warunek **Odebrano wiadomość od klienta**. AI odpowiada na ostatnią wiadomość w wątku, więc bez tego warunku mogłoby odpowiadać na własne odpowiedzi. Akcje dla wiadomości: krok **Wyślij wiadomość AI do wątku** to `AI_SEND_MESSAGE_TO_THREAD` w `actionSteps[].action.type`, z `uuidValue` = id integracji AI (`GET /integrations/ai`). Wyzwalacz **Odpowiedź AI w wątku** to `triggerType` = `AI_MESSAGE_RESPONSE`, a warunek **Odebrano wiadomość od klienta** to `MESSAGE_FROM_INTERLOCUTOR`. Do modelu trafia tekst ostatniej wiadomości w wątku (niezależnie od autora) jako jedyna wiadomość użytkownika oraz `systemPrompt` integracji. Pełny opis: [Akcje dla wiadomości](https://ritevo.com/pl/docs/automations/message-actions). ### Wymaga ponownego połączenia Ten stan pojawia się, gdy OpenAI odrzucił klucz API podczas pisania odpowiedzi - na przykład po jego usunięciu. Do czasu podania nowego klucza AI nie odpowie klientom. 1. Utwórz nowy klucz API w OpenAI Platform. 2. Na stronie integracji kliknij **Zaktualizuj token**, wklej klucz w polu **API Token** i zatwierdź. Sprawdzamy go krótkim zapytaniem próbnym - poprawny odświeży połączenie, a ustawienia zostają bez zmian. ![Okno Zaktualizuj token w integracji OpenAI z polem API Token](https://ritevo.com/docs/integrations/openai/pl-update-token.webp) > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie podpowiada odpowiedzi do ręcznego wstawienia - odpowiada tylko przez akcję automatyczną. - Nie czyta historii rozmowy ani danych zamówienia. - Nie zapisuje odpowiedzi jako szkicu do zatwierdzenia. - Nie ogranicza wydatków - limity ustawiasz na swoim koncie u dostawcy AI. ### Integracja przez API Endpointy tej integracji są pod `/integrations/ai/openai`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/ai`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/claude (updated 2026-09-29) ## Claude Integracja Claude z Ritevo: klucz API, model, prompt systemowy i limit tokenów, automatyczne odpowiedzi AI w wiadomościach, ponowne połączenie. Integracja z Claude pozwala odpowiadać klientom w wiadomościach tekstem napisanym przez model Claude. Podłączasz ją własnym kluczem API z Anthropic Console - za użycie płacisz bezpośrednio u dostawcy. > **Wymagana integracja:** Potrzebujesz konta w Anthropic Console z doładowanym saldem i klucza API. Integracji Claude możesz dodać dowolnie wiele, także kilka z tym samym kluczem API - na przykład z innym modelem albo innym promptem systemowym dla różnych kanałów. Każda działa osobno. Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami. Nowy klucz podasz przez `PATCH /integrations/ai/claude/{id}/token` - w każdym stanie integracji. Wysyła do dostawcy zapytanie próbne i ustawia `authError=false` i `active=true`. Błędny klucz przy tworzeniu albo zmianie klucza zwraca `INVALID_TOKEN`, inny błąd dostawcy `EXTERNAL_EXCEPTION`. ### Jak wygenerować klucz API Klucz tworzysz w Anthropic Console. Skopiuj go od razu - klucz jest pokazywany tylko raz. 1. Zaloguj się na console.anthropic.com. 2. Przejdź do **API Keys** i kliknij **Create Key**. 3. Skopiuj klucz. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Sztuczna inteligencja** wybierz kafelek **Claude**. 3. W polu **Nazwa konta** wpisz własną nazwę integracji, wklej **API Token** i wybierz **Model**. 4. W karcie **Ustawienia Zaawansowane** wpisz **Prompt systemowy** i ustaw **Maks. ilość tokenów** - opis niżej. 5. Kliknij **Utwórz integrację**. Od razu wysyłamy do Claude krótkie zapytanie próbne z tym kluczem i modelem: jeśli się uda, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Claude w sekcji Sztuczna inteligencja](https://ritevo.com/docs/integrations/claude/pl-catalogue.webp) ![Ekran dodawania integracji Claude z polami Nazwa konta, API Token, Model, Prompt systemowy i Maks. ilość tokenów](https://ritevo.com/docs/integrations/claude/pl-add.webp) ### Ustawienia integracji Na stronie integracji znajdziesz poniższe pola. Zmiany zapisujesz przyciskiem **Zaktualizuj integrację**: - **Nazwa konta** - Twoja własna nazwa integracji. Pod nią wybierasz integrację w akcji automatycznej. - **Model** - model Claude, który pisze odpowiedzi: claude-sonnet-4-5-20250929, claude-sonnet-4-20250514, claude-opus-4-20250514, claude-haiku-4-5-20251001 albo claude-3-5-haiku-20241022. - **Prompt systemowy** - instrukcja dla AI dołączana do każdej odpowiedzi: kim jesteś, jakim tonem odpisywać, godziny pracy, zasady zwrotów, w jakim języku odpowiadać. To jedyne miejsce, w którym przekazujesz AI wiedzę o firmie. - **Maks. ilość tokenów** - górny limit długości odpowiedzi. Domyślnie 1000. Za niski limit utnie odpowiedź w połowie i klient dostanie ją uciętą. - **Zaktualizuj token** - podajesz nowy klucz API. ![Szczegóły integracji Claude: nazwa konta, model, prompt systemowy, maks. ilość tokenów oraz przyciski Zaktualizuj token i Zaktualizuj integrację](https://ritevo.com/docs/integrations/claude/pl-details.webp) Pola integracji: `accountName`, `apiToken` (tylko przy tworzeniu), `model` = `claude-sonnet-4-5-20250929`, `claude-sonnet-4-20250514`, `claude-opus-4-20250514`, `claude-haiku-4-5-20251001`, `claude-3-5-haiku-20241022`, `systemPrompt` (do 10000 znaków) i `maxTokens`. Zmiana ustawień: `PUT /integrations/ai/claude/{id}` z tymi polami bez `apiToken` - zapis ustawia też `active=true`. ### Odpowiedzi AI w wiadomościach Integracja AI działa w akcjach dla wiadomości, w kroku **Wyślij wiadomość AI do wątku**. Szczegóły kroku i gotowy przykład znajdziesz w [Akcjach dla wiadomości](https://ritevo.com/pl/docs/automations/message-actions#ai-reply-example). - **Co dostaje AI** - treść ostatniej wiadomości w wątku oraz **Prompt systemowy**. Nie dostaje wcześniejszej historii rozmowy ani danych zamówienia. - **Wysyłka** - odpowiedź od razu trafia do klienta, bez zatwierdzania. - **Błąd** - gdy dostawca AI zwróci błąd, nic nie jest wysyłane, a akcja się zatrzymuje. Błąd zobaczysz w audycie wiadomości. - **Koszty** - każda odpowiedź rozlicza się na Twoim koncie u dostawcy AI. Dodanie integracji i zmiana klucza wysyłają jedno krótkie zapytanie próbne. > **Warto wiedzieć:** W akcji z krokiem **Wyślij wiadomość AI do wątku** ustaw warunek **Odebrano wiadomość od klienta**. AI odpowiada na ostatnią wiadomość w wątku, więc bez tego warunku mogłoby odpowiadać na własne odpowiedzi. Akcje dla wiadomości: krok **Wyślij wiadomość AI do wątku** to `AI_SEND_MESSAGE_TO_THREAD` w `actionSteps[].action.type`, z `uuidValue` = id integracji AI (`GET /integrations/ai`). Wyzwalacz **Odpowiedź AI w wątku** to `triggerType` = `AI_MESSAGE_RESPONSE`, a warunek **Odebrano wiadomość od klienta** to `MESSAGE_FROM_INTERLOCUTOR`. Do modelu trafia tekst ostatniej wiadomości w wątku (niezależnie od autora) jako jedyna wiadomość użytkownika oraz `systemPrompt` integracji. Pełny opis: [Akcje dla wiadomości](https://ritevo.com/pl/docs/automations/message-actions). ### Wymaga ponownego połączenia Ten stan pojawia się, gdy Claude odrzucił klucz API podczas pisania odpowiedzi - na przykład po jego usunięciu. Do czasu podania nowego klucza AI nie odpowie klientom. 1. Utwórz nowy klucz API w Anthropic Console. 2. Na stronie integracji kliknij **Zaktualizuj token**, wklej klucz w polu **API Token** i zatwierdź. Sprawdzamy go krótkim zapytaniem próbnym - poprawny odświeży połączenie, a ustawienia zostają bez zmian. ![Okno Zaktualizuj token w integracji Claude z polem API Token](https://ritevo.com/docs/integrations/claude/pl-update-token.webp) > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie podpowiada odpowiedzi do ręcznego wstawienia - odpowiada tylko przez akcję automatyczną. - Nie czyta historii rozmowy ani danych zamówienia. - Nie zapisuje odpowiedzi jako szkicu do zatwierdzenia. - Nie ogranicza wydatków - limity ustawiasz na swoim koncie u dostawcy AI. ### Integracja przez API Endpointy tej integracji są pod `/integrations/ai/claude`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/ai`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/hurtownia-karm (updated 2026-09-29) ## Hurtownia Karm Integracja Hurtowni Karm z Ritevo: pobieranie produktów, cen netto i stanów z oferty hurtowni, interwał synchronizacji i reguły cen. Integracja z Hurtownią Karm pobiera do Ritevo ofertę hurtowni: produkty, ceny i stany. Nie podajesz żadnych danych logowania - ofertę udostępnia nam hurtownia. > **Wymagana integracja:** Nie potrzebujesz klucza ani loginu. Wystarczy dodać integrację i wybrać, jak często pobierać ofertę. Integracji Hurtownia Karm możesz dodać dowolnie wiele - każda ma własny komplet produktów, na przykład z innymi regułami cen. Każda działa osobno. Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Magazyny i hurtownie** wybierz kafelek **Hurtownia Karm**. 3. W polu **Nazwa konta** wpisz własną nazwę integracji i kliknij **Utwórz integrację**. W ciągu minuty zaczniemy pierwsze pobieranie oferty. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Hurtownia Karm w sekcji Magazyny i hurtownie](https://ritevo.com/docs/integrations/hurtownia-karm/pl-catalogue.webp) ![Ekran dodawania integracji Hurtownia Karm z polem Nazwa konta i przyciskiem Utwórz integrację](https://ritevo.com/docs/integrations/hurtownia-karm/pl-add.webp) ### Ustawienia integracji Na stronie integracji znajdziesz poniższe pola. Zmiany zapisujesz przyciskiem **Zaktualizuj integrację**: - **Nazwa konta** - Twoja własna nazwa integracji. Pod nią widzisz produkty w kolumnie **Integracja** na liście **Produkty**. - **Interwał synchronizacji** - jak często pobieramy ofertę: **Nigdy**, **LIVE** (co godzinę), **Co 2 godziny** albo **Co 6 godzin**. Domyślnie **Nigdy** - wtedy oferta pobiera się tylko raz, zaraz po dodaniu. Więcej w [Pobieraniu produktów](https://ritevo.com/pl/docs/products/fetching-products#how-often). - **Reguły transformacji** - **Reguły cenowe** i **Reguły stanu**, które zmieniają każdą cenę i każdy stan tej integracji, na przykład doliczają marżę. Opis: [Pobieranie produktów](https://ritevo.com/pl/docs/products/fetching-products#rules). - **Dodaj produkt** - przycisk w nagłówku strony. Otwiera formularz nowego produktu z wybraną już tą integracją. ![Szczegóły integracji Hurtownia Karm: nazwa konta, interwał synchronizacji LIVE oraz reguły cenowe i reguły stanu](https://ritevo.com/docs/integrations/hurtownia-karm/pl-details.webp) Pola integracji: `accountName`, `syncInterval` (`NEVER`, `LIVE`, `EVERY_2H`, `EVERY_6H`) i `transformationRules`. Tworzenie: `POST /integrations/warehouses/hurtownia-karm` z `accountName`, zmiana: `PATCH /integrations/warehouses/hurtownia-karm/{id}`. ### Co pobieramy z hurtowni - **Dane produktu** - nazwa, kod jako SKU, EAN-y (pierwszy jako EAN, kolejne jako dodatkowe EAN-y), opis, zdjęcia, producent, najdokładniejsza kategoria i waga. Wymiarów hurtownia nie podaje. Produkt bez kodu w ofercie pomijamy, bo SKU jest wymagane. - **Cena** - cena netto ze stawką VAT i walutą z oferty. - **Stan** - ilość w magazynie o nazwie „Hurtownia Karm”. - **Aktywny** - produkt jest aktywny tylko wtedy, gdy hurtownia oznacza go jako aktywny, widoczny i dostępny do sprzedaży. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo i zatrzymuje pobieranie. Produkty, ceny i stany zapisane wcześniej zostają na liście **Produkty**. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie składa zamówień w hurtowni. - Nie pobiera wariantów produktów ani ceny brutto. - Nie zdejmuje ani nie rezerwuje stanów po sprzedaży - stan w Ritevo zmienia tylko pobranie z hurtowni albo Twoja edycja. - Nie wysyła produktów, cen ani stanów do kanałów sprzedaży. ### Integracja przez API Endpointy tej integracji są pod `/integrations/warehouses/hurtownia-karm`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/warehouses`. Produkty są pod `/integrations/warehouses/products`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/own-warehouse (updated 2026-09-29) ## Własny magazyn Własny magazyn w Ritevo: ręczne dodawanie produktów, cen i stanów, kilka magazynów naraz, reguły cen oraz dodawanie produktów przez API. Własny magazyn to miejsce na produkty, które prowadzisz sam. Nic nie jest pobierane z zewnątrz - produkty, ceny i stany dodajesz w Ritevo albo przez API. > **Wymagana integracja:** Nie potrzebujesz żadnego konta zewnętrznego. Integracji Własny magazyn możesz dodać dowolnie wiele - każda ma własny komplet produktów, na przykład z innymi regułami cen. Każda działa osobno. Unikalność nie jest sprawdzana, celowo: każde utworzenie integracji tworzy nową, także dla tego samego `externalId`, żeby jedno konto mogło mieć kilka integracji z różnymi danymi albo ustawieniami. ### Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Magazyny i hurtownie** wybierz kafelek **Własny magazyn**. 3. W polu **Nazwa konta** wpisz nazwę magazynu, na przykład „Magazyn główny”, i kliknij **Utwórz integrację**. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z zaznaczonym kafelkiem Własny magazyn w sekcji Magazyny i hurtownie](https://ritevo.com/docs/integrations/own-warehouse/pl-catalogue.webp) ![Ekran dodawania integracji Własny magazyn z polem Nazwa konta i przyciskiem Utwórz integrację](https://ritevo.com/docs/integrations/own-warehouse/pl-add.webp) ### Ustawienia integracji Na stronie integracji znajdziesz poniższe pola. Zmiany zapisujesz przyciskiem **Zaktualizuj integrację**: - **Nazwa konta** - Twoja własna nazwa integracji. Pod nią widzisz produkty w kolumnie **Integracja** na liście **Produkty**. - **Reguły transformacji** - **Reguły cenowe** i **Reguły stanu**, które zmieniają każdą cenę i każdy stan tej integracji, na przykład doliczają marżę. Opis: [Pobieranie produktów](https://ritevo.com/pl/docs/products/fetching-products#rules). - **Dodaj produkt** - przycisk w nagłówku strony. Otwiera formularz nowego produktu z wybraną już tą integracją. ![Szczegóły integracji Własny magazyn: nazwa konta, reguły transformacji oraz przyciski Dodaj produkt i Zaktualizuj integrację](https://ritevo.com/docs/integrations/own-warehouse/pl-details.webp) Pola integracji: `accountName` i `transformationRules`. Tworzenie: `POST /integrations/warehouses/own` z `accountName`, zmiana: `PATCH /integrations/warehouses/own/{id}`. Własny magazyn nie ma `syncInterval`. ### Dodawanie produktów Produkt dodajesz w menu **Produkty** albo na stronie integracji: 1. Kliknij **Dodaj produkt** i wybierz ten magazyn, jeśli nie jest już wybrany. 2. Uzupełnij **Dane podstawowe**, **Identyfikatory**, **Opis** i **Wymiary**. **Id zewnętrzne** możesz zostawić puste - jeśli podasz wartość, która już istnieje w tym magazynie, zaktualizujemy tamten produkt zamiast tworzyć nowy. 3. Kliknij **Zapisz produkt**. 4. W produkcie dodaj cenę przyciskiem **Dodaj cenę** i zapisz ją przyciskiem **Zapisz cenę**. 5. Dodaj stan przyciskiem **Dodaj stan** i zapisz przyciskiem **Zapisz stany**. Produkt może mieć kilka stanów, na przykład z różnych półek albo lokalizacji. > **Warto wiedzieć:** Zapis jest zlecany w tle - zobaczysz komunikat **Zlecono utworzenie produktu** albo **Zlecono aktualizację produktu**, a zmiany pojawią się po chwili. Zdjęć nie da się dodać w aplikacji - podajesz je tylko przez API. ### Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo i zatrzymuje pobieranie. Produkty, ceny i stany zapisane wcześniej zostają na liście **Produkty**. **Przywróć integrację** włącza ją z powrotem. ### Czego integracja nie robi - Nie importuje produktów z pliku - większe ilości dodasz przez API, do 1000 produktów w jednym zapytaniu. - Nie zdejmuje ani nie rezerwuje stanów po sprzedaży - stan w Ritevo zmienia tylko pobranie z hurtowni albo Twoja edycja. - Nie wysyła produktów, cen ani stanów do kanałów sprzedaży. ### Integracja przez API Endpointy tej integracji są pod `/integrations/warehouses/own`, a wspólne dla całego typu (lista, pobranie jednej, usunięcie, przywrócenie) pod `/integrations/warehouses`. Produkty zapisujesz przez `PUT /integrations/warehouses/{integrationId}/products` (oraz `/prices`, `/stocks`) - szczegóły w [Pobieraniu produktów](https://ritevo.com/pl/docs/products/fetching-products#api). Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/pl/docs/integrations/ritevo-printer (updated 2026-10-07) ## Ritevo Printer Ritevo Printer - aplikacja do drukowania etykiet kurierskich (PDF, ZPL, EPL) i paragonów na polskich drukarkach fiskalnych: obsługiwane systemy, pobieranie, podłączenie drukarki, druk z zamówienia i z akcji. Ritevo Printer drukuje etykiety kurierskie i paragony fiskalne prosto z zamówień w Ritevo. Instalujesz ją na komputerze, do którego podłączona jest drukarka - albo kilka drukarek naraz - a wydruk zlecasz w panelu: z zamówienia, akcją automatyczną albo nawet z telefonu. > **Wymagana integracja:** Potrzebujesz komputera z Windows, macOS albo Linuksem, do którego podłączona jest drukarka (albo kilka drukarek), z zainstalowaną aplikacją Ritevo Printer. W panelu Ritevo dodaj nową integrację **Drukarka** - osobną dla każdej drukarki - i powiąż ją z aplikacją Ritevo Printer na komputerze. ### Jak to działa - **Jedna drukarka - jedna integracja.** Każda drukarka to osobna integracja **Drukarka** w panelu, z własnym tokenem. - **Wiele drukarek w jednej aplikacji.** Na jednym stanowisku dodasz np. drukarkę fiskalną do paragonów i zwykłą drukarkę do etykiet PDF - każda pracuje niezależnie. - **Wiele stanowisk.** Każdy komputer ma własną aplikację Ritevo Printer ze swoimi drukarkami - np. kasa z paragonami i pakowalnia z etykietami albo osobne stanowiska kilku pracowników. - **Zlecasz skądkolwiek.** Wydruk zlecasz w panelu - na komputerze albo w telefonie - a drukuje komputer, na którym działa aplikacja z tą drukarką. - **Działa w tle.** Zamknięcie okna chowa aplikację do paska systemowego. Zaznacz **Uruchamiaj agenta po zalogowaniu**, żeby po restarcie komputera drukowała dalej. ### Obsługiwane systemy i drukarki Etykiety PDF wydrukujesz na każdej drukarce dodanej w komputerze, także na zwykłej atramentowej albo laserowej. Etykiety ZPL i EPL wydrukuje tylko drukarka etykiet, np. Zebra. Paragony drukujemy przez oprogramowanie, które dostarcza producent drukarki fiskalnej - a nie każdy producent przygotował je na każdy system. Co działa gdzie: | | Windows | Linux | macOS | | --- | --- | --- | --- | | Etykiety PDF | ✓ | ✓ | ✓ | | Etykiety ZPL / EPL | ✓ | ✓ | ✓ | | Paragony - Novitus | ✓ | ✓ tylko drukarka w sieci | ✓ | | Paragony - Posnet | ✓ | ✓ | ✓ tylko Mac z procesorem Intel | | Paragony - Elzab | ✓ | ✓ port /dev/ttyS albo drukarka w sieci | ✗ | - Drukarka Novitus musi pracować w protokole XML - to ustawienie w menu drukarki. W starszym protokole klasycznym aplikacja ją rozpozna, ale paragonu nie wydrukuje. - Drukarkę fiskalną podłączoną przez USB system widzi jako port szeregowy (na Windowsie port COM) - na Windowsie wymaga to sterownika producenta drukarki. - Drukarkę fiskalną w sieci podajesz adresem i portem, np. `tcp:192.168.1.50:6666` - port znajdziesz w ustawieniach drukarki. - Obsługujemy drukarki fiskalne Novitus, Posnet i Elzab, a paragony drukujemy tylko w PLN. ### Pobieranie i instalacja Pobierz wersję dla swojego systemu - wszystkie wersje są też na stronie [Pobierz Ritevo Printer](/pl/ritevo-printer): - **Windows** - [ritevo-printer-setup.exe](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer-setup.exe) - **macOS, Apple Silicon (M1 i nowsze)** - [ritevo-printer-arm64.dmg](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer-arm64.dmg) - **macOS, Intel** - [ritevo-printer-x64.dmg](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer-x64.dmg) - **Linux** - [ritevo-printer.AppImage](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer.AppImage) albo [ritevo-printer_amd64.deb](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer_amd64.deb) Aplikacja nie jest podpisana certyfikatem, więc przy pierwszym uruchomieniu system zapyta o zgodę: - **Windows** - w oknie SmartScreen kliknij **Więcej informacji**, a potem **Uruchom mimo to**. - **macOS** - przy komunikacie, że Apple nie może zweryfikować aplikacji, kliknij **Gotowe**, wejdź w **Ustawienia systemowe → Prywatność i ochrona** i kliknij **Otwórz mimo to**. Aktualizacje: na Windowsie i Linuksie (AppImage) nowa wersja pobiera się sama i instaluje, gdy nic się nie drukuje - możesz też kliknąć **Uruchom ponownie i zaktualizuj**. Na macOS aplikacja pokaże **Pobierz nową wersję** - pobierz plik i przeciągnij Ritevo Printer do folderu Aplikacje. Wersję .deb aktualizujesz ręcznie. ![Sekcja Aktualizacje w Ritevo Printer z numerem wersji i przyciskiem Sprawdź aktualizacje](https://ritevo.com/docs/integrations/ritevo-printer/pl-agent-updates.webp) ### Dodanie drukarki w panelu 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Drukarki** wybierz kafelek **Drukarka**. 3. Wpisz **Nazwa drukarki** - własną nazwę, np. stanowiska - i kliknij **Dodaj integrację**. 4. Otwórz drukarkę na liście integracji i w karcie **Token drukarki** kliknij **Pokaż token**. Skopiuj go - wkleisz go w aplikacji. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Katalog integracji w Ritevo z zaznaczonym kafelkiem Drukarka w sekcji Drukarki](https://ritevo.com/docs/integrations/ritevo-printer/pl-catalogue.webp) ![Formularz dodania drukarki z polem Nazwa drukarki](https://ritevo.com/docs/integrations/ritevo-printer/pl-add.webp) ![Lista integracji z dodaną drukarką Stanowisko #1](https://ritevo.com/docs/integrations/ritevo-printer/pl-list.webp) ### Dodanie drukarki w aplikacji 1. Otwórz Ritevo Printer i kliknij **+ Dodaj drukarkę**. 2. Wklej **Token drukarki** z panelu. 3. W polu **Drukarka** wybierz drukarkę, której chcesz używać. Drukarkę fiskalną podłączoną do sieci wybierz jako **Drukarka fiskalna w sieci (adres IP)** i wpisz jej adres. 4. Aplikacja sama sprawdzi, jaka to drukarka, i pokaże **Podłączona drukarka**. 5. Kliknij **Zapisz drukarkę**. 6. Kliknij **Uruchom**. Przy drukarce pojawi się **Działa - nasłuchuję zadań**. Możesz dodać kolejne drukarki, np. jedną do etykiet, a drugą do paragonów: kliknij jeszcze raz **+ Dodaj drukarkę** i wklej token kolejnej drukarki z panelu. ![Formularz nowej drukarki w Ritevo Printer z tokenem i rozpoznaną drukarką systemową](https://ritevo.com/docs/integrations/ritevo-printer/pl-agent-add.webp) ![Okno Ritevo Printer z listą drukarek i przyciskiem Dodaj drukarkę](https://ritevo.com/docs/integrations/ritevo-printer/pl-agent-printers.webp) > **Warto wiedzieć:** Drukarki do etykiet nie ma na liście? Dodaj ją najpierw w systemie: na Windowsie w **Ustawienia → Drukarki i skanery**, na Macu w **Ustawienia systemowe → Drukarki i skanery**. Na Macu przy zwykłej drukarce atramentowej lub laserowej wybierz sterownik **AirPrint** - z ogólnym sterownikiem PostScript wydruk nie wyjdzie. ### Drukowanie Wydruk zlecasz ręcznie albo akcją automatyczną: - **Etykieta** (ręcznie) - w szczegółach zamówienia, w karcie **Przesyłki**, kliknij **Drukuj** i wybierz drukarkę. - **Paragon** (ręcznie) - w szczegółach zamówienia rozwiń przycisk paragonu i w sekcji **Drukuj** wybierz drukarkę. To samo zrobisz z listy dokumentów. - **Wydrukuj etykietę przesyłki** (krok akcji) (API: "Wydrukuj etykietę przesyłki" = `PRINT_SHIPMENT_LABEL`; wartość w `actionSteps[].action.type`) - drukuje etykietę najnowszej udanej przesyłki zamówienia na wybranej drukarce. - **Wydrukuj paragon** (krok akcji) (API: "Wydrukuj paragon" = `PRINT_RECEIPT`; wartość w `actionSteps[].action.type`) - drukuje najnowszy paragon zamówienia na wybranej drukarce fiskalnej. - **Zlecenie wydruku** (wyzwalacz akcji) (API: "Zlecenie wydruku" = `CREATE_PRINT_JOB`; wartość w `triggerType`) - uruchamia akcję, gdy wydruk zostanie zlecony. ![Karta Przesyłki w zamówieniu z rozwiniętym przyciskiem Drukuj i listą drukarek](https://ritevo.com/docs/integrations/ritevo-printer/pl-print-label.webp) ![Wystawione dokumenty w zamówieniu z rozwiniętym paragonem i sekcją Drukuj z listą drukarek](https://ritevo.com/docs/integrations/ritevo-printer/pl-print-receipt.webp) Zlecony wydruk czeka w karcie **Aktualna kolejka** w szczegółach drukarki, aż aplikacja go odbierze - wydruki zlecone przy wyłączonym komputerze wyjdą po jego włączeniu. Wynik widzisz w karcie **Historia wydruków**: - **Wydrukowano** (API: "Wydrukowano" = `SUCCESS`; wartość w `status`) - aplikacja odebrała wydruk i wysłała go na drukarkę. - **Błąd** (API: "Błąd" = `ERROR`; wartość w `status`) - wydruku nie dało się przygotować, np. kurier nie oddał etykiety. Plakietka pokazuje rodzaj błędu, a ikona obok - jego treść. ![Szczegóły drukarki w Ritevo: token, aktualna kolejka i historia wydruków](https://ritevo.com/docs/integrations/ritevo-printer/pl-details.webp) W samej aplikacji, w sekcji **Ostatnie zadania i błędy**, widzisz, co i na której drukarce się wydrukowało, oraz błędy drukarki, np. brak papieru. ![Sekcja Ostatnie zadania i błędy w Ritevo Printer](https://ritevo.com/docs/integrations/ritevo-printer/pl-agent-history.webp) ### Druk w akcji automatycznej Na co zwrócić uwagę, gdy akcja ma coś wydrukować: - **Wydrukuj etykietę przesyłki** (API: "Wydrukuj etykietę przesyłki" = `PRINT_SHIPMENT_LABEL`; wartość w `uuidValue`: id integracji drukarki: `GET /integrations/printers`) - bierze najnowszą przesyłkę zamówienia, która została utworzona pomyślnie. Jeśli takiej nie ma, krok kończy się błędem. - **Wydrukuj paragon** (API: "Wydrukuj paragon" = `PRINT_RECEIPT`; wartość w `uuidValue`: id integracji drukarki: `GET /integrations/printers`) - bierze najnowszy paragon zamówienia, który nie został usunięty. Jeśli zamówienie nie ma paragonu, krok kończy się błędem. - **Utwórz przesyłkę**, potem **Wydrukuj etykietę przesyłki** (API: "Utwórz przesyłkę" = `CREATE_SHIPMENT`, "Wydrukuj etykietę przesyłki" = `PRINT_SHIPMENT_LABEL`) - najpierw przesyłka, w następnym kroku etykieta. Krok przesyłki czeka na odpowiedź kuriera, więc etykieta jest gotowa, zanim przyjdzie czas na druk. - **Wygeneruj paragon**, potem **Wydrukuj paragon** (API: "Wygeneruj paragon" = `GENERATE_RECEIPT`, "Wydrukuj paragon" = `PRINT_RECEIPT`) - tak samo dla paragonu: najpierw dokument, w następnym kroku wydruk. - **Status przesyłki jest** (API: "Status przesyłki jest" = `SHIPMENT_STATUS_IS`; wartość w `enumValues`: `PENDING`, `SUCCESS`, `ERROR`) - żeby nie drukować etykiety po nieudanej przesyłce, dodaj w kroku druku [rozgałęzienie](https://ritevo.com/pl/docs/automations/how-it-works#branches) z tym warunkiem i wartością Utworzona pomyślnie. Krok druku nie czeka, aż kartka wyjdzie z drukarki. Akcja idzie dalej, gdy wydruk trafi do kolejki albo gdy od razu się nie uda - błąd nie zatrzymuje akcji. Nie ma warunku na wynik wydruku, więc sprawdzisz go w **Historii wydruków**. Jeśli wydruk trafi na drukarkę złego rodzaju - etykieta na fiskalną albo paragon na zwykłą - odrzuci go dopiero aplikacja na komputerze. Zobaczysz to w jej historii, akcja się o tym nie dowie. ### Paragony fiskalne - Paragon drukujemy tylko przez oficjalną bibliotekę producenta drukarki. - Zanim paragon trafi na drukarkę, sprawdzamy, czy to paragon w złotówkach i czy suma pozycji zgadza się z kwotą dokumentu. - Aplikacja zapamiętuje każdy wydrukowany paragon. Jeśli ten sam paragon zostanie zlecony na tym komputerze jeszcze raz, nie wydrukuje go drugi raz i pokaże komunikat. Zabezpieczenie działa tylko w obrębie jednego komputera, dlatego drukarkę fiskalną podłącz w aplikacji tylko na jednym stanowisku i każdy paragon zlecaj na jedną drukarkę - inne stanowisko nie wie, co już zostało wydrukowane. - Gdy połączenie z drukarką zerwie się w trakcie paragonu, aplikacja pokaże **Sprawdź drukarkę** - zanim wyślesz paragon ponownie, sprawdź na drukarce, czy wyszedł. > **Warto wiedzieć:** Nagłówek paragonu - nazwę firmy, adres i NIP - drukarka fiskalna bierze ze swojej pamięci, wpisanej przez serwisanta przy fiskalizacji. Dane sprzedawcy i nazwa wystawcy z ustawień paragonu w Ritevo są przy druku fiskalnym pomijane i nie da się ich zmienić z panelu. ### Usunięcie integracji W szczegółach drukarki w panelu kliknij **Usuń integrację** - wydruki przestaną do niej trafiać. W aplikacji usuń ją przyciskiem **Usuń** przy drukarce. ### Czego integracja nie robi - Nie drukuje faktur ani korekt na drukarce fiskalnej - tylko paragony. - Nie drukuje paragonów w innej walucie niż PLN. - Nie obsługuje drukarek fiskalnych spoza Polski ani drukarek Novitus w protokole klasycznym. ### Integracja przez API Drukarki: `GET /integrations/printers` (lista), `GET /integrations/printers/{integrationId}` (szczegóły), `GET /integrations/printers/{integrationId}/queue` (aktualna kolejka), `GET /integrations/printers/{integrationId}/history` (historia wydruków, `status`: `SUCCESS` albo `ERROR`, przy błędzie `errorType` i `errorMessage`), `GET /integrations/printers/{integrationId}/token` (token do aplikacji). Dodanie: `POST /integrations/printers`, zmiana nazwy: `PATCH /integrations/printers/{integrationId}`, usunięcie: `DELETE /integrations/printers/{integrationId}`. Wydruk etykiety: `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}` (tylko przesyłka ze `status` = `SUCCESS`), wydruk paragonu: `POST /orders/billings/{billingId}/print/{printerIntegrationId}`. W akcjach dla zamówień kroki to `PRINT_SHIPMENT_LABEL` i `PRINT_RECEIPT` w `actionSteps[].action.type` z `uuidValue` = id drukarki, a wyzwalacz **Zlecenie wydruku** to `triggerType` = `CREATE_PRINT_JOB`. Pełny opis: [Akcje dla zamówień](https://ritevo.com/pl/docs/automations/order-actions). Kroki druku nie należą do kroków, które czekają na zewnętrzny system: następny krok rusza zaraz po przyjęciu wydruku do kolejki albo po błędzie (w historii `status` = `ERROR`, np. gdy zamówienie nie ma przesyłki ze `status` = `SUCCESS` albo nie ma paragonu). Etykieta jest zawsze z najnowszej przesyłki ze `status` = `SUCCESS`, paragon - z najnowszego nieusuniętego dokumentu z `billingType` = `RECEIPT`. Nie ma warunku akcji na wynik wydruku. Wyzwalacz `CREATE_PRINT_JOB` startuje akcję po każdym takim wyniku, udanym i nieudanym. Odrzucenia przez aplikację (zły rodzaj drukarki, drukarka niegotowa) nie wracają do akcji. # Help (en) Step-by-step guides: connecting integrations, automatic actions, orders, messages and the API. Source: https://ritevo.com/en/docs/orders/fetching-orders (updated 2026-10-10) ## Fetching orders How Ritevo fetches orders from marketplaces and online stores, how often it checks, and what to do when an order is missing. Ritevo checks your sales channels on its own and adds new orders to your list. There is nothing to import or refresh. > **Required integration:** You need at least one **marketplace** integration (e.g. eBay) or one **online store** integration (e.g. WooCommerce). Email and messaging apps are message channels - orders are never fetched from them. ### Turning fetching on and off Order fetching is set **separately for each integration**. After you add a new integration it is **off** - until you turn it on, no orders are fetched from that channel. To turn it on: 1. Go to **Integrations** and open the integration you want to fetch orders from. 2. Turn on the **Fetch orders** switch. 3. Save your changes. ![The "Fetch orders" switch in the integration settings](https://ritevo.com/docs/orders/en-fetch-orders-toggle.webp) From then on we check that channel about every 10 minutes. You can turn fetching off at any time with the same switch. Orders fetched earlier stay in Ritevo, new ones from that integration simply stop coming in. ### How often we check for orders Each integration is checked about **every 10 minutes**, so a new order shows up on your list within a dozen or so minutes of being placed. The first fetch reaches **7 days back**, so your list does not start empty. Older orders are not fetched. ### Where you will see a fetched order A fetched order appears in the **orders table** right away. That is where you open it and handle it in Ritevo from then on. > **Good to know:** All prices you see in Ritevo - in orders, invoices, receipts and corrections - are gross prices. The exception is warehouse products, whose prices are net. We calculate the net price from the gross price and the VAT rate: net = gross ÷ (1 + VAT rate). For example, 123 PLN gross at a 23% rate is 100 PLN net. ### Additional services Some channels pass on services the buyer added to the order, for example gift wrapping, carry-in or assembly. Each service appears as a separate line item - even when it costs 0.00 - so you see it while handling the order and have it on the invoice. - **Service for a product** - it has a service icon instead of a photo and the label **Additional service**, and the product it was bought with shows a badge with its name. - **Service for the whole order** - it applies to the whole parcel, not one product, and has the label **Service for the whole order**. - **Packing assistant** - services are not packed as pieces; you see them as badges on the product or in a separate card above the item list. When a channel does not pass on services, you can list the service as a separate offer or product, for example **Gift wrapping**. It then arrives as a regular line item - Ritevo does not mark it as a service, because it receives it the same way as any product. Whether a channel passes on services, and which ones, is described on its integration page, in the part about orders. A service is a line item with `lineItems[].additionalService.additionalService` = `true`. The field `additionalService.forLineItemId` points to the `id` of the product line item it was bought with; `null` means a service for the whole order. A regular line item has `additionalService` = `false` and `forLineItemId` = `null`. ### Who manages the order after it is fetched That depends on the order's status in Ritevo. **Order not confirmed yet** (for example **Awaiting payment** or **Awaiting confirmation**): if something changes in the sales channel, for example the customer pays, Ritevo updates the order on the next check. No second order is created. **Order with the Confirmed status**: from this point the order is managed by Ritevo. Further changes coming from the sales channel are **skipped**, so they do not overwrite what you have set on your side. Among other things, we skip: - a status change made in the sales channel, - a change to the invoice details made in the sales channel, - a shipping label generated in the sales channel. You handle all of this in Ritevo now, and the data in Ritevo is the one that counts. > **Good to know:** An order that arrived in Ritevo already as **Confirmed** is protected the same way from the very first moment. ### Orders appear even though fetching is off This is not an error. It happens when [message fetching](https://ritevo.com/en/docs/messages/fetching-messages) is turned on for the integration. In some integrations a message, dispute or claim refers to a specific order. When such a message arrives, Ritevo **fetches that one order on its own**, so you can see what the conversation is about straight away. Only orders linked to messages are fetched this way. The rest of the orders from that channel are still not fetched until you turn on **Fetch orders**. ### I cannot see an order > **Good to know:** The most common cause: the integration shows **Reconnection required**. It usually means the access you gave Ritevo in the sales channel has expired or was revoked - for example after a password change or when the connection reached its expiry date. Until you reconnect the integration, orders from that channel are not fetched. Check in this order: 1. Is the integration **Active**. 2. Is **Fetch orders** turned on - after adding an integration it is off by default. 3. Have a dozen or so minutes passed since the order was placed. 4. Is the order older than 7 days before the integration was added. ### Order and payment statuses through the API The order status (`status`) takes one of the values: - **Confirmed** (API: "Confirmed" = `CONFIRMED`; value in `status`) - the order is taken over by Ritevo. - **Cancelled** (API: "Cancelled" = `CANCELLED`; value in `status`) - the order is cancelled. - **Awaiting payment** (API: "Awaiting payment" = `WAITING_FOR_PAYMENT`; value in `status`) - waiting for the payment. - **Awaiting confirmation** (API: "Awaiting confirmation" = `WAITING_FOR_CONFIRMATION`; value in `status`) - waiting for your decision; a store status with no mapping lands here too. The payment status (`payment.paymentStatus`) is separate and Ritevo calculates it from the amounts: no paid amount (`paidAmount` = `null`) gives `WAITING_FOR_PAYMENT`; an amount equal to the order total gives `PAID`, a higher one `OVERPAID`, a lower one `UNDERPAID`. An amount of `0.00` is a zero payment, not a missing one - with a non-zero total it gives `UNDERPAID`, with a zero total `PAID`. --- Source: https://ritevo.com/en/docs/messages/fetching-messages (updated 2026-09-27) ## Fetching messages How Ritevo fetches messages, disputes and claims from sales channels, email and messaging apps, how often it checks, and what to do when one is missing. Ritevo gathers customer messages from all your connected channels in one inbox. This page covers the rules shared by every integration - whether it is a marketplace, an online store, email or a messaging app. > **Required integration:** You need at least one integration that supports messages: a **marketplace** (e.g. eBay), an **online store**, **email** or a **messaging app** (e.g. Messenger). Not every integration has messages - if it does not, there is no **Fetch messages** switch in its settings. ### Turning fetching on and off Message fetching is set **separately for each integration**. After you add a new integration it is **off** - until you turn it on, no messages are fetched from that channel. To turn it on: 1. Go to **Integrations** and open the integration you want to fetch messages from. 2. Turn on the **Fetch messages** switch. 3. Save your changes. ![The "Fetch messages" switch in the integration settings](https://ritevo.com/docs/messages/en-fetch-messages-toggle.webp) You can turn fetching off at any time with the same switch. Messages fetched earlier stay in Ritevo, new ones from that integration simply stop coming in. Message fetching and [order fetching](https://ritevo.com/en/docs/orders/fetching-orders) are two independent switches. You can have one, the other, or both turned on. ### How often we check for messages - **Marketplaces, online stores and email**: each integration is checked about **every 10 minutes**. - **Messaging apps** (Messenger, WhatsApp): a message reaches Ritevo **right away**, as soon as the customer sends it. ### What we fetch Every thread in Ritevo has one of three types: - **Message** (API: "Message" = `MESSAGE`; value in `threadType`) - a regular conversation with a customer. Every integration with messages supports it. - **Dispute** (API: "Dispute" = `DISCUSSION`; value in `threadType`) - a dispute opened by the customer in the sales channel. - **Claim** (API: "Claim" = `CLAIM`; value in `threadType`) - a claim filed through the sales channel. Disputes and claims are fetched only from sales channels that run them themselves. Email and messaging apps have messages only. Which types a specific integration supports is described on its own page. ### Where you will see fetched messages All threads land in the shared inbox in the **Messages** tab. Each one shows which integration it came from and what type it is. ### Messages and orders In some integrations a message, dispute or claim refers to a specific order. Ritevo then links the thread to that order, so you can see what the conversation is about straight away. > **Good to know:** If that order is not in Ritevo yet, **we fetch it on our own** - even when order fetching is turned off for that integration. Only that one linked order is fetched. More in [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders#linked-orders). ### I cannot see a message > **Good to know:** The most common cause: the integration shows **Reconnection required**. It usually means the access you gave Ritevo in that channel has expired or was revoked - for example after a password change or when the connection reached its expiry date. Until you reconnect the integration, messages from that channel are not fetched. Check in this order: 1. Is the integration **Active**. 2. Is **Fetch messages** turned on - after adding an integration it is off by default. 3. Does this integration support messages at all - if not, there is no switch. 4. Have a dozen or so minutes passed since the message was sent (does not apply to messaging apps). ### Thread types and statuses through the API Disputes and claims also have a status (`threadStatus`): - **Ongoing**, **Closed**, **Unresolved** (API: "Ongoing" = `DISPUTE_ONGOING`, "Closed" = `DISPUTE_CLOSED`, "Unresolved" = `DISPUTE_UNRESOLVED`; value in `threadStatus`) - dispute statuses. - **Submitted**, **Accepted**, **Rejected** (API: "Submitted" = `CLAIM_SUBMITTED`, "Accepted" = `CLAIM_ACCEPTED`, "Rejected" = `CLAIM_REJECTED`; value in `threadStatus`) - claim statuses. What each channel supports (replying, attachments, character limit) is returned by `GET /integrations/messages/capabilities`. The current response shape is in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/products/fetching-products (updated 2026-09-29) ## Fetching products How Ritevo fetches products, prices and stock from wholesalers, how often, what happens to deleted products, several warehouses and price rules. Products come into Ritevo from integrations in the **Warehouses and wholesalers** category: we fetch them from wholesalers automatically, and you add them to your own warehouse yourself. You see them all in one place, with price and stock. > **Required integration:** You need an integration from the **Warehouses and wholesalers** category - for example [Hurtownia Karm](https://ritevo.com/en/docs/integrations/hurtownia-karm) or an [Own warehouse](https://ritevo.com/en/docs/integrations/own-warehouse). ### Where the products are All products are in the **Products** menu. The list shows the name, manufacturer, price, stock, SKU and the integration the product comes from. Stock is the sum of all the product's stock levels. You filter by integration, name, SKU, EAN, manufacturer, category, price, stock and whether the product is deleted. ### Where products come from - **Wholesaler** - we fetch products, prices and stock from the wholesaler's offer at the interval you set. - **Own warehouse** - you add products yourself with **Add product**, and enter price and stock in the product. ### How often we fetch products For each wholesaler you choose how often we fetch its offer in the **Sync interval** field on the integration page: - **Never** (API: "Never" = `NEVER`; value in `syncInterval`) - the offer is fetched only once, right after the integration is added. The default. - **LIVE** (API: "LIVE" = `LIVE`; value in `syncInterval`) - every hour. - **Every 2 hours** (API: "Every 2 hours" = `EVERY_2H`; value in `syncInterval`) - every two hours. - **Every 6 hours** (API: "Every 6 hours" = `EVERY_6H`; value in `syncInterval`) - every six hours. > **Good to know:** On every fetch we update products first, and prices and stock right after. An own warehouse fetches nothing - it changes only when you change something. ### What a product holds - **Basic data** - name, SKU, EAN and additional EANs, description, images, manufacturer, category, weight and dimensions. - **Price** - net amount, VAT rate and currency. Every product has one price. - **Stock** - the quantity in a given warehouse. A product can have several stock levels, for example the wholesaler's and your own. - **Status** - the **Active** and **Deleted** switches. > **Good to know:** Warehouse product prices are net. Price rules also work on the net price. All other prices in Ritevo, for example in orders, invoices and receipts, are gross. ### Several warehouses and wholesalers You can have many warehouse integrations at once, including several own warehouses. Every product belongs to one integration - the same SKU or EAN in two warehouses means two separate products that are not merged. You see which integration a product comes from in the **Integration** column and filter. ### When a product is deleted - **The product left the wholesaler** - on the next fetch we mark it as deleted, and its wholesaler stock drops to 0. If it comes back to the offer, it is active again on the following fetch. - **You delete a wholesaler product yourself** - the **Deleted** switch lasts only until the next fetch, when the wholesaler overwrites the product again. - **You delete a product from your own warehouse** - turn on **Deleted** in the product. You restore it by turning the switch off. - **In the list** - deleted products still show in the **Products** list. You hide them with the **Product deleted** filter. ### Changes to wholesaler products You can edit a wholesaler product, but on the next fetch the wholesaler overwrites the name, description, price, EAN, dimensions and other fields. Only stock levels you added yourself with **Add stock** stay. The wholesaler's stock levels go back to the supplier's values every time. > **Good to know:** A wholesaler product shows the **Product comes from an external supplier** warning. For a lasting price or stock change across the whole wholesaler, use transformation rules - described below. ### Price and stock rules Every warehouse integration page has **Transformation rules**: separate **Price rules** and **Stock rules**. They apply to every price and every stock level of that integration - fetched from the wholesaler and entered by you. Each rule has a **Value from** and **Value to** range, an **Operation** and an **Operand**. Operations: - **Multiplier** (API: "Multiplier" = `MULTIPLY`; value in `operation`) - multiplies the value by the operand, for example 1.3 adds a 30% margin. - **Add** (API: "Add" = `ADD`; value in `operation`) - adds the operand to the value. - **Subtract** (API: "Subtract" = `SUBTRACT`; value in `operation`) - subtracts the operand from the value. - **Set to** (API: "Set to" = `SET_TO`; value in `operation`) - replaces the value with the operand, for example sets stock to 0. Rules are checked in order from the top - the first one whose range matches the value is applied. Each list holds at most 20 rules, which you add with **Add rule**. > **Good to know:** Example: a price rule from 0 to 100 with the **Multiplier** operation and operand 1.5 raises cheap products by half, and the next one, from 100 to 100000 with operand 1.2, raises the more expensive ones by 20%. ### Products and orders - **Linking** - we do not link an order line to a product automatically. In the order details click **Link offer to product** and pick the product. The link stays for that offer in later orders from the same integration too. - **Packing assistant** - uses linked products and compares the scanned code with their EAN. A line without a link is marked **No warehouse link**. - **Stock** - a sale does not change stock in Ritevo: nothing is deducted or reserved. ### Deleting a warehouse integration Deleting the integration stops fetching, but its products, prices and stock levels stay in the **Products** list. After you restore the integration, fetching resumes at the next due time. ### What is not there yet - It does not merge the same products from different warehouses into one. - It does not import products from a file - you add products to your own warehouse in the app or through the API. - It does not deduct or reserve stock after a sale. - It does not send products to sales channels. ### Products through the API List: `GET /integrations/warehouses/products` (pages of up to 5000), one product: `GET /integrations/warehouses/products/{id}`. Writes are asynchronous (202) and take up to 1000 items per request: `PUT /integrations/warehouses/{integrationId}/products` (fields `externalId`, `sku`, `name`, `description`, `ean`, `additionalEans`, `images`, `manufacturer`, `category`, `weight`, `width`, `height`, `length`, `active`, `deleted`, `price`), `PUT .../products/prices` (`productId`, `amount`, `currency`, `vatRate`) and `PUT .../products/stocks` (`productId`, `externalId`, `warehouse`, `quantity`, `deleted`). A product with the same `externalId` in a given integration is updated instead of created. In responses `original` = `true` marks supplier data, `false` - changed by hand. Offer-to-product links: `GET` and `DELETE /integrations/warehouses/external-offer-assignments`; you create a link with `POST /orders/{orderId}/line-items/{lineItemId}/warehouse-link`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. A wholesaler integration has `syncInterval` = `NEVER`, `LIVE` (every hour), `EVERY_2H` or `EVERY_6H`. `transformationRules` holds `priceRules` and `stockRules` - lists of up to 20 objects `valueFrom`, `valueTo`, `operation` (`MULTIPLY`, `ADD`, `SUBTRACT`, `SET_TO`) and `operand`. The first rule whose range matches wins. --- Source: https://ritevo.com/en/docs/automations/how-it-works (updated 2026-09-30) ## How automatic actions work Automatic actions in Ritevo: trigger, conditions and steps, run order, loop protection and the run audit. An automatic action is a rule: **when something happens and the conditions are met, Ritevo carries out the steps you set**. Everything an action does you can also do by hand - the action simply does it for you. > **Good to know:** Without an action that is created and turned on, nothing happens on its own. Ritevo has no hidden automation. ### Two kinds of actions You create actions separately for orders and for messages. They work the same way and differ in what they react to and what they can do: - [Order actions](https://ritevo.com/en/docs/automations/order-actions) - react to changes in an order and can change its status, issue a document, create a shipment, print a label, update order data and much more. - [Message actions](https://ritevo.com/en/docs/automations/message-actions) - react to customer messages and can reply for you, also with the help of AI, assign the thread to a user, set a status and much more. ### What an action is made of - **Trigger** - the one event that starts the action, for example **Order status changed** or **New thread**. Every action has exactly one trigger. - **Conditions** - optional. They narrow the action down, for example to paid orders only or to messages from the customer only. You can add up to 50 conditions. - **Steps** - what Ritevo should do. At least one, at most 50. They run in order. In the form these are the **Action #1**, **Action #2** and further cards, added with the **Add step** button. - **Run time zone** - conditions with a time of day or a day of the week are counted in it. - **Active / Inactive** - only active actions run. An inactive action stays saved but does nothing. You set everything in one form: basic settings at the top, conditions on the left, steps on the right. ![An empty new-action form: name and description, trigger, run time zone, the Active switch, a condition card and a step card](https://ritevo.com/docs/automations/en-action-form-empty.webp) ### How Ritevo runs an action 1. Something that is a trigger happens - no matter whether you made the change, it came from the sales channel, or another action made it. 2. Ritevo takes all active actions with that trigger. 3. For each of them it checks the conditions. If one is not met, that action does not run. 4. It carries out the steps in order. The next step starts only after the previous one succeeded. 5. Every run is saved in the audit. If several actions match one event, **all of them run**. Actions have no priority and no set order, so do not build actions that depend on which one fires first. When order matters, you have two ways - pick the one you prefer: - **One action with several steps.** Steps always run in order, and the next one starts only after the previous one succeeded. This is the simplest and most reliable way. - **A chain of actions.** The last step of action A is the trigger of action B - for example A ends with the **Create shipment** step and B has the **Shipment created** trigger. It is useful when you want the second part kept apart: with its own conditions, or so you can turn it off independently of the first. ### How conditions work - All conditions of an action have to be met **at the same time**. There is no "or" between conditions. - Inside one condition you can pick several values - then **any of them** is enough. For example in the **Integration is** condition you pick one or several from the list of your integrations: eBay and WooCommerce means "an order from eBay or from WooCommerce". - A range is set with two conditions: **from** and **to**. Working hours, for example, are **Action run time from** 08:00 and **Action run time to** 16:00. - Times of day and days of the week are counted in the **time zone set in the action**. The time in the form, however, is entered in your computer's time. So leave the action on the zone the form sets by itself - your own. Then **Action run time from** 08:00 simply means 8:00 where you are, also when the customer is in another country. If you change the action's zone to one different from yours, the time you entered shifts by the difference between the zones. Daylight saving time is handled automatically. - A range that crosses midnight (for example 22:00-05:00) needs **two actions**: one with the condition **from** 22:00 and another with the condition **to** 05:00. The form lets you set both conditions in one action, but such an action will never run - every condition is checked on its own, and no time of day is both after 22:00 and before 05:00. ### Branches inside a step A step can have branches, that is several variants with their own conditions. It is useful when the same action should do something different depending on the order or message. - Ritevo checks the variants in order and runs the **first** one whose conditions are met. - If no variant matches, it runs the step's default action. - If the step has no default action, the whole action stops and the audit shows **Action stopped by conditions**. - Branches have one level - a variant holds a single operation, not further steps. ### Loop protection An action changes data, and a data change can be a trigger. Ritevo makes sure actions do not keep setting each other off forever - in three ways: 1. **An action never triggers itself.** If an action with the **Order status changed** trigger changes the status itself, it will not start a second time because of that. 2. **Actions can trigger other actions, but not in a circle.** The last step of action A can start action B, and that one action C. But when saving or turning on an action would close a circle (A starts B, B starts A - also through more actions), Ritevo will not save it and shows an error about a detected infinite cycle. Only active actions count. 3. **A safety switch at run time.** If actions still run on the same order or thread too many times in a short period, Ritevo pauses them. The orders or messages audit then shows an **Infinite loop detected** entry together with the action and the step it happened on. Your manual changes are never blocked this way. > **Good to know:** While an action is going through its steps, its changes **do not start any new action** - the following steps only move the same action forward. A new action can be started only by an event from outside an action (a trigger) or by the **last step** of another action. ### Run audit Every run of an action is saved in the audit: **Settings → Audit**, separately for orders and for messages. You can filter entries by action and by result. Possible results: - **Action continues** - a step ran and there are more. - **Action finished** - the last step ran. - **Action stopped by conditions** - in a step with branches no variant matched. - **Infinite loop detected** - the safety switch kicked in. - **Error** - a step failed, for example an integration rejected the request. The entry holds the error description. In order actions, after an error in a step that uses an integration - shipment, sending a document to accounting, printing - the action continues: [Steps that wait for an external system](https://ritevo.com/en/docs/automations/order-actions#waiting-steps). After an error in any other step, the remaining steps of that action do not run. ### What actions do not do - They do not start at a set time. There is no "every day at 8:00" trigger - time exists only as a condition. - They do not wait. There is no "wait an hour" or "send after 2 days" step. - They cannot be run by hand on a chosen order or thread. You can only turn an action on or off. - One action has one trigger. For two events create two actions. - Limits: up to 1000 actions per company, up to 50 steps and 50 conditions per action. ### Saving an action through the API (for AI and integrators) This section exists only in the Markdown version. On the detailed pages, the names of triggers, conditions and steps are followed in brackets by their API names and the field the value goes in. Order actions are saved with `POST /orders/automatic-actions`, message actions with `POST /messages/automatic-actions`; a change is `PATCH /{id}`, turning on and off `PATCH /{id}/toggle-active`, deleting `DELETE /{id}`. The API base address is `https://api.ritevo.com/api`. The full definition of every endpoint and field: [Swagger UI](https://api.ritevo.com/api/webjars/swagger-ui/index.html), machine-readable (OpenAPI) at `https://api.ritevo.com/api/v1/api-docs`. The paths given next to values (for example `GET /integrations/shippings`) are relative to the base address. - Action fields: `name` and `description` (both required, up to 255 characters), `active`, `userTimezone` (required, an IANA zone name, for example `Europe/London`), `triggerType` (exactly one), `conditions` (0-50), `actionSteps` (1-50). - Step: `stepOrder` numbered from 1 with no gaps or repeats, and `action` or `conditionalBranches` (or both - then `action` is the default action). Variant: `branchOrder` from 1, `conditions` (at least one) and `action`. - Condition: `type` and **exactly the value field** given next to its name. Do not send the other fields. - Step operation (`action`): `type` and the value field given next to the step's name. - Time and date: `offsetDateTimeValue` is a full date-time with an offset, for example `2026-01-10T08:00:00+00:00`. For time-of-day conditions (`*_TIME_FROM`, `*_TIME_TO`) only the hour and minute read in `userTimezone` count, so give the time with that zone's offset; the date can be anything. For date conditions (`*_DATE_FROM`, `*_DATE_TO`) the whole instant counts. - Days of the week: `integerValues` with numbers 1-7, where 1 is Monday and 7 is Sunday. - Conditions without a value ("has invoice", "from customer"): `booleanValues` with a single `true`. Steps that need a confirmation (deleting): `booleanValue` equal to `true`. - Get the identifiers of integrations, custom statuses, message templates, users and document settings templates from the API lists - they are UUIDs. - Saving is rejected with code 409 if active actions would close a circle. The trigger an action fires follows from its **last** step: `UPDATE_STATUS` → `STATUS_CHANGED`, `UPDATE_USER_DEFINED_STATUS` → `USER_DEFINED_STATUS_CHANGED`, `UPDATE_PAYMENT` → `PAYMENT_DATA_CHANGED`, `GENERATE_INVOICE` / `DELETE_INVOICE` → `INVOICE_CHANGED`, `GENERATE_RECEIPT` / `DELETE_RECEIPT` → `RECEIPT_CHANGED`, `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` → `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING`, `CREATE_SHIPMENT` → `CREATE_SHIPMENT`, `PRINT_SHIPMENT_LABEL` / `PRINT_RECEIPT` → `CREATE_PRINT_JOB`, `DELETE_ORDER` / `RESTORE_ORDER` → `ORDER`; for messages `SEND_MESSAGE_TO_THREAD` → `MESSAGE_RESPONSE`, `TEMPLATE_SEND_MESSAGE_TO_THREAD` → `TEMPLATE_MESSAGE_RESPONSE`, `AI_SEND_MESSAGE_TO_THREAD` → `AI_MESSAGE_RESPONSE`, `UPDATE_ASSIGNED_USER` → `ASSIGNED_USER_CHANGED`, `UPDATE_READ_STATUS` → `READ_STATUS_CHANGED`. The rest: `UPDATE_OWN_NOTE` → `OWN_NOTE_CHANGED`, `UPDATE_FAVORITE_STATUS` → `FAVORITE_STATUS_CHANGED`, `UPDATE_ORDER_DATE` → `ORDER_DATE_CHANGED`, `UPDATE_BUYER` → `BUYER_DATA_CHANGED`, `UPDATE_COMPANY` / `USE_BUYER_AS_BILLING_RECIPIENT` → `COMPANY_DATA_CHANGED`, `UPDATE_DELIVERY_ADDRESS` → `DELIVERY_ADDRESS_CHANGED`, `UPDATE_DELIVERY_BASIC` → `DELIVERY_BASIC_CHANGED`, `UPDATE_DELIVERY_METHOD` → `DELIVERY_METHOD_CHANGED`, `UPDATE_DELIVERY_PICKUP_POINT` → `DELIVERY_PICKUP_POINT_CHANGED`, `UPDATE_DELIVERY_TIME` → `DELIVERY_TIME_CHANGED`, `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` → `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. --- Source: https://ritevo.com/en/docs/automations/order-actions (updated 2026-09-30) ## Automatic actions for orders Automatic order actions in Ritevo: triggers, conditions and steps - invoice, shipment, label, status - with ready-made examples. An order action reacts to a change in an order and carries out the steps you set on it. Most often it changes the order status or your own custom status, issues an invoice or a receipt, sends a document to the accounting system, creates a shipment, prints a label or a receipt, updates order data - the buyer, invoice details, delivery, payment - adds a note, marks the order as a favorite and much more. The general rules - conditions, branches, loop protection - are covered in [How automatic actions work](https://ritevo.com/en/docs/automations/how-it-works). > **Required integration:** Actions themselves need no integration. Specific steps do: **Create shipment** needs a shipping integration, **Send invoice to external accounting** an accounting integration, **Print shipment label** a printer integration. ### Where to find actions Order actions are in the **Orders → Actions** menu (in the left panel). For every action the list shows its trigger, conditions and steps, and whether it is active. You add a new action with the **Add new action** button in the top right corner. The breadcrumbs at the top of the page (**Dashboard → Orders → Actions**) always show where you are. ![The list of automatic order actions with the Actions item highlighted in the left panel; the Add new action button in the top right corner is framed](https://ritevo.com/docs/automations/en-order-actions-list.webp) The action form: basic settings at the top (name, description, trigger, time zone, **Active**), conditions on the left, steps on the right. ![An empty new-action form for orders: basic settings, a condition card and a step card](https://ritevo.com/docs/automations/en-action-form-empty.webp) ### Triggers A trigger is a change that happened in the order. It does not matter who made it: you, the sales channel while the order was fetched, or another action. #### Order and statuses - **Order** (API: "Order" = `ORDER`) - a new order reached Ritevo or an existing one was updated when fetched from the sales channel; also deleting and restoring an order. This is the trigger for "do something with every new order" actions. - **Order status changed** (API: "Order status changed" = `STATUS_CHANGED`) - the order status changed, for example to **Confirmed**. - **Status changed** (API: "Status changed" = `USER_DEFINED_STATUS_CHANGED`) - your own custom order status changed. - **Payment data changed** (API: "Payment data changed" = `PAYMENT_DATA_CHANGED`) - the payment changed, for example the order was paid. - **Order date changed**, **Own note changed**, **Favorite status changed**. (API: "Order date changed" = `ORDER_DATE_CHANGED`, "Own note changed" = `OWN_NOTE_CHANGED`, "Favorite status changed" = `FAVORITE_STATUS_CHANGED`) #### Order data - **Line item changed** (API: "Line item changed" = `LINE_ITEM_CHANGED`) - an item was added, changed or removed. - **Buyer data changed**, **Company data changed**. (API: "Buyer data changed" = `BUYER_DATA_CHANGED`, "Company data changed" = `COMPANY_DATA_CHANGED`) - **Delivery address changed**, **Delivery method changed**, **Pickup point changed**, **Delivery time changed**, **Basic delivery data changed**. (API: "Delivery address changed" = `DELIVERY_ADDRESS_CHANGED`, "Delivery method changed" = `DELIVERY_METHOD_CHANGED`, "Pickup point changed" = `DELIVERY_PICKUP_POINT_CHANGED`, "Delivery time changed" = `DELIVERY_TIME_CHANGED`, "Basic delivery data changed" = `DELIVERY_BASIC_CHANGED`) #### Documents, shipments and printing - **Invoice (added/removed)**, **Receipt (added/removed)** (API: "Invoice (added/removed)" = `INVOICE_CHANGED`, "Receipt (added/removed)" = `RECEIPT_CHANGED`) - a document was issued or deleted. - **Invoice sent to external accounting**, **Receipt sent to external accounting**. (API: "Invoice sent to external accounting" = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING`, "Receipt sent to external accounting" = `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`) - **Shipment created** (API: "Shipment created" = `CREATE_SHIPMENT`) - a shipment was created for the order. - **Print job** (API: "Print job" = `CREATE_PRINT_JOB`) - a label or receipt print was requested. ### Conditions Conditions check the order at the moment the action runs. The names below match the list in the action form. #### Integration and statuses - **Integration is** / **Integration is not** (API: "Integration is" = `INTEGRATION_IS`, "Integration is not" = `INTEGRATION_IS_NOT`; value in `uuidValues`: ids of sales integrations: `GET /integrations/marketplaces`, `GET /integrations/shops`) - you pick one or several from the list of your integrations. With several, it is enough that the order comes from any of them. - **Order status is** / **Order status is not** (API: "Order status is" = `ORDER_STATUS_IS`, "Order status is not" = `ORDER_STATUS_IS_NOT`; value in `enumValues`: `CONFIRMED`, `CANCELLED`, `WAITING_FOR_PAYMENT`, `WAITING_FOR_CONFIRMATION`) - you pick one or several order statuses, for example Confirmed. - **Order status changed to** (API: "Order status changed to" = `ORDER_STATUS_CHANGED_TO`; value in `enumValues`: `CONFIRMED`, `CANCELLED`, `WAITING_FOR_PAYMENT`, `WAITING_FOR_CONFIRMATION`) - use it with the **Order status changed** trigger: the condition is met when, after the change, the order has one of the statuses you picked. - **Status is** / **Status is not** / **Status changed to** (API: "Status is" = `USER_DEFINED_STATUS_IS`, "Status is not" = `USER_DEFINED_STATUS_IS_NOT`, "Status changed to" = `USER_DEFINED_STATUS_CHANGED_TO`; value in `uuidValues`: ids of custom order statuses: `GET /orders/statuses`) - the same for your own custom statuses. #### Payment - **Payment status is** / **Payment status is not** (API: "Payment status is" = `PAYMENT_STATUS_IS`, "Payment status is not" = `PAYMENT_STATUS_IS_NOT`; value in `enumValues`: `WAITING_FOR_PAYMENT`, `PAID`, `OVERPAID`, `UNDERPAID`) - for example Paid, Underpaid, Overpaid. - **Payment method is** / **Payment method is not** (API: "Payment method is" = `PAYMENT_METHOD_IS`, "Payment method is not" = `PAYMENT_METHOD_IS_NOT`; value in `enumValues`: `BANK_TRANSFER`, `CASH`, `CASH_ON_DELIVERY`, `COMPENSATION`, `CARD`, `PAYU`, `PAYPAL`, `P24`, `OTHER`) - one or several methods. - **Order not paid** (API: "Order not paid" = `PAYMENT_NOT_PAID`; value in `booleanValues`: always `[true]`) - nothing has come in yet. - **Amount paid greater than** / **less than** / **equal to** (API: "Amount paid greater than" = `PAYMENT_PAID_AMOUNT_GREATER_THAN`, "less than" = `PAYMENT_PAID_AMOUNT_LESS_THAN`, "equal to" = `PAYMENT_PAID_AMOUNT_EQUALS`; value in `bigDecimalValue`: a number, for example `500.00`) - compared with the amount you enter. - **Amount to pay greater than** / **less than** / **equal to** (API: "Amount to pay greater than" = `PAYMENT_TOTAL_TO_PAY_AMOUNT_GREATER_THAN`, "less than" = `PAYMENT_TOTAL_TO_PAY_AMOUNT_LESS_THAN`, "equal to" = `PAYMENT_TOTAL_TO_PAY_AMOUNT_EQUALS`; value in `bigDecimalValue`: a number, for example `500.00`) - for example different steps for orders above 100 EUR. #### Delivery and line items - **Delivery country is** / **Delivery country is not** (API: "Delivery country is" = `DELIVERY_COUNTRY_IS`, "Delivery country is not" = `DELIVERY_COUNTRY_IS_NOT`; value in `enumValues`: two-letter ISO country codes, for example `GB`, `DE`) - one or several countries. - **Delivery region is** / **Delivery region is not** (API: "Delivery region is" = `DELIVERY_REGION_IS`, "Delivery region is not" = `DELIVERY_REGION_IS_NOT`; value in `enumValues`: `EUROPE`) - currently Europe is available. - **Delivery city contains** / **Delivery city does not contain** (API: "Delivery city contains" = `DELIVERY_CITY_CONTAINS`, "Delivery city does not contain" = `DELIVERY_CITY_CONTAINS_NOT`; value in `stringValues`: a list of words or text fragments; any of them is enough, letter case does not matter) - part of the city name. - **Number of line items greater than** / **less than** / **equal to** (API: "Number of line items greater than" = `LINE_ITEMS_COUNT_GREATER_THAN`, "less than" = `LINE_ITEMS_COUNT_LESS_THAN`, "equal to" = `LINE_ITEMS_COUNT_EQUALS`; value in `integerValue`: a whole number) - how many different items the order has. - **Item quantity greater than** / **less than** / **equal to** (API: "Item quantity greater than" = `LINE_ITEM_QUANTITY_GREATER_THAN`, "less than" = `LINE_ITEM_QUANTITY_LESS_THAN`; value in `integerValue`: a whole number | "equal to" = `LINE_ITEM_QUANTITY_EQUALS`; value in `bigDecimalValue`: a number, for example `500.00`) - how many units an item has. - **Item name contains** / **Item name does not contain** (API: "Item name contains" = `LINE_ITEM_NAME_CONTAINS`, "Item name does not contain" = `LINE_ITEM_NAME_NOT_CONTAINS`; value in `stringValues`: a list of words or text fragments; any of them is enough, letter case does not matter) - one or several words; any of them is enough. #### Documents and shipment - **Has invoice** / **Has no invoice**, **Has receipt** / **Has no receipt**, **Has correction** / **Has no correction**. (API: "Has invoice" = `HAS_INVOICE`, "Has no invoice" = `HAS_INVOICE_NOT`, "Has receipt" = `HAS_RECEIPT`, "Has no receipt" = `HAS_RECEIPT_NOT`, "Has correction" = `HAS_CORRECTION`, "Has no correction" = `HAS_CORRECTION_NOT`; value in `booleanValues`: always `[true]`) - **Has a successful invoice transfer to external accounting** / **Has no successful invoice transfer to external accounting**, **Has a successful receipt transfer to external accounting** / **Has no successful receipt transfer to external accounting** (API: "Has a successful invoice transfer to external accounting" = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING`, "Has no successful invoice transfer to external accounting" = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`; value in `uuidValues`: id of an accounting integration: `GET /integrations/accountings` | "Has a successful receipt transfer to external accounting" = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING`, "Has no successful receipt transfer to external accounting" = `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT`; value in `uuidValues`: id of an accounting integration: `GET /integrations/accountings`) - you pick the accounting integration. - **Has shipment** / **Has no shipment**. (API: "Has shipment" = `HAS_SHIPMENT`, "Has no shipment" = `HAS_SHIPMENT_NOT`; value in `booleanValues`: always `[true]`) - **Shipment status is** / **Shipment status is not** (API: "Shipment status is" = `SHIPMENT_STATUS_IS`, "Shipment status is not" = `SHIPMENT_STATUS_IS_NOT`; value in `enumValues`: `PENDING`, `SUCCESS`, `ERROR`) - one or several shipment statuses. - **Shipment belongs to integration** / **Shipment does not belong to integration** (API: "Shipment belongs to integration" = `SHIPMENT_SHIPPING_INTEGRATION_IS`, "Shipment does not belong to integration" = `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT`; value in `uuidValues`: id of a shipping integration: `GET /integrations/shippings`) - you pick the shipping integration. #### Buyer, note and favorites - **Buyer email contains** / **does not contain**, **Buyer name contains** / **does not contain**, **Buyer company contains** / **does not contain** (API: "Buyer email contains" = `BUYER_EMAIL_CONTAINS`, "does not contain" = `BUYER_EMAIL_NOT_CONTAINS`, "Buyer name contains" = `BUYER_NAME_CONTAINS`, "does not contain" = `BUYER_NAME_NOT_CONTAINS`, "Buyer company contains" = `BUYER_COMPANY_CONTAINS`, "does not contain" = `BUYER_COMPANY_NOT_CONTAINS`; value in `stringValues`: a list of words or text fragments; any of them is enough, letter case does not matter) - part of the text. - **No note** / **Has note** / **Note was removed**. (API: "No note" = `OWN_NOTE_IS_EMPTY`, "Has note" = `OWN_NOTE_IS_NOT_EMPTY`, "Note was removed" = `OWN_NOTE_CHANGED_TO_EMPTY`; value in `booleanValues`: always `[true]`) - **Own note contains keywords** / **Own note does not contain keywords**. (API: "Own note contains keywords" = `OWN_NOTE_CONTAINS_KEYWORDS`, "Own note does not contain keywords" = `OWN_NOTE_NOT_CONTAINS_KEYWORDS`; value in `stringValues`: a list of words or text fragments; any of them is enough, letter case does not matter) - **Order is a favorite** / **Order is not a favorite**, **Favorite status changed from** / **to**. (API: "Order is a favorite" = `FAVORITE_STATUS_IS`, "Order is not a favorite" = `FAVORITE_STATUS_IS_NOT`, "Favorite status changed from" = `FAVORITE_STATUS_CHANGED_FROM`, "to" = `FAVORITE_STATUS_CHANGED_TO`; value in `booleanValue`: `true` or `false`) #### Time - **Action run time from** / **to**, **Action run day is** / **is not**, **Action run date from** / **to** (API: "Action run time from" = `CURRENT_TIME_FROM`, "to" = `CURRENT_TIME_TO`; value in `offsetDateTimeValue`: a date-time with the offset of the action's zone; only the hour and minute count, for example `2026-01-10T16:00:00+00:00` | "Action run day is" = `CURRENT_DAY_OF_WEEK_IS`, "is not" = `CURRENT_DAY_OF_WEEK_IS_NOT`; value in `integerValues`: numbers 1-7, where 1 is Monday and 7 is Sunday | "Action run date from" = `CURRENT_DATE_FROM`, "to" = `CURRENT_DATE_TO`; value in `offsetDateTimeValue`: a date-time with an offset; the whole instant counts) - counted from the moment the action runs. - **Order time from** / **to**, **Order day is** / **is not**, **Order date from** / **to** (API: "Order time from" = `ORDER_TIME_FROM`, "to" = `ORDER_TIME_TO`; value in `offsetDateTimeValue`: a date-time with the offset of the action's zone; only the hour and minute count, for example `2026-01-10T16:00:00+00:00` | "Order day is" = `ORDER_DAY_OF_WEEK_IS`, "is not" = `ORDER_DAY_OF_WEEK_IS_NOT`; value in `integerValues`: numbers 1-7, where 1 is Monday and 7 is Sunday | "Order date from" = `ORDER_DATE_FROM`, "to" = `ORDER_DATE_TO`; value in `offsetDateTimeValue`: a date-time with an offset; the whole instant counts) - counted from the moment the order was placed. - **Order age greater than (days)** / **Order age less than (days)** (API: "Order age greater than (days)" = `ORDER_AGE_DAYS_GREATER_THAN`, "Order age less than (days)" = `ORDER_AGE_DAYS_LESS_THAN`; value in `integerValue`: a whole number) - how many days have passed since the order was placed. > **Good to know:** The "has" conditions are the simplest protection against duplicates: add **Has no invoice** to an action that issues an invoice and **Has no shipment** to an action that creates a shipment. ### Steps - what an action can do #### Statuses and flags - **Update order status**, **Update status** (custom). (API: "Update order status" = `UPDATE_STATUS`; value in `enumValue`: `CONFIRMED`, `CANCELLED`, `WAITING_FOR_PAYMENT`, `WAITING_FOR_CONFIRMATION` | "Update status" = `UPDATE_USER_DEFINED_STATUS`; value in `uuidValue`: ids of custom order statuses: `GET /orders/statuses`) - **Update own note**, **Update favorite status**. (API: "Update own note" = `UPDATE_OWN_NOTE`; value in `stringValue`: text up to 255 characters; `null` clears the note | "Update favorite status" = `UPDATE_FAVORITE_STATUS`; value in `booleanValue`: `true` or `false`) #### Documents - **Generate invoice**, **Generate receipt** (API: "Generate invoice" = `GENERATE_INVOICE`, "Generate receipt" = `GENERATE_RECEIPT`; value in `uuidValue`: id of a document settings template: `GET /orders/billing/settings`) - using the document settings template you pick. - **Delete invoice**, **Delete receipt**. (API: "Delete invoice" = `DELETE_INVOICE`, "Delete receipt" = `DELETE_RECEIPT`; value in `booleanValue`: always `true` - a confirmation) - **Send invoice to external accounting**, **Send receipt to external accounting** (API: "Send invoice to external accounting" = `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING`, "Send receipt to external accounting" = `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING`; value in `uuidValue`: id of an accounting integration: `GET /integrations/accountings`) - needs an accounting integration. - **Update company data with buyer data** (API: "Update company data with buyer data" = `USE_BUYER_AS_BILLING_RECIPIENT`; value in `booleanValue`: always `true` - a confirmation) - copies the buyer's data into the data on the document. Plan sending documents step by step - first issuing, then sending: - **Invoice** - the first action ends with the **Generate invoice** step. The second starts on the **Invoice (added/removed)** trigger, has the **Has invoice** condition and the **Send invoice to external accounting** step. - **Receipt** - the same: the first action ends with the **Generate receipt** step, and the second starts on the **Receipt (added/removed)** trigger, has the **Has receipt** condition and the **Send receipt to external accounting** step. - **Corrections** - you can issue many corrections to one invoice. Send each right after issuing it, before you issue the next one. > **Good to know:** The send step always sends just one document - the newest non-deleted one of that type. If you first issue all documents and only then turn on sending, only the last one goes out, and you send the others by hand. You cannot send a deleted document. #### Shipments and printing - **Create shipment** (API: "Create shipment" = `CREATE_SHIPMENT`; value in `uuidValue`: id of a shipping integration: `GET /integrations/shippings`) - needs a shipping integration. - **Print shipment label** (API: "Print shipment label" = `PRINT_SHIPMENT_LABEL`; value in `uuidValue`: id of a printer integration: `GET /integrations/printers`) - prints the label of the order's newest successful shipment, needs a printer integration. - **Print receipt** (API: "Print receipt" = `PRINT_RECEIPT`; value in `uuidValue`: id of a printer integration: `GET /integrations/printers`) - prints the order's newest receipt. Plan label printing step by step, as two actions: - **First action** - ends with the **Create shipment** step. - **Second action** - starts on the **Shipment created** trigger, has the **Shipment status is** condition with **Created successfully** and a single **Print shipment label** step. This way every new shipment prints its label right away - also when the order has several parcels. > **Good to know:** The **Print shipment label** step always prints just one label - that of the newest successful shipment. If you first create all shipments and only then turn on printing, only the last one is printed, and you print the others by hand with **Print**. If a new shipment fails, the step prints the label of the previous successful one. #### Order data - **Update buyer data**, **Update company data**, **Update delivery address**, **Update delivery method**, **Update pickup point**, **Update delivery time**, **Update basic delivery data**, **Update payment data**, **Update order date** (API: "Update buyer data" = `UPDATE_BUYER`; value in `buyerData`: an object with the data to set; `useEntityWhenNull: true` leaves the fields you do not send unchanged | "Update company data" = `UPDATE_COMPANY`; value in `companyData`: an object with the data to set; `useEntityWhenNull: true` leaves the fields you do not send unchanged | "Update delivery address" = `UPDATE_DELIVERY_ADDRESS`; value in `deliveryAddressData`: an object with the data to set; `useEntityWhenNull: true` leaves the fields you do not send unchanged | "Update delivery method" = `UPDATE_DELIVERY_METHOD`; value in `deliveryMethodData`: an object with the data to set; `useEntityWhenNull: true` leaves the fields you do not send unchanged | "Update pickup point" = `UPDATE_DELIVERY_PICKUP_POINT`; value in `deliveryPickupPointData`: an object with the data to set; `useEntityWhenNull: true` leaves the fields you do not send unchanged | "Update delivery time" = `UPDATE_DELIVERY_TIME`; value in `deliveryTimeData`: an object with the data to set; `useEntityWhenNull: true` leaves the fields you do not send unchanged | "Update basic delivery data" = `UPDATE_DELIVERY_BASIC`; value in `deliveryBasicData`: an object with the data to set; `useEntityWhenNull: true` leaves the fields you do not send unchanged | "Update payment data" = `UPDATE_PAYMENT`; value in `paymentData`: an object with the data to set; `useEntityWhenNull: true` leaves the fields you do not send unchanged | "Update order date" = `UPDATE_ORDER_DATE`; value in `offsetDateTimeValue`: a date-time with an offset; the whole instant counts) - set the given data in the order. The **Fill empty fields with the order's current data** option leaves the fields you do not fill in unchanged. - **Delete order**, **Restore order**. (API: "Delete order" = `DELETE_ORDER`, "Restore order" = `RESTORE_ORDER`; value in `booleanValue`: always `true` - a confirmation) Steps that delete something require an explicit confirmation when you create the action. ### Steps that wait for an external system Some steps do not finish right away, because the answer has to come from outside: - **Send invoice to external accounting** / **Send receipt to external accounting** - some systems accept the document and confirm it only after a while. Until then the transfer is "in progress". - **Create shipment** - the carrier accepts the request and returns the tracking number and the label after a while. Until there is a final result, the action **waits**: it does not move to the next step and does not start other actions. It continues only when the external system answers - with **success** or an **error**. The same thing happens in both cases: - **Next step** - the action moves to the next step, after an error too. An error does not stop the action, so that you can react to it, for example set a custom status "Shipment problem". - **Other actions** - if it was the action's last step, actions with the **Shipment created** or **Invoice sent to external accounting** trigger can start. They also start after both a success and an error. - **Audit** - you will see the result, and for an error also its reason, in the orders audit. > **Good to know:** You do not need to add your own "wait until it is ready" conditions - the next step starts only after the answer anyway. What happens after an error is your decision. If the next step should run only after a success, add a [branch](https://ritevo.com/en/docs/automations/how-it-works#branches) to it with the **Shipment status is** Created successfully condition, or **Has a successful invoice transfer to external accounting** / **Has a successful receipt transfer to external accounting**, and do not set a default action. After an error the action then stops on that step. These conditions look at every shipment and transfer of the order, earlier ones too. ### Examples #### A shipment for confirmed orders from a chosen integration - Trigger: **Order**. - Conditions: **Integration is** the chosen sales integration, **Order status is** Confirmed. - Steps: **Create shipment** with the chosen shipping integration, then **Update status** to a custom status, for example "To pack". ![The action form: the Order trigger, the Integration is and Order status is conditions, the Create shipment and Update status steps](https://ritevo.com/docs/automations/en-order-action-shipment.webp) > **Good to know:** The second step runs once the carrier answers - also when the shipment ends with an error. If the status should change only after a successful shipment, add a branch to the second step with the **Shipment status is** Created successfully condition and no default action. If the same action could reach an order more than once, add the **Has no shipment** condition. #### Invoice and shipment after payment - Trigger: **Payment data changed**. - Conditions: **Payment status is** Paid, **Has no invoice**, **Has no shipment**. - Steps: **Generate invoice**, then **Create shipment**, then **Print shipment label**. #### Flagging international orders - Trigger: **Order status changed**. - Conditions: **Order status changed to** Confirmed, **Delivery country is not** your home country. - Step: **Update status** to a custom status, for example "International". #### One action, different carriers - Trigger: **Order status changed**, condition **Order status changed to** Confirmed. - Step **Create shipment** with branches: the first variant with the condition **Delivery country is not** your home country and an international carrier integration, the default action with the domestic one. ### What an order action will not do - It will not send a message or an email to the customer and will not use AI. Only [message actions](https://ritevo.com/en/docs/automations/message-actions) have those steps. - It will not run with a delay or at a set time. The **Order age greater than (days)** condition is checked only when something changes in the order - the passing of time alone starts nothing. - It will not issue a document or create a shipment without the settings those operations also need when done by hand (a document template, a shipping integration). ### Run audit Runs of order actions are in **Settings → Audit → Orders**. Every entry shows the action, the step number, the result and an error, if any. What the results mean is explained in [How automatic actions work](https://ritevo.com/en/docs/automations/how-it-works#history). ### Example of saving through the API The "Invoice and shipment after payment" action from the Examples section. The general rules of saving are on the [How automatic actions work](https://ritevo.com/en/docs/automations/how-it-works) page. ```json { "name": "Invoice and shipment after payment", "description": "Issues an invoice, creates a shipment and prints the label once the order is paid", "active": true, "userTimezone": "Europe/Warsaw", "triggerType": "PAYMENT_DATA_CHANGED", "conditions": [ { "type": "PAYMENT_STATUS_IS", "enumValues": [ "PAID" ] }, { "type": "HAS_INVOICE_NOT", "booleanValues": [ true ] }, { "type": "HAS_SHIPMENT_NOT", "booleanValues": [ true ] } ], "actionSteps": [ { "stepOrder": 1, "action": { "type": "GENERATE_INVOICE", "uuidValue": "" } }, { "stepOrder": 2, "action": { "type": "CREATE_SHIPMENT", "uuidValue": "" } }, { "stepOrder": 3, "action": { "type": "PRINT_SHIPMENT_LABEL", "uuidValue": "" } } ] } ``` --- Source: https://ritevo.com/en/docs/automations/message-actions (updated 2026-09-26) ## Automatic actions for messages Autoresponder and automatic message actions in Ritevo: triggers, time conditions, template and AI replies, loop protection. A message action reacts to what happens in your inbox: a new thread, a new message, a status change. Most often it replies to the customer - with fixed text, a template filled with the thread's data or a reply written by AI - assigns the thread to a specific user, sets your own custom status, marks the thread as read or favorite, adds a note and much more. The general rules are covered in [How automatic actions work](https://ritevo.com/en/docs/automations/how-it-works). > **Required integration:** You need an integration with [message fetching](https://ritevo.com/en/docs/messages/fetching-messages) turned on. The **Send AI message to thread** step also needs an AI integration (OpenAI or Claude), and **Send template message to thread** needs a saved message template. > **Good to know:** Add the **Message received from customer** condition to every action that replies to a customer. Without it the action also reacts to its own replies and can loop - explained below. ### Where to find actions Message actions are in the **Messages → Actions** menu (in the left panel). For every action the list shows its trigger, conditions and steps, and whether it is active. You add a new action with the **Add new action** button in the top right corner. The breadcrumbs at the top of the page (**Dashboard → Messages → Actions**) always show where you are. ![The list of automatic message actions with the Actions item highlighted in the left panel; the Add new action button in the top right corner is framed](https://ritevo.com/docs/automations/en-message-actions-list.webp) The action form looks the same as for orders: basic settings at the top (name, description, trigger, time zone, **Active**), conditions on the left, steps on the right. ![An empty new-action form for messages: basic settings, a condition card and a step card](https://ritevo.com/docs/automations/en-message-action-form-empty.webp) ### Triggers - **New thread** (API: "New thread" = `NEW_THREAD`) - a thread that was not in Ritevo before appeared. Usually this is the customer's first message about a matter. - **Reply in thread** (API: "Reply in thread" = `MESSAGE_RESPONSE`) - a new message appeared in an existing thread. **No matter who wrote it** - the customer or you. - **Template reply in thread** (API: "Template reply in thread" = `TEMPLATE_MESSAGE_RESPONSE`) - an automatic action sent a template reply. - **AI reply in thread** (API: "AI reply in thread" = `AI_MESSAGE_RESPONSE`) - an automatic action sent an AI reply. - **Status changed** (API: "Status changed" = `USER_DEFINED_STATUS_CHANGED`) - your own custom thread status changed. - **Assigned user changed**, **Read status changed**, **Favorite status changed**, **Own note changed**. (API: "Assigned user changed" = `ASSIGNED_USER_CHANGED`, "Read status changed" = `READ_STATUS_CHANGED`, "Favorite status changed" = `FAVORITE_STATUS_CHANGED`, "Own note changed" = `OWN_NOTE_CHANGED`) The customer's first message fires **New thread**, and every later one in the same conversation fires **Reply in thread**. A thread can be old: a customer who bought from you a year ago often writes in the same conversation, and then it is **Reply in thread**, not **New thread**. So always build an autoresponder as a **pair of actions** - one with the **New thread** trigger and one with the **Reply in thread** trigger, with the same conditions and steps. ### Why the "from customer" condition is necessary Messages you send - by hand or through an action - come back to Ritevo on the next fetch from the channel and are also "a new message in the thread". The **Reply in thread** trigger does not tell direction. Only conditions do: - **Message received from customer** (API: "Message received from customer" = `MESSAGE_FROM_INTERLOCUTOR`; value in `booleanValues`: always `[true]`) - the last message in the thread is from the customer. - **Message sent to customer** (API: "Message sent to customer" = `MESSAGE_FROM_SELF`; value in `booleanValues`: always `[true]`) - the last message is from you. An action without the **Message received from customer** condition **can loop**. Its own reply comes back on the next message fetch as a new message in the thread, the action replies to it again - and so on at every fetch, without end. The safety switch described on the general page will not stop this, because several minutes pass between the replies and it reacts to many runs in a short time. The customer would keep getting the same reply until you turn the action off. This one condition solves the problem at the source, so always add it. ### Conditions #### Who wrote and where from - **Message received from customer** / **Message sent to customer**. (API: "Message received from customer" = `MESSAGE_FROM_INTERLOCUTOR`, "Message sent to customer" = `MESSAGE_FROM_SELF`; value in `booleanValues`: always `[true]`) - **Integration is** / **Integration is not** (API: "Integration is" = `INTEGRATION_IS`, "Integration is not" = `INTEGRATION_IS_NOT`; value in `uuidValues`: ids of integrations with messages: `GET /integrations/marketplaces`, `GET /integrations/shops`, `GET /integrations/email`, `GET /integrations/messaging`) - which channel the thread comes from. You pick from the list of your integrations - one or several. With several, any of them is enough. - **Conversation type is** / **Conversation type is not** (API: "Conversation type is" = `THREAD_TYPE_IS`, "Conversation type is not" = `THREAD_TYPE_IS_NOT`; value in `enumValues`: `MESSAGE`, `DISCUSSION`, `CLAIM`) - Message, Dispute or Claim; one or several. - **Conversation status is** / **Conversation status is not** (API: "Conversation status is" = `THREAD_STATUS_IS`, "Conversation status is not" = `THREAD_STATUS_IS_NOT`; value in `enumValues`: `DISPUTE_ONGOING`, `DISPUTE_CLOSED`, `DISPUTE_UNRESOLVED`, `CLAIM_SUBMITTED`, `CLAIM_ACCEPTED`, `CLAIM_REJECTED`) - the state of the dispute or claim in the sales channel. #### Content - **Message contains keywords** / **Message does not contain keywords** (API: "Message contains keywords" = `MESSAGE_CONTAINS_KEYWORDS`, "Message does not contain keywords" = `MESSAGE_NOT_CONTAINS_KEYWORDS`; value in `stringValues`: a list of words or text fragments; any of them is enough, letter case does not matter) - the **last** message in the thread is checked. One of the given words is enough, letter case does not matter. - **Topic contains keywords** / **Topic does not contain keywords**, **Own note contains keywords** / **Own note does not contain keywords** (API: "Topic contains keywords" = `TOPIC_CONTAINS_KEYWORDS`, "Topic does not contain keywords" = `TOPIC_NOT_CONTAINS_KEYWORDS`, "Own note contains keywords" = `OWN_NOTE_CONTAINS_KEYWORDS`, "Own note does not contain keywords" = `OWN_NOTE_NOT_CONTAINS_KEYWORDS`; value in `stringValues`: a list of words or text fragments; any of them is enough, letter case does not matter) - work the same way. #### Time of day, day and date - **Action run time from** / **to** (API: "Action run time from" = `CURRENT_TIME_FROM`, "to" = `CURRENT_TIME_TO`; value in `offsetDateTimeValue`: a date-time with the offset of the action's zone; only the hour and minute count, for example `2026-01-10T16:00:00+00:00`) - what time it is at the moment the action runs. - **Message time from** / **to** (API: "Message time from" = `MESSAGE_TIME_FROM`, "to" = `MESSAGE_TIME_TO`; value in `offsetDateTimeValue`: a date-time with the offset of the action's zone; only the hour and minute count, for example `2026-01-10T16:00:00+00:00`) - what time the last message came in. - **Action run day is** / **is not**, **Message day is** / **is not** (API: "Action run day is" = `CURRENT_DAY_OF_WEEK_IS`, "is not" = `CURRENT_DAY_OF_WEEK_IS_NOT`, "Message day is" = `MESSAGE_DAY_OF_WEEK_IS`, "is not" = `MESSAGE_DAY_OF_WEEK_IS_NOT`; value in `integerValues`: numbers 1-7, where 1 is Monday and 7 is Sunday) - days of the week. - **Action run date from** / **to**, **Message date from** / **to** (API: "Action run date from" = `CURRENT_DATE_FROM`, "to" = `CURRENT_DATE_TO`, "Message date from" = `MESSAGE_DATE_FROM`, "to" = `MESSAGE_DATE_TO`; value in `offsetDateTimeValue`: a date-time with an offset; the whole instant counts) - for a holiday period, for example. > **Good to know:** Times are counted in the time zone set in the action. A range is two conditions (**from** and **to**), and the boundaries are included. A range across midnight needs two actions - [why](https://ritevo.com/en/docs/automations/how-it-works#conditions). #### Thread state - **Status is** / **Status is not** (API: "Status is" = `USER_DEFINED_STATUS_IS`, "Status is not" = `USER_DEFINED_STATUS_IS_NOT`; value in `uuidValues`: ids of custom thread statuses: `GET /messages/statuses`) - your own custom statuses, one or several. - **Assigned user is** / **is not** (API: "Assigned user is" = `ASSIGNED_USER_IS`, "is not" = `ASSIGNED_USER_IS_NOT`; value in `uuidValues`: ids of company users: `GET /company/users`) - one or several users. - **Conversation is read** / **Conversation is not read**, **Conversation is a favorite** / **Conversation is not a favorite**. (API: "Conversation is read" = `READ_STATUS_IS`, "Conversation is not read" = `READ_STATUS_IS_NOT`, "Conversation is a favorite" = `FAVORITE_STATUS_IS`, "Conversation is not a favorite" = `FAVORITE_STATUS_IS_NOT`; value in `booleanValues`: a list with one value: `[true]` or `[false]`) - **No note** / **Has note** / **Note was removed**. (API: "No note" = `OWN_NOTE_IS_EMPTY`, "Has note" = `OWN_NOTE_IS_NOT_EMPTY`, "Note was removed" = `OWN_NOTE_CHANGED_TO_EMPTY`; value in `booleanValues`: always `[true]`) - **Read status changed from** / **to**, **Favorite status changed from** / **to** (API: "Read status changed from" = `READ_STATUS_CHANGED_FROM`, "to" = `READ_STATUS_CHANGED_TO`, "Favorite status changed from" = `FAVORITE_STATUS_CHANGED_FROM`, "to" = `FAVORITE_STATUS_CHANGED_TO`; value in `booleanValues`: a list with one value: `[true]` or `[false]`) - they react to the change itself. ### Steps - what an action can do #### Replying to the customer - **Send message to thread** (API: "Send message to thread" = `SEND_MESSAGE_TO_THREAD`; value in `stringValue`: text up to 2000 characters) - fixed text, up to 2000 characters. Sent literally, without inserted values. - **Send template message to thread** (API: "Send template message to thread" = `TEMPLATE_SEND_MESSAGE_TO_THREAD`; value in `uuidValue`: id of a message template: `GET /messages/templates`) - content from a saved template. Inserted values work only in a template: **Other party**, **Thread topic**, **Thread status**, **Order number**, **Order ID (external)**, **Offer ID (external)**. In the template editor you click the value you want, and when the message is sent the thread's data is filled in. If the thread does not have a given value (for example a topic or an offer ID), it is inserted as empty. - **Send AI message to thread** (API: "Send AI message to thread" = `AI_SEND_MESSAGE_TO_THREAD`; value in `uuidValue`: id of an AI integration: `GET /integrations/ai`) - the chosen AI integration writes the reply and Ritevo **sends it to the customer right away**. #### How the AI reply works - AI receives **the text of the customer's last message** and the instructions you entered in the AI integration settings. It does not receive the earlier thread history or order data. - Everything AI should know about your business - working hours, return policy, tone of voice - goes into the AI integration's instructions. - There is no draft mode. The reply goes to the customer without your approval, so start with narrow conditions, for example keywords or a single channel. - If AI returns an error, nothing is sent and you will see the error in the messages audit. The cost of replies is billed by your account with the AI provider. #### Tidying the thread - **Assign user** (API: "Assign user" = `UPDATE_ASSIGNED_USER`; value in `uuidValue`: a user id from `GET /company/users`; `null` removes the assignment) - also removing the assignment. - **Update status** (custom), **Update read status**, **Update favorite status**, **Update own note**. (API: "Update status" = `UPDATE_USER_DEFINED_STATUS`; value in `uuidValue`: ids of custom thread statuses: `GET /messages/statuses` | "Update read status" = `UPDATE_READ_STATUS`, "Update favorite status" = `UPDATE_FAVORITE_STATUS`; value in `booleanValue`: `true` or `false` | "Update own note" = `UPDATE_OWN_NOTE`; value in `stringValue`: text up to 255 characters; `null` clears the note) ### Example: an out-of-hours autoresponder You work Monday to Friday, 8:00-16:00. A customer who writes outside those hours should be told when you will reply. > **Good to know:** You create every action below **twice**: once with the **New thread** trigger and once with the **Reply in thread** trigger. The conditions and the step are the same in both. Without the second version the autoresponder skips customers who write in a conversation that already exists in Ritevo - even if the previous message was a year ago. #### Action 1 - weekend - Conditions: **Message received from customer**, **Action run day is** Saturday, Sunday. - Step: **Send template message to thread** with text like "Thank you for your message. We will reply on the next working day." #### Action 2 - working days after 16:00 - Conditions: **Message received from customer**, **Action run day is not** Saturday, Sunday, **Action run time from** 16:00. - Step: the same as in action 1. #### Action 3 - working days before 8:00 - Conditions: **Message received from customer**, **Action run day is not** Saturday, Sunday, **Action run time to** 08:00. - Step: the same as in action 1. In total you create six actions: action 1, 2 and 3, each in two versions - with the **New thread** trigger and with the **Reply in thread** trigger. Actions 2 and 3 are separate because the 16:00-08:00 range crosses midnight. The day-of-week condition in actions 2 and 3 makes sure the customer does not get two replies at the weekend. ### Example: an AI reply with an assigned employee A pair of actions from the app: AI replies to every customer message and the thread goes to a chosen employee. Both actions have the same conditions and steps and differ only in the trigger. #### Action 1 - the New thread trigger - Trigger: **New thread**. - Condition: **Message received from customer**. - Steps: **Send AI message to thread** with the chosen AI integration, then **Assign user** to the chosen person. ![The action form: the New thread trigger, the Message received from customer condition, the Send AI message to thread and Assign user steps](https://ritevo.com/docs/automations/en-message-action-new-thread.webp) #### Action 2 - the Reply in thread trigger - The same, only with the **Reply in thread** trigger - so AI also replies to the customer's later messages in the same conversation. ![The same action with the Reply in thread trigger](https://ritevo.com/docs/automations/en-message-action-reply.webp) > **Good to know:** The **Message received from customer** condition is essential here: without it action 2 would reply to AI's own replies. An AI reply goes to the customer right away, so start with a single channel (the **Integration is** condition) and check the results in the audit. ### In which channels the reply works The action sends the reply the same way you reply by hand. If a channel does not allow a manual reply, the action will not reply there either. On a given integration's page you can check whether it lets you reply to messages, disputes and claims. ### What a message action will not do - It will not send an attachment. - It will not insert values from the thread into plain text - only into a template. - It will not close a dispute or claim or change their state in the sales channel. - It will not reply with a delay or "if nobody answered within an hour". - There is no "once per thread" limit and no pause between replies - you set the scope with the trigger and conditions. ### Run audit Runs are in **Settings → Audit → Messages**. What the results mean is explained in [How automatic actions work](https://ritevo.com/en/docs/automations/how-it-works#history). ### Example of saving through the API Action 2 from the autoresponder example (working days after 16:00) in the version with the **New thread** trigger. You create the second version the same way, changing `triggerType` to `MESSAGE_RESPONSE`. The general rules of saving are on the [How automatic actions work](https://ritevo.com/en/docs/automations/how-it-works) page. ```json { "name": "Autoresponder - working days after 16:00 (new thread)", "description": "Tells the customer when we will reply", "active": true, "userTimezone": "Europe/Warsaw", "triggerType": "NEW_THREAD", "conditions": [ { "type": "MESSAGE_FROM_INTERLOCUTOR", "booleanValues": [ true ] }, { "type": "CURRENT_DAY_OF_WEEK_IS_NOT", "integerValues": [ 6, 7 ] }, { "type": "CURRENT_TIME_FROM", "offsetDateTimeValue": "2026-01-10T16:00:00+01:00" } ], "actionSteps": [ { "stepOrder": 1, "action": { "type": "TEMPLATE_SEND_MESSAGE_TO_THREAD", "uuidValue": "" } } ] } ``` --- Source: https://ritevo.com/en/docs/general/errors (updated 2026-09-27) ## Errors in the app Error messages in Ritevo: what each error means for orders, documents, shipments, the warehouse, messages and integrations, and what to do. When an operation fails, Ritevo shows a short message. Below are all messages grouped by area, with an explanation of what they mean. #### Data and requests - **Validation error** (API: "Validation error" = `VALIDATION_ERROR`) - the data sent is incomplete or in the wrong format, for example an empty required field or a text that is too long. Correct the marked fields and save again. - **Invalid request** (API: "Invalid request" = `INVALID_REQUEST`) - the request cannot be read, for example its body is malformed. - **Invalid value** (API: "Invalid value" = `INVALID_ENUM`) - the chosen value is not on the allowed list. - **Unsupported data format** (API: "Unsupported data format" = `UNSUPPORTED_MEDIA_TYPE`) - the data came in a format Ritevo does not accept. - **Invalid parameter** (API: "Invalid parameter" = `INVALID_PARAMETER`) - a request parameter has a wrong value, for example an id in the wrong format. - **Missing parameter** (API: "Missing parameter" = `MISSING_PARAMETER`) - a required parameter is missing from the request. - **Internal error** (API: "Internal error" = `INTERNAL_ERROR`) - an error on Ritevo's side. Try again in a moment; if it keeps happening, contact us. #### Limits - **Limit exceeded** (API: "Limit exceeded" = `LIMIT_EXCEPTION`) - a limit was reached, for example the number of integrations, actions or items in one operation. #### Audit - **Audit log not found** (API: "Audit log not found" = `AUDIT_LOG_NOT_FOUND`) - the change history entry does not exist or belongs to another company. #### Automatic actions - **Action step validation error** (API: "Action step validation error" = `ACTION_STEP_VALIDATION`) - an action step is incomplete or has invalid settings. - **Automatic action not found** (API: "Automatic action not found" = `AUTOMATIC_ACTION_NOT_FOUND`) - the action does not exist or was deleted. - **Condition validation error** (API: "Condition validation error" = `CONDITION_VALIDATION`) - an action condition is incomplete or has an invalid value. - **Cyclic dependency detected** (API: "Cyclic dependency detected" = `CYCLIC_DEPENDENCY`) - saving the action would create a loop - actions would keep triggering each other. Change the trigger or the steps. #### Integrations - **Integration not found** (API: "Integration not found" = `INTEGRATION_NOT_FOUND`) - the integration does not exist, was deleted or belongs to another company. - **AI integration not found** (API: "AI integration not found" = `AI_INTEGRATION_NOT_FOUND`) - the chosen AI integration does not exist or was deleted. - **Invalid model** (API: "Invalid model" = `INVALID_MODEL`) - the chosen AI model is not available with this provider or on your account. - **Invalid token** (API: "Invalid token" = `INVALID_TOKEN`) - the AI provider rejected the API key. Check the key in the provider's panel. #### Documents - **Billing document already exists** (API: "Billing document already exists" = `BILLING_ALREADY_EXISTS`) - this order already has such a document. - **Document already transferred** (API: "Document already transferred" = `BILLING_ALREADY_TRANSFERRED`) - the document was already sent to the accounting integration and cannot be changed. - **External transfer not found** (API: "External transfer not found" = `BILLING_EXTERNAL_TRANSFER_NOT_FOUND`) - there is no record of sending this document to the accounting integration. - **Document already has a correction** (API: "Document already has a correction" = `BILLING_HAS_CORRECTION`) - a correction has already been issued for this document. - **Document has no correction** (API: "Document has no correction" = `BILLING_HAS_NO_CORRECTION`) - the operation needs a correction, but the document has none. - **Document line item not found** (API: "Document line item not found" = `BILLING_LINE_ITEM_NOT_FOUND`) - the given line item does not exist in the document. - **Billing document not found** (API: "Billing document not found" = `BILLING_NOT_FOUND`) - the document does not exist or belongs to another company. - **Billing documents not found** (API: "Billing documents not found" = `BILLINGS_NOT_FOUND`) - none of the chosen documents was found. - **Settings for the billing type not found** (API: "Settings for the billing type not found" = `BILLING_SETTINGS_BY_BILLING_TYPE_NOT_FOUND`) - settings for this document type are missing, for example the numbering for receipts. - **Billing settings not found** (API: "Billing settings not found" = `BILLING_SETTINGS_NOT_FOUND`) - the given document settings do not exist. - **Billing settings reference error** (API: "Billing settings reference error" = `BILLING_SETTINGS_REFERENCE`) - these settings cannot be deleted because documents have already been issued with them. - **Default settings cannot be deleted** (API: "Default settings cannot be deleted" = `DEFAULT_BILLING_SETTINGS_DELETION`) - the default document settings cannot be deleted. - **This document is not supported by this integration** (API: "This document is not supported by this integration" = `BILLING_TYPE_NOT_SUPPORTED`) - the chosen integration does not issue this document type, for example a correction or a receipt. - **Tax rate not supported** (API: "Tax rate not supported" = `TAX_RATE_NOT_SUPPORTED`) - the integration does not support the VAT rate of this line item. #### Orders - **Orders not found** (API: "Orders not found" = `ORDERS_NOT_FOUND`) - none of the chosen orders was found. - **Order not found** (API: "Order not found" = `ORDER_NOT_FOUND`) - the order does not exist or belongs to another company. - **Order line item not found** (API: "Order line item not found" = `ORDER_LINE_ITEM_NOT_FOUND`) - the given line item does not exist in the order. - **The order is not compatible with the chosen integration or shipping method** (API: "The order is not compatible with the chosen integration or shipping method" = `ORDER_AND_SHIPPING_COMPATIBILITY`) - the shipment cannot be created with this integration, for example an order from a different Allegro account than the one connected to Send with Allegro. #### Shipments and parcels - **Shipment not found** (API: "Shipment not found" = `SHIPMENT_NOT_FOUND`) - the shipment does not exist or belongs to another order. - **Parcel quantity exceeds the order quantity** (API: "Parcel quantity exceeds the order quantity" = `PACKAGE_QUANTITY_EXCEEDED`) - more items were added to the parcel than the order contains. - **Label does not match any of the order's shipments** (API: "Label does not match any of the order's shipments" = `PACKAGE_LABEL_NOT_FOUND`) - the scanned label does not belong to this order's shipments. - **Label already used in another parcel** (API: "Label already used in another parcel" = `PACKAGE_LABEL_ALREADY_USED`) - this label is already assigned to another parcel. #### Products and warehouse - **Product not found** (API: "Product not found" = `PRODUCT_NOT_FOUND`) - the product does not exist or belongs to another company. - **A product with this SKU already exists** (API: "A product with this SKU already exists" = `PRODUCT_SKU_ALREADY_EXISTS`) - the warehouse already has a product with the same SKU. - **Stock not found** (API: "Stock not found" = `STOCK_NOT_FOUND`) - there is no stock recorded for the product. - **Stock does not match the product** (API: "Stock does not match the product" = `STOCK_PRODUCT_MISMATCH`) - the given stock belongs to another product. - **Price not found** (API: "Price not found" = `PRICE_NOT_FOUND`) - there is no price recorded for the product. - **Price already exists** (API: "Price already exists" = `PRICE_ALREADY_EXISTS`) - the product already has the price you are trying to add. - **The line item has no offer id** (API: "The line item has no offer id" = `EXTERNAL_OFFER_ID_REQUIRED`) - the order line item cannot be linked to a product, because the sales channel did not pass the offer number. - **The offer is already linked to another product** (API: "The offer is already linked to another product" = `EXTERNAL_OFFER_ALREADY_ASSIGNED`) - this offer is already assigned to another product in the warehouse. #### Statuses - **Status not found** (API: "Status not found" = `STATUS_NOT_FOUND`) - the status does not exist or was deleted. - **Status operation error** (API: "Status operation error" = `STATUS_OPERATION`) - this operation cannot be done, for example deleting the default status or replacing a status with itself. #### Messages - **Message not found** (API: "Message not found" = `MESSAGE_NOT_FOUND`) - the thread does not exist or belongs to another company. - **Messages not found** (API: "Messages not found" = `MESSAGES_NOT_FOUND`) - none of the chosen threads was found. - **Message operation error** (API: "Message operation error" = `MESSAGE_OPERATION`) - this operation cannot be done for this thread type, for example finishing a claim in an ordinary message. - **Message template not found** (API: "Message template not found" = `MESSAGE_TEMPLATE_NOT_FOUND`) - the template does not exist or was deleted. - **The integration does not support messages** (API: "The integration does not support messages" = `MESSAGES_NOT_SUPPORTED`) - this channel has no messages. - **Messages of this integration are handled by e-mail** (API: "Messages of this integration are handled by e-mail" = `MESSAGES_SUPPORTED_BY_EMAIL`) - buyers write by e-mail - you handle them through the e-mail integration. - **This integration does not support replying** (API: "This integration does not support replying" = `MESSAGE_REPLY_NOT_SUPPORTED`) - you cannot reply from Ritevo in this channel or thread type. - **This integration does not support attachments** (API: "This integration does not support attachments" = `MESSAGE_ATTACHMENT_UPLOAD_NOT_SUPPORTED`) - this channel does not accept attachments in replies. - **This integration does not support downloading attachments** (API: "This integration does not support downloading attachments" = `MESSAGE_ATTACHMENT_DOWNLOAD_NOT_SUPPORTED`) - you can open the file only in the sales channel's panel. - **The message is too long** (API: "The message is too long" = `MESSAGE_LENGTH_EXCEEDED`) - the reply exceeds 2000 characters. #### Other - **External provider error** (API: "External provider error" = `EXTERNAL_EXCEPTION`) - the sales channel, courier or another provider rejected the operation. The provider's error text is shown in the message. - **Unexpected error** (API: "Unexpected error" = `UNEXPECTED`) - something went wrong on Ritevo's side. Try again; if it keeps happening, contact us. ### Errors in the API API errors use the Problem Details format (RFC 9457) and return three fields: - `code` - one of the error codes described above. - `title` - a short title of the error. - `detail` - usually a detailed description of what went wrong in the given request. --- Source: https://ritevo.com/en/docs/integrations/allegro (updated 2026-10-10) ## Allegro Allegro integration with Ritevo: connecting the account by signing in, fetching orders and messages, invoices, disputes and claims, reconnecting. The Allegro integration brings orders as well as messages, disputes and claims from your seller account into Ritevo. You connect it by signing in to Allegro as usual - no keys or passwords typed into Ritevo. > **Required integration:** You need an active Allegro seller account. One Allegro account is connected once; if you sell from several accounts, add each one as a separate integration. The same Allegro account can be connected only once. When you connect it again, Ritevo refreshes the existing integration and turns it back on, even if it was deleted. Uniqueness: the integration is unique within the company by `externalId` and the type `ALLEGRO`. Creating it again refreshes the existing integration instead of adding a new one: it sets `authError=false` right away, and `active=true` if the integration was inactive. With `authError` this is the only way to restore the connection. ### Connecting the account It takes a minute. Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Marketplace** section pick the **Allegro** tile. 3. Click **Add integration**. Ritevo redirects you to the Allegro sign-in page. 4. Sign in to your seller account and approve access for Ritevo. Allegro sends you back to Ritevo. 5. Back in Ritevo, wait a moment - do not close the window. Once the integration has been added, its settings open. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Allegro tile framed in the Marketplace section](https://ritevo.com/docs/integrations/allegro/en-catalogue.webp) ![The Allegro add-integration screen with the Add integration button](https://ritevo.com/docs/integrations/allegro/en-add.webp) ![The Allegro sign-in page Ritevo redirects to](https://ritevo.com/docs/integrations/allegro/en-login.webp) > **Good to know:** Ritevo never sees your Allegro password. You sign in on Allegro's page, and Ritevo receives from Allegro only a permission to access the account. You can revoke it at any time in your Allegro account settings - the integration then stops working and shows **Reconnection required**. ### Integration settings After connecting, the integration is **Active**, but order and message fetching are **off** - you turn them on yourself, separately: - **Account name** - the login of your Allegro account. Ritevo takes it from Allegro; it cannot be changed. - **Fetch orders** - once on, Ritevo checks for new and changed orders about every 10 minutes. The rules shared by all channels: [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders). - **Fetch messages** - once on, Ritevo fetches messages about every 10 minutes, reaching 7 days back on the first fetch. Shared rules: [Fetching messages](https://ritevo.com/en/docs/messages/fetching-messages). ![Allegro integration details: the account name and the Fetch orders and Fetch messages switches](https://ritevo.com/docs/integrations/allegro/en-details.webp) ### What this integration gives you - **Orders** - new and updated Allegro orders land in the orders table, with the buyer's details, invoice details, delivery (including the pickup point) and line items with offer images. - **Messages** - conversations from the Message Center as well as **disputes** and **claims** land in the shared inbox. You reply to all three from Ritevo, attachments included. - **Creating shipments** through Send with Allegro is a separate integration you add after connecting the account - it uses the same Allegro account. ### Orders from Allegro Ritevo fetches the whole Allegro order: the buyer, payment, delivery together with the pickup point, line items with prices and offer images, and the buyer's message. Allegro provides all of this through its API, so nothing has to be filled in by hand. - **Statuses and payments** - Allegro statuses and payment methods are translated to Ritevo statuses in one fixed way; marketplaces have no mappings of their own, unlike online stores. A cash-on-delivery order arrives as **Awaiting payment** with the **Cash on delivery** method. - **Additional services** - supported. When the buyer adds, for example, gift wrapping or carry-in to a product, you see it in the order as a separate line item under that product - also when it is free. More about [additional services](https://ritevo.com/en/docs/orders/fetching-orders#additional-services). - **Invoice** - Allegro states explicitly whether the buyer asked for an invoice. Such an order gets the **Customer asks for an invoice** flag with the company details and tax id filled in. > **Good to know:** An order with the **Confirmed** status is taken over by Ritevo - later changes on the sales channel's side are skipped. More in [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders#who-manages). ### Messages, disputes and claims from Allegro - **Messages** from the Message Center - only messages Allegro has already delivered reach Ritevo. Allegro checks your reply first, so confirming it was sent can take up to half a minute. - **Disputes** and **claims** - with the subject, description, decision deadline, the buyer's demand (repair, exchange, refund, partial refund) and the linked order. You reply to them from Ritevo; you can also end a dispute and resolve a claim - accept it or reject it with a reason. - If a message concerns an order that is not in Ritevo yet, we fetch it on our own - even with order fetching turned off. ### Reconnection required This state appears when the permission granted to Ritevo in Allegro has expired or was revoked - for example after a password change in Allegro or after disconnecting the app in the account settings. Until you reconnect, Ritevo neither fetches nor sends any data on that account. 1. Go through **Connecting the account** again, signing in to the **same** Allegro account. 2. Ritevo recognises the account by its identifier and refreshes the connection in the existing integration. The fetching settings and the history stay unchanged - no second integration is created. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not manage listings: it does not list, change prices or stock in Allegro. ### The integration through the API This integration's endpoints are under `/integrations/marketplaces/allegro`, and the ones shared by the whole type (list, get one, fetching switches, delete, restore) under `/integrations/marketplaces`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/ebay (updated 2026-10-10) ## eBay eBay integration with Ritevo: connecting the account by signing in to eBay, fetching orders and messages, what eBay provides through its API, reconnecting. The eBay integration brings orders and buyer messages from your seller account into Ritevo. You connect it by signing in to eBay as usual - no keys or passwords typed into Ritevo. > **Required integration:** You need an active eBay seller account. One eBay account is connected once; if you sell from several accounts, add each one as a separate integration. The same eBay account can be connected only once. When you connect it again, Ritevo refreshes the existing integration and turns it back on, even if it was deleted. Uniqueness: the integration is unique within the company by `externalId` and the type `EBAY`. Creating it again refreshes the existing integration instead of adding a new one: it sets `authError=false` right away, and `active=true` if the integration was inactive. With `authError` this is the only way to restore the connection. ### Connecting the account It takes a minute. Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Marketplace** section pick the **Ebay** tile. 3. Click **Add integration**. Ritevo redirects you to the eBay sign-in page. 4. Sign in to your seller account and approve access for Ritevo. eBay sends you back to Ritevo. 5. Back in Ritevo, wait a moment - do not close the window. Once the integration has been added, its settings open. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Ebay tile framed in the Marketplace section](https://ritevo.com/docs/integrations/ebay/en-catalogue.webp) ![The eBay add-integration screen with the Add integration button](https://ritevo.com/docs/integrations/ebay/en-add.webp) ![The eBay sign-in page Ritevo redirects to](https://ritevo.com/docs/integrations/ebay/en-login.webp) > **Good to know:** Ritevo never sees your eBay password. You sign in on eBay's page, and Ritevo receives from eBay only a permission to access the account. You can revoke it at any time in your eBay account settings - the integration then stops working and shows **Reconnection required**. ### Integration settings After connecting, the integration is **Active**, but order and message fetching are **off** - you turn them on yourself, separately: - **Account name** - the login of your eBay account. Ritevo takes it from eBay; it cannot be changed. - **Fetch orders** - once on, Ritevo checks for new and changed orders about every 10 minutes. The rules shared by all channels: [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders). - **Fetch messages** - once on, Ritevo fetches messages about every 10 minutes, reaching 7 days back on the first fetch. Shared rules: [Fetching messages](https://ritevo.com/en/docs/messages/fetching-messages). ![eBay integration details: the account name and the Fetch orders and Fetch messages switches](https://ritevo.com/docs/integrations/ebay/en-details.webp) ### What this integration gives you - **Orders** - new and updated eBay orders land in the orders table, with the buyer's details, delivery, line items and offer images. - **Messages** - conversations with buyers land in the shared inbox. You reply from Ritevo, with images as attachments. ### Orders from eBay Ritevo fetches the whole eBay order: the buyer, payment, delivery, line items with prices (after discounts) and offer images. eBay's API exposes only paid orders ready for processing, so every one arrives in Ritevo as **Confirmed**. Cancellations, returns and disputes are handled on eBay's side - they do not change the status in Ritevo. - **Statuses and payments** - eBay statuses and payment methods are translated to Ritevo statuses in one fixed way; marketplaces have no mappings of their own, unlike online stores. A cash-on-delivery order arrives as **Awaiting payment** with the **Cash on delivery** method. - **Pickup points** - eBay does not provide them through the API; an order arrives with a delivery address. - **eBay International Shipping** - the delivery address you see is the eBay hub you ship the parcel to, not the buyer's address. - **Additional services** - not supported. This integration does not pass on services such as gift wrapping or carry-in. If you want to sell them, list them as a separate product or offer - they then show in the order as a regular line item. More about [additional services](https://ritevo.com/en/docs/orders/fetching-orders#additional-services). - **Invoice** - if eBay provides the buyer's tax id or its equivalent, the order gets the **Customer asks for an invoice** flag with the company details and the number filled in. > **Good to know:** An order with the **Confirmed** status is taken over by Ritevo - later changes on the sales channel's side are skipped. More in [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders#who-manages). ### Messages from eBay - Buyer messages from your eBay inbox land in Ritevo. You reply from Ritevo; attachments can be **images only** (photos), which is how eBay works. ### Reconnection required This state appears when the permission granted to Ritevo in eBay has expired or was revoked - for example after a password change in eBay or after disconnecting the app in the account settings. Until you reconnect, Ritevo neither fetches nor sends any data on that account. 1. Go through **Connecting the account** again, signing in to the **same** eBay account. 2. Ritevo recognises the account by its identifier and refreshes the connection in the existing integration. The fetching settings and the history stay unchanged - no second integration is created. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not manage listings: it does not list, change prices or stock in eBay. ### The integration through the API This integration's endpoints are under `/integrations/marketplaces/ebay`, and the ones shared by the whole type (list, get one, fetching switches, delete, restore) under `/integrations/marketplaces`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. Account deletion on eBay's side: when eBay reports that a user account was deleted (Marketplace Account Deletion), Ritevo right away anonymises every integration with that account - sets `active=false`, replaces the account name with a placeholder and wipes the tokens. Orders and messages fetched earlier stay. --- Source: https://ritevo.com/en/docs/integrations/empik (updated 2026-10-10) ## Empik Empik Marketplace integration with Ritevo: connecting with an API key, fetching orders and messages, automatic order acceptance, disputes and incidents. The Empik Marketplace integration brings orders as well as messages and disputes from your seller account into Ritevo. You connect it with an API key from the Empik seller panel. > **Required integration:** You need an active Empik seller account and an API key generated in its panel. One Empik account is connected once; if you sell from several accounts, add each one as a separate integration. The same Empik account can be connected only once. When you connect it again, Ritevo refreshes the existing integration and turns it back on, even if it was deleted. Uniqueness: the integration is unique within the company by `externalId` and the type `EMPIK`. Creating it again refreshes the existing integration instead of adding a new one: it sets `authError=false` right away, and `active=true` if the integration was inactive. You can also send new credentials with `PATCH /integrations/marketplaces/empik/{id}/token` - in any state of the integration, also when `authError=false` and `active=true`; it sets `authError=false` and `active=true`. ### How to generate the API key You create the API key in the Empik seller panel. Copy it in full - you will paste it into Ritevo when adding the integration. 1. Sign in to the Empik Marketplace seller panel. 2. Click your user name in the top right corner and go to the account settings. 3. Choose **API key**. 4. Click **Generate new key**. If a key already exists, just copy it. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Marketplace** section pick the **Empik** tile. 3. In the **API Token** field paste the API key from your Empik seller panel. 4. Click **Add integration**. Ritevo checks the key with Empik right away: if it is valid, the integration is added and its settings open. If not - you will see the error returned by Empik and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Empik tile framed in the Marketplace section](https://ritevo.com/docs/integrations/empik/en-catalogue.webp) ![The Empik add-integration screen with the API Token field and the Add integration button](https://ritevo.com/docs/integrations/empik/en-add.webp) ### Integration settings After connecting, the integration is **Active**, but order and message fetching are **off** - you turn them on yourself, separately: - **Account name** - the name of your seller account, which Ritevo takes from Empik. It cannot be changed. - **Fetch orders** - once on, Ritevo checks for new and changed orders about every 10 minutes. The rules shared by all channels: [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders). - **Fetch messages** - once on, Ritevo fetches messages about every 10 minutes, reaching 7 days back on the first fetch. Shared rules: [Fetching messages](https://ritevo.com/en/docs/messages/fetching-messages). ![Empik integration details: the account name, the Fetch orders and Fetch messages switches and the Update credentials button](https://ritevo.com/docs/integrations/empik/en-details.webp) > **Good to know:** You can replace the key at any time with the same **Update credentials** button, not only after an error. ### What this integration gives you - **Orders** - new and updated Empik orders land in the orders table, with the buyer's details, invoice details, delivery (including the pickup point) and line items. - **Messages and disputes** - conversations with buyers and incident reports land in the shared inbox. ### Orders from Empik Ritevo fetches the whole Empik order: the buyer, payment, delivery together with the pickup point, line items and the buyer's message. Orders awaiting acceptance are **accepted automatically** by Ritevo - you do not have to accept them in the Empik panel. - **Statuses and payments** - Empik statuses and payment methods are translated to Ritevo statuses in one fixed way; marketplaces have no mappings of their own, unlike online stores. A cash-on-delivery order arrives as **Awaiting payment** with the **Cash on delivery** method. - **Additional services** - not supported. This integration does not pass on services such as gift wrapping or carry-in. If you want to sell them, list them as a separate product or offer - they then show in the order as a regular line item. More about [additional services](https://ritevo.com/en/docs/orders/fetching-orders#additional-services). - **Invoice** - if Empik provides the buyer's tax id or its equivalent, the order gets the **Customer asks for an invoice** flag with the company details and the number filled in. > **Good to know:** An order with the **Confirmed** status is taken over by Ritevo - later changes on the sales channel's side are skipped. More in [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders#who-manages). ### Messages and disputes from Empik - **Messages** - conversations with buyers from the Empik panel. You reply from Ritevo, attachments included. - **Disputes** - these are incident reports on order lines. Empik does not allow replying inside an incident, so at a dispute Ritevo shows **the existing conversations with that buyer for that order** - you reply in them like in an ordinary message - and a **Write to the buyer in a new conversation** button when there is no such conversation yet. The incident itself you close right there with **Resolve incident**, giving a reason. - If a message concerns an order that is not in Ritevo yet, we fetch it on our own - even with order fetching turned off. ### Reconnection required This state appears when the API key stopped working - it was revoked in the Empik panel or lost its permissions. Until you provide a new key, Ritevo neither fetches nor sends any data on that account. 1. Generate a new API key in your Empik seller panel. 2. On the integration page in Ritevo click **Update credentials**, paste the new key and confirm. Ritevo checks it with Empik just like when adding - a wrong key returns an error, a valid one refreshes the connection. The fetching settings and the history stay unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not manage listings: it does not list, change prices or stock in Empik. ### The integration through the API This integration's endpoints are under `/integrations/marketplaces/empik`, and the ones shared by the whole type (list, get one, fetching switches, delete, restore) under `/integrations/marketplaces`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/erli (updated 2026-10-10) ## Erli Erli integration with Ritevo: connecting the account with an API key, fetching orders, pickup points, buyer messages over email, reconnecting. The Erli integration brings orders from your seller account into Ritevo. You connect it with an API key from the Erli seller panel. Erli delivers buyer messages by email - you handle them in Ritevo through an email integration. > **Required integration:** You need an active Erli seller account and an API key generated in its panel. One Erli account is connected once; if you sell from several accounts, add each one as a separate integration. The same Erli account can be connected only once. When you connect it again, Ritevo refreshes the existing integration and turns it back on, even if it was deleted. Uniqueness: the integration is unique within the company by `externalId` and the type `ERLI`. Creating it again refreshes the existing integration instead of adding a new one: it sets `authError=false` right away, and `active=true` if the integration was inactive. You can also send new credentials with `PATCH /integrations/marketplaces/erli/{id}/token` - in any state of the integration, also when `authError=false` and `active=true`; it sets `authError=false` and `active=true`. ### How to generate the API key You create the API key in the Erli seller panel. Copy it in full - you will paste it into Ritevo when adding the integration. 1. Sign in to the Erli seller panel. 2. In the top right corner open **Moje ERLI** and choose **Ustawienia sklepu** (shop settings). 3. In the left menu choose **Metoda integracji** (integration method), then **Własna integracja po API** (own API integration). 4. In the **Opis klucza** (key description) field enter any name, for example "Ritevo", and click **Wygeneruj nowy klucz** (generate new key). ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Marketplace** section pick the **Erli** tile. 3. In the **API Token** field paste the API key from your Erli seller panel. 4. Click **Add integration**. Ritevo checks the key with Erli right away: if it is valid, the integration is added and its settings open. If not - you will see the error returned by Erli and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Erli tile framed in the Marketplace section](https://ritevo.com/docs/integrations/erli/en-catalogue.webp) ![The Erli add-integration screen with the API Token field and the Add integration button](https://ritevo.com/docs/integrations/erli/en-add.webp) ### Integration settings After connecting, the integration is **Active**, but order and message fetching are **off** - you turn them on yourself, separately: - **Account name** - the name of your seller account, which Ritevo takes from Erli. It cannot be changed. - **Fetch orders** - once on, Ritevo checks for new and changed orders about every 10 minutes. The rules shared by all channels: [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders). - **Fetch messages** - instead of a switch there is a note that Erli messages are handled through an email integration, and an **Add integration** button that leads to adding one. ![Erli integration details: the account name, the Fetch orders switch, the messages card pointing to the email integration and the Update credentials button](https://ritevo.com/docs/integrations/erli/en-details.webp) > **Good to know:** You can replace the key at any time with the same **Update credentials** button, not only after an error. ### What this integration gives you - **Orders** - new and updated Erli orders land in the orders table, with the buyer's details, invoice details, delivery (including the pickup point) and line items with images. - **Messages** - through an email integration, see below. ### Orders from Erli Ritevo fetches the whole Erli order: the buyer, payment, delivery together with the pickup point, line items with prices and product images. - **Statuses and payments** - Erli statuses and payment methods are translated to Ritevo statuses in one fixed way; marketplaces have no mappings of their own, unlike online stores. A cash-on-delivery order arrives as **Awaiting payment** with the **Cash on delivery** method. - **Returns** - an order the buyer has returned is still shown by Erli as purchased; in Ritevo it stays **Confirmed**. - **Additional services** - not supported. This integration does not pass on services such as gift wrapping or carry-in. If you want to sell them, list them as a separate product or offer - they then show in the order as a regular line item. More about [additional services](https://ritevo.com/en/docs/orders/fetching-orders#additional-services). - **Invoice** - if Erli provides the buyer's tax id or its equivalent, the order gets the **Customer asks for an invoice** flag with the company details and the number filled in. > **Good to know:** An order with the **Confirmed** status is taken over by Ritevo - later changes on the sales channel's side are skipped. More in [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders#who-manages). ### Buyer messages from Erli Erli has no inbox of its own - buyers write to you **by email** to the address set in your Erli account. To see and answer those messages in Ritevo, add an [email integration](https://ritevo.com/en/docs/messages/fetching-messages) for that mailbox. The messages then appear in Ritevo like ordinary emails; they are not linked to the Erli integration or its orders. ### Reconnection required This state appears when the API key stopped working - it was revoked in the Erli panel or lost its permissions. Until you provide a new key, Ritevo neither fetches nor sends any data on that account. 1. Generate a new API key in your Erli seller panel. 2. On the integration page in Ritevo click **Update credentials**, paste the new key and confirm. Ritevo checks it with Erli just like when adding - a wrong key returns an error, a valid one refreshes the connection. The fetching settings and the history stay unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not manage listings: it does not list, change prices or stock in Erli. - It does not fetch messages or disputes - Erli does not expose them through its API. ### The integration through the API This integration's endpoints are under `/integrations/marketplaces/erli`, and the ones shared by the whole type (list, get one, fetching switches, delete, restore) under `/integrations/marketplaces`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/own-sales-channel (updated 2026-09-27) ## Own sales channel The own sales channel in Ritevo: an integration for orders from outside marketplaces and stores - phone, email, in-store sales - that you add by hand. The own sales channel is an integration with no external system behind it. Most often it works as a **POS - quick in-person sales**: a customer buys in your physical shop or at a stand, and you add the order in Ritevo right away. It also suits orders taken by phone, by email or on a messenger. This way such orders have a source, just like orders from eBay or WooCommerce, and the same automatic actions, documents and shipments work on them. > **Required integration:** You do not need any account or key. You can create as many own channels as you like - for example one per point of sale (POS): a physical shop, a trade fair stand or phone sales. Each is a separate integration, so you can filter orders from each place separately and set separate automatic actions for them. Uniqueness: it is not checked for the type `OWN` - every creation gives a new channel. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Marketplace** section pick the **Own sales channel** tile. 3. Enter the **Account name** - any name you want to see this channel under, for example "Phone sales". 4. Click **Create integration**. The new channel's settings open. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Own sales channel tile framed in the Marketplace section](https://ritevo.com/docs/integrations/own/en-catalogue.webp) ![The own sales channel add screen with the Account name field and the Create integration button](https://ritevo.com/docs/integrations/own/en-add.webp) ### Channel settings The own channel has only an **Account name**, which you can change at any time and save with **Update integration**. There is no order or message fetching - there is nothing to fetch from. ![Own sales channel details: the account name and the Update integration button](https://ritevo.com/docs/integrations/own/en-details.webp) ### Orders in the own channel You add an order by hand in the orders table, choosing this channel as its source. You fill in what you need: the buyer, invoice details, delivery, line items and payment. From then on it works like any other order in Ritevo - you can issue a document for it, create a shipment, change its status, and automatic actions with the **Integration is** condition set to this channel run just like for marketplaces. ### Deleting the integration **Delete integration** marks the channel as off on the integrations list; the orders added earlier stay, and the channel can still be chosen when adding an order by hand. **Restore integration** turns it back on. ### What the integration does not do - It fetches no orders or messages and updates no listings - it is only a source for orders added by hand. ### The integration through the API This integration's endpoints are under `/integrations/marketplaces/own`, and the ones shared by the whole type (list, get one, fetching switches, delete, restore) under `/integrations/marketplaces`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/woocommerce (updated 2026-10-17) ## WooCommerce WooCommerce integration with Ritevo: REST API keys, connecting the store, mapping statuses, payments and plugin fields (tax id, parcel locker), orders. The WooCommerce integration brings orders from your WordPress store into Ritevo. You connect it with REST API keys generated in the WooCommerce panel. Because WooCommerce stores differ in their plugins, you set yourself how statuses, payment methods and plugin-added fields (tax id, pickup point) are read in Ritevo. > **Required integration:** You need a working WooCommerce store and access to its admin panel to generate the API keys. The same WooCommerce store can be connected only once. When you add it again, Ritevo refreshes the existing integration and turns it back on, even if it was deleted. Uniqueness: the integration is unique within the company by `externalId` and the type `WOOCOMMERCE`; `externalId` is the store url without a trailing `/` (a url ending in `/` is saved without it). Creating it again with the same url refreshes the existing integration instead of adding a new one: it replaces the credentials, sets `authError=false` and `active=true` and returns that integration. You can also send new credentials with `PATCH /integrations/shops/woocommerce/{integrationId}/credentials` - in any state of the integration, also when `authError=false` and `active=true`; it sets `authError=false` and `active=true`. ### How to generate the API key You create the keys in your store's WordPress panel. Copy both right away - you will paste them into Ritevo when adding the integration. 1. Sign in to the WordPress panel and in the left menu choose **WooCommerce**, then **Settings**. 2. Open the **Advanced** tab, then **REST API**. Click **Add key**. 3. In the **Description** field enter any name, for example "Ritevo". In the **User** field pick the store's administrator account. 4. In the **Permissions** field choose **Read/Write** - the highest available - and click **Generate API key**. 5. Copy the **Consumer key** and the **Consumer secret**. > **Good to know:** WooCommerce shows the consumer secret only once, right after generating. If you close the page without copying it, generate a new key. A key with **Read** permission only will not work - Ritevo rejects it when adding. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Online stores** section pick the **WooCommerce** tile. 3. In the **Account name** field enter your own name for the integration, for example the store's name. 4. In the **Store address** field enter the store's full address with `https://`, without a trailing slash and without `/wp-admin` - for example `https://mystore.com`. 5. In the **Consumer Key** and **Consumer Secret** fields paste the keys from the WooCommerce panel. 6. Click **Add integration**. Ritevo connects to the store right away and checks the details: if they are valid, the integration is added and its settings open. If not - you will see the error returned by the store and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the WooCommerce tile framed in the Online stores section](https://ritevo.com/docs/integrations/woocommerce/en-catalogue.webp) ![The WooCommerce add-integration screen with the Account name, Store address, Consumer Key and Consumer Secret fields](https://ritevo.com/docs/integrations/woocommerce/en-add.webp) ### Integration settings After connecting, the integration is **Active**, but order fetching is **off** - you turn it on yourself. On the integration page you will find: - **Account name** - your own name for this integration, for example the store's name. You can change it at any time. - **Store address** - the address given when adding. It cannot be changed here; a new address or new keys go through **Update credentials**. - **Fetch orders** - once on, Ritevo checks for new and changed orders about every 10 minutes. The rules shared by all channels: [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders). - **Order status mapping**, **Payment method mapping** and **Advanced mapping** - described below. ![WooCommerce integration details: the account name, store address, the Fetch orders switch and the Order status mapping card](https://ritevo.com/docs/integrations/woocommerce/en-details.webp) > **Good to know:** You can replace the key at any time with the same **Update credentials** button, not only after an error. ### Mapping statuses and payments Every store names its order statuses and payment methods its own way, so with online stores you decide yourself how they translate to Ritevo statuses and methods. You set the mapping once, on the integration page, and it applies to every order fetched from then on. > **Good to know:** You can change the mapping freely at any time to suit your needs - including the assignments filled in up front, which are only a starting point. #### Order status mapping Ritevo reads the status list from your store, including statuses added by plugins, so you see them under the same names as in the WooCommerce panel. **Up front** the standard WooCommerce statuses are assigned. **You assign yourself** the statuses added by plugins. The starting assignment: - **Confirmed** (API: "Confirmed" = `CONFIRMED`; value in `orderStatusMappings[].status`) - Processing, Completed, Refunded. A refunded order was a real sale, so it stays confirmed - you settle the refund separately. - **Cancelled** (API: "Cancelled" = `CANCELLED`; value in `orderStatusMappings[].status`) - Cancelled. - **Awaiting payment** (API: "Awaiting payment" = `WAITING_FOR_PAYMENT`; value in `orderStatusMappings[].status`) - Pending payment, Failed. - **Awaiting confirmation** (API: "Awaiting confirmation" = `WAITING_FOR_CONFIRMATION`; value in `orderStatusMappings[].status`) - On hold. One Ritevo status can have several store statuses assigned, but one store status only one Ritevo status. An order with a status you have not assigned anywhere arrives as **Awaiting confirmation** - you will see it and decide what to do. #### Payment method mapping Ritevo reads the method list from the payment gateways enabled in your store. **Up front** the methods built into WooCommerce are assigned. **You assign yourself** plugin gateways (Stripe, PayPal, Klarna and others), because every store has different ones. The starting assignment: - **Bank transfer** (API: "Bank transfer" = `BANK_TRANSFER`; value in `paymentMethodMappings[].paymentMethod`) - Direct bank transfer, Check payments. - **Cash on delivery** (API: "Cash on delivery" = `CASH_ON_DELIVERY`; value in `paymentMethodMappings[].paymentMethod`) - Cash on delivery. A payment made with a method you have not assigned anywhere arrives as **Other**. ![The Payment method mapping card of the WooCommerce integration with Direct bank transfer, Check payments and Cash on delivery assigned](https://ritevo.com/docs/integrations/woocommerce/en-payments.webp) #### Advanced mapping - plugin fields WooCommerce has no standard fields for a tax id, an invoice request or a pickup point - plugins add them, each under its own field name. In this card you point to the order field Ritevo should read each of these from. **Up front** the field names of popular plugins are filled in. **You add yourself** the field names of other plugins and remove the ones you do not need. - **Tax id / VAT number** (API: "Tax id / VAT number" = `TAX_ID`; value in `fieldMappings[].field`) - the field with the buyer's tax id. When it has a value, the order gets the company details and the number for the invoice. - **Invoice request** (API: "Invoice request" = `INVOICE_REQUESTED`; value in `fieldMappings[].field`) - the field Ritevo reads to tell whether the buyer wants an invoice. Only the value in the field matters: if it is "0", "no", "false" or "off", there is no request; any other value (for example "1", "yes", "true") is a request. When the field is empty, an invoice is requested whenever the buyer gave a tax id. - **Pickup point id** (API: "Pickup point id" = `PICKUP_POINT_ID`; value in `fieldMappings[].field`) - the field with the locker or point code (for example `WAW123`). - **Pickup point name** and **Pickup point description** (API: "Pickup point name" = `PICKUP_POINT_NAME`, "Pickup point description" = `PICKUP_POINT_DESCRIPTION`; value in `fieldMappings[].field`) - the fields with the point's name and address, if the plugin stores them. - **Pickup point country** (API: "Pickup point country" = `PICKUP_POINT_COUNTRY`; value in `fieldMappings[].field`) - usually stays empty; Ritevo then takes the country from the delivery address. You will find the field name in the plugin's settings or in the details of a test order. Enter it exactly - letter case and the leading underscore matter. One field can hold several names (for example after switching plugins): Ritevo uses the first one that has a value in the order. ![The Advanced mapping card of the WooCommerce integration with the Tax id / VAT number, Invoice request and pickup point fields, plus the Update credentials and Update integration buttons](https://ritevo.com/docs/integrations/woocommerce/en-advanced.webp) > **Good to know:** You save mapping changes with the **Update integration** button at the bottom of the page. They apply from the next fetch - orders fetched earlier do not change their status retroactively. You save the mappings with `PATCH /integrations/shops/woocommerce/{integrationId}` together with `accountName`: `orderStatusMappings` (`{ status, externalIds }`), `paymentMethodMappings` (`{ paymentMethod, externalIds }`) and `fieldMappings` (`{ field, keys }`) with every value listed above. Each list must carry every value of its enum - send an unassigned value with an empty list. `externalIds` are WooCommerce status slugs and payment gateway ids. The current shape is in Swagger. ### What this integration gives you - **Orders** - new and changed WooCommerce orders land in the orders table, with the buyer's details, invoice details, delivery (including the plugin's pickup point) and line items with product images. ### Orders from WooCommerce Ritevo fetches the whole WooCommerce order: the buyer, billing and shipping address, shipping method, payment, line items with gross prices and product images. An order changed in the store (for example a new status) is fetched again. - **Statuses and payments** - translated according to your mapping, described above. - **Invoice** - the company details and tax id are read from the fields set in **Advanced mapping**; with neither a company name nor a tax id the order has no invoice details. The invoice request follows the **Invoice request** field and gives the **Customer asks for an invoice** flag. - **Pickup point** - the point's code and name are read from the fields set in **Advanced mapping**; without them the order has only the delivery address. - **Buyer's note** - the order note typed at checkout goes into the order as the buyer's message. - **Additional services** - supported. Fees the shop added to the order, for example for gift wrapping or carry-in, show up as separate line items for the whole order. A discount added as a fee shows up with a negative amount. More about [additional services](https://ritevo.com/en/docs/orders/fetching-orders#additional-services). - **Guest checkout** - a guest order is fetched normally; the buyer then has no store customer id. > **Good to know:** An order with the **Confirmed** status is taken over by Ritevo - later changes on the sales channel's side are skipped. More in [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders#who-manages). ### Reconnection required This state appears when the store stopped accepting the credentials - the key was deleted in the store's panel, lost its permissions, or the store address changed. Until you provide new details, Ritevo neither fetches nor sends any data from that store. 1. Generate new keys in the store's panel - the same way as when connecting for the first time. 2. On the integration page in Ritevo click **Update credentials**, enter the store address and the new keys and confirm. Ritevo checks them with the store just like when adding - wrong details return an error, valid ones refresh the connection. The mappings, fetching settings and history stay unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not manage listings: it does not list, change prices or stock in WooCommerce. - It does not fetch messages - WooCommerce has no buyer inbox. Customers write by email, so add an [email integration](https://ritevo.com/en/docs/messages/fetching-messages) for the store's mailbox. - It sends nothing back to WooCommerce: when you change an order's status, create a shipment or issue an invoice in Ritevo, the order in WooCommerce stays unchanged. ### The integration through the API This integration's endpoints are under `/integrations/shops/woocommerce`, and the ones shared by the whole type (list, get one, fetching switches, delete, restore) under `/integrations/shops`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/prestashop (updated 2026-10-17) ## PrestaShop PrestaShop integration with Ritevo: the webservice key, connecting the store, mapping statuses and payment modules, orders and customer service messages. The PrestaShop integration brings orders and customer service messages from your store into Ritevo. You connect it with a webservice key generated in the PrestaShop panel. You translate the store's statuses and payment modules to Ritevo statuses in the mapping on the integration page. > **Required integration:** You need a working PrestaShop store and access to its admin panel to generate the API keys. The same PrestaShop store can be connected only once. When you add it again, Ritevo refreshes the existing integration and turns it back on, even if it was deleted. Uniqueness: the integration is unique within the company by `externalId` and the type `PRESTASHOP`; `externalId` is the store url without a trailing `/` (a url ending in `/` is saved without it). Creating it again with the same url refreshes the existing integration instead of adding a new one: it replaces the credentials, sets `authError=false` and `active=true` and returns that integration. You can also send new credentials with `PATCH /integrations/shops/prestashop/{integrationId}/credentials` - in any state of the integration, also when `authError=false` and `active=true`; it sets `authError=false` and `active=true`. ### How to generate the API key You create the key in the PrestaShop admin panel. Copy it in full - you will paste it into Ritevo when adding the integration. 1. Sign in to the PrestaShop panel and in the left menu choose **Advanced Parameters**, then **Webservice**. 2. In the **Configuration** section set **Enable PrestaShop's webservice** to **Yes** and save. 3. Click **Add new webservice key**. Click **Generate**, and in the **Key description** field enter any name, for example "Ritevo". 4. In the **Permissions** table tick **everything**: every resource and every action (View, Add, Modify, Delete). Set **Status** to **Yes** and save. Copy the key from the **Key** field. > **Good to know:** Grant full permissions even though Ritevo uses only some of them today - a key with missing access yields incomplete orders or no messages, and new Ritevo features will then work without touching the key. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Online stores** section pick the **PrestaShop** tile. 3. In the **Account name** field enter your own name for the integration, for example the store's name. 4. In the **Store address** field enter the store's full address with `https://`, without a trailing slash and without `/api` - for example `https://mystore.com`. 5. In the **Webservice key** field paste the key from the PrestaShop panel. 6. Click **Add integration**. Ritevo connects to the store right away and checks the details: if they are valid, the integration is added and its settings open. If not - you will see the error returned by the store and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the PrestaShop tile framed in the Online stores section](https://ritevo.com/docs/integrations/prestashop/en-catalogue.webp) ![The PrestaShop add-integration screen with the Account name, Store address and Webservice key fields](https://ritevo.com/docs/integrations/prestashop/en-add.webp) ### Integration settings After connecting, the integration is **Active**, but order fetching is **off** - you turn it on yourself. On the integration page you will find: - **Account name** - your own name for this integration, for example the store's name. You can change it at any time. - **Store address** - the address given when adding. It cannot be changed here; a new address or new keys go through **Update credentials**. - **Fetch orders** - once on, Ritevo checks for new and changed orders about every 10 minutes. The rules shared by all channels: [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders). - **Fetch messages** - once on, Ritevo fetches customer service threads about every 10 minutes, reaching 7 days back on the first fetch. Shared rules: [Fetching messages](https://ritevo.com/en/docs/messages/fetching-messages). - **Order status mapping** and **Payment method mapping** - described below. ![PrestaShop integration details: the pickup point notice, account name, store address and the Fetch orders and Fetch messages switches](https://ritevo.com/docs/integrations/prestashop/en-details.webp) > **Good to know:** You can replace the key at any time with the same **Update credentials** button, not only after an error. ### Mapping statuses and payments Every store names its order statuses and payment methods its own way, so with online stores you decide yourself how they translate to Ritevo statuses and methods. You set the mapping once, on the integration page, and it applies to every order fetched from then on. > **Good to know:** You can change the mapping freely at any time to suit your needs - including the assignments filled in up front, which are only a starting point. #### Order status mapping Ritevo reads the status list from your store, so you see them under the same names as in the PrestaShop panel. **Up front** the statuses PrestaShop is installed with are assigned. **You assign yourself** statuses added by payment modules or by hand. The starting assignment: - **Confirmed** (API: "Confirmed" = `CONFIRMED`; value in `orderStatusMappings[].status`) - Payment accepted, Processing in progress, Shipped, Delivered, Refunded, Remote payment accepted, Payment received. A refunded order was a real sale, so it stays confirmed. - **Cancelled** (API: "Cancelled" = `CANCELLED`; value in `orderStatusMappings[].status`) - Canceled. - **Awaiting payment** (API: "Awaiting payment" = `WAITING_FOR_PAYMENT`; value in `orderStatusMappings[].status`) - Awaiting check payment, Payment error, Awaiting bank wire payment, Awaiting remote payment, Awaiting Cash On Delivery validation. - **Awaiting confirmation** (API: "Awaiting confirmation" = `WAITING_FOR_CONFIRMATION`; value in `orderStatusMappings[].status`) - nothing up front; orders with an unassigned status land here too. One Ritevo status can have several store statuses assigned, but one store status only one Ritevo status. An order with a status you have not assigned anywhere arrives as **Awaiting confirmation** - you will see it and decide what to do. ![The Order status mapping card of the PrestaShop integration with the store's statuses assigned by default](https://ritevo.com/docs/integrations/prestashop/en-statuses.webp) #### Payment method mapping PrestaShop does not expose a list of payment modules, so here you type the **module names** by hand - the ones you see in the PrestaShop panel in an order's details or under **Modules → Payment** (for example `ps_wirepayment`, `payu`). **Up front** the most common modules are filled in. **You add yourself** other modules and remove the ones you do not need. The starting assignment: - **Bank transfer** (API: "Bank transfer" = `BANK_TRANSFER`; value in `paymentMethodMappings[].paymentMethod`) - ps_wirepayment, ps_checkpayment. - **Cash on delivery** (API: "Cash on delivery" = `CASH_ON_DELIVERY`; value in `paymentMethodMappings[].paymentMethod`) - ps_cashondelivery. - **Card** (API: "Card" = `CARD`; value in `paymentMethodMappings[].paymentMethod`) - stripe_official. - **PayU** (API: "PayU" = `PAYU`; value in `paymentMethodMappings[].paymentMethod`) - payu. - **PayPal** (API: "PayPal" = `PAYPAL`; value in `paymentMethodMappings[].paymentMethod`) - ps_checkout, paypal. - **P24** (API: "P24" = `P24`; value in `paymentMethodMappings[].paymentMethod`) - przelewy24. A payment made with a method you have not assigned anywhere arrives as **Other**. ![The Payment method mapping card of the PrestaShop integration with payment module names filled in by default](https://ritevo.com/docs/integrations/prestashop/en-payments.webp) > **Good to know:** You save mapping changes with the **Update integration** button at the bottom of the page. They apply from the next fetch - orders fetched earlier do not change their status retroactively. You save the mappings with `PATCH /integrations/shops/prestashop/{integrationId}` together with `accountName`: `orderStatusMappings` (`{ status, externalIds }`), `paymentMethodMappings` (`{ paymentMethod, externalIds }`) and `fieldMappings` as an empty list - this store has no fields to map. Each list must carry every value of its enum - send an unassigned value with an empty list. `externalIds` are PrestaShop status ids and payment module names. The current shape is in Swagger. ### What this integration gives you - **Orders** - new and changed PrestaShop orders land in the orders table, with the buyer's details, invoice details, delivery and line items with product images. - **Messages** - PrestaShop customer service threads land in the inbox; you reply to them from Ritevo. ### Orders from PrestaShop Ritevo fetches the whole PrestaShop order: the customer account with the invoice address, the delivery address and carrier, payments, line items with gross prices and product images. An order changed in the store (for example a new status) is fetched again. - **Statuses and payments** - translated according to your mapping, described above. The paid amount is the sum of payments registered in PrestaShop. - **Buyer's note** - the comment typed at checkout goes into the order as the buyer's message. - **Additional services** - supported. When the buyer chooses gift wrapping or recycled packaging, you see them in the order as separate line items for the whole order, also when they are free. The gift message is supported too - the text the buyer wants added to the parcel. You see it together with the buyer's message, in a **Gift message** box. More about [additional services](https://ritevo.com/en/docs/orders/fetching-orders#additional-services). - **Discounts** - cart rules (discount codes) appear as separate line items with a negative amount, so the items add up to the order total. - **Guest checkout** - a guest order is fetched normally. - **Invoice** - if PrestaShop provides the buyer's tax id or its equivalent, the order gets the **Customer asks for an invoice** flag with the company details and the number filled in. The card text is in `messageFromBuyer`, wrapped in `[GIFT_MESSAGE]` and `[/GIFT_MESSAGE]` markers, before the buyer's comment. Everything outside the markers is the buyer's message. > **Good to know:** An order with the **Confirmed** status is taken over by Ritevo - later changes on the sales channel's side are skipped. More in [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders#who-manages). ### Messages from PrestaShop Ritevo fetches threads from PrestaShop's **Customer Service** - both those from the contact form and those attached to an order. Each thread is a conversation in Ritevo: - **Reply** - you reply from Ritevo; in PrestaShop the reply is stored as a message from a store employee. There are no disputes or claims - PrestaShop has none. - **Link to the order** - a thread about an order is attached to that order in Ritevo. - **Private messages** - employee notes marked private in PrestaShop are not fetched. - **Attachments** - PrestaShop provides only the name of the attached file, not the file itself. In Ritevo you see the name; open the file in the PrestaShop panel. You cannot send attachments either. ### Reconnection required This state appears when the store stopped accepting the credentials - the key was deleted in the store's panel, lost its permissions, or the store address changed. Until you provide new details, Ritevo neither fetches nor sends any data from that store. 1. Generate new keys in the store's panel - the same way as when connecting for the first time. 2. On the integration page in Ritevo click **Update credentials**, enter the store address and the new keys and confirm. Ritevo checks them with the store just like when adding - wrong details return an error, valid ones refresh the connection. The mappings, fetching settings and history stay unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not manage listings: it does not list, change prices or stock in PrestaShop. - It does not support pickup points (for example parcel lockers). PrestaShop has no standard field for them - each carrier module stores the chosen point on its own, out of the webservice's reach. An order with such a delivery is fetched normally, but without the point; you see a warning about this at the top of the integration page. - It sends nothing back to PrestaShop: when you change an order's status, create a shipment or issue an invoice in Ritevo, the order in PrestaShop stays unchanged. ### The integration through the API This integration's endpoints are under `/integrations/shops/prestashop`, and the ones shared by the whole type (list, get one, fetching switches, delete, restore) under `/integrations/shops`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/shoper (updated 2026-10-17) ## Shoper Shoper integration with Ritevo: Client ID and API token, connecting the store, mapping your own statuses and payments, fetching orders, messages by email. The Shoper integration brings orders from your store into Ritevo. You connect it with API access details generated in the Shoper panel. Because every Shoper store sets up its own statuses and payment methods, after connecting you assign them to Ritevo statuses in the mapping. Shoper delivers buyer messages by email - you handle them in Ritevo through an email integration. > **Required integration:** You need a working Shoper store and access to its admin panel to generate the API keys. The same Shoper store can be connected only once. When you add it again, Ritevo refreshes the existing integration and turns it back on, even if it was deleted. Uniqueness: the integration is unique within the company by `externalId` and the type `SHOPER`; `externalId` is the store url without a trailing `/` (a url ending in `/` is saved without it). Creating it again with the same url refreshes the existing integration instead of adding a new one: it replaces the credentials, sets `authError=false` and `active=true` and returns that integration. You can also send new credentials with `PATCH /integrations/shops/shoper/{integrationId}/credentials` - in any state of the integration, also when `authError=false` and `active=true`; it sets `authError=false` and `active=true`. ### How to generate the API key You create the access details in the Shoper admin panel. Copy them right away - you will paste them into Ritevo when adding the integration. 1. Sign in to the Shoper panel and choose **Aplikacje i integracje** (apps and integrations), then **Zewnętrzne aplikacje** (external apps). 2. Click **Dodaj integrację** (add integration) and enter any name, for example "Ritevo". 3. Tick **all** access areas with full permissions - even though Ritevo uses only some of them today, new features will then work without changes in the Shoper panel. 4. Save and copy the **Client ID** and the **API token**. > **Good to know:** Shoper shows the token only once, right after creating it. If you close the window without copying it, create the integration in the Shoper panel again. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Online stores** section pick the **Shoper** tile. 3. In the **Account name** field enter your own name for the integration, for example the store's name. 4. In the **Store address** field enter the store's full address with `https://`, without a trailing slash - for example `https://mystore.shoparena.pl`. 5. In the **Client ID** and **API token** fields paste the details from the Shoper panel. 6. Click **Add integration**. Ritevo connects to the store right away and checks the details: if they are valid, the integration is added and its settings open. If not - you will see the error returned by the store and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Shoper tile framed in the Online stores section](https://ritevo.com/docs/integrations/shoper/en-catalogue.webp) ![The Shoper add-integration screen with the Account name, Store address, Client ID and API token fields](https://ritevo.com/docs/integrations/shoper/en-add.webp) ### Integration settings After connecting, the integration is **Active**, but order fetching is **off** - you turn it on yourself. On the integration page you will find: - **Account name** - your own name for this integration, for example the store's name. You can change it at any time. - **Store address** - the address given when adding. It cannot be changed here; a new address or new keys go through **Update credentials**. - **Client ID** - the identifier from the Shoper panel, given when adding. You change it together with the token through **Update credentials**. - **Fetch orders** - once on, Ritevo checks for new orders and status changes about every 10 minutes. The rules shared by all channels: [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders). - **Fetch messages** - instead of a switch there is a note that Shoper messages are handled through an email integration, and an **Add integration** button that leads to adding one. - **Order status mapping** and **Payment method mapping** - described below. ![Shoper integration details: the account name, store address, Client ID, the Fetch orders switch and the messages card pointing to the email integration](https://ritevo.com/docs/integrations/shoper/en-details.webp) > **Good to know:** You can replace the key at any time with the same **Update credentials** button, not only after an error. ### Mapping statuses and payments Every store names its order statuses and payment methods its own way, so with online stores you decide yourself how they translate to Ritevo statuses and methods. You set the mapping once, on the integration page, and it applies to every order fetched from then on. > **Good to know:** You can change the mapping freely at any time to suit your needs - including the assignments filled in up front, which are only a starting point. > **Good to know:** In Shoper you create statuses and payment methods yourself in the store's panel, so **nothing is assigned up front**. Set the mapping right after connecting, before you turn on order fetching - otherwise every order arrives as **Awaiting confirmation** with the **Other** payment. #### Order status mapping Ritevo reads the status list from your store, so you see them under the names you gave them in the Shoper panel. **Up front** nothing is assigned. **You assign yourself** every status, because every store creates its own. An example assignment for Shoper's standard statuses: - **Confirmed** (API: "Confirmed" = `CONFIRMED`; value in `orderStatusMappings[].status`) - accepted for processing, awaiting delivery, being packed, ready to ship, shipped. - **Cancelled** (API: "Cancelled" = `CANCELLED`; value in `orderStatusMappings[].status`) - cancelled. - **Awaiting payment** (API: "Awaiting payment" = `WAITING_FOR_PAYMENT`; value in `orderStatusMappings[].status`) - placed, awaiting payment, rejected. - **Awaiting confirmation** (API: "Awaiting confirmation" = `WAITING_FOR_CONFIRMATION`; value in `orderStatusMappings[].status`) - returned, claim - orders you want to look at before doing anything with them. One Ritevo status can have several store statuses assigned, but one store status only one Ritevo status. An order with a status you have not assigned anywhere arrives as **Awaiting confirmation** - you will see it and decide what to do. ![The Order status mapping card of the Shoper integration with an example assignment of the store's statuses](https://ritevo.com/docs/integrations/shoper/en-statuses.webp) #### Payment method mapping Ritevo reads the method list from the payments set up in your store, under their names from the Shoper panel. **Up front** nothing is assigned. **You assign yourself** every method, because every store has its own. An example assignment: - **Bank transfer** (API: "Bank transfer" = `BANK_TRANSFER`; value in `paymentMethodMappings[].paymentMethod`) - mBank mRaty, Przelewy24.pl, Klarna, InPost Pay, Stripe - online payment operators you want to settle like a transfer. - **Cash** (API: "Cash" = `CASH`; value in `paymentMethodMappings[].paymentMethod`) - Cash. - **Cash on delivery** (API: "Cash on delivery" = `CASH_ON_DELIVERY`; value in `paymentMethodMappings[].paymentMethod`) - Cash on delivery. - **P24** (API: "P24" = `P24`; value in `paymentMethodMappings[].paymentMethod`) - Autopay or another operator you want to see separately. A payment made with a method you have not assigned anywhere arrives as **Other**. ![The Payment method mapping card of the Shoper integration with an example assignment of the store's methods](https://ritevo.com/docs/integrations/shoper/en-payments.webp) > **Good to know:** You save mapping changes with the **Update integration** button at the bottom of the page. They apply from the next fetch - orders fetched earlier do not change their status retroactively. You save the mappings with `PATCH /integrations/shops/shoper/{integrationId}` together with `accountName`: `orderStatusMappings` (`{ status, externalIds }`), `paymentMethodMappings` (`{ paymentMethod, externalIds }`) and `fieldMappings` as an empty list - this store has no fields to map. Each list must carry every value of its enum - send an unassigned value with an empty list. `externalIds` are numeric Shoper status and payment ids. The current shape is in Swagger. ### What this integration gives you - **Orders** - new and changed Shoper orders land in the orders table, with the buyer's details, invoice details, delivery and line items with product images. - **Messages** - through an email integration, see below. ### Orders from Shoper Ritevo fetches the whole Shoper order: the buyer, billing and delivery address, payment, line items with gross prices and the product's main image. An order whose status changed in the store is fetched again. - **Statuses and payments** - translated according to your mapping, described above. The paid amount is what the buyer actually paid - including a partial payment. - **Delivery address** - when the buyer gave no separate delivery address, Ritevo uses the billing address. - **Dispatch deadline** - the dispatch date the store declared (from the products' lead times) goes into the order as the dispatch deadline. - **Variants and custom fields** - the chosen variant and whatever the buyer typed into the product's fields (for example an engraving) are appended to the line item's name. - **Merged orders** - if you merged several orders into one in Shoper, Ritevo fetches the original orders and skips the merged one, so goods are not counted twice. - **Additional services** - not supported. This integration does not pass on services such as gift wrapping or carry-in. If you want to sell them, list them as a separate product or offer - they then show in the order as a regular line item. More about [additional services](https://ritevo.com/en/docs/orders/fetching-orders#additional-services). - **Invoice** - if Shoper provides the buyer's tax id or its equivalent, the order gets the **Customer asks for an invoice** flag with the company details and the number filled in. > **Good to know:** An order with the **Confirmed** status is taken over by Ritevo - later changes on the sales channel's side are skipped. More in [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders#who-manages). ### Buyer messages from Shoper Shoper does not expose an inbox through its API - buyers write to you **by email** to the store's address. To see and answer those messages in Ritevo, add an [email integration](https://ritevo.com/en/docs/messages/fetching-messages) for that mailbox. The messages then appear in Ritevo like ordinary emails; they are not linked to the Shoper integration or its orders. ### Reconnection required This state appears when the store stopped accepting the credentials - the key was deleted in the store's panel, lost its permissions, or the store address changed. Until you provide new details, Ritevo neither fetches nor sends any data from that store. 1. Generate new keys in the store's panel - the same way as when connecting for the first time. 2. On the integration page in Ritevo click **Update credentials**, enter the store address and the new keys and confirm. Ritevo checks them with the store just like when adding - wrong details return an error, valid ones refresh the connection. The mappings, fetching settings and history stay unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not manage listings: it does not list, change prices or stock in Shoper. - It does not support deliveries to pickup points yet (for example parcel lockers). An order with such a delivery is fetched normally, but without the chosen point. - It does not fetch messages - Shoper does not expose them through its API. - It sends nothing back to Shoper: when you change an order's status, create a shipment or issue an invoice in Ritevo, the order in Shoper stays unchanged. ### The integration through the API This integration's endpoints are under `/integrations/shops/shoper`, and the ones shared by the whole type (list, get one, fetching switches, delete, restore) under `/integrations/shops`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/shopify (updated 2026-10-18) ## Shopify Shopify integration with Ritevo: connecting the store through the app, mapping statuses, payments and extra fields (tax id, parcel locker), fetching orders. The Shopify integration brings orders from your store into Ritevo. You connect it by approving the Ritevo app in your Shopify admin - no keys to copy. In the mapping you translate payment statuses, payment methods and the order's additional fields (tax id, pickup point) into Ritevo data. Shopify sends buyer messages by email - you handle them in Ritevo through an email integration. > **Required integration:** You need a working Shopify store and an account in its admin that can install apps. The same Shopify store can be connected only once. When you add it again, Ritevo refreshes the existing integration and turns it back on, even if it was deleted. Uniqueness: the integration is unique within the company by `externalId` and the type `SHOPIFY`; `externalId` is the store address `https://.myshopify.com`. The integration is created only after approving the app in Shopify: `POST /integrations/shops/shopify` takes Shopify's redirect parameters in `callbackQuery`, so you cannot create it through the API alone. Connecting the same store again refreshes the existing integration instead of adding a new one: it replaces the access and the store name, sets `authError=false` and `active=true` and returns that integration. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Online stores** section pick the **Shopify** tile and click **Add integration**. 3. Ritevo takes you to Shopify - sign in if needed, choose your store and install the Ritevo app. 4. Shopify asks right away for permission to access the store - approve it. 5. Back in Ritevo, wait a moment - do not close the window. Once the integration has been added, its settings open. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The screen for adding a Shopify integration with the Add integration button that leads to the install in Shopify](https://ritevo.com/docs/integrations/shopify/en-add.webp) > **Good to know:** Ritevo never sees your Shopify password and needs no API keys. Shopify passes Ritevo only a permission to access the store. You revoke it by uninstalling the Ritevo app in the Shopify admin - the integration then stops working and shows **Reconnection required**. ### Integration settings After connecting, the integration is **Active**, but order fetching is **off** - you turn it on yourself. On the integration page you will find: - **Account name** - the store's name from Shopify. Ritevo takes it from Shopify; it cannot be changed here and is refreshed when you reconnect. - **Store address** - the `.myshopify.com` address of the store you installed the app on. It cannot be changed. - **Fetch orders** - once on, Ritevo checks for new and changed orders about every 10 minutes. The newest orders can show up a few minutes late. The rules shared by all channels: [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders). - **Fetch messages** - instead of a switch there is a note that Shopify messages are handled through an email integration, and an **Add integration** button that leads to adding one. - **Order status mapping**, **Payment method mapping** and **Advanced mapping** - described below. ![Shopify integration details: the account name, store address, the Fetch orders switch and the messages card pointing to the email integration](https://ritevo.com/docs/integrations/shopify/en-details.webp) ### Mapping statuses and payments Every store names its order statuses and payment methods its own way, so with online stores you decide yourself how they translate to Ritevo statuses and methods. You set the mapping once, on the integration page, and it applies to every order fetched from then on. > **Good to know:** You can change the mapping freely at any time to suit your needs - including the assignments filled in up front, which are only a starting point. #### Order status mapping The order status in Ritevo follows the order's payment status in Shopify. These statuses are the same in every store, so **up front** all of them are assigned - in the list you see them under their Shopify names. The starting assignment: - **Confirmed** (API: "Confirmed" = `CONFIRMED`; value in `orderStatusMappings[].status`) - PAID (paid), PARTIALLY_REFUNDED (partially refunded), REFUNDED (refunded). A refunded order was a real sale, so it stays confirmed - you settle the refund separately. - **Cancelled** (API: "Cancelled" = `CANCELLED`; value in `orderStatusMappings[].status`) - VOIDED (payment voided), EXPIRED (payment expired). - **Awaiting payment** (API: "Awaiting payment" = `WAITING_FOR_PAYMENT`; value in `orderStatusMappings[].status`) - PENDING (waiting for payment), PARTIALLY_PAID (partially paid). - **Awaiting confirmation** (API: "Awaiting confirmation" = `WAITING_FOR_CONFIRMATION`; value in `orderStatusMappings[].status`) - AUTHORIZED (payment approved, but the money has not been captured yet). One Ritevo status can have several store statuses assigned, but one store status only one Ritevo status. An order with a status you have not assigned anywhere arrives as **Awaiting confirmation** - you will see it and decide what to do. ![The Order status mapping card of the Shopify integration with the Shopify payment statuses assigned by default](https://ritevo.com/docs/integrations/shopify/en-statuses.webp) > **Good to know:** An order cancelled in Shopify always arrives as **Cancelled**, whatever the status mapping says. Cancellation wins over the payment status, because a cancelled order keeps its payment status in Shopify (for example PAID or REFUNDED). #### Payment method mapping Shopify does not expose a store's list of payment methods, so you type the method names by hand - the way Shopify saves them in the order. You will find the name in the Shopify admin in the order details. **Up front** Shopify Payments, PayPal and the manual methods built into Shopify are filled in. **You add yourself** methods from payment apps and remove the ones you do not need. The starting assignment: - **Payment card** (API: "Payment card" = `CARD`; value in `paymentMethodMappings[].paymentMethod`) - `shopify_payments`. - **PayPal** (API: "PayPal" = `PAYPAL`; value in `paymentMethodMappings[].paymentMethod`) - `paypal`. - **Cash on delivery** (API: "Cash on delivery" = `CASH_ON_DELIVERY`; value in `paymentMethodMappings[].paymentMethod`) - `Cash on Delivery (COD)`. - **Bank transfer** (API: "Bank transfer" = `BANK_TRANSFER`; value in `paymentMethodMappings[].paymentMethod`) - `Bank Deposit`, `Money Order`. A payment made with a method you have not assigned anywhere arrives as **Other**. #### Advanced mapping - additional order fields Shopify has no standard fields for a tax id, an invoice request or a pickup point - apps add them, each under its own name, as the order's additional details. In this card you point to the field Ritevo should read each of these from. **Up front** the fields are empty. **You enter yourself** the field names of the apps your store uses. - **Tax id / VAT number** (API: "Tax id / VAT number" = `TAX_ID`; value in `fieldMappings[].field`) - the field with the buyer's tax id. When it has a value, the order gets the company details and the number for the invoice. - **Invoice request** (API: "Invoice request" = `INVOICE_REQUESTED`; value in `fieldMappings[].field`) - the field Ritevo reads to tell whether the buyer wants an invoice. Only the value in the field matters: if it is "0", "no", "false" or "off", there is no request; any other value (for example "1", "yes") is a request. When the field is empty, an invoice is requested whenever the buyer gave a tax id. - **Pickup point id** (API: "Pickup point id" = `PICKUP_POINT_ID`; value in `fieldMappings[].field`) - the field with the locker or point code (for example `WAW123`). - **Pickup point name** and **Pickup point description** (API: "Pickup point name" = `PICKUP_POINT_NAME`, "Pickup point description" = `PICKUP_POINT_DESCRIPTION`; value in `fieldMappings[].field`) - the fields with the point's name and address, if the app stores them. - **Pickup point country** (API: "Pickup point country" = `PICKUP_POINT_COUNTRY`; value in `fieldMappings[].field`) - usually stays empty; Ritevo then takes the country from the delivery address. You will find the field name in the Shopify admin in the details of a test order, in the additional details section. Enter it exactly - letter case matters. One field can hold several names (for example after switching apps): Ritevo uses the first one that has a value in the order. ![The Advanced mapping card of the Shopify integration with example field names NIP, Faktura, paczkomat_id and paczkomat_nazwa](https://ritevo.com/docs/integrations/shopify/en-advanced.webp) > **Good to know:** You save mapping changes with the **Update integration** button at the bottom of the page. They apply from the next fetch - orders fetched earlier do not change their status retroactively. You save the mappings with `PATCH /integrations/shops/shopify/{integrationId}`: `orderStatusMappings` (`{ status, externalIds }`), `paymentMethodMappings` (`{ paymentMethod, externalIds }`) and `fieldMappings` (`{ field, keys }`) with every value listed above. Each list must carry every value of its enum - send an unassigned value with an empty list. Status `externalIds` are Shopify payment statuses: `PENDING`, `AUTHORIZED`, `PARTIALLY_PAID`, `PAID`, `PARTIALLY_REFUNDED`, `REFUNDED`, `VOIDED`, `EXPIRED`; payment `externalIds` are gateway names from the Shopify order. The current shape is in Swagger. ### What this integration gives you - **Orders** - new and changed Shopify orders land in the orders table, with the buyer's details, invoice details, delivery and line items with product images. - **Messages** - through an email integration, see below. ### Orders from Shopify Ritevo fetches the whole Shopify order: the buyer, billing and shipping address, shipping method, payment and line items with product images. An order changed in the store (for example once paid) is fetched again. Every order is fetched - including in-person sales (Shopify POS) and test orders. - **Statuses and payments** - translated according to your mapping, described above. The payment number and payment date come from the latest successful capture of the money, and the paid amount is what the buyer actually paid. - **Amounts and VAT** - amounts are in the currency the buyer paid in. VAT rates come from the taxes Shopify charged on each line item; a line item without tax has 0% VAT. - **Tip** - it is a line item of the order, because that is how Shopify sends it, with the VAT rate from Shopify. - **Additional services** - supported. Additional fees added to the order in Shopify show up as separate line items for the whole order, under the store's name for them. Duties, when not included in prices, arrive as a **Duties** line item - a separate one for each VAT rate Shopify charged. More about [additional services](https://ritevo.com/en/docs/orders/fetching-orders#additional-services). - **Delivery** - when an order has several shipping methods, their names are joined with a comma and their costs added up. The dispatch deadline and estimated delivery date go into the order when Shopify provides them. - **Buyer** - the buyer's details come from the billing address, or from the shipping address when there is no billing address. - **Invoice** - the company name comes from the billing address and the tax id from the field set in **Advanced mapping**; with neither a company name nor a tax id the order has no invoice details. The invoice request follows the **Invoice request** field and gives the **Customer asks for an invoice** flag. - **Pickup point** - the point's code and name are read from the fields set in **Advanced mapping**; without them the order has only the delivery address. - **Country of origin** - follows the language and region the buyer ordered in (for example `de-DE` is Germany). When Shopify gives no region, Ritevo takes the store's country. The buyer's country is separate, in their address. - **Buyer's note** - the order note typed at checkout goes into the order as the buyer's message. > **Good to know:** When you turn **Fetch orders** off and back on, Ritevo fetches orders from the moment it was turned off. Shopify only gives access to orders from the last 60 days, so after a longer break older orders can no longer be fetched. Orders from the break arrive in Ritevo as new and can trigger automatic actions - check your actions before turning fetching back on. After more than 90 days without fetching the connection expires and you need to connect the store again. > **Good to know:** An order with the **Confirmed** status is taken over by Ritevo - later changes on the sales channel's side are skipped. More in [Fetching orders](https://ritevo.com/en/docs/orders/fetching-orders#who-manages). ### Buyer messages from Shopify Shopify does not expose its inbox (Shopify Inbox) through its API - buyers write to you **by email** to the store's address. To see and answer those messages in Ritevo, add an [email integration](https://ritevo.com/en/docs/messages/fetching-messages) for that mailbox. The messages then appear in Ritevo like ordinary emails; they are not linked to the Shopify integration or its orders. ### Reconnection required This state appears when the Ritevo app was uninstalled in the Shopify admin or the connection expired - for example when the integration did not connect to the store for over 90 days because fetching orders was off. Until you reconnect, Ritevo neither fetches nor sends any data from that store. 1. Go to **Integrations**, click **Add integration** and pick the **Shopify** tile. 2. Choose **the same** store in Shopify and approve the Ritevo app - just like the first time. 3. Ritevo recognises the store by its address and refreshes the connection in the existing integration. Mappings, fetching settings and history stay unchanged - no second integration is created. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not manage listings: it does not list, change prices or stock in Shopify. - It does not fetch messages - Shopify does not expose them through its API. - It does not carry over a cancellation or refund made in Shopify after the order was confirmed - the order in Ritevo stays unchanged. - It sends nothing back to Shopify: when you change an order's status, create a shipment or issue an invoice in Ritevo, the order in Shopify stays unchanged. ### The integration through the API This integration's endpoints are under `/integrations/shops/shopify`, and the ones shared by the whole type (list, get one, fetching switches, delete, restore) under `/integrations/shops`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/email (updated 2026-09-27) ## E-mail E-mail integration with Ritevo: connecting an IMAP/SMTP mailbox, app passwords, fetching emails as threads and replying to customers from Ritevo. The e-mail integration connects an ordinary mailbox to Ritevo - a company mailbox, Gmail, Outlook or any other that supports IMAP and SMTP. Customer emails land in the shared **Messages** inbox next to marketplace and store conversations, and you reply to them from Ritevo. Through e-mail you also cover sales channels with no inbox of their own - such an integration's page says so. > **Required integration:** You need an e-mail address, the mailbox password (or an app password) and a mailbox that allows IMAP and SMTP connections. One mailbox is connected once; if you handle several addresses, add each one as a separate integration. Within one company account a given address can be connected only once: when you or a colleague add it again, the existing integration is refreshed - even if it was deleted before - and no second one is created. The new password and server settings replace the previous ones. Uniqueness: the integration is unique within the company by `email` and the type `EMAIL`. Creating it again refreshes the existing integration instead of adding a new one: it sets `authError=false` right away, and `active=true` if the integration was inactive. You can also send new credentials with `PATCH /integrations/email/{integrationId}/credentials` - in any state of the integration, also when `authError=false` and `active=true`; it sets `authError=false` and `active=true`. ### App password Some mail providers do not let external programs in with your ordinary sign-in password. You then generate an **app password** in the mail account settings and give that one to Ritevo: - **Gmail** - you create an app password in your Google account settings, under security. It requires 2-step verification. - **Outlook, Yahoo, iCloud** - the same idea: an app password in the account's security settings. - **Company mail at a hosting provider** - the ordinary mailbox password usually works. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **E-mail** section pick the **Email** tile. 3. In the **Account name** field enter your own name for the integration, for example "Customer service". 4. In the **E-mail address** field enter the mailbox address. Ritevo fills in the server details from it right away - see below. 5. In the **Password** field enter the mailbox password or an app password. 6. Click **Add integration**. Ritevo connects to the mail server right away - separately for receiving (IMAP) and sending (SMTP). If both connections work, the integration is added and its settings open. If not - you will see the error returned by the server and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the E-mail filter selected and the Email tile framed](https://ritevo.com/docs/integrations/email/en-catalogue.webp) ![The e-mail add-integration screen with the Account name, E-mail address and Password fields, the app password note and the Show advanced settings button](https://ritevo.com/docs/integrations/email/en-add.webp) ### Server settings (IMAP / SMTP) The server settings sit under **Show advanced settings**. Usually you leave them alone - open them when adding the integration fails: - **Login (optional)** - leave it empty if you sign in with the e-mail address. Fill it in only when the server needs a different login. - **IMAP server (receiving)** and **IMAP port** - where Ritevo fetches emails from. - **SMTP server (sending)** and **SMTP port** - the server Ritevo sends your replies through. - **Encryption** - **SSL/TLS** or **STARTTLS**. Most often: port 993 for IMAP, port 465 with SSL/TLS or 587 with STARTTLS for SMTP. ![The expanded Server settings (IMAP / SMTP) card with the Login, IMAP server, IMAP port, SMTP server, SMTP port and Encryption fields](https://ritevo.com/docs/integrations/email/en-advanced.webp) Ritevo suggests the server details from the address: - **Gmail** - Google's servers, ports 993 and 465, SSL/TLS. - **Outlook, Hotmail, Live** - Microsoft's servers, ports 993 and 587, STARTTLS. - **Any other address** - `imap.` and `smtp.` on the address's domain (for `contact@mystore.com` that is `imap.mystore.com` and `smtp.mystore.com`), ports 993 and 465, SSL/TLS. > **Good to know:** If your mail uses different servers than suggested (common with hosting), you will find the right details in the hosting panel or in the provider's guide, in the part about setting up a mail client. ### Integration settings After connecting, the integration is **Active**, but message fetching is **off** - you turn it on yourself. On the integration page you will find: - **Account name** - your own name for the integration. You can change it at any time. - **E-mail address** - the address given when adding. It cannot be changed; a different address is added as a new integration. - **Fetch messages** - once on, Ritevo checks the mailbox about every 10 minutes, reaching 7 days back on the first fetch. Shared rules: [Fetching messages](https://ritevo.com/en/docs/messages/fetching-messages). - **Server settings (IMAP / SMTP)** - the same fields as when adding, described above. ![E-mail integration details: the account name, e-mail address, the Fetch messages switch, the server settings and the Update credentials and Update integration buttons](https://ritevo.com/docs/integrations/email/en-details.webp) > **Good to know:** You save server setting changes with **Update integration** - Ritevo first checks the new details with the server and saves them only if the connection works. You change the password separately, with **Update credentials**. ### Which emails land in Ritevo Ritevo reads two folders of the mailbox: **inbox** and **sent**. Emails from the same correspondence are joined into one thread, the way a mail client does it: - **Threads** - replies are attached to the conversation they belong to. When the customer's mail client did not mark that, Ritevo joins emails by subject. - **Sent from other programs** - a reply written, say, on your phone shows up in the thread too, because it lands in the sent folder. - **Other folders** - spam, archive and your own folders are not fetched. An email moved there by a mail rule will not reach Ritevo. - **Thread type** - every e-mail thread is a **Message**; e-mail has no disputes or claims. - **Orders** - e-mail threads are not linked to orders automatically, even if the customer wrote the order number in the text. - **Attachments** - you see the customer's attachments in the thread and download them from Ritevo. ### Replying from Ritevo - **Sender** - the reply goes out from the connected mailbox's address, through its SMTP server. The customer sees an ordinary email from you. - **Thread on the customer's side** - the reply lands in the same conversation in the customer's mailbox, not as a new email. - **Sent folder** - the reply is saved to your mailbox's sent folder, so you also see it in your mail client. ### Reconnection required This state appears when the mail server rejected the login or password - most often after the mailbox password changed or an app password was removed. On the integrations list such a mailbox has a red frame and **Reconnection required**. Until you provide a new password, Ritevo neither fetches emails nor sends replies from that mailbox. ![Two mailboxes on the integrations list: one with a red frame and Reconnection required, the other with the Active status](https://ritevo.com/docs/integrations/email/en-status.webp) 1. If you use an app password, generate a new one in the mail account settings. 2. On the integration page in Ritevo click **Update credentials**, enter the password and confirm. Ritevo checks it with the server just like when adding - a wrong password returns an error, a valid one refreshes the connection. The fetching settings and history stay unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not send new emails to customers on its own - you reply in existing threads. - It does not fetch emails from spam, archive or your own folders. - It does not move, flag or delete emails in your mailbox - the mailbox stays as it was. ### The e-mail integration through the API (for AI and integrators) This section exists only in the Markdown version. The e-mail integration has the type `EMAIL` and its own endpoints under `/integrations/email`. Every write that changes the server details or the password first connects to the mail server (IMAP and SMTP) and returns `424` on failure. - `POST /integrations/email` - adds a mailbox. Fields: `accountName` (required, up to 255 characters), `email` (required, an address), `username` (optional - the login when it differs from the address), `password` (required, up to 1000 characters), `imapHost`, `imapPort`, `smtpHost`, `smtpPort` (ports 1-65535), `security` (`SSL_TLS` or `STARTTLS`). `409` when this address is already connected. - `GET /integrations/email` and `GET /integrations/email/{integrationId}` - the list and one mailbox. The response has no password; it has `active`, `authError` (true = **Reconnection required**) and `messageConfig.fetchMessages`. - `PATCH /integrations/email/{integrationId}` - changes `accountName`, `username` and the server settings (the same fields as when adding, without `email` and `password`). - `PATCH /integrations/email/{integrationId}/credentials` - a new password: `{ "password": "..." }`. Clears `authError`. - `PATCH /integrations/email/{integrationId}/fetch-messages` - turns fetching on or off: `{ "fetchMessages": true }`. - `DELETE /integrations/email/{integrationId}` - **Delete integration** (sets `active=false`), `PATCH /integrations/email/{integrationId}/restore` - **Restore integration**. - E-mail threads have `threadType` = `MESSAGE` and no linked order. This integration's endpoints are under `/integrations/email`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. ```json { "accountName": "Sklep - obsługa klienta", "email": "kontakt@mojsklep.pl", "username": null, "password": "haslo-aplikacji", "imapHost": "imap.mojsklep.pl", "imapPort": 993, "smtpHost": "smtp.mojsklep.pl", "smtpPort": 465, "security": "SSL_TLS" } ``` --- Source: https://ritevo.com/en/docs/integrations/whatsapp (updated 2026-09-27) ## WhatsApp WhatsApp integration with Ritevo: connecting a WhatsApp Business number through Meta, the verification PIN, live customer messages and replying to them. The WhatsApp integration connects a WhatsApp Business number to Ritevo. Customer messages land in the shared **Messages** inbox the moment the customer sends them, and you reply from there. > **Required integration:** You need a Facebook account with access to a Meta business account and a phone number to connect as WhatsApp Business. You can create the WhatsApp Business account and add the number while connecting. One integration is one number - Meta's window always ends with one number picked. You connect several numbers one by one, each as a separate integration. Within one company account a number can be connected only once: when you or a colleague connect it again, the existing integration is refreshed - even if it was deleted before - and no second one is created. Uniqueness: the integration is unique within the company by `externalId` and the type `WHATSAPP`. Creating it again refreshes the existing integration instead of adding a new one: it sets `authError=false` right away, and `active=true` if the integration was inactive. With `authError` this is the only way to restore the connection. You connect WhatsApp through Facebook's sign-in window. You never give us your password - Meta passes on only the access you agree to in that window. ### Two-step verification PIN When connecting, you enter the number's 6-digit two-step verification PIN. Meta requires it to register the number for sending messages: - **Number without a PIN** - enter a new PIN; it becomes the number's PIN. Keep it, you will need it to reconnect. - **Number with a PIN** - enter the PIN the number already has. Meta rejects a different one. - **Forgot the PIN** - reset the number's two-step verification in the Meta panel and enter the new PIN when connecting. ### Connecting the account Start from the integrations list: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Messaging** section pick the **WhatsApp** tile. 3. In the **Verification PIN (6 digits)** field enter the number's PIN - see above. 4. Click **Connect WhatsApp**. Meta's window opens. 5. In Meta's window follow the steps: sign in, pick or create a WhatsApp Business account, pick or add a phone number and confirm sharing the data with **Continue**. 6. Go back to the integrations window. We check with Meta that you have access to the chosen account and number, connect the number for receiving messages and open the new integration's settings. If something does not match, you see the error returned by Meta and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The WhatsApp add-integration screen with the Verification PIN (6 digits) field, the PIN hint and the Connect WhatsApp button](https://ritevo.com/docs/integrations/whatsapp/en-add.webp) ![The Facebook for business sign-in window describing the WhatsApp Business account connection, with the Continue button](https://ritevo.com/docs/integrations/whatsapp/en-meta.webp) > **Good to know:** If the Facebook window stays blank or freezes, close it and click the connect button again - it is a fault on Facebook's side. Then follow the steps in the Facebook window. ### Integration settings The integration is **Active** and receives messages right away - there is no fetching switch here, because WhatsApp delivers messages as they arrive. On the integration page you will find, read-only: - **Account name** - the connected phone number. - **WABA ID** - the WhatsApp Business account's id in Meta. - **Phone number ID** - the number's id in Meta. ![WhatsApp integration details: account name, WABA ID and phone number ID, read-only](https://ritevo.com/docs/integrations/whatsapp/en-details.webp) ![The Messaging section of the integrations list with the WhatsApp and Messenger tiles marked Active](https://ritevo.com/docs/integrations/whatsapp/en-list.webp) ### Messages from WhatsApp - **Conversation history** - WhatsApp does not share history, so we store the messages and attachments ourselves from the moment of connecting. You can read them even when the integration needs reconnecting - without a connection you only cannot send replies. - **Live** - a customer's message shows up in the inbox right away, with no waiting for the next check. - **Threads** - each conversation with one customer number is one thread of the **Message** type. It is not linked to an order automatically. - **Replies from other programs** - if you also reply to customers on this number from another program, the thread shows only that a message was sent at that time - without its content. This is a WhatsApp limitation: it does not pass on the content of messages sent from other programs. To keep the whole conversation, reply to customers only in Ritevo. ### Replying to customers - **Right in the thread** - a sent reply shows in the thread right away, and its status changes once WhatsApp confirms delivery. - **24 hours** - WhatsApp lets you reply freely for 24 hours after the customer's last message. After that it rejects an ordinary reply and you see an error. From then on a conversation can only be started with an approved WhatsApp template - we do not send such templates yet, so you can write again only once the customer writes first. ### Reconnection required This state appears when Meta stopped accepting our access to the number - for example after the app's permissions were removed in the Meta business account settings. Until you reconnect, you cannot send replies from that number. 1. Go through **Connecting the account** again and pick the **same** number in Meta's window. 2. Enter the **same PIN** the number already has. The connection is refreshed in the existing integration - the history stays, no second integration is created. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not fetch conversations from before the number was connected. - It does not send approved WhatsApp templates, so it cannot start a conversation after the 24 hours. - It does not show the content of messages sent from another program connected to this number. ### The WhatsApp integration through the API (for AI and integrators) This section exists only in the Markdown version. The integration has the type `MESSAGING` and the provider `WHATSAPP`. Connecting needs Meta's window (Embedded Signup) in a browser, so the API alone cannot create the integration without a person. - `POST /integrations/messaging/whatsapp` - creates the integration from the result of Meta's window: `code` (single-use authorization code), `wabaId`, `phoneNumberId` and `verificationPin` (6 digits). The backend checks with Meta that the code grants access to that account and number; connecting the same number again refreshes the existing integration. - `GET /integrations/messaging/{integrationId}` - the integration: `accountName` (the number), `externalId` (`wabaId::-::phoneNumberId`), `phoneNumberId`, `displayPhoneNumber`, `active`, `authError` (true = **Reconnection required**). No access token. - `DELETE /integrations/messaging/{integrationId}` - **Delete integration**, `PATCH /integrations/messaging/{integrationId}/restore` - **Restore integration**. - Threads have `threadType` = `MESSAGE` and no linked order. You send a reply the same way as in other channels. This integration's endpoints are under `/integrations/messaging/whatsapp`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/messaging`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. Disconnecting the app on Meta's side: Meta does not notify Ritevo when access is removed. New messages stop arriving, and the integration gets `authError=true` on the first request to Meta, for example when sending a reply. The stored conversation history stays. --- Source: https://ritevo.com/en/docs/integrations/messenger (updated 2026-09-27) ## Messenger Messenger integration with Ritevo: connecting a Facebook Page, live customer messages, replying, attachments and reconnecting. The Messenger integration connects a Facebook Page to Ritevo. Messages customers send to the Page through Messenger land in the shared **Messages** inbox right away, and you reply from there. > **Required integration:** You need a Facebook Page and an account with full access to it. One integration is one Page. In Facebook's window tick exactly **one** Page - if you tick several, you see an error and nothing is saved. You connect several Pages one by one, each as a separate integration. Within one company account a Page can be connected only once: when you or a colleague connect it again, the existing integration is refreshed - even if it was deleted before - and no second one is created. Uniqueness: the integration is unique within the company by `externalId` and the type `MESSENGER`. Creating it again refreshes the existing integration instead of adding a new one: it sets `authError=false` right away, and `active=true` if the integration was inactive. With `authError` this is the only way to restore the connection. You connect Messenger through Facebook's sign-in window. You never give us your password - Meta passes on only the access you agree to in that window. ### Connecting the account Start from the integrations list: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Messaging** section pick the **Messenger** tile. 3. Click **Connect with Facebook**. Facebook's window opens. 4. Sign in and tick **one** Page you want to connect. If you have connected your account with Facebook before, the window asks whether to continue with the previous settings - click **Edit settings** to pick another Page, or **Continue**. 5. Go back to the integrations window and wait a moment - do not close it. We connect the Page for receiving messages and open the new integration's settings. If something fails, you see the error returned by Facebook and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Messenger add-integration screen with the note about picking one Page and the Connect with Facebook button](https://ritevo.com/docs/integrations/messenger/en-add.webp) ![The Facebook for business sign-in window asking whether to continue with the previous settings, with the Edit settings and Continue buttons](https://ritevo.com/docs/integrations/messenger/en-facebook.webp) > **Good to know:** If the Facebook window stays blank or freezes, close it and click the connect button again - it is a fault on Facebook's side. Then follow the steps in the Facebook window. ### Integration settings The integration is **Active** and receives messages right away - there is no fetching switch here, because Messenger delivers messages as they arrive. On the integration page you will find, read-only: - **Page name** - the name of the connected Facebook Page. - **Page ID** - the Page's id in Facebook. ![Messenger integration details: Page name and Page ID, read-only](https://ritevo.com/docs/integrations/messenger/en-details.webp) ![The Messaging section of the integrations list with the WhatsApp and Messenger tiles marked Active](https://ritevo.com/docs/integrations/messenger/en-list.webp) ### Messages from Messenger - **Conversation history** - Messenger does not share history, so we store the messages and attachments ourselves from the moment of connecting. You can read them even when the integration needs reconnecting - without a connection you only cannot send replies. - **Live** - a customer's message shows up in the inbox right away, with no waiting for the next check. - **Threads** - each conversation with one person is one thread of the **Message** type, labelled with the name from their profile. It is not linked to an order automatically. - **Page buttons** - when the customer taps a button set up on your Page in Messenger instead of writing (for example "Get started" or a menu item), the thread shows a message with that button's name. ### Replying to customers - **Right in the thread** - a sent reply shows in the thread right away, and its status changes once Messenger confirms it was sent. - **Attachment and text** - Messenger does not send a file and text in one message, so the customer gets two: the file first, then the text. - **24 hours** - Messenger lets you reply freely for 24 hours after the customer's last message. After that it rejects an ordinary reply and you see an error. From then on you can only write with messages carrying a special Meta tag (for example a human agent reply within 7 days) - we do not send such messages yet, so you can write again only once the customer writes first. ### Reconnection required This state appears when Facebook stopped accepting our access to the Page - for example after a password change, losing permissions to the Page or disconnecting the app in Facebook's settings. Until you reconnect, you cannot send replies from that Page. 1. Go through **Connecting the account** again and pick the **same** Page in Facebook's window. 2. The connection is refreshed in the existing integration - the history stays, no second integration is created. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not fetch conversations from before the Page was connected. - It does not start conversations with customers - you reply in conversations the customer opened. - It does not send messages with a special Meta tag, so it cannot write to the customer after the 24 hours. - It does not handle post comments or Instagram messages. ### The Messenger integration through the API (for AI and integrators) This section exists only in the Markdown version. The integration has the type `MESSAGING` and the provider `MESSENGER`. Connecting needs Facebook's sign-in window in a browser, so the API alone cannot create the integration without a person. - `POST /integrations/messaging/messenger` - creates the integration from the result of Facebook's window: `code` (single-use authorization code) and `redirectUri` (the URL of the page that opened the window - it must match exactly). Connecting the same Page again refreshes the existing integration. - `GET /integrations/messaging/{integrationId}` - the integration: `accountName` (Page name), `externalId` (Page id), `active`, `authError` (true = **Reconnection required**). No access token. - `DELETE /integrations/messaging/{integrationId}` - **Delete integration**, `PATCH /integrations/messaging/{integrationId}/restore` - **Restore integration**. - Threads have `threadType` = `MESSAGE` and no linked order. You send a reply the same way as in other channels. This integration's endpoints are under `/integrations/messaging/messenger`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/messaging`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. Disconnecting the app on Meta's side: Meta does not notify Ritevo when access is removed. New messages stop arriving, and the integration gets `authError=true` on the first request to Meta, for example when sending a reply. The stored conversation history stays. --- Source: https://ritevo.com/en/docs/integrations/wfirma (updated 2026-09-29) ## wFirma wFirma integration with Ritevo: connecting with API keys, sending invoices and receipts, VAT and contractor settings, reconnecting. The wFirma integration sends invoices and receipts issued in Ritevo to wFirma. You connect it with API keys from the wFirma panel and pick the company the documents should go to. > **Required integration:** You need a wFirma account and API keys generated in its panel: an access key (Access Key) and a secret key (Secret Key). You can add as many wFirma integrations as you like, including several for the same account - for example with different details or different document settings. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. `externalId` is the wFirma company ID. The companies available for the keys are returned by `POST /integrations/accountings/wfirma/companies`. You provide new keys with `PATCH /integrations/accountings/wfirma/{id}/credentials` - in any state of the integration. It checks that the keys see the `externalId` company and sets `authError=false` and `active=true`. ### Which documents it sends - **VAT invoice** (API: "VAT invoice" = `INVOICE`; value in `billingType`) - goes to wFirma as a VAT invoice or an invoice without VAT, depending on the **Invoice with VAT** setting on the integration page. - **Receipt** (API: "Receipt" = `RECEIPT`; value in `billingType`) - goes to wFirma as a receipt with or without VAT, depending on the **Receipt with VAT** setting on the integration page. - **Invoice correction** (API: "Invoice correction" = `CORRECTION`; value in `billingType`) - not supported. ### How to generate the API key You create API keys in the wFirma panel. wFirma shows the Secret Key only once, so copy both keys straight away - you will paste them into Ritevo when adding the integration. 1. Sign in to wFirma. 2. Go to **Ustawienia** → **Bezpieczeństwo** → **Aplikacje** → **Klucze API** (settings, security, applications, API keys) and click **Dodaj** (add). 3. Enter a name, for example "Ritevo", and confirm with your wFirma password. 4. Copy the **Access Key** and the **Secret Key**. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Accounting** section pick the **wFirma** tile. 3. Paste the **Access key (Access Key)** and the **Secret key (Secret Key)** and click **Next step**. We check the keys in wFirma - if they are wrong, you will see the error returned by wFirma. 4. From the **Select company** list pick the company from your wFirma account and click **Create integration**. The new integration's settings open. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the wFirma tile framed in the Accounting section](https://ritevo.com/docs/integrations/wfirma/en-catalogue.webp) ![The wFirma add-integration screen with the Access key and Secret key fields and the Next step button](https://ritevo.com/docs/integrations/wfirma/en-add.webp) ### Integration settings The integration is named after the company fetched from wFirma - you cannot change it. On the integration page you will find: - **Integration settings** - fixed rules: we send gross amounts only, wFirma numbers the document with its own numbering, and wFirma accepts Polish VAT rates only - more below. - **Create contractors** - once on, wFirma adds the buyer to its contractor list if they are not there yet. Off by default. - **Invoice with VAT** / **Invoice without VAT** - the kind of invoice created in wFirma. With VAT by default. - **Receipt with VAT** / **Receipt without VAT** - the kind of receipt created in wFirma. With VAT by default. - **Update credentials** - you enter new API keys for the same company. Creating: `accessKey`, `secretKey` and `externalId` - the company ID from `POST /integrations/accountings/wfirma/companies`, which returns `id:name` entries. You change settings with separate `PATCH` calls: `/{id}/invoice-with-vat` with `invoiceWithVat` (**Invoice with VAT** = `true`), `/{id}/receipt-with-vat` with `receiptWithVat` (**Receipt with VAT** = `true`) and `/{id}/auto-create-contractors` with `autoCreateContractors` (**Create contractors** = `true`). > **Good to know:** The switches save right away and apply to documents sent from then on. ### Sending documents > **Good to know:** One order can have only one active invoice and one active receipt. You issue another document of the same type only after deleting the previous one. You can issue any number of corrections to an invoice. You issue documents in the order. You send them to wFirma in two ways: - **By hand** - in the document details, in the **External accounting systems** card, click the button with the wFirma account name. The button shows up only on documents this integration supports. - **Automatically** - with the **Send invoice to external accounting** or **Send receipt to external accounting** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). Plan sending documents step by step - first issuing, then sending: - **Invoice** - the first action ends with the **Generate invoice** step. The second starts on the **Invoice (added/removed)** trigger, has the **Has invoice** condition and the **Send invoice to external accounting** step. - **Receipt** - the same: the first action ends with the **Generate receipt** step, and the second starts on the **Receipt (added/removed)** trigger, has the **Has receipt** condition and the **Send receipt to external accounting** step. - **Corrections** - you can issue many corrections to one invoice. Send each right after issuing it, before you issue the next one. > **Good to know:** The send step always sends just one document - the newest non-deleted one of that type. If you first issue all documents and only then turn on sending, only the last one goes out, and you send the others by hand. You cannot send a deleted document. In the same card every sending has its own icon. Hover over it to see the account, the state and the date: - **Sending** (API: "Sending" = `PENDING`; value in `externalTransfers[].status`) - the document is sent and we are waiting for wFirma to confirm it. - **Sent successfully** (API: "Sent successfully" = `SUCCESS`; value in `externalTransfers[].status`) - the document is in wFirma. Click the icon to download or open it. - **Sending failed** (API: "Sending failed" = `FAILED`; value in `externalTransfers[].status`) - the document did not reach wFirma. The reason is shown under the state. > **Good to know:** A document has only one sending to a given integration: you send it there once. If the sending fails, you can retry it with the same button. You send the same document to another accounting integration separately. Order actions: the **Send invoice to external accounting** and **Send receipt to external accounting** steps are `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` and `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` in `actionSteps[].action.type`, with `uuidValue` = the accounting integration id (`GET /integrations/accountings`). The **Invoice sent to external accounting** and **Receipt sent to external accounting** triggers are `triggerType` = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING` and `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. The **Has a successful invoice transfer to external accounting** / **Has no successful invoice transfer to external accounting** conditions are `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`, and for receipts `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT` (`uuidValues` = accounting integration ids). Only a `SUCCESS` transfer counts. The step takes the latest document in the order's `billings[]` with the given `billingType` (`INVOICE` or `RECEIPT`) and `deleted` = `false`. An order has at most one document of a given `billingType` with `deleted` = `false` - issuing a second one returns `BILLING_ALREADY_EXISTS`. Full description: [Order actions](https://ritevo.com/en/docs/automations/order-actions). #### How a document reaches wFirma - **Right away** - wFirma answers straight away, so the document is **Sent successfully** or **Sending failed** right after sending. - **Number and dates** - wFirma assigns the number. The issue date, sale date and payment due date come from the document in Ritevo. - **PDF** - clicking the icon downloads the PDF generated by wFirma. - **VAT rates** - wFirma accepts 23%, 8%, 5%, 0%, WDT (intra-EU supply), Zw. (exempt) and O.o (reverse charge) from us, and OSS rates are matched to the buyer's country. A document with any other rate is not sent - you will see the **Tax rate not supported** error. ### Reconnection required This state shows up when wFirma stops accepting the API keys - for example after they were deleted in the wFirma panel. Until you enter new keys, documents will not reach wFirma. 1. Generate new API keys in the wFirma panel - the same way as the first time. 2. On the integration page click **Update credentials**, paste both keys and confirm. We check them in wFirma - the keys must have access to the same company. Correct ones refresh the connection, and the settings and the history of sent documents stay unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo. Documents sent earlier stay in wFirma. **Restore integration** turns it back on. ### What the integration does not do - It does not send invoice corrections. - It does not change or delete documents that are already in wFirma. - It does not fetch documents from wFirma into Ritevo. ### The integration through the API This integration's endpoints are under `/integrations/accountings/wfirma`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/accountings`. You send a document with `POST /orders/billings/{billingId}/transfer-to-external-accounting/{integrationId}`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/ksef (updated 2026-09-29) ## KSeF KSeF integration with Ritevo: connecting with a KSeF certificate, sending invoices and corrections online, the KSeF number, reconnecting. The KSeF integration sends invoices and corrections issued in Ritevo to KSeF, the Polish National e-Invoicing System. You connect it with a KSeF certificate, and invoices go to KSeF in online mode. > **Required integration:** You need the company's NIP (Polish tax ID) and a KSeF authentication certificate: the private key file (.key), the password to that key and the certificate file (.pem or .crt). You can add as many KSeF integrations as you like, including several for the same account - for example with different details or different document settings. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. `externalId` is the NIP. You provide a new certificate with `PUT /integrations/accountings/ksef/{id}/certificate` - in any state of the integration. After a successful KSeF sign-in it sets `authError=false` and `active=true`. ### Which documents it sends - **VAT invoice** (API: "VAT invoice" = `INVOICE`; value in `billingType`) - goes to KSeF as a basic invoice. - **Invoice correction** (API: "Invoice correction" = `CORRECTION`; value in `billingType`) - goes to KSeF as a corrective invoice. - **Receipt** (API: "Receipt" = `RECEIPT`; value in `billingType`) - not supported. ### How to get a KSeF certificate You generate the certificate in Aplikacja Podatnika KSeF, the Ministry of Finance's KSeF taxpayer application. The private key password cannot be recovered, so keep it together with both files - you will enter them in Ritevo when adding the integration. If you lose the password or the key file, the only way out is to generate a new certificate with a new key pair. 1. Sign in to Aplikacja Podatnika KSeF, for example with Profil Zaufany (the Polish trusted profile). 2. In the certificates section choose **Wnioskuj o certyfikat** (request a certificate). 3. Choose the authentication certificate, enter its name and set the private key password. 4. Click **Generuj** (generate). The private key file (.key) is saved on your computer. 5. Once the request is approved, download the certificate file (.crt). ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Accounting** section pick the **KSeF** tile. 3. In the **Account name** field enter your own name for the integration, and in the **Nip** field the NIP of the company you issue invoices for. 4. Add the **Private key file (.key)**, enter the **Key password** and add the **Certificate file (.pem/.crt)**. 5. Click **Create integration**. We sign in to KSeF with the certificate right away: if it works, the integration is added and its settings open. If not - you will see an error and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the KSeF tile framed in the Accounting section](https://ritevo.com/docs/integrations/ksef/en-catalogue.webp) ![The KSeF add-integration screen with the Account name and Nip fields, the certificate files and the key password](https://ritevo.com/docs/integrations/ksef/en-add.webp) ### Integration settings On the integration page you will find: - **Invoices are sent in online mode** - every invoice goes to KSeF as soon as you send it. - **Account name** - your own name for the integration. You change it and save it with **Update integration**. - **Update credentials** - you enter new files and a password, for example when the certificate is about to expire. We check them in KSeF the same way as when adding. Creating: `accountName`, `nip`, `certificateBase64` (the .key file in Base64), `certificatePassword` and `certificatePemBase64` (the .pem or .crt file in Base64). You change the name with `PATCH /integrations/accountings/ksef/{id}` with `accountName`, and the certificate with `PUT /integrations/accountings/ksef/{id}/certificate` with the same three certificate fields. ![KSeF integration details: the online mode note, the account name and the Update credentials button](https://ritevo.com/docs/integrations/ksef/en-details.webp) ### Sending documents > **Good to know:** One order can have only one active invoice and one active receipt. You issue another document of the same type only after deleting the previous one. You can issue any number of corrections to an invoice. You issue documents in the order. You send them to KSeF in two ways: - **By hand** - in the document details, in the **External accounting systems** card, click the button with the KSeF account name. The button shows up only on documents this integration supports. - **Automatically** - with the **Send invoice to external accounting** or **Send receipt to external accounting** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). Plan sending documents step by step - first issuing, then sending: - **Invoice** - the first action ends with the **Generate invoice** step. The second starts on the **Invoice (added/removed)** trigger, has the **Has invoice** condition and the **Send invoice to external accounting** step. - **Receipt** - the same: the first action ends with the **Generate receipt** step, and the second starts on the **Receipt (added/removed)** trigger, has the **Has receipt** condition and the **Send receipt to external accounting** step. - **Corrections** - you can issue many corrections to one invoice. Send each right after issuing it, before you issue the next one. > **Good to know:** The send step always sends just one document - the newest non-deleted one of that type. If you first issue all documents and only then turn on sending, only the last one goes out, and you send the others by hand. You cannot send a deleted document. In the same card every sending has its own icon. Hover over it to see the account, the state and the date: - **Sending** (API: "Sending" = `PENDING`; value in `externalTransfers[].status`) - the document is sent and we are waiting for KSeF to confirm it. - **Sent successfully** (API: "Sent successfully" = `SUCCESS`; value in `externalTransfers[].status`) - the document is in KSeF. Click the icon to download or open it. - **Sending failed** (API: "Sending failed" = `FAILED`; value in `externalTransfers[].status`) - the document did not reach KSeF. The reason is shown under the state. > **Good to know:** A document has only one sending to a given integration: you send it there once. If the sending fails, you can retry it with the same button. You send the same document to another accounting integration separately. Order actions: the **Send invoice to external accounting** and **Send receipt to external accounting** steps are `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` and `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` in `actionSteps[].action.type`, with `uuidValue` = the accounting integration id (`GET /integrations/accountings`). The **Invoice sent to external accounting** and **Receipt sent to external accounting** triggers are `triggerType` = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING` and `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. The **Has a successful invoice transfer to external accounting** / **Has no successful invoice transfer to external accounting** conditions are `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`, and for receipts `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT` (`uuidValues` = accounting integration ids). Only a `SUCCESS` transfer counts. The step takes the latest document in the order's `billings[]` with the given `billingType` (`INVOICE` or `RECEIPT`) and `deleted` = `false`. An order has at most one document of a given `billingType` with `deleted` = `false` - issuing a second one returns `BILLING_ALREADY_EXISTS`. Full description: [Order actions](https://ritevo.com/en/docs/automations/order-actions). #### How an invoice reaches KSeF - **Confirmation** - KSeF processes the invoice after receiving it, so at first it is **Sending**. We check the KSeF response every few seconds. If KSeF does not confirm the invoice within 24 hours, the sending ends with an error. - **Numbers and date** - the invoice carries the number assigned in Ritevo. Once accepted, KSeF gives it a KSeF number. The issue date in KSeF is the day of sending. - **PDF** - clicking the icon downloads a PDF prepared from the invoice stored in KSeF, with the KSeF number. - **Corrections** - you send them by hand. Automatic actions send only invoices and receipts. - **VAT rates** - KSeF accepts 23%, 8%, 5%, 0%, WDT (intra-EU supply), Zw. (exempt) and O.o (reverse charge) from us, as well as the former 22% and 7%. OSS rates are sent as OSS sales. An invoice with any other rate is not sent - you will see the **Tax rate not supported** error. ### Reconnection required This state shows up when KSeF stops accepting the certificate - for example after it expired or was revoked. Until then invoices will not reach KSeF. 1. Generate a new KSeF certificate - the same way as the first time. 2. On the integration page click **Update credentials**, add the new files, enter the password and confirm. A valid certificate refreshes the connection, and the history of sent invoices stays unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ![The Update credentials window of the KSeF integration with fields for the private key file, the key password and the certificate file](https://ritevo.com/docs/integrations/ksef/en-update.webp) ### Deleting the integration **Delete integration** turns the integration off in Ritevo. Documents sent earlier stay in KSeF. **Restore integration** turns it back on. ### What the integration does not do - It does not send receipts. - It does not send invoices in offline mode - online only. - It does not change invoices that are already in KSeF - you make changes with a correction. - It does not fetch purchase invoices or other documents from KSeF. ### The integration through the API This integration's endpoints are under `/integrations/accountings/ksef`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/accountings`. You send a document with `POST /orders/billings/{billingId}/transfer-to-external-accounting/{integrationId}`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/eparagony (updated 2026-09-29) ## eparagony.pl eparagony.pl integration with Ritevo: connecting with API credentials, sending receipts, fiscalisation and printing, webhook secret, reconnecting. The eparagony.pl integration sends receipts issued in Ritevo to eParagony. You connect it with API credentials from the eParagony panel and point it at a point of sale. > **Required integration:** You need an eParagony account with a point of sale and API credentials: Client ID, Client Secret, the webhook secret and the point of sale ID (posId). You can add as many eparagony.pl integrations as you like, including several for the same account - for example with different details or different document settings. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. `externalId` is the `posId`. You provide new credentials with `PATCH /integrations/accountings/eparagony/{id}/credentials` - in any state of the integration. It checks the Client ID and Client Secret in eParagony and sets `authError=false` and `active=true`. ### Which documents it sends - **Receipt** (API: "Receipt" = `RECEIPT`; value in `billingType`) - goes to eParagony as an e-receipt. - **VAT invoice** and **Invoice correction** (API: "VAT invoice" = `INVOICE`, "Invoice correction" = `CORRECTION`; value in `billingType`) - not supported. ### Where to find the credentials eParagony provides the API credentials after you register for the service, together with the API documentation. Have them ready before adding the integration: 1. Create an eparagony.pl account if you do not have one yet. 2. Have the **Client ID**, the **Client Secret** and the webhook secret ready. 3. Have the ID of the point of sale (posId) the receipts should go to ready. 4. If you cannot find these details, write to eParagony support: pomoc@eparagony.pl. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Accounting** section pick the **eParagony** tile. 3. In the **Basic settings** card enter the **Account name** - your own name for the integration - and the **Point of sale ID (posId)**. 4. In the **Credentials** card paste the **Client ID**, the **Client Secret** and the **Webhook secret**. 5. In the **Integration settings** card set **Fiscalise documents** and **Print receipt** - described below. 6. Click **Create integration**. We check the Client ID and Client Secret in eParagony right away: if they are correct, the integration is added and its settings open. If not - you will see an error and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the eParagony tile framed in the Accounting section](https://ritevo.com/docs/integrations/eparagony/en-catalogue.webp) ![The eParagony add-integration screen with the Basic settings, Credentials and Integration settings cards](https://ritevo.com/docs/integrations/eparagony/en-add.webp) ### Integration settings On the integration page you will find the fields below. You save changes to the name and switches with **Update integration**: - **Account name** - your own name for the integration. You can change it at any time. - **Point of sale ID (posId)** - the point entered when adding. It cannot be changed - you add another point as a new integration. - **Fiscalise documents** - once on, eParagony fiscalises the receipt. This needs the eParagony document printing service running on your side. On by default. - **Print receipt** - once on, eParagony prints the receipt. For a stationary point of sale only. Off by default. - **Update credentials** - you enter a new Client ID, Client Secret and webhook secret. Creating: `accountName`, `posId`, `clientId`, `clientSecret`, `webhookSecret`, `fiscalize` (**Fiscalise documents**) and `print` (**Print receipt**) - both `true` or `false`. You change settings with `PATCH /integrations/accountings/eparagony/{id}` with `accountName`, `fiscalize` and `print`. > **Good to know:** The webhook secret cannot be checked on saving. If it is wrong, the receipt reaches eParagony, but we get no confirmation and the sending stays **Sending**. Enter it exactly as it is in the eParagony panel. ### Sending documents > **Good to know:** One order can have only one active invoice and one active receipt. You issue another document of the same type only after deleting the previous one. You can issue any number of corrections to an invoice. You issue documents in the order. You send them to eparagony.pl in two ways: - **By hand** - in the document details, in the **External accounting systems** card, click the button with the eparagony.pl account name. The button shows up only on documents this integration supports. - **Automatically** - with the **Send invoice to external accounting** or **Send receipt to external accounting** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). Plan sending documents step by step - first issuing, then sending: - **Invoice** - the first action ends with the **Generate invoice** step. The second starts on the **Invoice (added/removed)** trigger, has the **Has invoice** condition and the **Send invoice to external accounting** step. - **Receipt** - the same: the first action ends with the **Generate receipt** step, and the second starts on the **Receipt (added/removed)** trigger, has the **Has receipt** condition and the **Send receipt to external accounting** step. - **Corrections** - you can issue many corrections to one invoice. Send each right after issuing it, before you issue the next one. > **Good to know:** The send step always sends just one document - the newest non-deleted one of that type. If you first issue all documents and only then turn on sending, only the last one goes out, and you send the others by hand. You cannot send a deleted document. In the same card every sending has its own icon. Hover over it to see the account, the state and the date: - **Sending** (API: "Sending" = `PENDING`; value in `externalTransfers[].status`) - the document is sent and we are waiting for eparagony.pl to confirm it. - **Sent successfully** (API: "Sent successfully" = `SUCCESS`; value in `externalTransfers[].status`) - the document is in eparagony.pl. Click the icon to download or open it. - **Sending failed** (API: "Sending failed" = `FAILED`; value in `externalTransfers[].status`) - the document did not reach eparagony.pl. The reason is shown under the state. > **Good to know:** A document has only one sending to a given integration: you send it there once. If the sending fails, you can retry it with the same button. You send the same document to another accounting integration separately. Order actions: the **Send invoice to external accounting** and **Send receipt to external accounting** steps are `TRANSFER_INVOICE_TO_EXTERNAL_ACCOUNTING` and `TRANSFER_RECEIPT_TO_EXTERNAL_ACCOUNTING` in `actionSteps[].action.type`, with `uuidValue` = the accounting integration id (`GET /integrations/accountings`). The **Invoice sent to external accounting** and **Receipt sent to external accounting** triggers are `triggerType` = `TRANSFERRED_INVOICE_TO_EXTERNAL_ACCOUNTING` and `TRANSFERRED_RECEIPT_TO_EXTERNAL_ACCOUNTING`. The **Has a successful invoice transfer to external accounting** / **Has no successful invoice transfer to external accounting** conditions are `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_INVOICE_TO_ACCOUNTING_NOT`, and for receipts `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING` / `HAS_SUCCESSFUL_EXTERNAL_TRANSFER_RECEIPT_TO_ACCOUNTING_NOT` (`uuidValues` = accounting integration ids). Only a `SUCCESS` transfer counts. The step takes the latest document in the order's `billings[]` with the given `billingType` (`INVOICE` or `RECEIPT`) and `deleted` = `false`. An order has at most one document of a given `billingType` with `deleted` = `false` - issuing a second one returns `BILLING_ALREADY_EXISTS`. Full description: [Order actions](https://ritevo.com/en/docs/automations/order-actions). #### How a receipt reaches eParagony - **Without fiscalisation** - eParagony accepts the receipt straight away, so it is **Sent successfully** right after sending. - **With fiscalisation** - the receipt stays **Sending** until eParagony confirms the fiscalisation. Then it changes to **Sent successfully** or to **Sending failed** with the reason from eParagony. - **Number** - in eParagony the receipt carries the number assigned in Ritevo. - **Preview** - clicking the icon opens the receipt on the eParagony site. - **VAT rates** - eParagony accepts 23%, 8%, 5%, 0% and Zw. (exempt) from us, as well as the former 22%, 7% and 3%. A receipt with any other rate is not sent - you will see the **Tax rate not supported** error. ### Reconnection required This state shows up when eParagony stops accepting the Client ID and Client Secret - for example after they were changed in the eParagony panel. Until then receipts will not reach eParagony. 1. Copy the current credentials in the eParagony panel. 2. On the integration page click **Update credentials**, paste the Client ID, Client Secret and webhook secret and confirm. We check them in eParagony the same way as when adding - correct ones refresh the connection. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo. Documents sent earlier stay in eparagony.pl. **Restore integration** turns it back on. ### What the integration does not do - It does not send invoices or corrections. - It does not change or cancel receipts that are already in eParagony. ### The integration through the API This integration's endpoints are under `/integrations/accountings/eparagony`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/accountings`. You send a document with `POST /orders/billings/{billingId}/transfer-to-external-accounting/{integrationId}`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/send-with-allegro (updated 2026-10-07) ## Send with Allegro Send with Allegro in Ritevo: linking the Allegro account, parcel and drop-off point settings, creating shipments and labels for Allegro orders. The Send with Allegro integration (Wysyłam z Allegro) creates shipments for Allegro orders through the Send with Allegro service. It has no login of its own - it uses the Allegro account you already connected in Ritevo. > **Required integration:** You need an Allegro account connected in Ritevo as an [Allegro integration](https://ritevo.com/en/docs/integrations/allegro). You can add as many Send with Allegro integrations as you like, including several for the same account - for example with a different label format, parcel or sender address. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. `externalId` is not used. The integration points to the Allegro account with `marketplaceAccountId`. There is no credentials endpoint - an auth error belongs to the Allegro integration under `/integrations/marketplaces`, and saving this integration's settings always sets `authError=false` and `active=true`. ### Which shipments it creates - **Allegro orders only** - from the Allegro account you pick in the integration. For other orders you will not see the button, and an action ends with the **The order is not compatible with the selected integration or shipping method** error. - **Carrier** - the one the buyer chose on Allegro. You do not pick it in Ritevo. - **Pickup point** - when the buyer chose a parcel locker or a point, the shipment goes there. - **Cash on delivery** - when the order is cash on delivery and the chosen Allegro delivery supports it. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Shipments** section pick the **Wysyłam z Allegro** tile. 3. In the **Allegro marketplace account** field pick the account whose orders you want to ship, and in the **Account name** field enter your own name for the integration. 4. Fill in the other settings described below and click **Create integration**. The new integration's settings open. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Wysyłam z Allegro tile framed in the Shipments section](https://ritevo.com/docs/integrations/send-with-allegro/en-catalogue.webp) ![The Send with Allegro add screen with the Allegro marketplace account, Account name, Page size and Label format fields](https://ritevo.com/docs/integrations/send-with-allegro/en-add.webp) ### Integration settings On the integration page you will find the fields below. You save changes with **Update integration**: - **Allegro marketplace account** - the Allegro account whose orders you ship. - **Account name** - your own name for the integration. - **Page size** - A4 or A6. A4 by default. - **Label format** - PDF or ZPL. PDF by default. - **Pickup points** - the numbers of the points where you drop off parcels of each carrier: DPD, Poczta Polska, Allegro One, Allegro International and InPost. An empty field means a courier collects the parcel, a filled one that you drop it off at that point. The **UPS point number** is not used today. - **Parcel details** - the type (**Parcel**, **Letter**, **Pallet** or **Other**), the dimensions in centimetres and the weight in kilograms. These go into every shipment. - **Cash on delivery** - the **IBAN account number** and the **Account owner**. We send them only when the chosen Allegro delivery requires them. - **Sender address on the label** - the sender details the carrier prints on the label. - **Courier pickup address** - the address the courier collects parcels from. It can differ from the sender address on the label - for example in dropshipping: the label shows your shop, and the courier collects the parcel from the wholesaler. - **Additional insurance** - the insurance amount of every shipment: **None**, **Order value with delivery**, **Order value without delivery** or **Fixed amount**. In **Currency source** you pick the order currency, the delivery country currency or a fixed currency. Integration fields: `accountName`, `marketplaceAccountId` (the Allegro integration id from `GET /integrations/marketplaces`), `pageSize` = `A4` or `A6`, `labelFormat` = `PDF` or `ZPL`, point numbers `dpdPickupPointNumber`, `upsPickupPointNumber`, `pocztaPolskaPickupPointNumber`, `allegroOnePickupPointNumber`, `allegroInternationalPickupPointNumber`, `inPostPickupPointNumber`, `packageDetails` with `packageType` (**Parcel** = `PACKAGE`, **Letter** = `DOX`, **Pallet** = `PALLET`, **Other** = `OTHER`) and `length`, `width`, `height` in cm and `weight` in kg, plus `cashOnDeliveryBankDetails` with `iban` and `ownerName`. Fields shared by shipping integrations: `senderAddress` and `pickupAddress` (`companyName`, `firstName`, `lastName`, `street`, `city`, `zipCode`, `countryCode`, `phoneNumber`, `email`) and `additionalInsurance`. In it `insuranceType`: **None** = `NONE`, **Order value with delivery** = `ORDER_AMOUNT_WITH_DELIVERY`, **Order value without delivery** = `ORDER_AMOUNT_WITHOUT_DELIVERY`, **Fixed amount** = `FIXED_AMOUNT` (amount in `fixedAmount`), and `currencySource`: **Order currency** = `ORDER_CURRENCY`, **Delivery country currency** = `DELIVERY_COUNTRY_CURRENCY`, **Fixed currency** = `FIXED` (currency in `fixedCurrency`, required with `FIXED`). ![Send with Allegro integration details: basic settings with the Allegro account and the sender address on the label](https://ritevo.com/docs/integrations/send-with-allegro/en-details.webp) ![The Pickup points card with DPD, UPS, Poczta Polska, Allegro One, Allegro International and InPost point numbers](https://ritevo.com/docs/integrations/send-with-allegro/en-pickup-points.webp) ![The Parcel details and Cash on delivery cards with parcel type, dimensions, weight, IBAN and account owner](https://ritevo.com/docs/integrations/send-with-allegro/en-package.webp) ![The Sender address on the label card with company, first and last name, address, country, phone and email fields](https://ritevo.com/docs/integrations/shipping/en-sender.webp) ![The Courier pickup address card with company, first and last name, address, country, phone and email fields](https://ritevo.com/docs/integrations/shipping/en-pickup-address.webp) ![The Additional insurance card with the Insurance type and Currency source fields](https://ritevo.com/docs/integrations/shipping/en-insurance.webp) > **Good to know:** The integration does not book a courier pickup. You book the pickup directly with the carrier or set up a regular pickup schedule with them. > **Good to know:** When the order's payment method is **Cash on delivery**, the shipment gets cash on delivery automatically - in the order's amount and currency. ### Creating shipments You create a shipment from the order in two ways: - **By hand** - in the order details, in the **Shipments** card, click the button with the Send with Allegro integration name. You only see buttons for active integrations that match the order. - **Automatically** - with the **Create shipment** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). The shipment details come from the order: - **Recipient** - the order's delivery address and the buyer's phone and email. - **Pickup point** - the point the buyer chose, if the order has one. - **Cash on delivery** - the amount to pay from the order, when the payment method is **Cash on delivery**. - **Parcel** - one shipment is always one parcel. In the same card every shipment has a tracking number, a state and a creation date. The states: - **Being created** (API: "Being created" = `PENDING`; value in `shipments[].status`) - the carrier is still creating the shipment. We check it every few seconds. If the carrier does not confirm the shipment within 24 hours, it ends with an error. - **Created successfully** (API: "Created successfully" = `SUCCESS`; value in `shipments[].status`) - the shipment is with the carrier and has a tracking number. - **Creation failed** (API: "Creation failed" = `ERROR`; value in `shipments[].status`) - the carrier did not accept the shipment. The reason is shown next to the state, and for a carrier error also the carrier's message. You download the label of a created shipment with the **Download** button in the **Shipments** card. You print it in two ways - the [Ritevo Printer](https://ritevo.com/en/docs/integrations/ritevo-printer) app must run on the computer with the printer: - **By hand** - in the **Shipments** card click **Print** and pick the printer. - **Automatically** - with the **Print shipment label** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). The step prints the label of the latest shipment in the **Created successfully** state - it skips shipments being created and failed ones. Plan label printing step by step, as two actions: - **First action** - ends with the **Create shipment** step. - **Second action** - starts on the **Shipment created** trigger, has the **Shipment status is** condition with **Created successfully** and a single **Print shipment label** step. This way every new shipment prints its label right away - also when the order has several parcels. > **Good to know:** The **Print shipment label** step always prints just one label - that of the newest successful shipment. If you first create all shipments and only then turn on printing, only the last one is printed, and you print the others by hand with **Print**. If a new shipment fails, the step prints the label of the previous successful one. > **Good to know:** Every button click and every run of the **Create shipment** step creates a new shipment with the carrier. A shipment cannot be cancelled in Ritevo - you cancel it in the carrier's panel. #### How a shipment reaches Allegro - **Confirmation** - Allegro creates the shipment in the background, so at first it is **Being created**. - **Tracking number** - the shipment number assigned by Allegro. - **Cash on delivery without an account number** - when the delivery needs an account number for cash on delivery and you did not enter it in the integration, the shipment fails. - **Delivery without cash on delivery** - a cash on delivery order with a delivery that does not support it also fails. You create a shipment with `POST /orders/{orderId}/create-shipments/{shipmentIntegrationId}` - the response is 202, and the result shows up later in the order's `shipments[]` (`status`, `trackingNumber`, `errorType`, `errorMessage`). You download the label with `GET /orders/{orderId}/shipments/{shipmentId}/label` and request printing with `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}`. Order actions: the **Create shipment** step is `CREATE_SHIPMENT` and **Print shipment label** is `PRINT_SHIPMENT_LABEL` - both in `actionSteps[].action.type`, with `uuidValue` = the shipping integration id (`GET /integrations/shippings`) or the printer id (`GET /integrations/printers`). The **Shipment created** trigger is `triggerType` = `CREATE_SHIPMENT`. Conditions: **Has shipment** / **Has no shipment** = `HAS_SHIPMENT` / `HAS_SHIPMENT_NOT` (`booleanValues` = `[true]`), **Shipment status is** / **Shipment status is not** = `SHIPMENT_STATUS_IS` / `SHIPMENT_STATUS_IS_NOT` (`enumValues`: `PENDING`, `SUCCESS`, `ERROR`), **Shipment belongs to integration** / **Shipment does not belong to integration** = `SHIPMENT_SHIPPING_INTEGRATION_IS` / `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT` (`uuidValues` = shipping integration ids). The print step in an action takes the newest shipment with `status` = `SUCCESS` (by `createdAt`); manual printing via `POST /orders/{orderId}/print-shipment-label/...` also accepts only a `SUCCESS` shipment and returns `SHIPMENT_NOT_FOUND` otherwise. `SHIPMENT_STATUS_IS` is met when any shipment of the order has the given status, not only the latest. Full description: [Order actions](https://ritevo.com/en/docs/automations/order-actions). ### Reconnection required Send with Allegro has no login of its own, so it never needs reconnecting itself. When the Allegro account stops working, reconnect it on the [Allegro integration](https://ritevo.com/en/docs/integrations/allegro#reconnect) page - shipments start working again with no change in this integration. ### Deleting the integration **Delete integration** turns the integration off in Ritevo. Shipments created earlier stay in the orders and with the carrier. **Restore integration** turns it back on. ### What the integration does not do - It does not book a courier pickup. - It does not cancel shipments. - It does not track a shipment after it is created - you check the delivery state with the carrier. - It does not send the tracking number to the sales channel. - It does not create shipments with several parcels. - It does not create shipments for orders from outside the chosen Allegro account. ### The integration through the API This integration's endpoints are under `/integrations/shippings/send-with-allegro`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/shippings`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/inpost (updated 2026-10-07) ## InPost InPost ShipX integration with Ritevo: API token and organization ID, parcel size and drop-off method, parcel locker shipments with cash on delivery, labels, reconnecting. The InPost integration creates parcel locker shipments through the InPost ShipX API. You connect it with an API token and an organization ID from InPost's Manager Paczek (parcel manager). > **Required integration:** You need an InPost Manager Paczek account with the company and invoice details filled in. You can add as many InPost integrations as you like, including several for the same account - for example with a different label format, parcel or sender address. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. `externalId` is not used. You provide a new token with `PATCH /integrations/shippings/inpost-locker-x/{id}/token` - in any state of the integration. It checks the token in InPost and sets `authError=false` and `active=true`. ### Which shipments it creates - **Parcel locker** - the shipment always goes to the parcel locker the buyer chose. The order must have a pickup point - without it InPost rejects the shipment. - **Courier** - courier shipments are not supported. - **Allegro orders** - get the Paczkomat Allegro service, the others the standard Paczkomat service. - **Cash on delivery and insurance** - cash on delivery from the order, insurance from the integration settings. - **Any sales channel** - you can create a shipment for an order from any channel. ### Where to find the token and the organization ID You will find both in InPost's Manager Paczek. Have them ready before adding the integration: 1. Sign in to InPost's Manager Paczek at manager.paczkomaty.pl. 2. Go to **Moje konto** → **API** (my account, API) and in the **API ShipX** tab click **Generuj** (generate). Copy the token. 3. In the **Ustawienia organizacji** (organization settings) tab copy the organization ID. It only shows up after the token is generated. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Shipments** section pick the **Inpost paczkomat ShipX** tile. 3. Enter the **Account name** - your own name for the integration - and paste the **ShipX API token** and the **ShipX organization ID**. 4. Fill in the other settings described below and click **Add integration**. We check the token in InPost right away: if it is wrong, you will see the error returned by InPost and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Inpost paczkomat ShipX tile framed in the Shipments section](https://ritevo.com/docs/integrations/inpost/en-catalogue.webp) ![The InPost add screen with Account name, ShipX API token, ShipX organization ID, parcel size, label format, drop-off method and point code fields](https://ritevo.com/docs/integrations/inpost/en-add.webp) ### Integration settings On the integration page you will find the fields below. You save changes with **Update integration**: - **Account name** - your own name for the integration. - **Default parcel size** - **Size A**, **Size B** or **Size C**. A by default. - **Label format** - A4 PDF, A6 PDF, A6 ZPL, A6 ZPL 300dpi or A6 EPL. A6 PDF by default. - **Drop-off method** - how you hand parcels over to InPost: **Courier pickup**, **Drop-off at a Paczkomat locker**, **Drop-off at an InPost branch**, **Drop-off at a POK**, **Drop-off at a POP (PaczkoPunkt)** or **Drop-off at any point**. Courier pickup by default. - **Drop-off point code** - the code of the point where you drop off parcels. The field is required for every drop-off method. - **Update token** - you enter a new ShipX API token. - **Sender address on the label** - the sender details the carrier prints on the label. - **Courier pickup address** - the address the courier collects parcels from. It can differ from the sender address on the label - for example in dropshipping: the label shows your shop, and the courier collects the parcel from the wholesaler. - **Additional insurance** - the insurance amount of every shipment: **None**, **Order value with delivery**, **Order value without delivery** or **Fixed amount**. In **Currency source** you pick the order currency, the delivery country currency or a fixed currency. Integration fields: `accountName`, `apiToken`, `organizationId`, `defaultTemplate` (**Size A** = `SMALL`, **Size B** = `MEDIUM`, **Size C** = `LARGE`), `labelFormat` (`A4_PDF`, `A6_PDF`, `A6_ZPL`, `A6_ZPL_300`, `A6_EPL`), `sendingMethod` (**Courier pickup** = `DISPATCH_ORDER`, **Drop-off at a Paczkomat locker** = `PARCEL_LOCKER`, **Drop-off at an InPost branch** = `BRANCH`, **Drop-off at a POK** = `POK`, **Drop-off at a POP (PaczkoPunkt)** = `POP`, **Drop-off at any point** = `ANY_POINT`) and `dropoffPoint`. Fields shared by shipping integrations: `senderAddress` and `pickupAddress` (`companyName`, `firstName`, `lastName`, `street`, `city`, `zipCode`, `countryCode`, `phoneNumber`, `email`) and `additionalInsurance`. In it `insuranceType`: **None** = `NONE`, **Order value with delivery** = `ORDER_AMOUNT_WITH_DELIVERY`, **Order value without delivery** = `ORDER_AMOUNT_WITHOUT_DELIVERY`, **Fixed amount** = `FIXED_AMOUNT` (amount in `fixedAmount`), and `currencySource`: **Order currency** = `ORDER_CURRENCY`, **Delivery country currency** = `DELIVERY_COUNTRY_CURRENCY`, **Fixed currency** = `FIXED` (currency in `fixedCurrency`, required with `FIXED`). ![InPost integration details: basic settings with parcel size, label format, drop-off method and point code, and the sender address](https://ritevo.com/docs/integrations/inpost/en-details.webp) ![The Sender address on the label card with company, first and last name, address, country, phone and email fields](https://ritevo.com/docs/integrations/shipping/en-sender.webp) ![The Courier pickup address card with company, first and last name, address, country, phone and email fields](https://ritevo.com/docs/integrations/shipping/en-pickup-address.webp) ![The Additional insurance card with the Insurance type and Currency source fields](https://ritevo.com/docs/integrations/shipping/en-insurance.webp) > **Good to know:** The integration does not book a courier pickup. You book the pickup directly with the carrier or set up a regular pickup schedule with them. > **Good to know:** When the order's payment method is **Cash on delivery**, the shipment gets cash on delivery automatically - in the order's amount and currency. ### Creating shipments You create a shipment from the order in two ways: - **By hand** - in the order details, in the **Shipments** card, click the button with the InPost integration name. You only see buttons for active integrations that match the order. - **Automatically** - with the **Create shipment** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). The shipment details come from the order: - **Recipient** - the order's delivery address and the buyer's phone and email. - **Pickup point** - the point the buyer chose, if the order has one. - **Cash on delivery** - the amount to pay from the order, when the payment method is **Cash on delivery**. - **Parcel** - one shipment is always one parcel. In the same card every shipment has a tracking number, a state and a creation date. The states: - **Being created** (API: "Being created" = `PENDING`; value in `shipments[].status`) - the carrier is still creating the shipment. We check it every few seconds. If the carrier does not confirm the shipment within 24 hours, it ends with an error. - **Created successfully** (API: "Created successfully" = `SUCCESS`; value in `shipments[].status`) - the shipment is with the carrier and has a tracking number. - **Creation failed** (API: "Creation failed" = `ERROR`; value in `shipments[].status`) - the carrier did not accept the shipment. The reason is shown next to the state, and for a carrier error also the carrier's message. You download the label of a created shipment with the **Download** button in the **Shipments** card. You print it in two ways - the [Ritevo Printer](https://ritevo.com/en/docs/integrations/ritevo-printer) app must run on the computer with the printer: - **By hand** - in the **Shipments** card click **Print** and pick the printer. - **Automatically** - with the **Print shipment label** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). The step prints the label of the latest shipment in the **Created successfully** state - it skips shipments being created and failed ones. Plan label printing step by step, as two actions: - **First action** - ends with the **Create shipment** step. - **Second action** - starts on the **Shipment created** trigger, has the **Shipment status is** condition with **Created successfully** and a single **Print shipment label** step. This way every new shipment prints its label right away - also when the order has several parcels. > **Good to know:** The **Print shipment label** step always prints just one label - that of the newest successful shipment. If you first create all shipments and only then turn on printing, only the last one is printed, and you print the others by hand with **Print**. If a new shipment fails, the step prints the label of the previous successful one. > **Good to know:** Every button click and every run of the **Create shipment** step creates a new shipment with the carrier. A shipment cannot be cancelled in Ritevo - you cancel it in the carrier's panel. #### How a shipment reaches InPost - **Confirmation** - InPost creates the shipment in the background, so at first it is **Being created**. When InPost assigns the tracking number, it changes to **Created successfully**. - **Tracking number** - the InPost shipment number. The same number is on the label. - **Cancelled in InPost** - a shipment cancelled in InPost while being created ends with an error. You create a shipment with `POST /orders/{orderId}/create-shipments/{shipmentIntegrationId}` - the response is 202, and the result shows up later in the order's `shipments[]` (`status`, `trackingNumber`, `errorType`, `errorMessage`). You download the label with `GET /orders/{orderId}/shipments/{shipmentId}/label` and request printing with `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}`. Order actions: the **Create shipment** step is `CREATE_SHIPMENT` and **Print shipment label** is `PRINT_SHIPMENT_LABEL` - both in `actionSteps[].action.type`, with `uuidValue` = the shipping integration id (`GET /integrations/shippings`) or the printer id (`GET /integrations/printers`). The **Shipment created** trigger is `triggerType` = `CREATE_SHIPMENT`. Conditions: **Has shipment** / **Has no shipment** = `HAS_SHIPMENT` / `HAS_SHIPMENT_NOT` (`booleanValues` = `[true]`), **Shipment status is** / **Shipment status is not** = `SHIPMENT_STATUS_IS` / `SHIPMENT_STATUS_IS_NOT` (`enumValues`: `PENDING`, `SUCCESS`, `ERROR`), **Shipment belongs to integration** / **Shipment does not belong to integration** = `SHIPMENT_SHIPPING_INTEGRATION_IS` / `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT` (`uuidValues` = shipping integration ids). The print step in an action takes the newest shipment with `status` = `SUCCESS` (by `createdAt`); manual printing via `POST /orders/{orderId}/print-shipment-label/...` also accepts only a `SUCCESS` shipment and returns `SHIPMENT_NOT_FOUND` otherwise. `SHIPMENT_STATUS_IS` is met when any shipment of the order has the given status, not only the latest. Full description: [Order actions](https://ritevo.com/en/docs/automations/order-actions). ### Reconnection required This state shows up when InPost stops accepting the token - for example after a new token was generated in Manager Paczek. Until you enter a new token you cannot create shipments or download labels. 1. Copy the current token from the **API ShipX** tab in InPost's Manager Paczek. 2. On the integration page click **Update token**, paste it into the **New ShipX API token** field and confirm. We check it in InPost the same way as when adding - a valid one refreshes the connection, and the settings stay unchanged. ![The bottom of the InPost integration page with the Update token and Update integration buttons](https://ritevo.com/docs/integrations/inpost/en-token.webp) ![The Update token window of the InPost integration with the New ShipX API token field](https://ritevo.com/docs/integrations/inpost/en-update-token.webp) > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo. Shipments created earlier stay in the orders and with the carrier. **Restore integration** turns it back on. ### What the integration does not do - It does not book a courier pickup. - It does not cancel shipments. - It does not track a shipment after it is created - you check the delivery state with the carrier. - It does not send the tracking number to the sales channel. - It does not create shipments with several parcels. - It does not create courier shipments - parcel lockers only. ### The integration through the API This integration's endpoints are under `/integrations/shippings/inpost-locker-x`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/shippings`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/dpd (updated 2026-10-07) ## DPD DPD Polska integration with Ritevo: API access and Numkat numbers, parcel and extra services, courier and DPD Pickup shipments, labels, reconnecting. The DPD Polska integration creates DPD courier shipments and shipments to DPD Pickup points. You connect it with DPD API credentials and your Numkat customer numbers. > **Required integration:** You need a contract with DPD Polska and a DPD API login and password. These are different from your DPD panel login - your DPD account manager gives them to you. You can add as many DPD integrations as you like, including several for the same account - for example with a different label format, parcel or sender address. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. `externalId` is not used. You provide new credentials with `PATCH /integrations/shippings/dpd-pl/{id}/credentials` - in any state of the integration. It checks them in DPD and sets `authError=false` and `active=true`. ### Which shipments it creates - **Courier** - by default the shipment goes by courier to the order's address. - **DPD Pickup point** - with the **Dostawa do punktu PUDO (DPD_PICKUP)** service ticked, the shipment goes to the point chosen in the order. An order without a pickup point fails. - **Cash on delivery and insurance** - cash on delivery from the order, insurance from the integration settings as a declared value rounded to whole units. - **Domestic shipments** - labels are requested as domestic, so international shipments may fail. ### Where to get the API access DPD gives you the API login and password and the Numkat numbers. Have them ready before adding the integration: 1. Ask your DPD account manager for DPD API access. 2. Note the API login and password and your Numkat (MasterFID). 3. If you ship from several locations, also ask for the Numkat of the dispatch location. With one location it is the same number. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Shipments** section pick the **Dpd PL** tile. 3. Enter the **Account name** - your own name for the integration - and the DPD API **Login** and **Password**. 4. Enter the **Numkat (MasterFID)**, the **Sender Numkat (MasterFID)** and the **DPDInfoServices Numkat (MasterFID) (parcel tracking)**. 5. Fill in the other settings described below and click **Add integration**. We check the login and password in DPD right away: if they are wrong, you will see the error returned by DPD and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Dpd PL tile framed in the Shipments section](https://ritevo.com/docs/integrations/dpd/en-catalogue.webp) ![The DPD add screen with Account name, Login, Password, three Numkat numbers and label format fields](https://ritevo.com/docs/integrations/dpd/en-add.webp) ### Integration settings On the integration page you will find the fields below. You save changes with **Update integration**: - **Account name** - your own name for the integration. - **Numkat (MasterFID)** - your main DPD customer number. - **Sender Numkat (MasterFID)** - the number of the dispatch location. DPD bills the shipments to this number. With one location enter the same number as above. - **DPDInfoServices Numkat (MasterFID) (parcel tracking)** - the number for DPD parcel tracking. The field is required, but we do not track DPD shipments today. - **Label format** - A4 PDF, A6 PDF, A6 ZPL or A6 EPL. A4 PDF by default. - **Parcel details** - the dimensions in centimetres and the weight in kilograms of every shipment. Dimensions are rounded to whole centimetres. - **Extra services** - DPD services added to every shipment, for example Saturday delivery, delivery by 12:00 or return documents. **Etykieta cyfrowa (DIGITAL_LABEL)** and **Nadanie w punkcie PUDO (PUDO_TO_SEND)** only work when both are ticked. - **Update credentials** - you enter a new DPD API login and password. - **Sender address on the label** - the sender details the carrier prints on the label. - **Courier pickup address** - the address the courier collects parcels from. It can differ from the sender address on the label - for example in dropshipping: the label shows your shop, and the courier collects the parcel from the wholesaler. - **Additional insurance** - the insurance amount of every shipment: **None**, **Order value with delivery**, **Order value without delivery** or **Fixed amount**. In **Currency source** you pick the order currency, the delivery country currency or a fixed currency. Integration fields: `accountName`, `apiLogin`, `apiPassword`, `masterFid`, `senderFid`, `infoServicesFid` (numbers), `labelFormat` (`A4_PDF`, `A6_PDF`, `A6_ZPL`, `A6_EPL`), `packageDetails` with `length`, `width`, `height` in cm and `weight` in kg, and `additionalServices` - a list of: `CARRY_IN`, `CUD`, `ROD`, `HAND_DELIVERY`, `SELF_COLLECTION`, `PRIVATE_PERSON`, `DEDICATED_DELIVERY`, `PALETTE`, `DOX`, `DPD_EXPRESS`, `DOCUMENTS_INTERNATIONAL`, `DPD_LQ`, `DPD_NEXT_DAY`, `DPD_PICKUP`, `DPD_TODAY`, `INTERNATIONAL`, `SATURDAY`, `TIME0930`, `TIME1200`, `TIRES`, `TIRES_EXPORT`, `DIGITAL_LABEL`, `PUDO_TO_SEND`. The API value is the name in brackets next to the service in the app. Fields shared by shipping integrations: `senderAddress` and `pickupAddress` (`companyName`, `firstName`, `lastName`, `street`, `city`, `zipCode`, `countryCode`, `phoneNumber`, `email`) and `additionalInsurance`. In it `insuranceType`: **None** = `NONE`, **Order value with delivery** = `ORDER_AMOUNT_WITH_DELIVERY`, **Order value without delivery** = `ORDER_AMOUNT_WITHOUT_DELIVERY`, **Fixed amount** = `FIXED_AMOUNT` (amount in `fixedAmount`), and `currencySource`: **Order currency** = `ORDER_CURRENCY`, **Delivery country currency** = `DELIVERY_COUNTRY_CURRENCY`, **Fixed currency** = `FIXED` (currency in `fixedCurrency`, required with `FIXED`). ![The Extra services card with the list of DPD services to tick](https://ritevo.com/docs/integrations/dpd/en-services.webp) ![The Sender address on the label card with company, first and last name, address, country, phone and email fields](https://ritevo.com/docs/integrations/shipping/en-sender.webp) ![The Courier pickup address card with company, first and last name, address, country, phone and email fields](https://ritevo.com/docs/integrations/shipping/en-pickup-address.webp) ![The Additional insurance card with the Insurance type and Currency source fields](https://ritevo.com/docs/integrations/shipping/en-insurance.webp) > **Good to know:** The integration does not book a courier pickup. You book the pickup directly with the carrier or set up a regular pickup schedule with them. > **Good to know:** When the order's payment method is **Cash on delivery**, the shipment gets cash on delivery automatically - in the order's amount and currency. ### Creating shipments You create a shipment from the order in two ways: - **By hand** - in the order details, in the **Shipments** card, click the button with the DPD integration name. You only see buttons for active integrations that match the order. - **Automatically** - with the **Create shipment** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). The shipment details come from the order: - **Recipient** - the order's delivery address and the buyer's phone and email. - **Pickup point** - the point the buyer chose, if the order has one. - **Cash on delivery** - the amount to pay from the order, when the payment method is **Cash on delivery**. - **Parcel** - one shipment is always one parcel. In the same card every shipment has a tracking number, a state and a creation date. The states: - **Being created** (API: "Being created" = `PENDING`; value in `shipments[].status`) - the carrier is still creating the shipment. We check it every few seconds. If the carrier does not confirm the shipment within 24 hours, it ends with an error. - **Created successfully** (API: "Created successfully" = `SUCCESS`; value in `shipments[].status`) - the shipment is with the carrier and has a tracking number. - **Creation failed** (API: "Creation failed" = `ERROR`; value in `shipments[].status`) - the carrier did not accept the shipment. The reason is shown next to the state, and for a carrier error also the carrier's message. You download the label of a created shipment with the **Download** button in the **Shipments** card. You print it in two ways - the [Ritevo Printer](https://ritevo.com/en/docs/integrations/ritevo-printer) app must run on the computer with the printer: - **By hand** - in the **Shipments** card click **Print** and pick the printer. - **Automatically** - with the **Print shipment label** step in [order actions](https://ritevo.com/en/docs/automations/order-actions). The step prints the label of the latest shipment in the **Created successfully** state - it skips shipments being created and failed ones. Plan label printing step by step, as two actions: - **First action** - ends with the **Create shipment** step. - **Second action** - starts on the **Shipment created** trigger, has the **Shipment status is** condition with **Created successfully** and a single **Print shipment label** step. This way every new shipment prints its label right away - also when the order has several parcels. > **Good to know:** The **Print shipment label** step always prints just one label - that of the newest successful shipment. If you first create all shipments and only then turn on printing, only the last one is printed, and you print the others by hand with **Print**. If a new shipment fails, the step prints the label of the previous successful one. > **Good to know:** Every button click and every run of the **Create shipment** step creates a new shipment with the carrier. A shipment cannot be cancelled in Ritevo - you cancel it in the carrier's panel. #### How a shipment reaches DPD - **Right away** - DPD answers straight away, so the shipment is **Created successfully** or **Creation failed** right after sending. - **Tracking number** - the DPD waybill number. The same number is on the label. You create a shipment with `POST /orders/{orderId}/create-shipments/{shipmentIntegrationId}` - the response is 202, and the result shows up later in the order's `shipments[]` (`status`, `trackingNumber`, `errorType`, `errorMessage`). You download the label with `GET /orders/{orderId}/shipments/{shipmentId}/label` and request printing with `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}`. Order actions: the **Create shipment** step is `CREATE_SHIPMENT` and **Print shipment label** is `PRINT_SHIPMENT_LABEL` - both in `actionSteps[].action.type`, with `uuidValue` = the shipping integration id (`GET /integrations/shippings`) or the printer id (`GET /integrations/printers`). The **Shipment created** trigger is `triggerType` = `CREATE_SHIPMENT`. Conditions: **Has shipment** / **Has no shipment** = `HAS_SHIPMENT` / `HAS_SHIPMENT_NOT` (`booleanValues` = `[true]`), **Shipment status is** / **Shipment status is not** = `SHIPMENT_STATUS_IS` / `SHIPMENT_STATUS_IS_NOT` (`enumValues`: `PENDING`, `SUCCESS`, `ERROR`), **Shipment belongs to integration** / **Shipment does not belong to integration** = `SHIPMENT_SHIPPING_INTEGRATION_IS` / `SHIPMENT_SHIPPING_INTEGRATION_IS_NOT` (`uuidValues` = shipping integration ids). The print step in an action takes the newest shipment with `status` = `SUCCESS` (by `createdAt`); manual printing via `POST /orders/{orderId}/print-shipment-label/...` also accepts only a `SUCCESS` shipment and returns `SHIPMENT_NOT_FOUND` otherwise. `SHIPMENT_STATUS_IS` is met when any shipment of the order has the given status, not only the latest. Full description: [Order actions](https://ritevo.com/en/docs/automations/order-actions). ### Reconnection required This state shows up when DPD stops accepting the API login and password - for example after DPD changed them. Until you enter new ones you cannot create shipments or download labels. 1. Ask your DPD account manager for the current API credentials. 2. On the integration page click **Update credentials**, enter the **Login** and **Password** and confirm. We check them in DPD the same way as when adding - correct ones refresh the connection, and the settings stay unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo. Shipments created earlier stay in the orders and with the carrier. **Restore integration** turns it back on. ### What the integration does not do - It does not book a courier pickup. - It does not cancel shipments. - It does not track a shipment after it is created - you check the delivery state with the carrier. - It does not send the tracking number to the sales channel. - It does not create shipments with several parcels. - It does not track shipments through DPDInfoServices, even though the tracking number is in the settings. ### The integration through the API This integration's endpoints are under `/integrations/shippings/dpd-pl`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/shippings`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/openai (updated 2026-09-29) ## OpenAI OpenAI integration with Ritevo: API key, model, system prompt and token limit, automatic AI replies in messages, reconnecting. The OpenAI integration lets you reply to customers in messages with text written by a OpenAI model. You connect it with your own API key from OpenAI Platform - you pay for usage directly to the provider. > **Required integration:** You need a OpenAI Platform account with credit and an API key. You can add as many OpenAI integrations as you like, including several with the same API key - for example with a different model or system prompt for different channels. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. You provide a new key with `PATCH /integrations/ai/openai/{id}/token` - in any state of the integration. It sends the provider a test request and sets `authError=false` and `active=true`. A wrong key on create or key change returns `INVALID_TOKEN`, any other provider error `EXTERNAL_EXCEPTION`. ### How to generate the API key You create the key in OpenAI Platform. Copy it straight away - the key is shown only once. 1. Sign in at platform.openai.com. 2. Go to **API Keys** and click **Create new secret key**. 3. Copy the key. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Artificial intelligence** section pick the **OpenAI** tile. 3. In the **Account name** field enter your own name for the integration, paste the **API Token** and pick the **Model**. 4. In the **Advanced settings** card enter the **System prompt** and set **Max tokens** - described below. 5. Click **Create integration**. We send OpenAI a short test request with this key and model right away: if it works, the integration is added and its settings open. If not - you will see an error and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the OpenAI tile framed in the Artificial intelligence section](https://ritevo.com/docs/integrations/openai/en-catalogue.webp) ![The OpenAI add screen with the Account name, API Token, Model, System prompt and Max tokens fields](https://ritevo.com/docs/integrations/openai/en-add.webp) ### Integration settings On the integration page you will find the fields below. You save changes with **Update integration**: - **Account name** - your own name for the integration. You pick the integration by this name in an automatic action. - **Model** - the OpenAI model that writes the replies: gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4 or gpt-3.5-turbo. - **System prompt** - the instruction for the AI added to every reply: who you are, what tone to use, opening hours, return rules, which language to answer in. It is the only place where you give the AI knowledge about your business. - **Max tokens** - the upper limit on reply length. 1000 by default. Too low a limit cuts the reply off halfway and the customer gets it truncated. - **Update token** - you enter a new API key. ![OpenAI integration details: account name, model, system prompt, max tokens and the Update token and Update integration buttons](https://ritevo.com/docs/integrations/openai/en-details.webp) Integration fields: `accountName`, `apiToken` (on create only), `model` = `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`, `gpt-4`, `gpt-3.5-turbo`, `systemPrompt` (up to 10000 characters) and `maxTokens`. Changing settings: `PUT /integrations/ai/openai/{id}` with these fields without `apiToken` - saving also sets `active=true`. ### AI replies in messages The AI integration works in message actions, in the **Send AI message to thread** step. Step details and a ready example are in [Message actions](https://ritevo.com/en/docs/automations/message-actions#ai-reply-example). - **What the AI gets** - the text of the latest message in the thread and the **System prompt**. It does not get the earlier conversation history or order data. - **Sending** - the reply goes to the customer right away, without approval. - **Error** - when the AI provider returns an error, nothing is sent and the action stops. You see the error in the message audit. - **Costs** - every reply is billed to your account with the AI provider. Adding the integration and changing the key send one short test request. > **Good to know:** In an action with the **Send AI message to thread** step, set the **Message received from customer** condition. The AI replies to the latest message in the thread, so without this condition it could reply to its own replies. Message actions: the **Send AI message to thread** step is `AI_SEND_MESSAGE_TO_THREAD` in `actionSteps[].action.type`, with `uuidValue` = the AI integration id (`GET /integrations/ai`). The **AI reply in thread** trigger is `triggerType` = `AI_MESSAGE_RESPONSE`, and the **Message received from customer** condition is `MESSAGE_FROM_INTERLOCUTOR`. The model gets the text of the latest message in the thread (whoever wrote it) as the only user message plus the integration's `systemPrompt`. Full description: [Message actions](https://ritevo.com/en/docs/automations/message-actions). ### Reconnection required This state shows up when OpenAI rejected the API key while writing a reply - for example after the key was deleted. Until you enter a new key, the AI will not reply to customers. 1. Create a new API key in OpenAI Platform. 2. On the integration page click **Update token**, paste the key into the **API Token** field and confirm. We check it with a short test request - a valid one refreshes the connection, and the settings stay unchanged. ![The Update token window of the OpenAI integration with the API Token field](https://ritevo.com/docs/integrations/openai/en-update-token.webp) > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not suggest replies to insert by hand - it replies only through an automatic action. - It does not read the conversation history or order data. - It does not save replies as drafts for approval. - It does not cap spending - you set limits in your account with the AI provider. ### The integration through the API This integration's endpoints are under `/integrations/ai/openai`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/ai`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/claude (updated 2026-09-29) ## Claude Claude integration with Ritevo: API key, model, system prompt and token limit, automatic AI replies in messages, reconnecting. The Claude integration lets you reply to customers in messages with text written by a Claude model. You connect it with your own API key from Anthropic Console - you pay for usage directly to the provider. > **Required integration:** You need a Anthropic Console account with credit and an API key. You can add as many Claude integrations as you like, including several with the same API key - for example with a different model or system prompt for different channels. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. You provide a new key with `PATCH /integrations/ai/claude/{id}/token` - in any state of the integration. It sends the provider a test request and sets `authError=false` and `active=true`. A wrong key on create or key change returns `INVALID_TOKEN`, any other provider error `EXTERNAL_EXCEPTION`. ### How to generate the API key You create the key in Anthropic Console. Copy it straight away - the key is shown only once. 1. Sign in at console.anthropic.com. 2. Go to **API Keys** and click **Create Key**. 3. Copy the key. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Artificial intelligence** section pick the **Claude** tile. 3. In the **Account name** field enter your own name for the integration, paste the **API Token** and pick the **Model**. 4. In the **Advanced settings** card enter the **System prompt** and set **Max tokens** - described below. 5. Click **Create integration**. We send Claude a short test request with this key and model right away: if it works, the integration is added and its settings open. If not - you will see an error and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Claude tile framed in the Artificial intelligence section](https://ritevo.com/docs/integrations/claude/en-catalogue.webp) ![The Claude add screen with the Account name, API Token, Model, System prompt and Max tokens fields](https://ritevo.com/docs/integrations/claude/en-add.webp) ### Integration settings On the integration page you will find the fields below. You save changes with **Update integration**: - **Account name** - your own name for the integration. You pick the integration by this name in an automatic action. - **Model** - the Claude model that writes the replies: claude-sonnet-4-5-20250929, claude-sonnet-4-20250514, claude-opus-4-20250514, claude-haiku-4-5-20251001 or claude-3-5-haiku-20241022. - **System prompt** - the instruction for the AI added to every reply: who you are, what tone to use, opening hours, return rules, which language to answer in. It is the only place where you give the AI knowledge about your business. - **Max tokens** - the upper limit on reply length. 1000 by default. Too low a limit cuts the reply off halfway and the customer gets it truncated. - **Update token** - you enter a new API key. ![Claude integration details: account name, model, system prompt, max tokens and the Update token and Update integration buttons](https://ritevo.com/docs/integrations/claude/en-details.webp) Integration fields: `accountName`, `apiToken` (on create only), `model` = `claude-sonnet-4-5-20250929`, `claude-sonnet-4-20250514`, `claude-opus-4-20250514`, `claude-haiku-4-5-20251001`, `claude-3-5-haiku-20241022`, `systemPrompt` (up to 10000 characters) and `maxTokens`. Changing settings: `PUT /integrations/ai/claude/{id}` with these fields without `apiToken` - saving also sets `active=true`. ### AI replies in messages The AI integration works in message actions, in the **Send AI message to thread** step. Step details and a ready example are in [Message actions](https://ritevo.com/en/docs/automations/message-actions#ai-reply-example). - **What the AI gets** - the text of the latest message in the thread and the **System prompt**. It does not get the earlier conversation history or order data. - **Sending** - the reply goes to the customer right away, without approval. - **Error** - when the AI provider returns an error, nothing is sent and the action stops. You see the error in the message audit. - **Costs** - every reply is billed to your account with the AI provider. Adding the integration and changing the key send one short test request. > **Good to know:** In an action with the **Send AI message to thread** step, set the **Message received from customer** condition. The AI replies to the latest message in the thread, so without this condition it could reply to its own replies. Message actions: the **Send AI message to thread** step is `AI_SEND_MESSAGE_TO_THREAD` in `actionSteps[].action.type`, with `uuidValue` = the AI integration id (`GET /integrations/ai`). The **AI reply in thread** trigger is `triggerType` = `AI_MESSAGE_RESPONSE`, and the **Message received from customer** condition is `MESSAGE_FROM_INTERLOCUTOR`. The model gets the text of the latest message in the thread (whoever wrote it) as the only user message plus the integration's `systemPrompt`. Full description: [Message actions](https://ritevo.com/en/docs/automations/message-actions). ### Reconnection required This state shows up when Claude rejected the API key while writing a reply - for example after the key was deleted. Until you enter a new key, the AI will not reply to customers. 1. Create a new API key in Anthropic Console. 2. On the integration page click **Update token**, paste the key into the **API Token** field and confirm. We check it with a short test request - a valid one refreshes the connection, and the settings stay unchanged. ![The Update token window of the Claude integration with the API Token field](https://ritevo.com/docs/integrations/claude/en-update-token.webp) > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ### Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ### What the integration does not do - It does not suggest replies to insert by hand - it replies only through an automatic action. - It does not read the conversation history or order data. - It does not save replies as drafts for approval. - It does not cap spending - you set limits in your account with the AI provider. ### The integration through the API This integration's endpoints are under `/integrations/ai/claude`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/ai`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/hurtownia-karm (updated 2026-09-29) ## Hurtownia Karm Hurtownia Karm integration with Ritevo: fetching products, net prices and stock from the wholesaler's offer, sync interval and price rules. The Hurtownia Karm integration brings the wholesaler's offer into Ritevo: products, prices and stock. You enter no login details - the wholesaler makes the offer available to us. > **Required integration:** You need no key or login. Just add the integration and choose how often to fetch the offer. You can add as many Hurtownia Karm integrations as you like - each has its own set of products, for example with different price rules. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Warehouses and wholesalers** section pick the **Hurtownia Karm** tile. 3. In the **Account name** field enter your own name for the integration and click **Create integration**. Within a minute we start the first fetch of the offer. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Hurtownia Karm tile framed in the Warehouses and wholesalers section](https://ritevo.com/docs/integrations/hurtownia-karm/en-catalogue.webp) ![The Hurtownia Karm add screen with the Account name field and the Create integration button](https://ritevo.com/docs/integrations/hurtownia-karm/en-add.webp) ### Integration settings On the integration page you will find the fields below. You save changes with **Update integration**: - **Account name** - your own name for the integration. You see products under it in the **Integration** column of the **Products** list. - **Sync interval** - how often we fetch the offer: **Never**, **LIVE** (every hour), **Every 2 hours** or **Every 6 hours**. **Never** by default - then the offer is fetched only once, right after adding. More in [Fetching products](https://ritevo.com/en/docs/products/fetching-products#how-often). - **Transformation rules** - **Price rules** and **Stock rules** that change every price and every stock level of this integration, for example to add a margin. Described in [Fetching products](https://ritevo.com/en/docs/products/fetching-products#rules). - **Add product** - a button in the page header. It opens the new product form with this integration already selected. ![Hurtownia Karm integration details: account name, the LIVE sync interval and the price and stock rules](https://ritevo.com/docs/integrations/hurtownia-karm/en-details.webp) Integration fields: `accountName`, `syncInterval` (`NEVER`, `LIVE`, `EVERY_2H`, `EVERY_6H`) and `transformationRules`. Create: `POST /integrations/warehouses/hurtownia-karm` with `accountName`, change: `PATCH /integrations/warehouses/hurtownia-karm/{id}`. ### What we fetch from the wholesaler - **Product data** - name, code as SKU, EANs (the first as the EAN, the rest as additional EANs), description, images, manufacturer, the most specific category and weight. The wholesaler does not provide dimensions. A product without a code in the offer is skipped, because SKU is required. - **Price** - the net price with the VAT rate and currency from the offer. - **Stock** - the quantity in a warehouse named “Hurtownia Karm”. - **Active** - a product is active only when the wholesaler marks it as active, visible and available for sale. ### Deleting the integration **Delete integration** turns the integration off in Ritevo and stops fetching. Products, prices and stock levels saved earlier stay in the **Products** list. **Restore integration** turns it back on. ### What the integration does not do - It does not place orders with the wholesaler. - It does not fetch product variants or gross prices. - It does not deduct or reserve stock after a sale - stock in Ritevo changes only through a wholesaler fetch or your own edit. - It does not send products, prices or stock levels to sales channels. ### The integration through the API This integration's endpoints are under `/integrations/warehouses/hurtownia-karm`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/warehouses`. Products are under `/integrations/warehouses/products`. The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/own-warehouse (updated 2026-09-29) ## Own warehouse Own warehouse in Ritevo: adding products, prices and stock by hand, several warehouses at once, price rules and adding products through the API. An own warehouse is a place for products you manage yourself. Nothing is fetched from outside - you add products, prices and stock in Ritevo or through the API. > **Required integration:** You need no external account. You can add as many Own warehouse integrations as you like - each has its own set of products, for example with different price rules. Each works on its own. Uniqueness is not checked, on purpose: every create call makes a new integration, also for the same `externalId`, so one account can have several integrations with different details or settings. ### Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Warehouses and wholesalers** section pick the **Own warehouse** tile. 3. In the **Account name** field enter the warehouse name, for example “Main warehouse”, and click **Create integration**. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the Own warehouse tile framed in the Warehouses and wholesalers section](https://ritevo.com/docs/integrations/own-warehouse/en-catalogue.webp) ![The Own warehouse add screen with the Account name field and the Create integration button](https://ritevo.com/docs/integrations/own-warehouse/en-add.webp) ### Integration settings On the integration page you will find the fields below. You save changes with **Update integration**: - **Account name** - your own name for the integration. You see products under it in the **Integration** column of the **Products** list. - **Transformation rules** - **Price rules** and **Stock rules** that change every price and every stock level of this integration, for example to add a margin. Described in [Fetching products](https://ritevo.com/en/docs/products/fetching-products#rules). - **Add product** - a button in the page header. It opens the new product form with this integration already selected. ![Own warehouse integration details: account name, transformation rules and the Add product and Update integration buttons](https://ritevo.com/docs/integrations/own-warehouse/en-details.webp) Integration fields: `accountName` and `transformationRules`. Create: `POST /integrations/warehouses/own` with `accountName`, change: `PATCH /integrations/warehouses/own/{id}`. An own warehouse has no `syncInterval`. ### Adding products You add a product in the **Products** menu or on the integration page: 1. Click **Add product** and pick this warehouse, if it is not selected yet. 2. Fill in **Basic data**, **Identifiers**, **Description** and **Dimensions**. You can leave **External id** empty - if you enter a value that already exists in this warehouse, we update that product instead of creating a new one. 3. Click **Save product**. 4. In the product add a price with **Add price** and save it with **Save price**. 5. Add stock with **Add stock** and save it with **Save stock**. A product can have several stock levels, for example from different shelves or locations. > **Good to know:** Saving is queued in the background - you see **Product creation requested** or **Product update requested**, and the changes show up shortly. Images cannot be added in the app - you provide them only through the API. ### Deleting the integration **Delete integration** turns the integration off in Ritevo and stops fetching. Products, prices and stock levels saved earlier stay in the **Products** list. **Restore integration** turns it back on. ### What the integration does not do - It does not import products from a file - you add larger amounts through the API, up to 1000 products per request. - It does not deduct or reserve stock after a sale - stock in Ritevo changes only through a wholesaler fetch or your own edit. - It does not send products, prices or stock levels to sales channels. ### The integration through the API This integration's endpoints are under `/integrations/warehouses/own`, and the ones shared by the whole type (list, get one, delete, restore) under `/integrations/warehouses`. You save products with `PUT /integrations/warehouses/{integrationId}/products` (and `/prices`, `/stocks`) - details in [Fetching products](https://ritevo.com/en/docs/products/fetching-products#api). The current paths, fields, types and response codes are always in Swagger: https://api.ritevo.com/api/v1/api-docs. --- Source: https://ritevo.com/en/docs/integrations/ritevo-printer (updated 2026-10-07) ## Ritevo Printer Ritevo Printer - the app that prints courier labels (PDF, ZPL, EPL) and receipts on Polish fiscal printers: supported systems, download, connecting a printer, printing from orders and actions. Ritevo Printer prints courier labels and fiscal receipts straight from your Ritevo orders. You install it on the computer your printer is connected to - or several printers at once - and order printouts in the panel: from an order, with an automatic action or even from your phone. > **Required integration:** You need a computer with Windows, macOS or Linux that your printer (or several printers) is connected to, with the Ritevo Printer app installed. In the Ritevo panel add a new **Printer** integration - a separate one for each printer - and link it with the Ritevo Printer app on the computer. ### How it works - **One printer - one integration.** Every printer is a separate **Printer** integration in the panel, with its own token. - **Many printers in one app.** At one workstation you can add e.g. a fiscal printer for receipts and an ordinary printer for PDF labels - each works on its own. - **Many workstations.** Every computer has its own Ritevo Printer app with its own printers - e.g. a till with receipts and a packing station with labels, or separate workstations for several employees. - **Order from anywhere.** You order a printout in the panel - on a computer or on your phone - and it is printed by the computer running the app with that printer. - **Runs in the background.** Closing the window hides the app in the system tray. Tick **Start the agent at login** so it keeps printing after the computer restarts. ### Supported systems and printers PDF labels print on any printer added to the computer, also an ordinary inkjet or laser printer. ZPL and EPL labels print only on a label printer, e.g. Zebra. Receipts are printed through software supplied by the fiscal printer vendor - and not every vendor made it for every system. What works where: | | Windows | Linux | macOS | | --- | --- | --- | --- | | PDF labels | ✓ | ✓ | ✓ | | ZPL / EPL labels | ✓ | ✓ | ✓ | | Receipts - Novitus | ✓ | ✓ network printer only | ✓ | | Receipts - Posnet | ✓ | ✓ | ✓ Intel Macs only | | Receipts - Elzab | ✓ | ✓ /dev/ttyS port or network printer | ✗ | - A Novitus printer must use the XML protocol - a setting in the printer's menu. In the older classic protocol the app recognises it but cannot print a receipt. - The system sees a fiscal printer connected over USB as a serial port (a COM port on Windows) - on Windows this needs the printer vendor's driver. - A fiscal printer on the network is given as its address and port, e.g. `tcp:192.168.1.50:6666` - you will find the port in the printer's settings. - We support Novitus, Posnet and Elzab fiscal printers, and receipts are printed only in PLN. ### Download and installation Download the version for your system - all versions are also on the [Download Ritevo Printer](/en/ritevo-printer) page: - **Windows** - [ritevo-printer-setup.exe](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer-setup.exe) - **macOS, Apple Silicon (M1 and newer)** - [ritevo-printer-arm64.dmg](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer-arm64.dmg) - **macOS, Intel** - [ritevo-printer-x64.dmg](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer-x64.dmg) - **Linux** - [ritevo-printer.AppImage](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer.AppImage) or [ritevo-printer_amd64.deb](https://ritevo-printer.s3.eu-north-1.amazonaws.com/ritevo-printer/ritevo-printer_amd64.deb) The app is not signed with a certificate, so on the first launch the system asks for your consent: - **Windows** - in the SmartScreen window click **More info**, then **Run anyway**. - **macOS** - when told that Apple cannot verify the app, click **Done**, go to **System Settings → Privacy & Security** and click **Open Anyway**. Updates: on Windows and Linux (AppImage) a new version downloads by itself and installs when nothing is printing - you can also click **Restart and update**. On macOS the app shows **Download the new version** - download the file and drag Ritevo Printer to the Applications folder. The .deb version is updated by hand. ![The Updates section in Ritevo Printer with the version number and the Check for updates button](https://ritevo.com/docs/integrations/ritevo-printer/en-agent-updates.webp) ### Adding the printer in the panel 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **Printers** section pick the **Printer** tile. 3. Enter the **Printer name** - your own name, e.g. of the workstation - and click **Add integration**. 4. Open the printer in the integrations list and in the **Printer token** card click **Show token**. Copy it - you paste it in the app. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Ritevo integration catalogue with the Printer tile framed in the Printers section](https://ritevo.com/docs/integrations/ritevo-printer/en-catalogue.webp) ![The add printer form with the Printer name field](https://ritevo.com/docs/integrations/ritevo-printer/en-add.webp) ![The integrations list with the added printer Stanowisko #1](https://ritevo.com/docs/integrations/ritevo-printer/en-list.webp) ### Adding the printer in the app 1. Open Ritevo Printer and click **+ Add printer**. 2. Paste the **Printer token** from the panel. 3. In the **Printer** field choose the printer you want to use. Choose a fiscal printer connected to the network as **Fiscal printer on the network (IP address)** and enter its address. 4. The app finds out by itself what printer it is and shows **Connected printer**. 5. Click **Save printer**. 6. Click **Start**. The printer shows **Working - waiting for jobs**. You can add more printers, e.g. one for labels and another for receipts: click **+ Add printer** again and paste the token of the next printer from the panel. ![The new printer form in Ritevo Printer with the token and a recognised system printer](https://ritevo.com/docs/integrations/ritevo-printer/en-agent-add.webp) ![The Ritevo Printer window with the printers list and the Add printer button](https://ritevo.com/docs/integrations/ritevo-printer/en-agent-printers.webp) > **Good to know:** Your label printer is not on the list? Add it to the system first: on Windows in **Settings → Printers & scanners**, on a Mac in **System Settings → Printers & Scanners**. On a Mac pick the **AirPrint** driver for an ordinary inkjet or laser printer - with the generic PostScript driver nothing comes out. ### Printing You order a printout by hand or with an automatic action: - **Label** (by hand) - in the order details, in the **Shipments** card, click **Print** and choose the printer. - **Receipt** (by hand) - in the order details open the receipt button and choose the printer in the **Print** section. You can do the same from the documents list. - **Print shipment label** (action step) (API: "Print shipment label" = `PRINT_SHIPMENT_LABEL`; value in `actionSteps[].action.type`) - prints the label of the order's newest successful shipment on the chosen printer. - **Print receipt** (action step) (API: "Print receipt" = `PRINT_RECEIPT`; value in `actionSteps[].action.type`) - prints the order's newest receipt on the chosen fiscal printer. - **Print job ordered** (action trigger) (API: "Print job ordered" = `CREATE_PRINT_JOB`; value in `triggerType`) - starts the action when a printout is ordered. ![The Shipments card in an order with the Print button open and the list of printers](https://ritevo.com/docs/integrations/ritevo-printer/en-print-label.webp) ![Issued documents in an order with the receipt open and the Print section listing the printers](https://ritevo.com/docs/integrations/ritevo-printer/en-print-receipt.webp) An ordered printout waits in the **Current queue** card in the printer's details until the app picks it up - printouts ordered while the computer is off come out once it is on. You see the result in the **Print history** card: - **Printed** (API: "Printed" = `SUCCESS`; value in `status`) - the app picked up the printout and sent it to the printer. - **Error** (API: "Error" = `ERROR`; value in `status`) - the printout could not be prepared, e.g. the courier did not hand over the label. The badge shows the kind of error and the icon next to it the message. ![Printer details in Ritevo: token, current queue and print history](https://ritevo.com/docs/integrations/ritevo-printer/en-details.webp) In the app itself, in the **Recent jobs and errors** section, you see what was printed on which printer, and printer errors such as running out of paper. ![The Recent jobs and errors section in Ritevo Printer](https://ritevo.com/docs/integrations/ritevo-printer/en-agent-history.webp) ### Printing in an automatic action What to keep in mind when an action is to print something: - **Print shipment label** (API: "Print shipment label" = `PRINT_SHIPMENT_LABEL`; value in `uuidValue`: id of a printer integration: `GET /integrations/printers`) - takes the order's newest shipment that was created successfully. If there is none, the step ends with an error. - **Print receipt** (API: "Print receipt" = `PRINT_RECEIPT`; value in `uuidValue`: id of a printer integration: `GET /integrations/printers`) - takes the order's newest receipt that has not been deleted. If the order has no receipt, the step ends with an error. - **Create shipment**, then **Print shipment label** (API: "Create shipment" = `CREATE_SHIPMENT`, "Print shipment label" = `PRINT_SHIPMENT_LABEL`) - first the shipment, the label in the next step. The shipment step waits for the courier's answer, so the label is ready before it is time to print. - **Generate receipt**, then **Print receipt** (API: "Generate receipt" = `GENERATE_RECEIPT`, "Print receipt" = `PRINT_RECEIPT`) - the same for a receipt: first the document, the printout in the next step. - **Shipment status is** (API: "Shipment status is" = `SHIPMENT_STATUS_IS`; value in `enumValues`: `PENDING`, `SUCCESS`, `ERROR`) - to avoid printing a label after a failed shipment, add a [branch](https://ritevo.com/en/docs/automations/how-it-works#branches) with this condition and the value Created successfully in the print step. The print step does not wait for the paper to come out of the printer. The action moves on once the printout is in the queue, or right away when it fails - an error does not stop the action. There is no condition on the printout's result, so you check it in the **Print history**. If a printout reaches the wrong kind of printer - a label on a fiscal one or a receipt on an ordinary one - only the app on the computer rejects it. You see that in the app's history; the action does not learn about it. ### Fiscal receipts - A receipt is printed only through the printer vendor's official library. - Before a receipt reaches the printer we check that it is a receipt in Polish zloty and that its items add up to the document total. - The app remembers every receipt it printed. If the same receipt is ordered again on this computer, it is not printed a second time and the app shows a message. This protection works only within one computer, so connect a fiscal printer in the app at one workstation only and order each receipt to one printer - another workstation does not know what has already been printed. - When the connection to the printer breaks during a receipt, the app shows **Check the printer** - check on the printer whether it came out before sending it again. > **Good to know:** The receipt header - company name, address and tax ID - comes from the fiscal printer's own memory, entered by the service technician at fiscalisation. The seller details and issuer name from the Ritevo receipt settings are left out of a fiscal printout and cannot be changed from the panel. ### Deleting the integration In the printer's details in the panel click **Delete integration** - printouts stop going to it. In the app remove it with the **Remove** button next to the printer. ### What the integration does not do - It does not print invoices or corrections on a fiscal printer - only receipts. - It does not print receipts in a currency other than PLN. - It does not support fiscal printers from outside Poland or Novitus printers in the classic protocol. ### The integration through the API Printers: `GET /integrations/printers` (list), `GET /integrations/printers/{integrationId}` (details), `GET /integrations/printers/{integrationId}/queue` (current queue), `GET /integrations/printers/{integrationId}/history` (print history, `status`: `SUCCESS` or `ERROR`, with `errorType` and `errorMessage` on an error), `GET /integrations/printers/{integrationId}/token` (the token for the app). Adding: `POST /integrations/printers`, renaming: `PATCH /integrations/printers/{integrationId}`, deleting: `DELETE /integrations/printers/{integrationId}`. Printing a label: `POST /orders/{orderId}/print-shipment-label/{shipmentId}/{printerIntegrationId}` (only a shipment with `status` = `SUCCESS`), printing a receipt: `POST /orders/billings/{billingId}/print/{printerIntegrationId}`. In order actions the steps are `PRINT_SHIPMENT_LABEL` and `PRINT_RECEIPT` in `actionSteps[].action.type` with `uuidValue` = the printer id, and the **Print job ordered** trigger is `triggerType` = `CREATE_PRINT_JOB`. Full description: [Order actions](https://ritevo.com/en/docs/automations/order-actions). Print steps are not among the steps that wait for an external system: the next step starts right after the printout is accepted into the queue, or after an error (in the history `status` = `ERROR`, e.g. when the order has no shipment with `status` = `SUCCESS` or no receipt). The label always comes from the newest shipment with `status` = `SUCCESS`, the receipt from the newest not-deleted document with `billingType` = `RECEIPT`. There is no action condition on the printout's result. The `CREATE_PRINT_JOB` trigger starts an action after every such result, successful or failed. Rejections by the app (wrong kind of printer, printer not ready) do not come back to the action.