Zasoby i operacje
Jak zbudowane jest API PowerHub: jednolity CRUD na zasobach, filtrowanie i stronicowanie, operacje domenowe oraz pełna lista zasobów. Jedna konwencja, którą raz opanowaną stosujesz do wszystkiego.
Jedna konwencja dla wszystkiego
Większość zasobów obsługiwana jest tym samym zestawem operacji. Jeżeli wiesz, jak pobrać listę produktów, wiesz też, jak pobrać listę magazynów, szablonów wiadomości albo serii numeracji. Różni się wyłącznie nazwa zasobu w ścieżce.
| Operacja | Metoda i ścieżka | Opis |
|---|---|---|
| Lista | GET /{zasób} | Zwraca stronę wyników wraz z liczbą wszystkich pasujących rekordów. |
| Pojedynczy rekord | GET /{zasób}/{id} | Pełny rekord. |
| Utworzenie | POST /{zasób} | Ciało żądania to obiekt rekordu. |
| Zmiana | PATCH /{zasób}/{id} | Wysyłasz tylko pola, które zmieniasz. |
| Usunięcie | DELETE /{zasób}/{id} | Domyślnie usunięcie miękkie: rekord znika z list, ale zostaje w bazie. |
| Przywrócenie | POST /{zasób}/{id}/restore | Cofa usunięcie miękkie. |
Poza jednolitym CRUD-em istnieją operacje domenowe, czyli te, które robią coś więcej niż zapis rekordu: wystawienie faktury, utworzenie przesyłki, zmiana statusu zamówienia z automatyzacjami. Ich komplet znajdziesz w kolekcji Postman.
Parametry list
Listy obsługują wspólny zestaw parametrów zapytania, jednakowy dla wszystkich zasobów:
| Pole | Opis |
|---|---|
| page | Numer strony, liczony od 1. |
| limit | Rozmiar strony. Powyżej ustalonego sufitu wartość jest przycinana. |
| sort | Nazwa pola sortowania. |
| order | Kierunek sortowania: asc albo desc. |
| q | Szukanie pełnotekstowe po najważniejszych polach zasobu. |
| {pole} | Filtr po dokładnej wartości pola, na przykład status=active. |
| {pole}_from / {pole}_to | Filtr zakresowy dla dat i liczb, na przykład created_at_from, total_minor_to. |
| include_deleted | Dołącza rekordy usunięte miękko. |
Przykładowe zapytanie o listę z filtrem, sortowaniem i stronicowaniem:
GET /orders?status=new&placed_at_from=2026-08-01&limit=50&sort=placed_at&order=desc Authorization: Bearer sk_live_...
Przy przechodzeniu dużych, jednocześnie napływających list nie polegaj wyłącznie na numerze strony. Filtruj po zakresie dat albo po identyfikatorze ostatniego rekordu, jeżeli przechodzisz cały zbiór.
Kwoty, waluty i daty
- Kwoty przekazujemy w najmniejszej jednostce waluty (grosze) w polach z końcówką _minor. 149,90 zł to 14990.
- Źródłem prawdy na pozycjach zamówienia jest kwota brutto, a netto liczy się ze stawki VAT.
- Waluta jest polem rekordu; nie przeliczamy kwot w locie.
- Daty i czasy są w formacie ISO 8601 ze strefą UTC.
Organizacja i uprawnienia
Klucz API działa w obrębie jednej organizacji i nie da się nim sięgnąć po dane innej. Klucz respektuje też uprawnienia: te same atomy moduł i akcja, które ograniczają użytkownika w panelu, ograniczają wywołania API. Brak uprawnienia to odpowiedź 403, a nie pusta lista.
Spis zasobów
Poniżej pełna lista zasobów obsługiwanych jednolitym CRUD-em, pogrupowana tematycznie. Nazwa w tabeli jest zarazem ścieżką w API.
| Obszar | Zasoby |
|---|---|
| Zamówienia i sprzedaż | orders, messages, message-threads, message-templates, email-accounts, reservations, sales-documents, sales-document-lines, sales-register, numbering-series, vat-rates, refunds, store-credits, coupons, coupon-redemptions, gift-cards, promotions, promotion-targets |
| Zwroty | returns, return-lines, return-forms, return-reasons, return-status-groups, return-item-statuses |
| Klienci | customers, customer-addresses, customer-status-groups, contacts, consents, segments, reviews |
| Katalog | products, product-variants, product-media, media-assets, catalogs, categories, manufacturers, attributes, attribute-values, tags, custom-fields, prices, price-groups, bundle-items, batches, serial-numbers |
| Magazyn | warehouses, locations, stock-levels, stock-movements, warehouse-documents, stocktakes, stocktake-schemes, transfers, suppliers |
| Wysyłka i realizacja | shipments, fulfillment-shipments, carriers, shipping-methods, pickup-points, packaging, packing-stations |
| Kanały i integracje | channels, channel-listings, connected-accounts, integration-providers, entity-mappings, sync-cursors, sync-runs, webhook-events, outbound-webhooks, marketplace-fees, settlements |
| Wystawianie ofert | listing-profiles, listing-description-templates |
| Automatyzacje | rule-actions, rule-conditions, automation-runs, action-groups, custom-events |
| Finanse | expenses, expense-lines, expense-categories, cost-rules, bank-accounts, bank-transactions |
| Asystent AI | agent-conversations, agent-memories, agent-permissions, agent-skills |
| Konto i platforma | memberships, roles, settings, notifications, audit-log, feature-flags, content-pages, print-templates, import-export-jobs |
Kompletny, zawsze aktualny opis pól każdego zasobu wraz z przykładami żądań znajdziesz w kolekcji Postman. Ten artykuł opisuje konwencje; kolekcja opisuje pola.