AMCS Group VehicleEvent API

openapi: 3.2.0
info:
  title: AMCS Platform REST Vehicle Event API
  description: '![latest End points](/amcsrestapi/diagram/endpointslatest.svg)


    # Overview


    ## Who Should Read this Document


    This document contains a technical description of the AMCS Platform REST API. It is intended for:


    · System integrators


    · Customer IT team looking to integrate AMCS Platform with another system


    · Third parties looking to integrate their system with AMCS Platform


    ## Document Scope


    This document introduces the technical aspects of the AMCS Platform REST API. The purpose of this document is to provide readers with detail on how to:


    · Access the REST API


    · Make calls to the API to retrieve, append and update resources


    · Retrieve the incremental changes to a collection


    · Find more detail on the end points that are available from an environment. ## Summary


    AMCS Platform REST API is designed to support the integration of AMCS Platform with other systems. With care and additional infrastructure, the REST API can be used to build functionality on top of Platform but that is not it’s primary purpose. The ‘changes since’ process provides the main means of performing an initial synchronisation of the AMCS Platform and another system, and then keeping them synchronised. Methods are also provided to create and update resources. # Integration Patterns and Tools


    The AMCS Platform provides a number of tools that can be used to connect systems. Care should be taken to match the right tooling to the intended pattern of integration. · When an extract-based approach is needed, use BI reporting. · When derived values are require, use the data mart. · When business processes on different systems need to be integrated by synchronising the data on each through an event style interface, use the REST API. An integration using the REST API will need to take full responsibility for all aspects of the integration including:


    · Pulling change events from AMCS Platform


    · Filtering the changed resources for the ones that are of interest


    · Pulling additional resources from the REST API in order the retrieve all the properties needed by the destination


    · Mashing resources to create the complete view required


    · Translating that into the form required by the destination


    · Validating this to ensure it meet the entry rules of the destination


    · Pushing the result to the destination


    In the early stages of designing the interface care should be taken to ensure that the need for caching/staging has been considered. The changes since functionality is effectively a means of pulling create/change events from platform. The only filters available enable retrieval of related resources to build a view external to AMCS Platform


    # Basics


    The AMCS REST API provides a RESTful interface that allows access to the primary business resources of the AMCS platform. The interface follows general HATEOAS compliance principles. ## Quick start


    A quickstart walkthrough based on node.js and covering authentication and getting a page of customers can be found here. ## Interface definitions


    Swagger documentation for the end points available on an environment can be found at:


    Before 8.5: https://{environment domain name}/swagger/ui/index


    From 8.5: https://{environment domain name}/erp/api/swagger/ui/index


    ## HTTP Interface


    The following HTTP RESTful methods are provided as part of this API:


    · GET: Provides read access to retrieve details of one or more resources. · POST: Creates or updates a single resource or a set of resources. · PUT: Updates a single resource or a set of resources. Note:


    · DELETE methods are currently not provided as part of the API. The REST API URIs begin with


    https://{environment domain name}/erp/api/integrator/erp


    For example:

    https://prod.amcs-at-mycompany.com/erp/api/integrator/erp


    This should be used as the base of the URI.'
  version: latest
servers:
- url: https://ete-p5-tst-svc-core.amcsplatform.com/erp/api/integrator/erp
tags:
- name: VehicleEvent
paths:
  /fleet/vehicleEvents/changes:
    get:
      tags:
      - VehicleEvent
      summary: Retrieve changes
      description: '| Property | Description |

        | ------------------------- | ------------------------------------------------------------------------ |

        | GUID| The GUID associated to the vehicle event.|

        | AdditionalInformation| The additional information associated to the vehicle event.|

        | BinVisitedCount| The bin visited count associated to the vehicle event.|

        | CurrentWeight | The current weight associated to the vehicle event.|

        | Distance | The distance associated to the vehicle event.|

        | EventDate | The event date associated to the vehicle event.|

        | FlexibleData| The flexible data associated to the vehicle event.|

        | IsAcknowledged| Whether the vehicle event is acknowledged.|

        | IsGeoCompressed| Whether the vehicle event is geo compressed.|

        | Location| The location associated to the vehicle event.|

        | NumberOfPictures| The number of pictures associated to the vehicle event.|

        | Speed| The speed associated to the vehicle event.|

        | SpeedLimit| The speed limit associated to the vehicle event.|

        | SysUserName| The system user name associated to the vehicle event.|

        | TimeStamp| The time stamp associated to the vehicle event.|

        | TotalDistance| The total distance associated to the vehicle event.|

        | VehicleCode| The vehicle code associated to the vehicle event.|

        | VehicleEventXML| The vehicle event XML associated to the vehicle event.|

        | VehicleEventTypeListItem| The GUID and description associated to the vehicle event.|

        | RelatedJobGuid| The related job GUID associated to the vehicle event. Filterable|

        | RelatedRouteGuid| The related route GUID associated to the vehicle event. Filterable|

        | RelatedRouteVisitGroupGuid| The related route visit group GUID associated to the vehicle event. Filterable|

        | RelatedScheduleGuid| The related schedule GUID associated to the vehicle event. Filterable|

        | RelatedVehicleGuid| The related vehicle GUID associated to the vehicle event.|

        | IsDeleted| Whether the vehicle event is deleted|'
      operationId: VehicleEvent_GetChanges
      parameters:
      - name: since
        in: query
        schema:
          type: string
      - name: cursor
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResourceChanges_ApiIntegratorVehicleEventResource'
  /fleet/vehicleEvents/{guid}:
    get:
      tags:
      - VehicleEvent
      summary: Find with GUID
      description: '| Property | Description |

        | ------------------------- | ------------------------------------------------------------------------ |

        | GUID| The GUID associated to the vehicle event.|

        | AdditionalInformation| The additional information associated to the vehicle event.|

        | BinVisitedCount| The bin visited count associated to the vehicle event.|

        | CurrentWeight | The current weight associated to the vehicle event.|

        | Distance | The distance associated to the vehicle event.|

        | EventDate | The event date associated to the vehicle event.|

        | FlexibleData| The flexible data associated to the vehicle event.|

        | IsAcknowledged| Whether the vehicle event is acknowledged.|

        | IsGeoCompressed| Whether the vehicle event is geo compressed.|

        | Location| The location associated to the vehicle event.|

        | NumberOfPictures| The number of pictures associated to the vehicle event.|

        | Speed| The speed associated to the vehicle event.|

        | SpeedLimit| The speed limit associated to the vehicle event.|

        | SysUserName| The system user name associated to the vehicle event.|

        | TimeStamp| The time stamp associated to the vehicle event.|

        | TotalDistance| The total distance associated to the vehicle event.|

        | VehicleCode| The vehicle code associated to the vehicle event.|

        | VehicleEventXML| The vehicle event XML associated to the vehicle event.|

        | VehicleEventTypeListItem| The GUID and description associated to the vehicle event.|

        | RelatedJobGuid| The related job GUID associated to the vehicle event. Filterable|

        | RelatedRouteGuid| The related route GUID associated to the vehicle event. Filterable|

        | RelatedRouteVisitGroupGuid| The related route visit group GUID associated to the vehicle event. Filterable|

        | RelatedScheduleGuid| The related schedule GUID associated to the vehicle event. Filterable|

        | RelatedVehicleGuid| The related vehicle GUID associated to the vehicle event.|

        | IsDeleted| Whether the vehicle event is deleted|'
      operationId: VehicleEvent_Get
      parameters:
      - name: guid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: udf
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResourceResultEntity_ApiIntegratorVehicleEventResource'
    put:
      tags:
      - VehicleEvent
      summary: Partial update
      description: '| Property | Description | Required |

        | ------------------------------------- | ----------------------------------------------------------------------------- | -------- |

        | GUID| The GUID associated to the vehicle event.| No |

        | AdditionalInformation| The additional information associated to the vehicle event.| No |

        | BinVisitedCount| The bin visited count associated to the vehicle event.| No |

        | CurrentWeight | The current weight associated to the vehicle event.| No |

        | Distance | The distance associated to the vehicle event.| No |

        | EventDate | The event date associated to the vehicle event.| No |

        | FlexibleData| The flexible data associated to the vehicle event.| No |

        | IsAcknowledged| Whether the vehicle event is acknowledged.| Yes |

        | IsGeoCompressed| Whether the vehicle event is geo compressed.| Yes |

        | Location| The location associated to the vehicle event.| No |

        | NumberOfPictures| The number of pictures associated to the vehicle event.| No |

        | Speed| The speed associated to the vehicle event.| No |

        | SpeedLimit| The speed limit associated to the vehicle event.| No |

        | SysUserName| The system user name associated to the vehicle event.| No |

        | TimeStamp| The time stamp associated to the vehicle event.| No |

        | TotalDistance| The total distance associated to the vehicle event.| No |

        | VehicleCode| The vehicle code associated to the vehicle event.| Yes |

        | VehicleEventXML| The vehicle event XML associated to the vehicle event.| No |

        | VehicleEventTypeListItem| The GUID and description associated to the vehicle event.| No |

        | RelatedJobGuid| The related job GUID associated to the vehicle event.| No |

        | RelatedRouteGuid| The related route GUID associated to the vehicle event.| No |

        | RelatedRouteVisitGroupGuid| The related route visit group GUID associated to the vehicle event.| No |

        | RelatedScheduleGuid| The related schedule GUID associated to the vehicle event.| No |

        | RelatedVehicleGuid| The related vehicle GUID associated to the vehicle event.| Yes |

        | IsDeleted| Whether the vehicle event is deleted| No |


        **Extra validations**


        | Condition | Error message |

        | --------- | ------------- |

        | Invalid RelatedJobGuid | Failed to retrieve Job with RelatedJobGuid of {Guid} |

        | Invalid RelatedRouteGuid | Failed to retrieve Route with RelatedRouteGuid of {Guid} |

        | Invalid RelatedScheduleGuid | Failed to retrieve Schedule with RelatedScheduleGuid of {Guid} |

        | Invalid RelatedVehicleGuid | Failed to retrieve Vehicle with RelatedVehicleGuid of {Guid} |

        | VehicleEventType not found with value VehicleEventTypeListItem.Guid | Failed to retrieve VehicleEventType with GUID of {value of VehicleEventTypeListItem.Guid} |

        | If IsDeleted is set as true on the payload | IsDeleted is TRUE. Could not process the request. Resources can not be deleted via the REST API. |

        | Location.Lat value not in range between -90 and 90 or Location.Long value not in range between -180 and 180 | Location.Lat value must be between -90 and 90. Location.Long value must be between -180 and 180. |'
      operationId: VehicleEvent_Update
      parameters:
      - name: guid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiIntegratorVehicleEventResource'
        required: true
        x-bodyName: null
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResourceId'
  /fleet/vehicleEvents:
    get:
      tags:
      - VehicleEvent
      summary: Find with Filters
      description: '| Property | Description |

        | ------------------------- | ------------------------------------------------------------------------ |

        | GUID| The GUID associated to the vehicle event.|

        | AdditionalInformation| The additional information associated to the vehicle event.|

        | BinVisitedCount| The bin visited count associated to the vehicle event.|

        | CurrentWeight | The current weight associated to the vehicle event.|

        | Distance | The distance associated to the vehicle event.|

        | EventDate | The event date associated to the vehicle event.|

        | FlexibleData| The flexible data associated to the vehicle event.|

        | IsAcknowledged| Whether the vehicle event is acknowledged.|

        | IsGeoCompressed| Whether the vehicle event is geo compressed.|

        | Location| The location associated to the vehicle event.|

        | NumberOfPictures| The number of pictures associated to the vehicle event.|

        | Speed| The speed associated to the vehicle event.|

        | SpeedLimit| The speed limit associated to the vehicle event.|

        | SysUserName| The system user name associated to the vehicle event.|

        | TimeStamp| The time stamp associated to the vehicle event.|

        | TotalDistance| The total distance associated to the vehicle event.|

        | VehicleCode| The vehicle code associated to the vehicle event.|

        | VehicleEventXML| The vehicle event XML associated to the vehicle event.|

        | VehicleEventTypeListItem| The GUID and description associated to the vehicle event.|

        | RelatedJobGuid| The related job GUID associated to the vehicle event. Filterable|

        | RelatedRouteGuid| The related route GUID associated to the vehicle event. Filterable|

        | RelatedRouteVisitGroupGuid| The related route visit group GUID associated to the vehicle event. Filterable|

        | RelatedScheduleGuid| The related schedule GUID associated to the vehicle event. Filterable|

        | RelatedVehicleGuid| The related vehicle GUID associated to the vehicle event.|

        | IsDeleted| Whether the vehicle event is deleted|'
      operationId: VehicleEvent_GetCollection
      parameters:
      - name: filter
        in: query
        schema:
          type: string
      - name: max
        in: query
        schema:
          type: integer
          format: int32
      - name: page
        in: query
        schema:
          type: integer
          format: int32
      - name: includeCount
        in: query
        schema:
          type: boolean
      - name: udf
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResourceResultCollection_ApiIntegratorVehicleEventResource'
    post:
      tags:
      - VehicleEvent
      summary: Create or update
      description: '| Property | Description | Required |

        | ------------------------------------- | ----------------------------------------------------------------------------- | -------- |

        | GUID| The GUID associated to the vehicle event.| No |

        | AdditionalInformation| The additional information associated to the vehicle event.| No |

        | BinVisitedCount| The bin visited count associated to the vehicle event.| No |

        | CurrentWeight | The current weight associated to the vehicle event.| No |

        | Distance | The distance associated to the vehicle event.| No |

        | EventDate | The event date associated to the vehicle event.| No |

        | FlexibleData| The flexible data associated to the vehicle event.| No |

        | IsAcknowledged| Whether the vehicle event is acknowledged.| Yes |

        | IsGeoCompressed| Whether the vehicle event is geo compressed.| Yes |

        | Location| The location associated to the vehicle event.| No |

        | NumberOfPictures| The number of pictures associated to the vehicle event.| No |

        | Speed| The speed associated to the vehicle event.| No |

        | SpeedLimit| The speed limit associated to the vehicle event.| No |

        | SysUserName| The system user name associated to the vehicle event.| No |

        | TimeStamp| The time stamp associated to the vehicle event.| No |

        | TotalDistance| The total distance associated to the vehicle event.| No |

        | VehicleCode| The vehicle code associated to the vehicle event.| Yes |

        | VehicleEventXML| The vehicle event XML associated to the vehicle event.| No |

        | VehicleEventTypeListItem| The GUID and description associated to the vehicle event.| No |

        | RelatedJobGuid| The related job GUID associated to the vehicle event.| No |

        | RelatedRouteGuid| The related route GUID associated to the vehicle event.| No |

        | RelatedRouteVisitGroupGuid| The related route visit group GUID associated to the vehicle event.| No |

        | RelatedScheduleGuid| The related schedule GUID associated to the vehicle event.| No |

        | RelatedVehicleGuid| The related vehicle GUID associated to the vehicle event.| Yes |

        | IsDeleted| Whether the vehicle event is deleted| No |


        **Extra validations**


        | Condition | Error message |

        | --------- | ------------- |

        | Invalid RelatedJobGuid | Failed to retrieve Job with RelatedJobGuid of {Guid} |

        | Invalid RelatedRouteGuid | Failed to retrieve Route with RelatedRouteGuid of {Guid} |

        | Invalid RelatedScheduleGuid | Failed to retrieve Schedule with RelatedScheduleGuid of {Guid} |

        | Invalid RelatedVehicleGuid | Failed to retrieve Vehicle with RelatedVehicleGuid of {Guid} |

        | VehicleEventType not found with value VehicleEventTypeListItem.Guid | Failed to retrieve VehicleEventType with GUID of {value of VehicleEventTypeListItem.Guid} |

        | If IsDeleted is set as true on the payload | IsDeleted is TRUE. Could not process the request. Resources can not be deleted via the REST API. |

        | Location.Lat value not in range between -90 and 90 or Location.Long value not in range between -180 and 180 | Location.Lat value must be between -90 and 90. Location.Long value must be between -180 and 180. |'
      operationId: VehicleEvent_Create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiIntegratorVehicleEventResource'
        required: true
        x-bodyName: null
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResourceId'
components:
  schemas:
    ApiIntegratorLocationGeoLocationResource:
      type: object
      properties:
        Lat:
          type: number
          format: double
        Long:
          type: number
          format: double
    ApiResourceResultCollectionExtra:
      type: object
      properties:
        count:
          type: integer
          format: int32
    ApiResourceResultEntityLinks:
      type: object
      properties:
        self:
          type: string
        associations:
          type: array
          items:
            type: string
        expand:
          type: array
          items:
            type: string
        operations:
          type: array
          items:
            type: string
    ApiResourceResultEntityExtra:
      type: object
      properties:
        expand:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: object
        include:
          type: object
          additionalProperties:
            type: array
            items:
              type: object
              additionalProperties:
                type: object
    ApiResourceResultUpdatesExtra:
      type: object
      properties:
        until:
          type: string
        cursor:
          type: string
    ApiResourceId:
      type: object
      properties:
        resource:
          type: string
          format: uuid
        errors:
          $ref: '#/components/schemas/ApiResourceErrors'
        status:
          $ref: '#/components/schemas/ApiResourceStatus'
    ApiIntegratorListItemResource:
      type: object
      properties:
        Description:
          type: string
        Guid:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
    ApiResourceChanges_ApiIntegratorVehicleEventResource:
      type: object
      properties:
        resource:
          type: array
          items:
            $ref: '#/components/schemas/ApiIntegratorVehicleEventResource'
        extra:
          $ref: '#/components/schemas/ApiResourceResultUpdatesExtra'
        errors:
          $ref: '#/components/schemas/ApiResourceErrors'
        status:
          $ref: '#/components/schemas/ApiResourceStatus'
    ApiResourceStatus:
      type: object
      properties:
        id:
          type: integer
          format: int32
        isSuccess:
          type: boolean
    ApiResourceResultEntity_ApiIntegratorVehicleEventResource:
      type: object
      properties:
        resource:
          $ref: '#/components/schemas/ApiIntegratorVehicleEventResource'
        links:
          $ref: '#/components/schemas/ApiResourceResultEntityLinks'
        extra:
          $ref: '#/components/schemas/ApiResourceResultEntityExtra'
        errors:
          $ref: '#/components/schemas/ApiResourceErrors'
        status:
          $ref: '#/components/schemas/ApiResourceStatus'
    ApiResourceErrors:
      type: object
      properties:
        errors:
          type: string
    ApiIntegratorVehicleEventResource:
      type: object
      properties:
        AdditionalInformation:
          type: string
        BinVisitedCount:
          type: integer
          format: int32
        CurrentWeight:
          type: number
          format: double
        Distance:
          type: number
          format: double
        FlexibleData:
          type: string
        IsGeoCompressed:
          type: boolean
        Location:
          $ref: '#/components/schemas/ApiIntegratorLocationGeoLocationResource'
        NumberOfPictures:
          type: integer
          format: int32
        TimeStamp:
          type: string
          format: offsetDateTime
          example: '2000-01-01T00:00:00+01:00'
        TotalDistance:
          type: number
          format: double
        VehicleCode:
          type: string
        VehicleEventXML:
          type: string
        VehicleEventTypeListItem:
          $ref: '#/components/schemas/ApiIntegratorListItemResource'
        RelatedScheduleGuid:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        RelatedJobGuid:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        RelatedRouteGuid:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        RelatedRouteVisitGroupGuid:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        RelatedVehicleGuid:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
        EventDate:
          type: string
          format: localDate
          example: '2000-01-01'
        IsAcknowledged:
          type: boolean
        IsDeleted:
          type: boolean
        GUID:
          type: string
          format: uuid
          example: 00000000-0000-0000-0000-000000000000
    ApiResourceResultCollection_ApiIntegratorVehicleEventResource:
      type: object
      properties:
        resource:
          type: array
          items:
            $ref: '#/components/schemas/ApiIntegratorVehicleEventResource'
        extra:
          $ref: '#/components/schemas/ApiResourceResultCollectionExtra'
        errors:
          $ref: '#/components/schemas/ApiResourceErrors'
        status:
          $ref: '#/components/schemas/ApiResourceStatus'