PATCH /integration/documents/r1/documents

BPMN Diagram (TBD)

Business Logic

This Integration API update a document if it’s already present.

System verifies Permission Required and starts the elaboration that is organized in steps.

STEP 1 - External System Validation

System takes Input fields and checks their existence in internal configuration.

If System can obtain the Output fields → continue to next step.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

STEP 2 - New Version File Creation

System takes Input fields and creates a new version of an existing files

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

STEP 3 - Upload URL Retrieve

System takes Input fields and retrieves the Presigned URL.

If System can obtain the Output fields, it automatically uploads the file → continue to next step.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

STEP 4 - Metadata Creation or Update

System checks whether there is any metadata in the request.

This step is skipped if the input Metadata fields are absent.

STEP 4a - Resource Id Retrieve (perhaps to be eliminated in the future)

System takes uuid created in step File Creation and uses it as Input Field.

If System can obtain the Output fields -> continue to the next step.

If System can’t obtain the Output fields → responds with error. Elaboration is stopped.

STEP 4b - Metadata Retrieve

System takes Input fields and checks their existence.

Input filed resourceId corresponds to the id output retrieved in the step Resource Id Retrieve.

If System can obtain the Output fields → continue to the step Metadata Update.

If System can’t obtain the Output fields → continue to the step Metadata Creation

STEP 4c - Metadata Update

System takes Input fields and updates the metadata record.

If Response State is SUCCESS → continue to the step File activation.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

STEP 4d - Metadata Creation

System takes Input fields and creates the Metadata record.

If Response State is SUCCESS → continue to next step.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

STEP 5 - File Activation

System uploads file on the presignedURL and then activates it.

If Response State is SUCCESS → elaboration is stopped. See Response payload fields.

If Response State is ERROR → elaboration is stopped. See Response payload fields.

Path Parameters

As their name suggests, they are included in the URL path of the endpoint.

Not applicable.

Query String Parameters

Start with a ? and includes parameters listed one after the another separated by &.

Not applicable.

Header Parameters

Parameters included in the request headers. Generally, request headers are used to keep authorization parameters.

Default.

Request Body Parameters

Request body parameters are used when clients send data to the API. They are shipped in a JSON Object only in POST, PUT, or PATCH requests.

The objects in input could have also the extension object that allows to add additional, customized data to this API. More info here How to use APIs: Custom data via Extension.

Request example

Creation example - Work Order Case

{
  "extension": {
    "myFieldName": "myValue"
  },
  "externalSystemCode": "SAP",
  "file": {
    "extension": {
      "myFieldName": "myValue"
    },
    "fileUuid": "214dbe38-1240-4acf-8b34-a06db8136270",
    "name": "doc2",
    "startValidityDate": "2026-07-10T21:36:02.491Z",
    "endValidityDate": "2026-08-10T21:36:02.491Z" 
    },
    "metadata": {
      "extension": {
        "myFieldName": "myValue"
      },
      "description":"broken meter report 1",
      "number":"2",
      "notes":"To be replaced"
    }
  }
}

Response documentation

Response payload fields

Compliant with RFC Standard https://www.rfc-editor.org/rfc/rfc9457.html

Extension fields:

Response example

{
  "uuid": "c89f7ea8-7ef5-4f3f-bd37-d11fc50088c1"
}

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "External system string does not exist",
  "instance": "/integration/work-orders/r1/documents",
  "code": "IA001_001"
} 

Response error codes