Integracja z 1C, ERP, CRM-systemami i CommerceAPI
Automatyczny eksport przy zamówieniu / Wysyłka danych POST o zamówieniu w formacie JSON
Automatyczny eksport przy zamówieniu możesz włączyć w ustawieniach strony, w zakładce «Sklep», określając ścieżkę do wysyłki danych.Na podany adres będzie wysyłane żądanie POST, ze wszystkimi danymi o zamówieniu, w tym danymi kontaktowymi zamawiającego i listą produktów. Dane kontaktowe i informacje o zamówieniu będą przekazywane w formacie JSON, żądaniem POST.
Na przykład, w 1c możesz zaimplementować przyjmowanie zamówień przez «HTTP serwis»->«SiteExchange» -> «POSTData»
Jeśli po wysłaniu żądania, Twój serwis zwróci dane JSON, z zawartością «Number» lub «crm_order_id», to do zamówienia zostanie dodany zewnętrzny numer zamówienia.
Automatyczny eksport statystyk sprzedaży / Wysyłka danych POST o zamówieniu w formacie JSON
Automatyczny eksport statystyk sprzedaży możesz włączyć w ustawieniach strony, w zakładce «Sklep», określając ścieżkę do wysyłki danych.Na podany adres będzie wysyłane żądanie POST, ze wszystkimi danymi o zamówieniu, które zmieniają się w Statystyce sprzedaży. Informacje będą przekazywane żądaniem POST w formacie JSON.
Na przykład, w 1c możesz zaimplementować przyjmowanie zamówień przez «HTTP serwis»->«SiteExchange» -> «POSTData»
Ponadto możesz włączyć zewnętrzny dostęp do swojej statystyki, określając «Klucz dostępu do statystyki sprzedaży».
Dostęp do statystyk sprzedaży / JSON
Określ klucz dostępu do statystyk sprzedaży w ustawieniach, w zakładce «Sklep». Jeśli potrzebujesz uzyskać dostęp do statystyk sprzedaży zewnętrzną aplikacją, możesz wykonać (POST/GET lub AJAX) żądanie pod adresem «
/ajax.php?statistic_sell» Przy tym należy podać klucz w żądaniu, z szyfrowaniem MD5. Na przykład, jeśli masz określony klucz «123», to w żądaniu będzie to «
202cb962ac59075b964b07152d234b70».W takim przypadku żądanie będzie wyglądać następująco: «
/ajax.php?statistic_sell&key=202cb962ac59075b964b07152d234b70»
W żądaniu można określić dane do sortowania lub wyszukiwania (parametry GET/POST), które można pobrać na stronie statystyk sprzedaży w centrum administracyjnym (
/page.php?p=statistic_sell&mystat). Sortowanie i wybór parametrów odbywa się przez żądanie GET/POST, na przykład «&sort_dateperiod=1week» oznacza, że będą wyświetlane statystyki sprzedaży za tydzień. Dane wyświetlane są w formacie JSON.
Zwróć uwagę, że jeśli używasz otwartych dla odwiedzających żądań strony, to za pomocą Twojego klucza mogą uzyskać dostęp do Twoich statystyk sprzedaży.
Dostęp do cennika sklepu / Pełny wywóz cennika w CSV
Określ klucz dostępu do cennika sklepu w ustawieniach, w zakładce «Sklep». Pełny wywóz cennika znajduje się pod adresem «/csv_export_products.csv»
Przy tym należy podać klucz w żądaniu, z szyfrowaniem MD5. Na przykład, jeśli masz określony klucz «123», to w żądaniu będzie to «
202cb962ac59075b964b07152d234b70».W takim przypadku żądanie będzie wyglądać następująco: «
/csv_export_products.csv?key=202cb962ac59075b964b07152d234b70»
W żądaniu można określić dane do sortowania i wyboru pól, które można pobrać na stronie eksportu w centrum administracyjnym (/page.php?p=submit_catalog_page&subpage&export_from_shop). Sortowanie i wybór parametrów odbywa się przez żądanie GET/POST, na przykład «
&export_product_access=export_product_access» oznacza, że będzie eksportowane pole z danymi o dostępie do produktu. Dane wyświetlane są w formacie CSV.
Plik eksportu jest buforowany w celu zmniejszenia obciążenia i aktualizowany raz na dobę. Usunąć bufor można za pomocą przycisku «Wyczyść bufor eksportu XML/CSV».
Przykład: https://templatedemo437544.boostore.pro/csv_export_products.csv?key=202cb962ac59075b964b07152d234b70
Dodatkowo zaimplementowano mechanizm wymiany danych przez API, podobny do WooCommerce API. API pozwala uzyskiwać i aktualizować informacje o zamówieniach i produktach, a także kategoriach. Instrukcje i ustawienia w sekcji «Sklep» - «Wymiana danych JSON Commerce API».
Commerce API (Products/Categories/Sales Statistics)
Commerce API — Krótki podręcznik metod
Klucz dostępu
Do pracy z API potrzebny jest klucz dostępu (Consumer Secret), który tworzysz w sekcji „Ustawienia”, „Sklep”, „Dostęp do statystyk sprzedaży”. Klucz generowany jest na podstawie klucza do dostępu do statystyk sprzedaży.
Metody API (HTTP)
Wszystkie zapytania kierowane są na bazowy URL twojej strony, np.: https://site.com/api/commerce/
1. Statystyki sprzedaży
| Metoda | URL | Opis |
|---|---|---|
| GET | /orders | Pobierz statystyki zamówień |
| GET | /orders/{id} | Pobierz statystyki pojedynczego zamówienia po ID |
| GET | /crm_orders/{id} | Pobierz statystyki pojedynczego zamówienia po zewnętrznym CRM ID |
| DELETE | /orders/{id} | Usuń zamówienie po ID |
| DELETE | /crm_orders/{id} | Usuń zamówienie po zewnętrznym CRM ID |
| POST | /orders | Dodaj nowe zamówienie |
| UPDATE | /orders/{id} | Zaktualizuj zamówienie po ID (PATCH/PUT/UPDATE) |
| UPDATE | /crm_orders/{id} | Zaktualizuj zamówienie po zewnętrznym CRM ID (PATCH/PUT/UPDATE) |
2. Produkty
| Metoda | URL | Opis |
|---|---|---|
| POST | /products | Masowe dodawanie i aktualizacja produktów |
| GET | /products | Pobierz listę produktów |
| GET | /products/{id} | Podgląd pojedynczego produktu po ID |
| GET | /products/sku/{sku} | Podgląd pojedynczego produktu po SKU (kod produktu) |
| UPDATE | /products/{id} | Zaktualizuj produkt po ID (PATCH/PUT/UPDATE) |
| UPDATE | /products/sku/{sku} | Zaktualizuj produkt po SKU (kod produktu) (PATCH/PUT/UPDATE) |
| UPDATE | /products | Masowa aktualizacja kilku produktów (PATCH/PUT/UPDATE) |
| DELETE | /products/{id} | Usuń produkt po ID |
| DELETE | /products/sku/{sku} | Usuń produkt po SKU (kod produktu) |
3. Kategorie sklepu
| Metoda | URL | Opis |
|---|---|---|
| POST | /products/categories | Masowe dodawanie i aktualizacja kategorii |
| GET | /products/categories | Pobierz listę kategorii produktów |
| GET | /products/categories/{id} | Pobierz kategorię według ID |
| GET | /products/categories/id/{id} | Pobierz kategorię według ID (alternatywna opcja) |
| GET | /products/categories/name/{name} | Pobierz kategorię według nazwy |
| UPDATE | /products/categories | Masowa aktualizacja kilku kategorii (PATCH/PUT/UPDATE) |
| UPDATE | /products/categories/{id} | Zaktualizuj kategorię według ID (PATCH/PUT/UPDATE) |
| UPDATE | /products/categories/id/{id} | Zaktualizuj kategorię według ID (alternatywna opcja) |
| UPDATE | /products/categories/name/{name} | Zaktualizuj kategorię według nazwy |
Parametry kategorii nadrzędnych
| Parametr | Typ | Opis |
|---|---|---|
category_parent_id |
int | ID kategorii nadrzędnej. Używany w pierwszej kolejności, jeśli jest podany. |
category_parent_name |
string | Łacińska nazwa (alias / slug, adres otwarcia kategorii) kategorii nadrzędnej. Używany, jeśli category_parent_id nie jest podany. W przypadku zbieżności nazw można doprecyzować przez category_lang. |
category_lang |
string | Język kategorii. Stosowany do rozwiązywania kolizji takich samych category_parent_name w różnych językach. |
Zasada działania:
- Najpierw sprawdzany jest
category_parent_id. - Jeśli nie jest podany – używany jest
category_parent_name. - W przypadku zbieżności nazw – dodawana jest weryfikacja przez
category_lang.
Szczególna zasada:
Aby dodać kategorię do głównej (korzeniowej) kategorii, należy wskazać category_parent_name = "main" i obowiązkowo podać parametr category_lang – język kategorii nadrzędnej.
Aktualizacja i usuwanie:
update_exists (bool) – jeśli true, aktualizuje kategorię, jeśli już istnieje (domyślnie false).
delete (bool) – jeśli true, kategoria zostanie usunięta.
4. Producenci
| Metoda | URL | Opis |
|---|---|---|
| POST | /products/producers | Masowe dodawanie i aktualizacja producentów |
| GET | /products/producers | Pobierz listę producentów |
| GET | /products/producers/{id} | Pobierz producenta według ID |
| GET | /products/producers/id/{id} | Pobierz producenta według ID (alternatywna opcja) |
| GET | /products/producers/name/{name} | Pobierz producenta według nazwy |
| UPDATE | /products/producers | Masowa aktualizacja kilku producentów (PATCH/PUT/UPDATE) |
| UPDATE | /products/producers/{id} | Zaktualizuj producenta według ID (PATCH/PUT/UPDATE) |
| UPDATE | /products/producers/id/{id} | Zaktualizuj producenta według ID (alternatywna opcja) |
| UPDATE | /products/producers/name/{name} | Zaktualizuj producenta według nazwy |
Parametry powiązań producentów
| Parametr | Typ | Opis |
|---|---|---|
producer_parent_id |
int | ID producenta nadrzędnego (grupy). Używany w pierwszej kolejności, jeśli jest podany. |
producer_parent_name |
string | Łacińska nazwa (alias / slug, adres otwarcia producenta). Używany, jeśli producer_parent_id nie jest podany. W przypadku zbieżności nazw można doprecyzować przez producer_lang. |
producer_lang |
string | Język producenta. Stosowany do rozwiązywania kolizji takich samych producer_parent_name w różnych językach. |
Zasada działania:
- Najpierw sprawdzany jest
producer_parent_id. - Jeśli nie jest podany – używany jest
producer_parent_name. - W przypadku zbieżności nazw – dodawana jest weryfikacja przez
producer_lang.
Szczególna zasada:
Aby dodać producenta do głównej (korzeniowej) grupy producentów, należy wskazać producer_parent_name = "main" i obowiązkowo podać parametr producer_lang – język grupy nadrzędnej.
Aktualizacja i usuwanie:
update_exists (bool) – jeśli true, aktualizuje producenta, jeśli już istnieje (domyślnie false).
delete (bool) – jeśli true, producent zostanie usunięty.
5. Kolekcje
| Metoda | URL | Opis |
|---|---|---|
| POST | /products/collections | Masowe dodawanie i aktualizacja kolekcji |
| GET | /products/collections | Pobierz listę kolekcji |
| GET | /products/collections/{id} | Pobierz kolekcję według ID |
| GET | /products/collections/id/{id} | Pobierz kolekcję według ID (alternatywna opcja) |
| GET | /products/collections/name/{name} | Pobierz kolekcję według nazwy |
| UPDATE | /products/collections | Masowa aktualizacja kilku kolekcji (PATCH/PUT/UPDATE) |
| UPDATE | /products/collections/{id} | Zaktualizuj kolekcję według ID (PATCH/PUT/UPDATE) |
| UPDATE | /products/collections/id/{id} | Zaktualizuj kolekcję według ID (alternatywna opcja) |
| UPDATE | /products/collections/name/{name} | Zaktualizuj kolekcję według nazwy |
Parametry powiązań kolekcji
| Parametr | Typ | Opis |
|---|---|---|
collection_parent_id |
int | ID kolekcji nadrzędnej. Używany w pierwszej kolejności, jeśli jest podany. |
collection_parent_name |
string | Łacińska nazwa (alias / slug, adres otwarcia kolekcji). Używany, jeśli collection_parent_id nie jest podany. W przypadku zbieżności nazw można doprecyzować przez collection_lang. |
collection_lang |
string | Język kolekcji. Stosowany do rozwiązywania kolizji takich samych collection_parent_name w różnych językach. |
Zasada działania:
- Najpierw sprawdzany jest
collection_parent_id. - Jeśli nie jest podany – używany jest
collection_parent_name. - W przypadku zbieżności nazw – dodawana jest weryfikacja przez
collection_lang.
Szczególna zasada:
Aby dodać kolekcję do głównej (korzeniowej) kolekcji, należy wskazać collection_parent_name = "main" i obowiązkowo podać parametr collection_lang – język kolekcji nadrzędnej.
Aktualizacja i usuwanie:
update_exists (bool) – jeśli true, aktualizuje kolekcję, jeśli już istnieje (domyślnie false).
delete (bool) – jeśli true, kolekcja zostanie usunięta.
6. Sortowanie i paginacja
Dla metod /orders i /products dostępne są parametry stronicowania i sortowania:
Parametry paginacji
| Parametr | Typ | Opis |
|---|---|---|
page | int | Numer strony (domyślnie 1) |
per_page | int | Liczba elementów na stronę (domyślnie 90, maksymalnie 2000) |
Parametry sortowania
| Parametr | Typ | Dozwolone wartości | Opis |
|---|---|---|---|
orderby | string | id, title, price, date, views | Pole do sortowania |
order | string | asc, desc | Kierunek sortowania |
Parametry języka
| Parametr | Typ | Dozwolone wartości | Opis |
|---|---|---|---|
l | string | ru, ua, en, de, fr, es, it, pl | Język wyświetlania wartości |
Dodatkowo dla zamówień
Można filtrować zamówienia według daty i statusu:
?after=YYYY-MM-DD— Data początkowa (w formacie ISO)?before=YYYY-MM-DD— Data końcowa?status=pending|processing|on-hold|completed|cancelled|0|1|2|3|5|6|7|8— Status zamówienia (można podać tekstowy status WooCommerce lub kod liczbowy)0— Nieprzetworzone (pending)1— Zamówienie w trakcie realizacji (processing)7— Zamówienie w trakcie realizacji, oczekuje na dostawę (on-hold)3— Zrealizowane (completed)8— Zrealizowane i zakończone (completed)2— Anulowane (cancelled)5— Anulowane: brak w magazynie (cancelled)6— Anulowane: odmowa (cancelled)?show_deleted=1— Pokaż ukryte zamówienia
Przykłady
GET /orders?page=2&per_page=100&after=2024-06-01&before=2024-06-30
GET /products?orderby=price&order=asc&per_page=50
Przykład autoryzacji
W zapytaniu należy podać klucze:
?consumer_secret=TWOJ_SEKRET (uwaga, nie udostępniaj tego klucza publicznie!)
Lub przez nagłówek Authorization z OAuth 1.0a.
Dodaj nowe zamówienie (POST /orders)
Aby utworzyć nowe zamówienie przez API, wyślij żądanie POST na /orders z treścią JSON.
Minimalnie musisz podać:
email— Email klienta (wymagane!)line_items— Lista produktów do dodania
Parametry zamówienia
Podczas tworzenia zamówienia możesz podać dodatkowe pola, na przykład:
{
"first_name": "Imię",
"last_name": "Nazwisko",
"email": "alex@example.com",
"phone": "+487001112233",
"address": "Pełny adres jeśli nie używasz eform",
"buyer_address_eform1": "Województwo",
"buyer_address_eform2": "Miasto",
"buyer_address_eform3": "Ulica",
"buyer_address_eform4": "Numer domu",
"buyer_address_eform5": "Mieszkanie",
"postcode": "01-001",
"total": "999",
"status": "processing",
"status_for_customer": "processing",
"line_items": [ ... ]
}
Opis pola total:
total— końcowa kwota zamówienia (ciąg lub liczba). Jeśli podana, będzie użyta jako ostateczna cena zamówienia.- Jeśli
totalnie jest podane, kwota zamówienia zostanie automatycznie obliczona na podstawie sumyline_items. - Pole
totalnie jest wymagane i może być użyte do zamówień bez produktów.
Format line_items
Parametr line_items to tablica produktów. Każdy produkt to obiekt z następującymi polami:
"line_items": [
{
"product_id": 478734,
"quantity": 1,
"price": 100,
"currency": "USD"
},
{
"product_id": 478268,
"quantity": 10,
"variation": "51"
},
{
"product_id": 478266,
"quantity": 1,
"variation_id": 735302
}
]
- product_id — ID produktu (wymagane!).
- quantity — Ilość sztuk (wymagane!).
- price — (opcjonalne) Jeśli podana cena — będzie użyta ta wartość zamiast ceny wyliczonej na stronie.
- currency — (opcjonalne) Waluta konkretnego produktu (np.
USDlubPLN). Jeśli podana i różna od głównej waluty zamówienia (currency), system automatycznie przeliczy cenę. - variation_id — ID wariantu produktu — sposób wskazania wariantu, jeśli istnieje.
- variation — Nazwa lub kod wariantu — używane, jeśli nie ma
variation_id. Jeśli podane oba — priorytet mavariation_id.
Ważne: Jeśli główna waluta zamówienia (currency) nie jest podana — użyta zostanie domyślna waluta sklepu.
Jeśli waluta produktu różni się od głównej — cena zostanie przeliczona automatycznie.
Aktualizacja produktów
Aktualizacja produktu odbywa się przez HTTP UPDATE (lub PATCH/PUT) z użyciem URL z ID lub SKU produktu, albo wielu produktów jednym żądaniem:
/products/{id}— aktualizacja produktu po ID/products/sku/{sku}— aktualizacja produktu po kodzie SKU/products— masowa aktualizacja wielu produktów (do 5000 w jednym żądaniu)
Przy masowej aktualizacji ścieżka /products nie zawiera ID ani SKU. W tym przypadku należy przesłać tablicę obiektów produktów w parametrze products. Każdy element musi zawierać co najmniej id lub sku. Jeśli podane jest id, ma ono priorytet i może zastąpić sku. Jeśli id nie jest podane, wyszukiwanie odbywa się po sku.
Aktualizacja przesyła pełny zestaw danych produktu w formacie JSON. Wszystkie przesłane dane zastępują istniejące wartości, w tym:
- Główne właściwości produktu (nazwa, opis, ceny, status itp.)
- Atrybuty
- Warianty
- Obrazy
- Kategorie i tagi
- Ustawienia dodatkowe i meta pola
Warianty są aktualizowane zgodnie z poniższym algorytmem dla każdego wariantu w tablicy variations:
- Jeśli podane jest
id, aktualizacja odbywa się po nim. - Jeśli
idbrak, ale podane jestsku, aktualizacja odbywa się po kodzie. - Jeśli nie ma ani
id, anisku, ale jesttitle, aktualizacja odbywa się po nazwie. - Jeśli wariant nie zostanie znaleziony, zostanie utworzony nowy z podanymi parametrami.
Aktualizacja po SKU jest wygodna, gdy ID wariantu nie jest znane, ale znany jest unikalny kod.
Przy aktualizacji wszystkie pola w JSON zastąpią aktualne wartości produktu; aby zachować dane bez zmian, po prostu ich nie wysyłaj.
- Duplikaty wariantów: jeśli w tablicy
variationswystępują powtarzające się po SKU lub nazwie warianty — zostaną pominięte (ten sam wariant nie zostanie dodany dwa razy). - Główny obraz: w tablicy
imagesobraz pod indeksem0jest uznawany za główny. Jeśliimages[0]nie istnieje lub nie jest przesłany — głównym zostanie pierwszy poprawnie załadowany obraz. - Maksymalna liczba obrazów: dla jednego produktu można przesłać maksymalnie 10 obrazów. Próba przesłania większej liczby spowoduje pominięcie nadmiarowych plików.
-
Zarządzanie obrazami:
- Usuwanie obrazów: aby usunąć obraz po indeksie, ustaw w tablicy
imageswartość"delete". Na przykładimages[2] = "delete"usunie obraz o indeksie 2. Możesz jednocześnie usuwać i przesyłać, wskazując wiele kluczy:images[3] = "delete",images[1] = "https://...". - Puste indeksy: jeśli podasz pusty ciąg lub
false, ten indeks zostanie pominięty bez błędu. - Nadpisanie obrazów: parametr
images_replace: jeślitrue, system nadpisze istniejące pliki obrazów pod podanymi indeksami (usunie stary plik i cache). Jeślifalselub brak — nadpisanie jest wyłączone. - Pomijanie zajętych indeksów: parametr
images_skip_index: jeślitrue, a indeks jest zajęty i nadpisanie jest wyłączone — system znajdzie kolejny wolny indeks i zapisze tam plik. Jeślifalselub brak — indeks jest brany dokładnie jak podany. - Nowy indeks przy konflikcie: parametr
images_replace_new_index: jeślitrue, a indeks jest zajęty i zarówno nadpisanie, jak i auto-pomijanie są wyłączone — plik zostanie zapisany pod nowym wolnym indeksem. Jeśli wszystkie trzy parametry tofalselub brak i indeks jest zajęty — plik nie zostanie przesłany.
- Usuwanie obrazów: aby usunąć obraz po indeksie, ustaw w tablicy
Parametry produktu
Dostępne wartości można zobaczyć w przykładowym kodzie poniżej. Znajdują się tam również dodatkowe wyjaśnienia niektórych wartości, które mogą być przydatne.
-
Dostępne wartości
price_forDla każdego produktu można określić parametr
price_for, który ustala jednostkę rozliczeniową ceny. Dozwolone jest użycie kodu liczbowego lub tekstu (na przykład „Za 1 kg”). Oto pełna lista wartości:Można użyć wartości liczbowej lub tekstowej — system automatycznie rozpozna i przypisze właściwy kod.
-
Dostępne wartości
stock_statusDla każdego produktu możesz ustawić parametr
stock_status, który określa status dostępności produktu i jego zachowanie na stronie. Można użyć kodu liczbowego lub słowa kluczowego — system rozpoznaje obie wersje.Można podać wartość liczbową lub tekst — system automatycznie rozpozna i przekształci na odpowiedni kod.
Jeśli dla produktu ustawiono
3, zostanie on ukryty na liście produktów na stronie. Jeśli ustawiono4, produkt będzie widoczny, ale nie będzie można go dodać do koszyka. Opcja5informuje kupującego, że dostępność należy potwierdzić. -
Promocja i dostępne wartości
promotion_expires_jobDla każdego produktu możesz ustawić parametr
promotion_expires_job, który określa, co zrobić z promocją po upływie jej terminu.
Można użyć kodu liczbowego lub słowa kluczowego — system rozpoznaje obie wersje.Można podać wartość liczbową lub tekst — system automatycznie rozpozna i przekształci na odpowiedni kod.
Ważne: Aby aktywować licznik promocji, pamiętaj, aby ustawić
promotionna1— to oznacza, że promocja jest aktywna.Należy również podać datę zakończenia promocji w parametrze
promotion_expires— można ją ustawić jako czas UNIX (np.time()) lub w formacieYYYY-MM-DDTHH:MM:SS+00:00(np.2025-06-28T00:00:00+00:00).
Dodawanie produktów
Ta metoda pozwala dodać jeden lub kilka produktów jednym żądaniem (do 3000 w jednym żądaniu).
Format żądania jest identyczny jak przy aktualizacji: możesz przesłać tablicę products
lub pojedynczy produkt.
- Sprawdzanie ID: podczas dodawania nowego produktu pole
idpowinno być puste lub pominięte. Jeśliidjest podane i produkt z tym ID już istnieje — system zaktualizuje ten produkt zamiast tworzyć nowy. - Sprawdzanie SKU: przed dodaniem system sprawdzi, czy istnieje produkt z tym SKU. Jeśli tak — zostanie zaktualizowany, a nie dodany ponownie.
Możesz dodać nowe produkty i zaktualizować istniejące jednym żądaniem.
To podstawowy opis głównych metod pracy z Commerce API / WooCommerce API v3 dla zamówień, produktów i kategorii.
Poniżej znajdują się przykładowe skrypty, które pomogą prawidłowo używać metod API w praktyce.