openapi: 3.0.0
info:
  title: Tracking Device API
  version: '2.0'
  description: >-
    The Tracking Device API is a unified interface to post or request
    information about tracking devices. Usually a tracking device is a vehicle,
    which needs to be registered to our platform before you can feed GPS data to
    other endpoints.


    *Make sure you request the Auth API first*
  contact:
    name: ''
    email: ''
servers:
  - url: https://tracking-device-api.services.simacan.com/api/public/v2
    description: Production Environment
  - url: https://tracking-device-api-stg.services.simacan.com/api/public/v2
    description: Staging Environment
paths:
  /:
    post:
      requestBody:
        description: Tracking Device that needs to be added to the service
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postTrackingDevice'
        required: true
      responses:
        '200':
          description: >-
            Indicates that your request was successful. You will see an entity
            describing or containing the result of your action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postTrackingDeviceResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
      security:
        - BearerAuth: []
      operationId: postTrackingDevice
      summary: Register or update a tracking device
      description: >-
        Registers a new or updates an existing tracking device depending if the
        device is already known. A device is defined by a unique combination of
        the externalSystemId and the externalDeviceId. So registering an already
        existing device will update all the attributes except the DeviceUUID
    put:
      requestBody:
        description: Tracking Device that needs to be added to the service
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postTrackingDevice'
        required: true
      responses:
        '200':
          description: >-
            Indicates that your request was successful. You will see an entity
            describing or containing the result of your action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postTrackingDeviceResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
      security:
        - BearerAuth: []
      operationId: putTrackingDevice
      summary: Register or update a tracking device
      description: >-
        Registers a new or updates an existing tracking device depending if the
        device is already known. A device is defined by a unique combination of
        the externalSystemId and the externalDeviceId. So registering an already
        existing device will update all the attributes except the DeviceUUID
    get:
      summary: Retrieve all devices
      description: >-
        Retrieves all devices of the associated carriers of the authenticated
        account.
      operationId: getTrackingDevices
      responses:
        '200':
          description: >-
            Indicates that your request was successful. You will see an entity
            describing or containing the result of your action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postTrackingDeviceResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /external-system/{externalSystemId}/external-device/{externalDeviceId}:
    get:
      summary: Retrieve a device by externalDeviceId
      description: >-
        Retrieves a single device of the associated carrier of the authenticated
        account, based on the externalDeviceId
      operationId: getTrackingDeviceById
      parameters:
        - name: externalSystemId
          in: path
          schema:
            type: string
          description: >-
            Identifier for the source system we use to uniquely recognize the
            shipper/carrier
          required: true
        - name: externalDeviceId
          in: path
          schema:
            type: string
          description: >-
            The identifier you use to recognize the device/vehicle in your
            source system
          required: true
      responses:
        '200':
          description: >-
            Indicates that your request was successful. You will see an entity
            describing or containing the result of your action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postTrackingDeviceResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
  /external-system/{externalSystemId}/license-plate/{licensePlate}:
    get:
      summary: Retrieve device by license plate
      description: >-
        Retrieves a single device of the associated carrier of the authenticated
        account, based on the linked license plate
      operationId: getTrackingDeviceByLicensePlate
      parameters:
        - name: externalSystemId
          in: path
          schema:
            type: string
          description: >-
            Identifier for the source system we use to uniquely recognize the
            shipper/carrier
          required: true
        - name: licensePlate
          in: path
          schema:
            type: string
          description: License Plate linked for the current tracking device
          required: true
      responses:
        '200':
          description: >-
            Indicates that your request was successful. You will see an entity
            describing or containing the result of your action
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/postTrackingDeviceResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
components:
  securitySchemes:
    BearerAuth:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: >-
        Before any request you do, make sure you have obtained an access token
        from the Auth API. You need to send the access token through an HTTP
        Authorization request header
  schemas:
    postTrackingDeviceResponse:
      properties:
        deviceUUID:
          type: string
          description: This is the Simacan generated universally unique identifier
          example: b9ed42ff-3ffb-4418-9498-5eb0ba308899
        externalSystemId:
          type: string
          example: fms-janszoon_transport
          description: >-
            Identifier for the source system we use to uniquely recognize the
            shipper/carrier
        externalDeviceId:
          type: string
          description: >-
            The identifier you use to recognize the device/vehicle in your
            source system
          example: '1234'
        customerDeviceId:
          type: string
        active:
          type: boolean
          description: Indicates whether the current tracking device is active or not
          example: 'true'
        relation:
          type: string
          example: janszoon_transport
        carrierCode:
          type: string
          description: >-
            This code is used by the Simacan Control Tower to match a Tracking
            Device with a carrier
        creationDate:
          type: string
          example: '2020-06-07T09:17:43Z'
          description: Timestamp when record was created
        lastUpdatedDate:
          type: string
          description: Timestamp when record was updated
        licensePlate:
          type: string
          example: AB-12-CD
          description: License Plate linked with the current tracking device
        driverName:
          type: string
          description: Driver name linked with the current tracking device
        attributes:
          type: object
          description: Any freeform additional attributes
          example:
            carBrand: Mercedes
    postTrackingDevice:
      required:
        - externalDeviceId
        - externalSystemId
        - active
        - carrierCode
        - customerDeviceId
      type: object
      properties:
        externalDeviceId:
          type: string
          description: >-
            The identifier you use to recognize the device/vehicle in your
            source system
        externalSystemId:
          type: string
          description: >-
            Identifier for the source system we use to uniquely recognize the
            shipper/carrier
        active:
          type: boolean
          default: true
          description: Indicates whether the current tracking device is active or not
        carrierCode:
          type: string
          description: >-
            This code is used by the Simacan Control Tower to match a Tracking
            Device with a carrier
        customerDeviceId:
          type: string
        licensePlate:
          type: string
          description: License Plate linked with the current tracking device
        driverName:
          type: string
          description: Driver name linked with the current tracking device
        attributes:
          type: object
          description: Any freeform additional attributes
      xml:
        name: postTrackingDevice
  responses:
    '400':
      content:
        text/plain:
          schema:
            type: string
            description: error message
            example: The body of the request could not be parsed.
      description: >-
        Bad Request: You will receive this status, when the data you’ve
        delivered is not in the correct format. You will see an entity
        describing what went wrong.
    '401':
      content:
        text/plain:
          schema:
            type: string
            description: error message
            example: Authentication credentials were missing or incorrect.
      description: >-
        Unauthorized: Whenever you will get this status, you have either
        provided the wrong credentials or none at all. Check if you bearer token
        has not expired. 
    '403':
      content:
        text/plain:
          schema:
            type: string
            description: error message
            example: Access to this resource is not allowed.
      description: >-
        Forbidden: You will receive this status, when you successfully supplied
        credentials, but your username does not have the necessary permissions
        for the resource.
    '404':
      content:
        text/plain:
          schema:
            type: string
            description: error message
            example: The requested resource was not found.
      description: >-
        Not Found: Whenever you will get a 404, you are probably using a
        malformed or incorrect URL.
    postTrackingDeviceResponse:
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/postTrackingDeviceResponse'
      description: successful operation
tags:
  - name: ''
security:
  - BearerAuth: []
