NextGen APIs
NextGen APIs
Breadcrumbs

POST /integration/tracking/r1/resource-positions (WIP)

Http Verb

POST

Url

/integration/tracking/r1/resource-positions

Permissions required

Core Additional Parameters: Edit (fsm.core.additionalparameter.edit)

Last Modified Version

r1

Tech Tags


Available Async

No

BPMN Diagram (WIP)

diagram (1).svg

Business Logic

This Integration API inserts a Resource GPS Coordinates.

System verifies that one of identificationNumber and secondaryIdentificationNumber must be filled.

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.

API Verb: GET

Resource: External Systems

Input: externalSystemCode, active=true

Output: externalSystemId

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.

Error Type:

STEP 2 - Resource Validation

System takes Input fields and checks their existence.

API Verb: GET

Resource: Resource

Input: identificationNumber, secondaryIdentificationNumber, loan=false

Output: resourceId

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.

Error Type:

STEP 3 - Resource Latest Position Existence

System uses resourceId retrieved from the previous step as input field.

API Verb: GET

Resource: Resource-positions/latest

Input: resourceId

Output: resourceLatestPositionId

If System can obtain the Output fields → continue to the step Resource GPS location Update.

If System can’t obtain the Output fields → continue to the step Resource GPS location Creation.

Error Type:

  • Others - see link in Resource

STEP 4 - Resource GPS location Creation

System takes Input fields and creates the entity.

API Verb: POST

Resource: Resource-positions/latest

Input: resourceId, xCoordinate, yCoordinate, detectionDate, accuracy

Output: Response State

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

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

Error Type:

  • Others - see link in Resource

STEP 5 - Resource GPS location Update

System takes Input fields and creates the entity.

API Verb: PATCH

Resource: Resource-positions/latest/{latestResourcePositionId}

Input: xCoordinate, yCoordinate, detectionDate, accuracy

Output: Response State

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

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

Error Type:

  • Others - see link in Resource


Path Parameters

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

Not present.

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.

Field


Description

Mandatory

Constraint

1

externalSystemCode


External system code

Y

Not Blank

2

identificationNumber


Identification Number

N

Null or Not Blank

3

secondaryIdentificationNumber


Secondary Identification Number of resource

N

Null or Not Blank

4

position

xCoordinate

The geographic X coordinate (Longitude) of the resource's location

Y

Not Null

5

yCoordinate

The geographic Y coordinate (Latitude) of the resource's location

Y

Not Null

6

detectionDate

The timestamp indicating when the coordinates were recorded. Must follow the ISO-8601 format (e.g., 2026-02-13T16:15:30Z)

N


7

accuracy

The accuracy radius of the GPS coordinates, typically expressed in meters

N


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

JSON
{
  "extension": {},
  "externalSystemCode": "SAP",
  "identificationNumber": "123434234",
  "position": {
    "extension": {},
    "xCoordinate": -118.243683,
    "yCoordinate": 34.052235,
    "detectionDate": "2026-02-13T16:30:00Z",
    "accuracy": 10
    }
}

Response documentation

Response payload fields

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

Extension fields:

Field

Description

Note

id

Created instance id

Only for SUCCESS

code

Extension member of a Problem Details Object that contains the error code

Only for ERROR

Response example

Error example

JSON
{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "External system string does not exist",
  "instance": "/integration/tracking/r1/resource-positions",
  "code": "IA001_001"
}

Response error codes