API

Przewodnik po REST API WAMA

Integruj swoje systemy z WAMA przez HTTPS JSON API pod adresem https://www.wama.cloud.

Ta strona opisuje uwierzytelnianie kluczami API, kontekst multi-tenant punktu sprzedaży, stronicowanie i błędy. Pola żądań i odpowiedzi znajdziesz w interaktywnej referencji OpenAPI (pełny ekran).

Otwórz interaktywną referencję API

Pierwsze kroki

Utwórz klucz API w aplikacji webowej WAMA (Ustawienia → Integracje). Preferuj tylko odczyt, jeśli integracja nie musi zapisywać danych.
Wywołuj /api/** z nagłówkiem Authorization: Bearer <api_key> (lub X-Api-Key).
Korzystaj z interaktywnej referencji API dla pól żądania/odpowiedzi.

Bazowy URL: https://www.wama.cloud

Porada

Klucze API to obsługiwany sposób dla skryptów, aplikacji partnerskich oraz AI / MCP. Nie używaj interaktywnego logowania (email/hasło OAuth) do integracji machine-to-machine.

Uwierzytelnianie

Utworzenie klucza API

Zaloguj się do WAMA w przeglądarce jako administrator konta (ROLE_USER / Administrator).
Otwórz Ustawienia → Integracje.
Wybierz Utwórz klucz API, ustaw nazwę, punkt sprzedaży, do którego klucz jest przypisany, zakres oraz opcjonalną datę wygaśnięcia.
Skopiuj klucz od razu — pełny sekret jest pokazywany tylko raz.

Format klucza:

wama_<publicId>_<secret>

Przechowuj go jak hasło (zmienna środowiskowa lub menedżer sekretów). Nigdy nie commituj kluczy do repozytoriów ani nie wklejaj ich do publicznych ticketów.

Zakresy (scopes)

Zakres	Wartość	Zachowanie
Tylko odczyt	`read`	Tylko `GET` / `HEAD` / `OPTIONS`; metody mutujące zwracają 403
Odczyt i zapis	`read_write`	Ten sam dostęp co użytkownik tworzący dla danego punktu sprzedaży (z wyjątkiem zarządzania kluczami)

Preferuj tylko odczyt do raportów, synchronizacji i asystentów AI, chyba że potrzebny jest zapis.

Wywołanie API

Wysyłaj klucz jako nagłówek HTTP w każdym żądaniu:

Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET

Opcjonalny alias (ten sam klucz):

X-Api-Key: wama_YOUR_PUBLIC_ID_YOUR_SECRET

Jeśli jednocześnie jest JWT Authorization: Bearer … oraz X-Api-Key, wygrywa JWT, a X-Api-Key jest ignorowany.

Przykład:

curl -X GET 'https://www.wama.cloud/api/products' \
  -H 'Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET' \
  -H 'Accept: application/json'

Równoważnie z X-Api-Key:

curl -X GET 'https://www.wama.cloud/api/products' \
  -H 'X-Api-Key: wama_YOUR_PUBLIC_ID_YOUR_SECRET' \
  -H 'Accept: application/json'

Unieważnienie lub rotacja

Unieważniaj klucze w Ustawienia → Integracje. Unieważnione lub wygasłe klucze zwracają 401. Aby obrócić klucz, utwórz nowy, zaktualizuj klienta i unieważnij stary.

Klucze API nie mogą tworzyć, listować ani unieważniać innych kluczy — zarządzaj kluczami tylko w aplikacji webowej (sesja użytkownika).

Punkt sprzedaży (multi-tenant)

Stany magazynowe, sprzedaż i powiązane dane należą do punktu sprzedaży (POS).

Każdy klucz API jest przypisany do jednego POS przy tworzeniu. Żądania z tym kluczem zawsze używają tego POS — nie przełączasz POS przez POST /api/point-of-sales/... przy użyciu klucza API.

Utwórz osobny klucz dla każdego magazynu/sklepu, jeśli potrzebujesz wielu kontekstów POS.

Stronicowanie

Endpointy list przyjmują parametry stronicowania Spring Data:

Parametr	Opis
`page`	Indeks strony od zera
`size`	Rozmiar strony
`sort`	Pole i kierunek, np. `timeModified,desc`

Udane odpowiedzi listowe zawierają:

Nagłówek	Opis
`X-Total-Count`	Łączna liczba pasujących elementów na wszystkich stronach

Błędy

Większość błędów zwraca JSON w postaci:

{
  "message": "error.validation",
  "description": "Optional human-readable text",
  "fieldErrors": [
    {
      "objectName": "productDTO",
      "field": "barcode",
      "message": "NotNull",
      "defaultMessage": "must not be null"
    }
  ]
}

Parametryzowane błędy domenowe mogą zwracać { "message": "...", "params": ["..."] }.

Typowe wyniki uwierzytelniania:

Status	Znaczenie
401	Brakujący, nieprawidłowy, unieważniony lub wygasły klucz API
403	Zakres tylko do odczytu, a metoda mutuje dane

Konwencje

Ciała JSON w żądaniu i odpowiedzi (Content-Type: application/json)
Daty w ISO-8601 z offsetem (np. 2026-03-15T10:30:00.000Z)
Kwoty jako liczby dziesiętne z obiektami waluty, gdzie dotyczy
Id nadaje serwer; pomiń je (lub wyślij null) przy tworzeniu

Przykład: lista produktów

curl 'https://www.wama.cloud/api/products?page=0&size=20&sort=timeModified,desc' \
  -H 'Authorization: Bearer wama_YOUR_PUBLIC_ID_YOUR_SECRET'

Referencja OpenAPI

Przeglądaj wszystkie publiczne endpointy:

Otwórz interaktywną referencję API