Integracja z Shoper

SynclyLink łączy się ze sklepem Shoper przez Integration Hub i API Shoper. Do jednej firmy możesz podłączyć wiele sklepów, osobno konfigurować mapowania oraz śledzić import w Centrum Integracji.

Co umożliwia integracja?

• Import zamówień z Shoper do SynclyLink.
• Import produktów i wariantów z Shoper.
• Mapowanie statusów zamówień, metod dostawy i metod płatności.
• Automatyczne rejestrowanie płatności na podstawie pola paid.
• Aktualizację stanów magazynowych z SynclyLink do Shoper.
• Podgląd rekordów importu i błędów w Centrum Integracji.

Podłączanie sklepu

Integracje -> Shoper -> Dodaj sklep

Podczas dodawania sklepu uzupełnij:

• etykietę konta,
• URL sklepu, np. https://twojsklep.pl,
• API base URL, np. https://twojsklep.pl/webapi/rest,
• client_id,
• client_secret,
• interwał synchronizacji.

notatka

Nie wpisujesz ręcznie access tokenu ani refresh tokenu. SynclyLink i Integration Hub pobierają oraz odświeżają tokeny automatycznie na podstawie danych klienta API.

Autoryzacja i tokeny

Shoper obsługuje OAuth oraz autoryzację po client_id i client_secret. W konfiguracji SynclyLink przechowywane są dane klienta API, a tokeny dostępowe są odnawiane automatycznie.

Gdy Integration Hub pobierze lub odświeży tokeny, zapisuje je w SynclyLink przez wewnętrzny endpoint:

POST /internal/v1/shoper/accounts/:id/tokens

W kartotece konta możesz użyć przycisku Odśwież token, jeśli trzeba wymusić regenerację tokenu integracyjnego używanego do komunikacji wewnętrznej.

Konfiguracja mapowań

W szczegółach konta Shoper dostępne są trzy sekcje mapowań.

Mapowania statusów

Mapowanie statusów określa, jaki status zamówienia w SynclyLink ma zostać ustawiony dla statusu z Shoper.

Przykład:

Status Shoper	Status płatności	Status SynclyLink
1	*	NEW
2	paid	PROCESSING
shipped	*	SENT

Mapowania dostaw

Mapowanie dostaw przypisuje kod dostawy z Shoper do metody wysyłki w SynclyLink.

Przykład:

Kod Shoper	Metoda wysyłki w SynclyLink
8	INPOST
courier	DPD

Mapowania płatności

Mapowanie płatności przypisuje identyfikator lub nazwę metody płatności z Shoper do metody płatności w SynclyLink.

Przykład:

Metoda Shoper	Metoda płatności w SynclyLink
1	PRZELEW
blik	BLIK
card	KARTA

Import zamówień

Zamówienia trafiają do SynclyLink przez Integration Hub i Centrum Integracji:

Shoper API /orders
  -> Integration Hub
  -> POST /internal/v1/integration-core/shoper/inbox
  -> integration_inbox: shoper / order
  -> normalizacja do CanonicalOrder
  -> utworzenie zamówienia sprzedaży

Podczas importu system:

• tworzy lub odnajduje klienta,
• przenosi adres rozliczeniowy i adres dostawy,
• mapuje stawkę VAT z linii,
• mapuje status, dostawę i płatność,
• decyduje o rodzaju dokumentu fiskalnego,
• zapisuje błędy walidacji w Centrum Integracji.

Jeśli payload nie ma NIP-u (tax_identification_number jest puste), zamówienie powinno zostać potraktowane jako paragon, a nie faktura.

Automatyczne płatności

Shoper przekazuje kwotę zapłaconą w polu paid.

Jeżeli paid jest większe od 0, SynclyLink rejestruje płatność do zamówienia na tę kwotę. Metoda płatności jest ustalana z mapowania płatności, np. na podstawie payment_id.

wskazówka

Jeśli płatność nie utworzyła się poprawnie, sprawdź mapowanie płatności dla danego konta oraz rekord shoper / order w Centrum Integracji.

Import produktów

Produkty są pobierane z Shoper przez Integration Hub:

Shoper API /products
  -> Integration Hub
  -> POST /internal/v1/shoper/accounts/:id/items/bulk
  -> integration_inbox: shoper / item
  -> shoper_item
  -> CanonicalItem

System zapisuje między innymi:

• identyfikator produktu z Shoper,
• identyfikator wariantu lub stanu magazynowego,
• SKU,
• nazwę,
• cenę,
• VAT,
• EAN,
• ilość magazynową,
• powiązanie z kartoteką towaru SynclyLink, gdy uda się dopasować po SKU.

Aktualizacja stanów magazynowych

Zmiana stanu w magazynie SynclyLink uruchamia eksport do Shoper:

InventoryUpdatedEvent
  -> ShoperInventoryWorker
  -> outbox_event: connector=shoper, topic=inventory.updated
  -> Integration Hub /shoper/inventory/push
  -> aktualizacja produktu lub wariantu w Shoper

Ilość wysyłana do Shoper to dostępny stan sprzedażowy. Produkt jest odnajdywany po mapowaniu w shoper_item, przede wszystkim po identyfikatorze wariantu lub produktu z Shoper.

Logi i diagnostyka

Najważniejsze miejsca diagnostyczne:

• Konto Shoper -> Logi sync: rekordy z Centrum Integracji dla danego konta.
• Konto Shoper -> Zamówienia: importy zamówień.
• Centrum Integracji: wszystkie rekordy shoper / item, shoper / order, shoper / sync_run.
• Integration Hub logs: błędy połączenia z API Shoper, odświeżania tokenów i aktualizacji stanów.

Typowe problemy:

• błędny api_base_url, np. literówka w domenie sklepu,
• brak mapowania metody płatności lub dostawy,
• brak wymaganego słownika w SynclyLink, np. stawki VAT,
• niepoprawny token lub wygasłe dane klienta API,
• produkt bez SKU, którego nie da się połączyć z kartoteką towaru.