# 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. --- Cała pomoc w jednym pliku: https://ritevo.com/llms-full.txt. Mapa pomocy z linkami do wszystkich stron: https://ritevo.com/llms.txt.