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