Interfejs REST API AMAGE - dokumenty magazynowe

Wstęp/Kontekst

Kontekst dla operacji na obiektach dotyczących dokumentów magazynowych (WarehouseDocument/WarehouseDocumentItem) w systemie AMAGE, którą należy w zapytaniu rozszerzyć o odpowiednią metodę.

  • rest/amage/v1/warehouse-documents

Struktury danych

Struktury i typy danych wykorzystywane w zapytaniach i odpowiedziach.

Rezultat operacji

W polach ID/UUID znajduje się identyfikator nowo utworzonego lub edytowanego obiektu. W przypadku poprawnego wykonania operacji pole success jest ustawiane na true. W przypadku wystąpienia błędu pole success jest ustawiane na false, a w polu message znajduje się opis błędu. Kod błędu zawiera wtedy kod HTTP typu NOT_FOUND lub BAD_REQUEST. Zwracany w zapytaniu wtedy jest również kod BAD_REQUEST. W zależności od typu błędu podczas przetwarzania zapytania kod błędu może być różny niż zwracany główny kod zapytania. Kod zapytania będzie BAD_REQUEST, a kod wewnętrzny będzie ustawiony na NOT_FOUND w przypadku takim, gdy zapytanie będzie ustawiało właściwość obiektu na inny obiekt w systemie. Parametr JSON będzie poprawny (UUID rekordu), ale takiego rekordu nie będzie w systemie. W związku z tym w polu errorCode pojawi się kod NOT_FOUND. W polu opisowym message komunikat informujący jakiego rekordu nie znaleziono, a główny kod błędu zapytania będzie wynosił BAD_REQUEST.

{
    "id": 1,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success": true,
    "errorCode": 0,
    "message": ""
}

Typ dokumentu magazynowego

Element wyliczeniowy, który określa typ dokumentu magazynowego (WarehouseDocumentType):

  • RECEPTION - przyjęcie

  • TRANSFER - przesunięcie

  • RELEASE - wydanie

  • INVENTORY - inwentaryzacja

Typ dokumentu przyjęcia

Element wyliczeniowy, który określa typ dokumentu przyjęcia (ReceptionDocumentType):

  • PURCHASE - zakup

  • RETURN - zwrot

  • OTHER - inny

Typ dokumentu przesunięcia

Element wyliczeniowy, który określa typ dokumentu przesunięcia (TransferDocumentType):

  • INTERNAL - przesunięcie wewnętrzne

  • EXTERNAL - przesunięcie zewnętrzne

Typ dokumentu wydania

Element wyliczeniowy, który określa typ dokumentu wydania (ReleaseDocumentType):

  • SALE - sprzedaż

  • CONSUMPTION - zużycie

  • OTHER - inny

Stan elementu dokumentu

Element wyliczeniowy, który określa stan elementu dokumentu (WarehouseDocumentItemState):

  • PENDING - oczekujący

  • SETTLED - rozliczony

Dokument magazynowy

Struktura dokumentu magazynowego (WarehouseDocumentDto):

{
    "id": 1,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "number": "WD/001/2025",
    "tstamp": "2025-10-22T10:30:00.000Z",
    "signedByUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "description": "Opis dokumentu",
    "type": "RECEPTION",
    "receptionType": "PURCHASE",
    "transferType": null,
    "releaseType": null,
    "destinationUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "takenByUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "reservation": false,
    "reservedByUuid": null,
    "reservedExpectedDate": null,
    "supplierUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "waybillNumber": "WB/123/2025",
    "connectedDocumentUuid": null,
    "warehouseUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "placeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "otherWarehouseUuid": null,
    "otherPlaceUuid": null,
    "costAllocated": false,
    "accountUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "workOrderUuid": null,
    "deliveryUuid": null,
    "extReference": "EXT-REF-123",
    "items": [
        {
            "id": 1,
            "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "documentUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "itemState": "PENDING",
            "typeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "itemUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "itemCount": 10.0,
            "unitPrice": 99.99,
            "workOrderUuid": null,
            "accountUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "extReference": "ITEM-REF-001"
        }
    ]
}

Element dokumentu magazynowego

Struktura elementu dokumentu magazynowego (WarehouseDocumentItemDto):

{
    "id": 1,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "documentUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "itemState": "PENDING",
    "typeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "itemUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "itemCount": 10.0,
    "unitPrice": 99.99,
    "workOrderUuid": null,
    "accountUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "extReference": "ITEM-REF-001"
}

Dokumenty magazynowe - Operacje API

Operacje dotyczące dokumentów magazynowych i ich elementów.

Pobieranie liczby dokumentów magazynowych

  • Metoda: GET

  • Ścieżka: /count

  • Generuje: application/json

  • Wymaga: application/json, text/plain

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Zwraca liczbę wszystkich dokumentów magazynowych w systemie.

123456

Pobranie listy dokumentów magazynowych

  • Metoda: GET

  • Ścieżka: /list

  • Generuje: application/json

  • Wymaga: application/json, text/plain

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • page - RequestParam - strona - liczona od 1 (domyślnie 1)

  • size - RequestParam - rozmiar strony - liczba rekordów na stronie (domyślnie 50), sugerujemy ograniczenie do 1000 elementów

Zwracane dane to lista obiektów JSON ze strukturą dokumentu magazynowego. Lista zawiera pełne informacje o dokumentach wraz z listą elementów.

W przypadku pobierania danych z systemu pole ID, UUID będą w zwracanej strukturze wypełnione danymi pochodzącymi z systemu. Pole ID to identyfikator lokalnej bazy danych. Pole UUID to identyfikator globalny w systemie AMAGE, który może służyć jako identyfikator jednoznacznie identyfikujący obiekt w systemie i w integracjach pomiędzy systemami.

Pobranie dokumentu magazynowego po UUID

  • Metoda: GET

  • Ścieżka: /get/by-uuid/{uuid}

  • Generuje: application/json

  • Wymaga: application/json, text/plain

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • uuid - identyfikator UUID dokumentu magazynowego

Zwracane dane to pojedynczy obiekt JSON ze strukturą dokumentu magazynowego tożsamą z metodą /list, wraz z pełną listą elementów dokumentu.

Dodanie nowego dokumentu magazynowego

  • Metoda: POST

  • Ścieżka: /add

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • WarehouseDocumentDto - BodyContent - struktura JSON tożsama z pojedynczym elementem z metody /list. Pole ID zostanie zastąpione podczas zapisu rekordu

Zwracane dane to obiekt odpowiedzi z polem ID/UUID nowo utworzonego dokumentu magazynowego.

W przypadku zapisu danych z systemu pole ID nie może być wypełnione. Zostaje ono uzupełnione podczas zapisu rekordu do bazy danych i zwrócone w strukturze odpowiedzi. Jeśli pole UUID zostanie podane, to taka wartość zostanie przypisana do rekordu. System nie sprawdza unikalności UUID w ramach struktur lub kontekstu całego systemu. Jeśli UUID nie zostanie podane, to system wygeneruje własne unikalne UUID.

Edycja dokumentu magazynowego

  • Metoda: POST

  • Ścieżka: /edit/{uuid}

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • uuid - identyfikator UUID dokumentu magazynowego

  • WarehouseDocumentDto - BodyContent - struktura JSON tożsama z pojedynczym elementem z metody /list

Zwracane dane to obiekt odpowiedzi z polem ID/UUID modyfikowanego dokumentu magazynowego.

Nie można edytować dokumentu magazynowego, jeśli zawiera on elementy w stanie SETTLED (rozliczony). W takim przypadku zwrócony zostanie błąd z komunikatem "Cannot edit Warehouse Document with settled items".

Usunięcie dokumentu magazynowego

  • Metoda: DELETE

  • Ścieżka: /delete/{uuid}

  • Generuje: application/json

  • Wymaga: application/json, text/plain

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • uuid - identyfikator UUID dokumentu magazynowego

Zwracane dane to obiekt odpowiedzi z polem ID/UUID usuwanego dokumentu magazynowego.

Usunięcie dokumentu magazynowego może się nie powieść ze względu na powiązanie dokumentu z innymi rekordami w systemie. W takim przypadku zwrócony zostanie błąd z informacją dotyczącą problemu.

Dodanie dokumentu magazynowego jako szkic (draft)

  • Metoda: POST

  • Ścieżka: /add-draft

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • WarehouseDocumentDto - BodyContent - struktura JSON dokumentu magazynowego (jak w metodzie /add)

Zwracane dane to obiekt odpowiedzi z polem ID/UUID nowo utworzonego szkicu dokumentu magazynowego.

Dokument utworzony jako szkic nie jest dokumentem finalnym i wymaga zatwierdzenia (settle), aby był traktowany jako rozliczony dokument magazynowy.

Przykład odpowiedzi:

{
    "id": 1,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success": true,
    "errorCode": 0,
    "message": ""
}

Zatwierdzenie (settle) dokumentu magazynowego

  • Metoda: POST

  • Ścieżka: /settle/{uuid}

  • Generuje: application/json

  • Wymaga: application/json, text/plain

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • uuid - identyfikator UUID dokumentu magazynowego do zatwierdzenia

Zwracane dane to obiekt odpowiedzi z polem ID/UUID zatwierdzonego dokumentu magazynowego.

Nie można zatwierdzić dokumentu, który nie istnieje lub ma nieprawidłowy format UUID. W takim przypadku zwracany jest błąd z odpowiednim komunikatem i kodem błędu BAD_REQUEST lub NOT_FOUND.

Przykład odpowiedzi (sukces):

{
    "id": 1,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "success": true,
    "errorCode": 0,
    "message": ""
}

Przykład odpowiedzi (błąd - zły UUID):

{
    "id": null,
    "uuid": null,
    "success": false,
    "errorCode": 400,
    "message": "Wrong Warehouse Document UUID format or non-existent"
}

Przykład odpowiedzi (błąd - nie znaleziono dokumentu):

{
    "id": null,
    "uuid": null,
    "success": false,
    "errorCode": 404,
    "message": "Warehouse Document not found"
}

Elementy dokumentów magazynowych - Operacje API

Operacje dotyczące pojedynczych elementów (pozycji) dokumentów magazynowych.

Dodanie elementu do dokumentu magazynowego

  • Metoda: POST

  • Ścieżka: /add-item/{uuid}

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • uuid - identyfikator UUID dokumentu magazynowego

  • WarehouseDocumentItemDto - BodyContent - struktura JSON elementu dokumentu

Zwracane dane to obiekt odpowiedzi z polem ID/UUID nowo utworzonego elementu dokumentu magazynowego.

Nie można dodawać elementów do dokumentu magazynowego, jeśli dokument zawiera już elementy w stanie SETTLED (rozliczony). W takim przypadku zwrócony zostanie błąd z komunikatem "Cannot add items to Warehouse Document with settled items".

Edycja elementu dokumentu magazynowego

  • Metoda: POST

  • Ścieżka: /edit-item/{uuid}

  • Generuje: application/json

  • Wymaga: application/json

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • uuid - identyfikator UUID elementu dokumentu magazynowego

  • WarehouseDocumentItemDto - BodyContent - struktura JSON elementu dokumentu

Zwracane dane to obiekt odpowiedzi z polem ID/UUID modyfikowanego elementu dokumentu magazynowego.

Nie można edytować elementów dokumentu magazynowego, jeśli dokument zawiera elementy w stanie SETTLED (rozliczony). W takim przypadku zwrócony zostanie błąd z komunikatem "Cannot edit items of Warehouse Document with settled items".

Usunięcie elementu z dokumentu magazynowego

  • Metoda: DELETE

  • Ścieżka: /delete-item/{uuid}

  • Generuje: application/json

  • Wymaga: application/json, text/plain

  • Autoryzacja: podpis API (device-uuid, api-key, api-sign)

Parametry:

  • uuid - identyfikator UUID elementu dokumentu magazynowego

Zwracane dane to obiekt odpowiedzi z polem ID/UUID usuwanego elementu dokumentu magazynowego.

Nie można usuwać elementów z dokumentu magazynowego, jeśli dokument zawiera elementy w stanie SETTLED (rozliczony). W takim przypadku zwrócony zostanie błąd z komunikatem "Cannot delete items of Warehouse Document with settled items".

Zasady bezpieczeństwa i ograniczenia

Ochrona rozliczonych dokumentów

System chroni integralność danych magazynowych poprzez blokowanie modyfikacji dokumentów i ich elementów, które zostały już rozliczone. Jeśli jakikolwiek element dokumentu magazynowego ma stan SETTLED:

  • Nie można edytować dokumentu

  • Nie można dodawać nowych elementów do dokumentu

  • Nie można edytować istniejących elementów dokumentu

  • Nie można usuwać elementów z dokumentu

Walidacja UUID

Wszystkie operacje wymagające identyfikatora UUID przeprowadzają walidację formatu. W przypadku nieprawidłowego formatu UUID zwracany jest kod błędu BAD_REQUEST z odpowiednim komunikatem.

Powiązania z innymi obiektami

Dokumenty magazynowe mogą być powiązane z wieloma obiektami w systemie poprzez pola UUID:

  • signedByUuid - użytkownik podpisujący dokument

  • destinationUuid - miejsce docelowe

  • takenByUuid - osoba odbierająca

  • supplierUuid - dostawca

  • connectedDocumentUuid - powiązany dokument

  • warehouseUuid - magazyn

  • placeUuid - miejsce w magazynie

  • otherWarehouseUuid - drugi magazyn (dla przesunięć)

  • otherPlaceUuid - drugie miejsce (dla przesunięć)

  • accountUuid - konto księgowe

  • workOrderUuid - zlecenie pracy

  • deliveryUuid - dostawa

Wszystkie te powiązania powinny być weryfikowane podczas zapisu - w przypadku podania nieistniejącego UUID system zwróci błąd NOT_FOUND w polu errorCode z kodem zapytania BAD_REQUEST.