Project-Pro/shopPRO
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ebab220f7ed195198bc3a78f572e199d3ad127e5
shopPRO/docs/API.md

8.0 KiB
Raw Blame History

shopPRO REST API

REST API do integracji z ordersPRO i innymi systemami zewnetrznymi.

Autentykacja

Kazde zapytanie wymaga headera X-Api-Key z kluczem API.

X-Api-Key: {klucz_api}

Klucz przechowywany jest w pp_settings jako parametr api_key. API jest stateless (bez sesji).

Format odpowiedzi

Sukces (HTTP 200)

{
  "status": "ok",
  "data": { ... }
}

Blad

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

Kody bledow:

Kod HTTP Opis
UNAUTHORIZED 401 Brak lub nieprawidlowy klucz API
BAD_REQUEST 400 Brakujace lub niepoprawne parametry
NOT_FOUND 404 Nie znaleziono zasobu/endpointu/akcji
METHOD_NOT_ALLOWED 405 Nieprawidlowa metoda HTTP
INTERNAL_ERROR 500 Blad wewnetrzny serwera

Endpointy

Zamowienia

Lista zamowien

GET api.php?endpoint=orders&action=list

Parametry filtrowania (opcjonalne):

Parametr Typ Opis
status int Filtruj po statusie zamowienia
paid int (0/1) Filtruj po statusie platnosci
date_from date (YYYY-MM-DD) Zamowienia od daty
date_to date (YYYY-MM-DD) Zamowienia do daty
updated_since datetime (YYYY-MM-DD HH:MM:SS) Zamowienia zmodyfikowane od podanej daty (klucz do pollingu)
number string Szukaj po numerze zamowienia
client string Szukaj po imieniu, nazwisku lub emailu klienta
page int Numer strony (domyslnie 1)
per_page int Wynikow na strone (domyslnie 50, max 100)

Odpowiedz:

{
  "status": "ok",
  "data": {
    "items": [
      {
        "id": 42,
        "number": "2026/02/001",
        "date_order": "2026-02-19 10:30:00",
        "updated_at": "2026-02-19 12:00:00",
        "status": 4,
        "paid": 1,
        "client_name": "Jan",
        "client_surname": "Kowalski",
        "client_email": "jan@example.com",
        "client_phone": "111222333",
        "client_street": "Testowa 1",
        "client_postal_code": "00-000",
        "client_city": "Warszawa",
        "firm_name": null,
        "firm_nip": null,
        "transport": "Kurier DPD",
        "transport_cost": 15.00,
        "payment_method": "Przelew bankowy",
        "summary": 150.00
      }
    ],
    "total": 1,
    "page": 1,
    "per_page": 50
  }
}

Szczegoly zamowienia

GET api.php?endpoint=orders&action=get&id={order_id}

Zwraca pelne dane zamowienia z produktami i historia statusow.

Zmiana statusu zamowienia

PUT api.php?endpoint=orders&action=change_status&id={order_id}
Content-Type: application/json

{
  "status_id": 5,
  "send_email": true
}

Odpowiedz:

{
  "status": "ok",
  "data": {
    "order_id": 42,
    "status_id": 5,
    "changed": true
  }
}

Oznacz jako oplacone

PUT api.php?endpoint=orders&action=set_paid&id={order_id}

Opcjonalnie w body: {"send_email": true}

Oznacz jako nieoplacone

PUT api.php?endpoint=orders&action=set_unpaid&id={order_id}

Produkty

Lista produktow

GET api.php?endpoint=products&action=list

Parametry filtrowania (opcjonalne):

Parametr Typ Opis
search string Szukaj po nazwie, EAN lub SKU
status int (0/1) Filtruj po statusie (1 = aktywny, 0 = nieaktywny)
promoted int (0/1) Filtruj po promocji
sort string Sortuj po: id, name, price_brutto, status, promoted, quantity (domyslnie id)
sort_dir string Kierunek: ASC lub DESC (domyslnie DESC)
page int Numer strony (domyslnie 1)
per_page int Wynikow na strone (domyslnie 50, max 100)

Odpowiedz:

{
  "status": "ok",
  "data": {
    "items": [
      {
        "id": 1,
        "sku": "PROD-001",
        "ean": "5901234123457",
        "name": "Produkt testowy",
        "price_brutto": 99.99,
        "price_brutto_promo": null,
        "price_netto": 81.29,
        "price_netto_promo": null,
        "quantity": 10,
        "status": 1,
        "promoted": 0,
        "vat": 23,
        "weight": 0.5,
        "main_image": "product1.jpg",
        "date_add": "2026-01-15 10:00:00",
        "date_modify": "2026-02-19 12:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "per_page": 50
  }
}

Szczegoly produktu

GET api.php?endpoint=products&action=get&id={product_id}

Zwraca pelne dane produktu z jezykami, zdjeciami, kategoriami i atrybutami.

Odpowiedz:

{
  "status": "ok",
  "data": {
    "id": 1,
    "sku": "PROD-001",
    "ean": "5901234123457",
    "price_brutto": 99.99,
    "price_brutto_promo": null,
    "price_netto": 81.29,
    "price_netto_promo": null,
    "quantity": 10,
    "status": 1,
    "promoted": 0,
    "vat": 23,
    "weight": 0.5,
    "stock_0_buy": 0,
    "custom_label_0": null,
    "set_id": null,
    "product_unit_id": 1,
    "producer_id": 3,
    "date_add": "2026-01-15 10:00:00",
    "date_modify": "2026-02-19 12:00:00",
    "languages": {
      "pl": {
        "name": "Produkt testowy",
        "short_description": "Krotki opis",
        "description": "<p>Pelny opis produktu</p>",
        "meta_description": null,
        "meta_keywords": null,
        "meta_title": null,
        "seo_link": "produkt-testowy",
        "copy_from": null,
        "warehouse_message_zero": null,
        "warehouse_message_nonzero": null,
        "tab_name_1": null,
        "tab_description_1": null,
        "tab_name_2": null,
        "tab_description_2": null,
        "canonical": null
      }
    },
    "images": [
      {"id": 1, "src": "product1.jpg", "alt": "Zdjecie produktu"}
    ],
    "categories": [1, 5],
    "attributes": [
      {"attribute_id": 1, "value_id": 3}
    ]
  }
}

Tworzenie produktu

POST api.php?endpoint=products&action=create
Content-Type: application/json

{
  "price_brutto": 99.99,
  "vat": 23,
  "quantity": 10,
  "status": 1,
  "sku": "PROD-001",
  "ean": "5901234123457",
  "weight": 0.5,
  "languages": {
    "pl": {
      "name": "Nowy produkt",
      "description": "<p>Opis produktu</p>"
    }
  },
  "categories": [1, 5],
  "products_related": [10, 20]
}

Wymagane: languages (min. 1 jezyk z name) oraz price_brutto.

Odpowiedz (HTTP 201):

{
  "status": "ok",
  "data": {
    "id": 42
  }
}

Aktualizacja produktu

PUT api.php?endpoint=products&action=update&id={product_id}
Content-Type: application/json

{
  "price_brutto": 129.99,
  "status": 1,
  "languages": {
    "pl": {
      "name": "Zaktualizowana nazwa"
    }
  }
}

Partial update — wystarczy przeslac tylko zmienione pola. Pola nieprzeslane zachowuja aktualna wartosc.

Odpowiedz: pelne dane produktu (jak w get).

Slowniki

Lista statusow zamowien

GET api.php?endpoint=dictionaries&action=statuses

Odpowiedz:

{
  "status": "ok",
  "data": [
    {"id": 0, "name": "Nowe"},
    {"id": 1, "name": "Oplacone"},
    {"id": 4, "name": "W realizacji"},
    {"id": 6, "name": "Wyslane"}
  ]
}

Lista metod transportu

GET api.php?endpoint=dictionaries&action=transports

Lista metod platnosci

GET api.php?endpoint=dictionaries&action=payment_methods

Polling

Aby pobierac tylko nowe/zmienione zamowienia, uzyj parametru updated_since:

GET api.php?endpoint=orders&action=list&updated_since=2026-02-19 12:00:00

Kolumna updated_at w pp_shop_orders jest aktualizowana automatycznie przy kazdej modyfikacji zamowienia (zmiana statusu, platnosci, edycja danych, tworzenie zamowienia).

Konfiguracja

Klucz API ustawia sie w panelu admina w ustawieniach sklepu lub bezposrednio w bazie:

INSERT INTO pp_settings (param, value) VALUES ('api_key', 'twoj-klucz-api');
-- lub
UPDATE pp_settings SET value = 'twoj-klucz-api' WHERE param = 'api_key';

Architektura

  • Entry point: api.php
  • Router: \api\ApiRouter (autoload/api/ApiRouter.php)
  • Kontrolery: autoload/api/Controllers/
    • OrdersApiController — zamowienia (5 akcji)
    • ProductsApiController — produkty (4 akcje: list, get, create, update)
    • DictionariesApiController — slowniki (3 akcje)
Reference in New Issue View Git Blame Copy Permalink