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


---

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