platformaerp.com

API platformaERP - Indeksy

Dokuemntacja API do sprawdzania i zakładania indeksów (kartotek towarowych) w platformaERP.

Podsumowanie

Operacja	Metoda	Endpoint	Wymagana rola
Sprawdzenie, czy indeks istnieje	`GET`	`/api/srs/714/item.lower.json?search={tekst}&pscope=item`	`erp_indeksy`
Utworzenie / aktualizacja indeksu	`POST`	`/api/srs/901/api.json`	`erp_magazyn` + uprawnienie `item_insertupdate`
Lista jednostek miary	`GET`	`/api/srs/821/run.lower.json?dictionary=itemUnit`	-
Lista grup asortymentowych	`GET`	`/api/srs/957/list.lower.json?pscope=list`	-

slowo lower jest opcjona;lnie normalizuje nazwy atrybutów do malych liter

Uwierzytelnianie

W systemie należy utworzyć użytkownika w kontekście ktorego ma pracoać api np api@klient.com nadać odpowiednie uprawnienia i wygenerować TOKEN API.

Token przekaż w nagłówku Authorization (zalecane):

Przykład weryfikacji uwierzytelninieniaa

Bash
HOST="https://app.platformaerp.com"   # adres Twojej instancji
TOKEN="twoj-token-api"

curl -s "$HOST/api/core/system/ping" -H "Authorization: Token $TOKEN"

Przykładowa odpowiedz

JSON
{
  "success":true,
  "message":"OK",
  "executed_at":"2026-10-28T20:48:23.9143451Z",
  "data":{
      "items":{
        "authenticated":false,
        "username":null,
        "version":"2522"},
      }
}

Scenariusz integracji

Jednorazowo pobierz słowniki: jednostki miary i grupy asortymentowe .
Sprawdź, czy indeks istnieje - wyszukaj po kodzie indeksu (srs/714).
Jeśli istnieje - zapisz u siebie zwrócony itemid.
Jeśli nie istnieje - wygeneruj nowy GUID itemID, utwórz indeks (srs/901) i zapisz itemID u siebie.

Sprawdzenie, czy indeks istnieje

Request

Bash
curl -s -G "$HOST/api/srs/714/item.lower.json" \
  -H "Authorization: Token $TOKEN" \
  --data-urlencode "search=3957B" \
  --data-urlencode "pscope=item"

Parametry

search - szukany tekst: kod indeksu, nazwa magazynowa, nazwa handlowa, grupa asortymentowa, materiał, uwagi
pscope=item - wymagany; ogranicza wyszukiwanie do indeksów (bez niego przeszukiwane są wszystkie moduły do którego użytkownik ma dostęp)

Response

JSON
{
  "success": true,
  "message": "",
  "data": {
    "item": [
      {
        "itemid": "bb9cb814-da35-4622-b19c-dc13b7adf100",
        "itemcode": "3957B",
        "name": "Antenna 1 x 4 with Flat Top",
        "itemstockquantity": null,
        "itemorderquantity": 3.0,
        "itemreservationquantity": 0.0
      }
    ]
  }
}

itemid - identyfikator indeksu (GUID)
itemcode - kod indeksu
name - nazwa magazynowa
itemstockquantity, itemorderquantity, itemreservationquantity - stan, ilość w zamówieniach, rezerwacje

Indeks nie istnieje - pusta lista: "data": { "item": [] }.

Wyszukiwanie jest pełnotekstowe, nie dokładne

Zwraca indeksy zawierające wszystkie podane słowa, w dowolnej kolejności, bez względu na wielkość liter i polskie znaki.
Dopasowanie częściowe: search=3957 zwraca 3957A i 3957B.
Maksymalnie 100 wierszy, tylko indeksy aktywne.

Utworzenie indeksu

Przykład (Uwaga potwierdź kody na swojej instancji):

JM Sztuka 59fda1d1-1f33-41fb-ae24-e0c1ff42ec0d
GRUPA DETALE / DETALOWE / INDEKSY PRODUKCYJNE : f6b8eeb8-5e8e-4cdd-a796-905988696d62

Request

Bash
HOST="https://noma-test.platformaerp.com"   # adres Twojej instancji
TOKEN="TOKEN"

curl -s -X POST "$HOST/api/srs/901/api.json" \
  -H "Authorization: Token $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "itemID": "4a17e1a0-40c1-406b-a8b3-3f2fbc8da08f",
    "itemName": "Rura M8x40 ocynk",
    "itemUnitID": "59fda1d1-1f33-41fb-ae24-e0c1ff42ec0d",
    "itemclass": [
      {
        "itemGroupID": "f6b8eeb8-5e8e-4cdd-a796-905988696d62",
        "mainGroup": "true",
        "discountGroup": "true"
      }
    ]
  }'

Note

Parametry wysyłaj w treści JSON (POST). Pole itemclass jest odczytywane tylko z treści JSON.

Pola wymagane

Pole	Typ	Opis
`itemID`	GUID	Identyfikator indeksu, generowany przez system zewnętrzny. Nowy GUID = nowy indeks, istniejący GUID = aktualizacja
`itemName`	tekst (250)	Nazwa magazynowa
`itemUnitID`	GUID	Jednostka miary, zob. sekcję Słowniki poniżej
`itemclass`	tablica	Grupy asortymentowe. Dokładnie jedna z `mainGroup: true` (grupa główna) i dokładnie jedna z `discountGroup: true` (grupa cennikowa); może to być ta sama grupa

Pola opcjonalne

Pole	Typ	Domyślnie	Opis
`itemCode`	tekst (20)	generowany	Kod indeksu, zapisywany wielkimi literami. Puste = kod nadany automatycznie wg prefiksu grupy głównej
`itemNameShort`	tekst (100)	`itemName`	Nazwa krótka
`itemNameCommercial`	tekst (250)	-	Nazwa handlowa
`itemNameCommercialForeign`	tekst (250)	-	Nazwa handlowa obcojęzyczna
`itemMemo`	tekst	-	Uwagi
`itemWeight`	liczba	-	Waga
`dimensionX`, `dimensionY`, `dimensionZ`	liczba	-	Wymiary
`itemMaterial`	tekst (100)	-	Materiał
`itemTaxRate`	liczba całkowita	`23`	Stawka VAT (%)
`isStorable`	`0`/`1`	`1`	Indeks magazynowy
`pkwiu`	tekst (50)	-	PKWiU
`cn`	tekst (100)	-	Kod CN
`gtu`	tekst (10)	-	Kod GTU
`countryoforigin`	tekst (3)	-	Kraj pochodzenia, np. `PL`

Response

JSON
{
  "success": true,
  "message": "",
  "data": { "api": [] }
}

Sprawdzaj pole success. Identyfikatorem utworzonego indeksu jest wysłany itemID.

Słowniki

GUID-y jednostek i grup różnią się między instancjami - pobierz je z API.

Jednostki miary

Bash
curl -s "$HOST/api/srs/821/run.json?dictionary=itemUnit" -H "Authorization: Token $TOKEN"

JSON
{
  "success": true,
  "data": {
    "list": [
      { "dictionaryKey": "59fda1d1-1f33-41fb-ae24-e0c1ff42ec0d", "dictionaryValue": "szt.", "decimalValue": null },
      { "dictionaryKey": "96c7b8a8-3cab-4d9c-b915-56c102e1d9e2", "dictionaryValue": "godz", "decimalValue": null }
    ]
  }
}

Grupy asortymentowe (value = grupa / podkategoria / kategoria)

Bash
curl -s "$HOST/api/srs/957/list.json?pscope=list" -H "Authorization: Token $TOKEN"

JSON
{
  "success": true,
  "data": {
    "list": [
      { "key": "d6816e5a-1034-4149-8b95-4707117e5781", "value": "Grupa / Podkategoria / Kategoria" }
    ]
  }
}

Obsługa błędów

HTTP 401 - brak lub nieprawidłowy token.
Błąd biznesowy - HTTP 200, "success": false i opis w message.

JSON
{ "success": false, "message": "#error.item.notDefinedAnyItemGroup" }

`message`	Przyczyna
`#NoRights [item_insertupdate]`	Użytkownik tokenu nie ma uprawnienia do zakładania indeksów