# 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.


---

Cała pomoc w jednym pliku: https://ritevo.com/llms-full.txt. Mapa pomocy z linkami do wszystkich stron: https://ritevo.com/llms.txt.