AMAGE REST API - Work Orders

Introduction/Context

Context for operations on work order module objects in the AMAGE system, which should be extended with the appropriate method in the query.

rest/amage/v1/work-orders

Data structures

Structures and data types used in queries and responses.

Result:

The ID/UUID fields contain the identifier of the newly created or edited object. If the operation is performed correctly, the success field is set to true. If an error occurs, the success field is set to false, and the message field contains a description of the error. The error code then contains an HTTP code of the NOT_FOUND or BAD_REQUEST type. The BAD_REQUEST code is also returned in the query. Depending on the type of error during query processing, the error code may be different than the main query code returned. The query code will be BAD_REQUEST, and the internal code will be set to NOT_FOUND in the case when the query sets an object property to another object in the system. The JSON parameter will be correct (record UUID), but there will be no such record in the system. Therefore, the NOT_FOUND code will appear in the errorCode field. In the message description field, a message informing what record was not found, and the main query error code will be BAD_REQUEST.

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

Standardowy rezultat operacji (WorkOrdersOperationResultDto):

Każda operacja modyfikująca zwraca obiekt:

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

Znaczenie pól:

id – identyfikator rekordu w bazie (może być null przy błędzie).
uuid – UUID rekordu (może być null przy błędzie).
success – flaga powodzenia operacji (true/false).
errorCode – kod błędu (np. 400 przy błędnym UUID, 404 gdy encja nie istnieje).
message – krótki opis błędu lub pusty przy sukcesie.

W przypadku błędów HTTP 400 (np. niepoprawny format UUID) lub 404 (np. brak encji) ciało nadal zwiera powyższą strukturę z success=false i odpowiednim errorCode/message.

Przykładowe odpowiedzi błędów (400/404)

Niepoprawny format UUID:

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

Brak encji (np. zlecenie nie istnieje):

{
    "id": null,
    "uuid": null,
    "success": false,
    "errorCode": 404,
    "message": "Work Order not found"
}

Nagłówki autoryzacji (podpis API)

Każde wywołanie wymaga podpisu API w nagłówkach:

device-uuid – identyfikator urządzenia/klienta
api-key – klucz aplikacji
api-sign – podpis żądania zgodnie z polityką integracji
Content-Type – application/json lub text/plain (zgodnie z sekcją endpointu)

Brak lub niepoprawny podpis może skutkować odpowiedzią 400 Bad Request.

Work Order Status Type:

NEW,
SCHEDULED,
IN_PROGRESS,
ON_HOLD,
FINISHED,
VOID

Work order priority:

 LOW,
NORMAL,
HIGH

Work order

Metoda	Ścieżka	Body	Zwraca	Typowe kody
GET	/rest/amage/v1/work-orders/count	brak	liczba (Long)	200, 400
GET	/rest/amage/v1/work-orders/list?page=&size=	brak	lista WorkOrderDto	200, 404
GET	/rest/amage/v1/work-orders/get/by-uuid/{uuid}	brak	WorkOrderDto	200, 400, 404
POST	/rest/amage/v1/work-orders/add	WorkOrderDto	WorkOrdersOperationResultDto	200, 400
POST	/rest/amage/v1/work-orders/edit/{uuid}	WorkOrderDto	WorkOrdersOperationResultDto	200, 400, 404
POST	/rest/amage/v1/work-orders/add-history/{uuid}	WorkOrderHistoryDto	WorkOrdersOperationResultDto	200, 400, 404
POST	/rest/amage/v1/work-orders/edit-history/{uuid}	WorkOrderHistoryDto	WorkOrdersOperationResultDto	200, 400, 404
DELETE	/rest/amage/v1/work-orders/delete-history/{uuid}	brak	WorkOrdersOperationResultDto	200, 400, 404
POST	/rest/amage/v1/work-orders/add-workorder-elementtype-plan/{uuid}	WorkOrderElementTypePlanItemDto	WorkOrdersOperationResultDto	200, 400, 404
POST	/rest/amage/v1/work-orders/edit-workorder-elementtype-plan/{uuid}	WorkOrderElementTypePlanItemDto	WorkOrdersOperationResultDto	200, 400, 404
DELETE	/rest/amage/v1/work-orders/delete-workorder-elementtype-plan/{uuid}	brak	WorkOrdersOperationResultDto	200, 400, 404
POST	/rest/amage/v1/work-orders/asset-plan/{work-order-uuid}/join-asset-to-plan-by-uuid/{uuid}	brak	WorkOrdersOperationResultDto	200, 400, 404
POST	/rest/amage/v1/work-orders/asset-plan/{work-order-uuid}/remove-asset-from-plan-by-uuid/{uuid}	brak	WorkOrdersOperationResultDto	200, 400, 404
POST	/rest/amage/v1/work-orders/asset-plan/{work-order-uuid}/remove-asset-plan-by-uuid/{uuid}	brak	WorkOrdersOperationResultDto	200, 400, 404

Metoda

Ścieżka

Body

Zwraca

Typowe kody

GET

/rest/amage/v1/work-orders/count

brak

liczba (Long)

200, 400

GET

/rest/amage/v1/work-orders/list?page=&size=

brak

lista WorkOrderDto

200, 404

GET

/rest/amage/v1/work-orders/get/by-uuid/{uuid}

brak

WorkOrderDto

200, 400, 404

POST

/rest/amage/v1/work-orders/add

WorkOrderDto

WorkOrdersOperationResultDto

200, 400

POST

/rest/amage/v1/work-orders/edit/{uuid}

WorkOrderDto

WorkOrdersOperationResultDto

200, 400, 404

POST

/rest/amage/v1/work-orders/add-history/{uuid}

WorkOrderHistoryDto

WorkOrdersOperationResultDto

200, 400, 404

POST

/rest/amage/v1/work-orders/edit-history/{uuid}

WorkOrderHistoryDto

WorkOrdersOperationResultDto

200, 400, 404

DELETE

/rest/amage/v1/work-orders/delete-history/{uuid}

brak

WorkOrdersOperationResultDto

200, 400, 404

POST

/rest/amage/v1/work-orders/add-workorder-elementtype-plan/{uuid}

WorkOrderElementTypePlanItemDto

WorkOrdersOperationResultDto

200, 400, 404

POST

/rest/amage/v1/work-orders/edit-workorder-elementtype-plan/{uuid}

WorkOrderElementTypePlanItemDto

WorkOrdersOperationResultDto

200, 400, 404

DELETE

/rest/amage/v1/work-orders/delete-workorder-elementtype-plan/{uuid}

brak

WorkOrdersOperationResultDto

200, 400, 404

POST

/rest/amage/v1/work-orders/asset-plan/{work-order-uuid}/join-asset-to-plan-by-uuid/{uuid}

brak

WorkOrdersOperationResultDto

200, 400, 404

POST

/rest/amage/v1/work-orders/asset-plan/{work-order-uuid}/remove-asset-from-plan-by-uuid/{uuid}

brak

WorkOrdersOperationResultDto

200, 400, 404

POST

/rest/amage/v1/work-orders/asset-plan/{work-order-uuid}/remove-asset-plan-by-uuid/{uuid}

brak

WorkOrdersOperationResultDto

200, 400, 404

Getting the number of item types

Method: GET
Path: /count
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Returns the number of all work orders in the system.

Kody odpowiedzi:

200 OK – poprawne zapytanie, zwracany jest licznik.
400 Bad Request – błędne nagłówki/podpis lub niepoprawny format.

{
    123456
}

Downloading the list of work orders

Method: GET
Path: /list
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

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, implementacja może narzucać mniejszą wartość.

The returned data is an array of JSON objects with the structure:

{
    "uuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "name": "Nazwa zlecenia",
    "description": "Opis zlecenia",
    "typeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "stateName": "IN_PROGRESS",
    "priorityName": "NORMAL",
    "archived": false,
    "contractUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "contractScopeUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "accountUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "created": "2021-01-01T12:00:00",
    "beginDate": "2021-01-01T12:00:00",
    "deadlineDate": "2021-01-01T12:00:00",
    "notes": "notes",
    "startDate": "2021-01-01T12:00:00",
    "finishDate": "2021-01-01T12:00:00",
    "assignedDepartmentUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "assignedUserUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "assignedContractorUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "verifyUserUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "protocolNumber": "A/23/330/2000",
    "parentUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "customerUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "locationUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "placeOfWorkUuid": "f25e62ea-0100-4f4e-aad2-853cf48df2b9",
    "budget": 1000.0,
    "hoursEstimated": 10.0,
    "workAmount": 100.0,
    "workAmountUnit": "metry",
    "workUnitMinutesTotal": 150.0,
    "workUnitMinutes": 100.0,
    "workUnitPrice": 156.0,
    "progressCompleted": 75,
    "elementTypePlanCompleted": false,
    "elementTypePlanTotalCount": 10,
    "elementTypePlanCompletedCount": 7,
    "progressCompletedUpdated": "2021-01-02T10:00:00",
    "elementTypePlanUpdated": "2021-01-02T10:05:00"
}

In case of retrieving data from the system, the ID and UUID fields will be filled in the returned structure with data from the system. The ID field is the local database identifier. The UUID field is a global identifier in the AMAGE system, which can be used as an identifier that uniquely identifies an object in the system and in integrations between systems.

Kody odpowiedzi:

200 OK – zwrócono listę zleceń.
404 Not Found – brak danych (np. błąd obsługi danych).

Downloading a work order by UUID

Method: GET
Path: /get/by-uuid/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

UUID - work order identifier

The data returned is a single JSON object with an element type structure identical to the /list method.

Kody odpowiedzi:

200 OK – zwrócono obiekt.
400 Bad Request – niepoprawny format UUID lub zduplikowany wpis.
404 Not Found – brak zlecenia o podanym UUID.

Adding a new work order

Method: POST
Path: /add
Generates: application/json
Requires: application/json
Authorization: API signature (device-uuid, api-key, api-sign)

The query body should contain a JSON object with the work order data. The object has the same structure as the /list method.

Query

/rest/amage/v1/work-orders/add

Response

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

When saving data from the system, the ID field cannot be filled in. It is filled in when saving the record to the database and returned in the response structure. If the UUID field is provided, then such a value will be assigned to the record. The system does not check the uniqueness of the UUID within the structures or context of the entire system. If the UUID is not provided, the system will generate its own unique UUID.

Kody odpowiedzi:

200 OK – utworzono zlecenie, w odpowiedzi zwracane id i uuid.
400 Bad Request – błąd walidacji danych wejściowych.

Editing a work order

Method: POST
Path: /edit/{uuid}
Generates: application/json
Requires: application/json
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

UUID - work order identifier

In the query body, you should include a JSON object with the work order data. The object has the same structure as in the case of adding a work order. Non-empty fields will be updated in the work order.

Query

/rest/amage/v1/work-orders/edit/f25e62ea-0100-4f4e-aad2-853cf48df2b9

Response

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

Kody odpowiedzi:

200 OK – zapisano zmiany, w odpowiedzi id i uuid rekordu.
400 Bad Request – niepoprawny UUID w ścieżce lub błąd walidacji.
404 Not Found – zlecenie do edycji nie istnieje (zwracane jako 400 z errorCode=404).

Work order history

Save history to an existing work order

Method: POST
Path: /add-history/{uuid}
Generates: application/json
Requires: application/json
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

UUID - work order identifier

The query body should contain a JSON object with the work order history data. The object has the following structure:

{
    "workOrderUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "reportedOn":"2021-01-01T12:00:00",
    "reportedByUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "tstamp":"2021-01-01T12:00:00",
    "stateName": "IN_PROGRESS",
    "message": "message",
    "hoursReported":8.0,
    "workAmountReported":10.0,
    "participantCount":5,
    "valid":true,
    "participants":[
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527"
        },
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527"
        }
    ],
    "workOrderExpenditures":[
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "tstamp":"2021-01-01T12:00:00",
            "elementTypeUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "itemCount":10.0,
            "message": "message"
        }
    ]
}

Query

/rest/amage/v1/work-orders/add-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

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

Kody odpowiedzi:

200 OK – dodano wpis historii.
400 Bad Request – niepoprawny UUID zlecenia lub błąd walidacji danych historii.
404 Not Found – zlecenie nie istnieje (zwracane jako 400 z errorCode=404).

Edit work order history

Method: POST
Path: /edit-history/{uuid}
Generates: application/json
Requires: application/json
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

UUID - history entry identifier

In the query body, you should include a JSON object with the work order history data. The object has a j/n structure. If a list of users is provided, the existing list will be cleared and replaced with the provided one. The same for consumption.

{
    "workOrderUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "reportedOn":"2021-01-01T12:00:00",
    "reportedByUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "tstamp":"2021-01-01T12:00:00",
    "stateName": "IN_PROGRESS",
    "message": "message",
    "hoursReported":8.0,
    "workAmountReported":10.0,
    "participantCount":5,
    "valid":true,
    "participants":[
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527"
        },
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527"
        }
    ],
    "workOrderExpenditures":[
        {
            "uuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "tstamp":"2021-01-01T12:00:00",
            "elementTypeUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
            "itemCount":10.0,
            "message": "message"
        }
    ]
}

Query

/rest/amage/v1/work-orders/edit-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

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

Kody odpowiedzi:

200 OK – zaktualizowano wpis historii.
400 Bad Request – niepoprawny UUID wpisu historii lub błąd walidacji danych.
404 Not Found – wpis historii nie istnieje (zwracane jako 400 z errorCode=404).

Delete work order history

Method: DELETE
Path: /delete-history/{uuid}
Generates: application/json
Requires: application/json
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

UUID - history entry identifier

Query content (body) is empty.

Query

/rest/amage/v1/work-orders/delete-history/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

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

Kody odpowiedzi:

200 OK – usunięto wpis historii.
400 Bad Request – niepoprawny UUID lub błąd walidacji.
404 Not Found – wpis historii nie istnieje (zwracane jako 400 z errorCode=404).

Work order material plan

Saving a material plan to an existing work order

Method: POST
Path: /add-workorder-elementtype-plan/{uuid}
Generates: application/json
Requires: application/json
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

UUID - work order identifier

The query body should contain a JSON object with the work order material plan data. The object has the following structure:

{
    "workOrderUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "elementTypeUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "itemCount":10.0,
    "category":"category",
    "code":"code"
}

Query

/rest/amage/v1/work-orders/add-workorder-elementtype-plan/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

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

Kody odpowiedzi:

200 OK – dodano pozycję planu materiałowego.
400 Bad Request – niepoprawny UUID zlecenia lub błąd walidacji danych planu.
404 Not Found – zlecenie nie istnieje (zwracane jako 400 z errorCode=404).

Editing a material plan for a work order

Method: POST
Path: /edit-workorder-elementtype-plan/{uuid}
Generates: application/json
Requires: application/json
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

UUID - material plan entry identifier

In the body of the request (body), include a JSON object with the material plan data for the work order. The object has the structure:

{
    "workOrderUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "elementTypeUuid":"1c4066e6-cdd6-4903-803a-b6bffe689527",
    "itemCount":10.0,
    "category":"category",
    "code":"code"
}

Query

/rest/amage/v1/work-orders/edit-workorder-elementtype-plan/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

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

Kody odpowiedzi:

200 OK – zaktualizowano pozycję planu materiałowego.
400 Bad Request – niepoprawny UUID pozycji lub błąd walidacji danych.
404 Not Found – pozycja nie istnieje (zwracane jako 400 z errorCode=404).

Removal of work order material plan

Method: DELETE
Path: /delete-workorder-elementtype-plan/{uuid}
Generates: application/json
Requires: application/json
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

UUID - Material Plan Identifier

Query content (body) is empty.

Query

/rest/amage/v1/work-orders/delete-workorder-elementtype-plan/1c4066e6-cdd6-4903-803a-b6bffe689527

Response

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

Kody odpowiedzi:

200 OK – usunięto pozycję planu materiałowego.
400 Bad Request – niepoprawny UUID pozycji lub błąd walidacji.
404 Not Found – pozycja nie istnieje (zwracane jako 400 z errorCode=404).

Work Order Resource Plan

The work order resource plan allows you to operate on the list of resources assigned to a given work order.

Linking an existing resource to a work order

Method: POST
Path: /asset-plan/{work-order-uuid}/join-asset-to-plan-by-uuid/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

work-order-uuid - work order UUID
uuid - resource identifier

The data returned is a JSON object with a structure containing the ID/UUID of the newly created work order resource plan record.

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

Kody odpowiedzi:

200 OK – przypięto zasób do planu zlecenia.
400 Bad Request – niepoprawny UUID zlecenia lub zasobu, błąd walidacji, duplikat zasobu w planie.
404 Not Found – brak zlecenia lub zasobu (zwracane jako 400 z errorCode=404).

Removing a resource from a work order plan

Method: POST
Path: /asset-plan/{work-order-uuid}/remove-asset-from-plan-by-uuid/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

work-order-uuid - work order UUID
uuid - resource identifier

The data returned is a JSON object with a structure containing the ID/UUID of the deleted work order resource plan record.

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

Kody odpowiedzi:

200 OK – usunięto zasób z planu.
400 Bad Request – niepoprawny UUID zlecenia lub zasobu.
404 Not Found – brak zlecenia lub zasobu (zwracane jako 400 z errorCode=404).

If a resource is added multiple times to a given work order, the query will return an error. You should use a method that explicitly specifies the resource plan record ID for the work order.

This method requires the specific work order resource plan record ID to be provided in the UUID field.

Method: POST
Path: /asset-plan/{work-order-uuid}/remove-asset-plan-by-uuid/{uuid}
Generates: application/json
Requires: application/json, text/plain
Authorization: API signature (device-uuid, api-key, api-sign)

Parametrs:

work-order-uuid - work order UUID
uuid - resource plan entry identifier for the work order

The data returned is a JSON object with a structure containing the ID/UUID of the deleted work order resource plan record.

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

Kody odpowiedzi:

200 OK – usunięto wpis planu zasobów.
400 Bad Request – niepoprawny UUID zlecenia lub wpisu planu.
404 Not Found – brak zlecenia lub wpisu planu (zwracane jako 400 z errorCode=404).

AMAGE REST API - Work Orders

Introduction/Context

Data structures

Work order

Getting the number of item types

Downloading the list of work orders

Downloading a work order by UUID

Adding a new work order

Editing a work order

Work order history

Save history to an existing work order

Edit work order history

Delete work order history

Work order material plan

Saving a material plan to an existing work order

Editing a material plan for a work order

Removal of work order material plan

Work Order Resource Plan

Linking an existing resource to a work order

Removing a resource from a work order plan

Delete resource plan item related to work order