Interfejs REST API AMAGE - zamówienia, dostawy, reklamacje

Wstęp/Kontekst

Kontekst dla operacji na obiektach dotyczących zamówień (Order), dostaw (Delivery) i reklamacji (Complaint) w systemie AMAGE.

Dostępne konteksty API:

  • rest/amage/v1/orders - operacje na zamówieniach

  • rest/amage/v1/deliveries - operacje na dostawach

  • rest/amage/v1/complaints - operacje na reklamacjach

Struktury danych

Struktury i typy danych wykorzystywane w zapytaniach i odpowiedziach.

Wynik 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.

DeliveryOperationResultDto:

{
    "success": true,
    "errorCode": 0,
    "message": "",
    "deliveryUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "delivery": { /* obiekt DeliveryDto */ }
}

OrderOperationResultDto:

{
    "success": true,
    "errorCode": 0,
    "message": "",
    "orderUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "order": { /* obiekt OrderDto */ }
}

ComplaintOperationResultDto:

{
    "success": true,
    "errorCode": 0,
    "message": "",
    "complaintUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "complaint": { /* obiekt ComplaintDto */ }
}

Struktura DeliveryDto

{
    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "number": "DLV/2025/001",
    "originNumber": "WZ-123",
    "originOrder": "ZAM/2025/001",
    "contractorUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "tstamp": "2025-10-22T10:00:00Z",
    "receivedDate": "2025-10-22T11:00:00Z",
    "receivedByUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "loadingDate": "2025-10-22T09:00:00Z",
    "checkDate": "2025-10-22T12:00:00Z",
    "checkedByUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "description": "Dostawa materiałów budowlanych",
    "currencyCode": "PLN",
    "exchangeRate": 1.0,
    "deliveryType": "STANDARD",
    "deliveryState": "LOADING_ON_SITE",
    "deliveryExpectedDate": "2025-10-22T10:00:00Z",
    "deliveryInfo": "Informacje dodatkowe",
    "needsAttention": false,
    "needsAttentionNote": "",
    "orderDocumentUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "warehouseUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "placeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "costAllocated": false,
    "workOrderUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "locationUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "transportUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "extReference": "EXT-REF-001",
    "receiverSignature": null,
    "checkerSignature": null,
    "items": [
        {
            "id": 12345,
            "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "deliveryUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "itemUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "itemCount": 100.0,
            "checkedCount": 100.0,
            "unitPrice": 10.50,
            "description": "Cement Portland",
            "originWarehouseUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "originWarehousePlaceUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9"
        }
    ]
}

Struktura OrderDto

{
    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "number": "ZAM/2025/001",
    "tstamp": "2025-10-22T10:00:00Z",
    "supplierUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "extReference": "EXT-ORD-001",
    "orderDate": "2025-10-22T00:00:00Z",
    "daysToDelivery": 7,
    "deliveryDate": "2025-10-29T00:00:00Z",
    "currencyCode": "PLN",
    "orderType": "STANDARD",
    "orderState": "NEW",
    "termsAndConditions": null,
    "createdByUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "acceptedByUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "deliveryReceiverUser": "Jan Kowalski",
    "deliveryReceiverContactPhone": "+48 123 456 789",
    "deliveryReceiverContactInfo": "Odbiór w godzinach 8-16",
    "transportUnits": 1,
    "supplierConfirmed": true,
    "supplierConfirmedTstamp": "2025-10-22T11:00:00Z",
    "supplierMessage": "Zamówienie przyjęte do realizacji",
    "supplierDeliveryDate": "2025-10-29T10:00:00Z",
    "supplierReturnCheckDate": "2025-10-23T00:00:00Z",
    "supplierToken": "TOKEN123",
    "costAllocated": false,
    "workOrderUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "accountUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "locationUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "notes": "Uwagi do zamówienia",
    "items": [
        {
            "id": 12345,
            "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "orderUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "itemUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "itemCount": 100.0,
            "unitPrice": 10.50,
            "description": "Cement Portland CEM I 42,5",
            "originWarehouseUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "originWarehousePlaceUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "workOrderUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "accountUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "extReference": "EXT-ITEM-001",
            "parametersHash": "hash123"
        }
    ]
}

Struktura ComplaintDto

{
    "id": 12345,
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "number": "REK/2025/001",
    "description": "Uszkodzone opakowania",
    "tstamp": "2025-10-22T10:00:00Z",
    "createdByUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "complaintState": "NEW",
    "deliveryUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "items": [
        {
            "id": 12345,
            "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "complaintUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "itemUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
            "itemName": "Cement Portland",
            "itemCount": 100.0,
            "unitPrice": 10.50,
            "qualityCount": 5.0,
            "quantityCount": 0.0,
            "parametersHash": "hash123"
        }
    ]
}
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.

Dostawy - Operacje API

Operacje dotyczące dostaw realizowane poprzez kontekst rest/amage/v1/deliveries.

Pobieranie liczby dostaw

  • 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 dostaw w systemie.

123456

Pobranie listy dostaw

  • 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)

Zwracane dane to tablica obiektów JSON ze strukturą DeliveryDto.

Pobranie dostawy 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 dostawy

Zwracane dane to pojedynczy obiekt JSON ze strukturą DeliveryDto.

Dodanie nowej dostawy

  • Metoda: POST

  • Ścieżka: /add

  • Generuje: application/json

  • Wymaga: application/json

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

Parametry:

  • DeliveryDto - BodyContent - struktura JSON zgodna z DeliveryDto. Pole ID zostanie zastąpione podczas zapisu rekordu.

Zwracane dane to obiekt DeliveryOperationResultDto z polem deliveryUuid nowo utworzonej dostawy.

W przypadku zapisu danych 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 dostawy

  • 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 dostawy

  • DeliveryDto - BodyContent - struktura JSON zgodna z DeliveryDto. Pole ID/UUID zostają zignorowane podczas aktualizacji.

Zwracane dane to obiekt DeliveryOperationResultDto z polem deliveryUuid modyfikowanej dostawy.

Edycja dostawy jest możliwa tylko wtedy, gdy stan dostawy to LOADING_ON_SITE. W przeciwnym razie zwracany jest błąd z kodem BAD_REQUEST i komunikatem "Cannot edit delivery with state other than LOADING_ON_SITE".

Usunięcie dostawy

  • 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 dostawy

Zwracane dane to obiekt DeliveryOperationResultDto z informacją o wyniku operacji.

Usunięcie dostawy może się nie powieść ze względu na powiązanie z innymi rekordami w systemie. Usunięcie jest możliwe tylko wtedy, gdy stan dostawy to LOADING_ON_SITE. W przeciwnym razie zwracany jest błąd z kodem BAD_REQUEST.

Zamówienia - Operacje API

Operacje dotyczące zamówień realizowane poprzez kontekst rest/amage/v1/orders.

Pobieranie liczby zamówień

  • 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 zamówień w systemie.

123456

Pobranie listy zamówień

  • 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)

Zwracane dane to tablica obiektów JSON ze strukturą OrderDto.

Pobranie zamówienia 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 zamówienia

Zwracane dane to pojedynczy obiekt JSON ze strukturą OrderDto.

Dodanie nowego zamówienia

  • Metoda: POST

  • Ścieżka: /add

  • Generuje: application/json

  • Wymaga: application/json

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

Parametry:

  • OrderDto - BodyContent - struktura JSON zgodna z OrderDto. Pole ID zostanie zastąpione podczas zapisu rekordu.

Zwracane dane to obiekt OrderOperationResultDto z polem orderUuid nowo utworzonego zamówienia.

W przypadku zapisu danych 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.

Aktualizacja zamówienia

  • Metoda: POST

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

  • Generuje: application/json

  • Wymaga: application/json

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

Parametry:

  • uuid - identyfikator UUID zamówienia

  • OrderDto - BodyContent - struktura JSON zgodna z OrderDto. Pole ID/UUID zostają zignorowane podczas aktualizacji.

Zwracane dane to obiekt OrderOperationResultDto z polem orderUuid modyfikowanego zamówienia.

Usunięcie zamówienia

  • 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 zamówienia

Zwracane dane to obiekt OrderOperationResultDto z informacją o wyniku operacji.

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

Reklamacje - Operacje API

Operacje dotyczące reklamacji realizowane poprzez kontekst rest/amage/v1/complaints.

Pobieranie liczby reklamacji

  • 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 reklamacji w systemie.

123456

Pobranie listy reklamacji

  • 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)

Zwracane dane to tablica obiektów JSON ze strukturą ComplaintDto.

Pobranie reklamacji 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 reklamacji

Zwracane dane to pojedynczy obiekt JSON ze strukturą ComplaintDto.

Pobranie reklamacji dla dostawy

  • Metoda: GET

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

  • Generuje: application/json

  • Wymaga: application/json, text/plain

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

Parametry:

  • delivery-uuid - identyfikator UUID dostawy

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

  • size - RequestParam - rozmiar strony - liczba rekordów na stronie (domyślnie 50)

Zwracane dane to tablica obiektów JSON ze strukturą ComplaintDto dla wszystkich reklamacji powiązanych z daną dostawą.

Dodanie nowej reklamacji

  • Metoda: POST

  • Ścieżka: /add

  • Generuje: application/json

  • Wymaga: application/json

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

Parametry:

  • ComplaintDto - BodyContent - struktura JSON zgodna z ComplaintDto. Pole ID zostanie zastąpione podczas zapisu rekordu.

Zwracane dane to obiekt ComplaintOperationResultDto z polem complaintUuid nowo utworzonej reklamacji.

Reklamacja musi być powiązana z istniejącą dostawą poprzez pole deliveryUuid. System sprawdzi, czy dostawa istnieje przed utworzeniem reklamacji.

Aktualizacja reklamacji

  • Metoda: POST

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

  • Generuje: application/json

  • Wymaga: application/json

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

Parametry:

  • uuid - identyfikator UUID reklamacji

  • ComplaintDto - BodyContent - struktura JSON zgodna z ComplaintDto. Pole ID/UUID zostają zignorowane podczas aktualizacji.

Zwracane dane to obiekt ComplaintOperationResultDto z polem complaintUuid modyfikowanej reklamacji.

Usunięcie reklamacji

  • 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 reklamacji

Zwracane dane to obiekt ComplaintOperationResultDto z informacją o wyniku operacji.

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