openapi: 3.0.0
info:
  title: Transport Realisation API
  version: '1.0'
  description: >-
    This service aims to receive trip based realization data for our customers,
    in order to update the actual status of a trip in the Control Tower.
  contact:
    name: ''
    email: ''
servers:
  - url: https://transport-realisation-receiver.services.simacan.com/api/public
    description: Production Environment
  - url: https://transport-realisation-receiver-stg.services.simacan.com/api/public
    description: Staging Environment
paths:
  /{shipper_code}/transporter/v2/{carrier_code}/realisation:
    post:
      summary: Realisation update
      operationId: getRealisationUpdate
      description: >-
        The realisation endpoint enables you to send realisation data for a
        specific trip
      parameters:
        - name: shipper_code
          in: path
          schema:
            type: string
          description: Unique shipper code as provided by Simacan
          required: true
        - name: carrier_code
          in: path
          schema:
            type: string
          description: Unique carrier code as provided by Simacan
          required: true
      requestBody:
        description: ''
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/realisationUpdate'
            examples:
              minimal:
                summary: Minimal dataset
                value: >-
                  <?xml version="1.0" encoding="utf-8"?>

                  <realisation xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns="http://www.simacan.com/schemas/rct/transporter/v2/realisation">
                    <tripRealisation xmlns="">
                      <tripId>123456</tripId>
                      <timestamp>2020-12-31T14:13:22.11823+01:00</timestamp>
                      <heading>180</heading>
                      <speed>75</speed>
                      <x>4.89145</x>
                      <y>52.37376</y>
                    </tripRealisation>
                  </realisation>
              trailer:
                summary: Minimal dataset with Trailer
                value: >-
                  <?xml version="1.0" encoding="utf-8"?>

                  <realisation
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns="http://www.simacan.com/schemas/rct/transporter/v2/realisation">
                    <tripRealisation xmlns="">
                      <tripId>123456</tripId>
                      <timestamp>2020-12-31T14:13:22.11823+01:00</timestamp>
                      <activity>RIJDEN</activity>
                      <heading>180</heading>
                      <mileage>209923.27</mileage>
                      <speed>75</speed>
                      <x>4.89145</x>
                      <y>52.37376</y>
                      <trailers>
                        <trailer>
                          <trailerId>508818951RR</trailerId>
                          <licensePlate>12-ABC-3</licensePlate>
                        </trailer>
                      </trailers>
                    </tripRealisation>
                  </realisation>
              shipments:
                summary: Minimal dataset with Trailer and Stops
                value: >-
                  <?xml version="1.0" encoding="utf-8"?>

                  <realisation
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns="http://www.simacan.com/schemas/rct/transporter/v2/realisation">
                    <tripRealisation xmlns="">
                      <tripId>123456</tripId>
                      <timestamp>2020-12-31T14:13:22.11823+01:00</timestamp>
                      <activity>RIJDEN</activity>
                      <heading>180</heading>
                      <mileage>209923.27</mileage>
                      <speed>75</speed>
                      <x>4.89145</x>
                      <y>52.37376</y>
                      <trailers>
                        <trailer>
                          <trailerId>508818951RR</trailerId>
                          <licensePlate>12-ABC-3</licensePlate>
                        </trailer>
                      </trailers>
                      <stops>
                        <stop>
                          <stopId>132733200</stopId>
                          <realisedArrival>2020-12-31T13:13:22.11823+01:00</realisedArrival>
                          <licensePlateTrailer>45-DEF-6</licensePlateTrailer>
                          <shipments>
                            <shipment>
                              <shipmentId>132733200</shipmentId>
                              <shipmentType>PICKUP</shipmentType>
                              <typeOfGoods>OVERIG</typeOfGoods>
                              <loadCarriers>
                                <loadCarrier>
                                  <loadCarrierType>MELKRIC</loadCarrierType>
                                  <quantity>25</quantity>
                                </loadCarrier>
                                <loadCarrier>
                                  <loadCarrierType>BLOK_PALLET_VOL</loadCarrierType>
                                  <quantity>25</quantity>
                                </loadCarrier>
                              </loadCarriers>
                            </shipment>
                          </shipments>
                        </stop>
                      </stops>
                    </tripRealisation>
                  </realisation>
      responses:
        '200':
          $ref: '#/components/responses/200'
        '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
  responses:
    '200':
      description: The post message has been successfully processed
      content:
        text/plain:
          schema:
            type: string
            description: success message
          examples:
            Succes message:
              summary: A success message
              value: Successfully received {messages.length} updates
    '400':
      description: >-
        The request was invalid or cannot be otherwise served. Possible causes
        are invalid XML or missing required parameters. An accompanying error
        message will explain further.
      content:
        text/plain:
          schema:
            type: string
            description: error message
            example: The body of the request could not be parsed.
    '401':
      description: Authentication credentials were missing or incorrect.
      content:
        text/plain:
          examples:
            Error notice:
              summary: An error message
              value: Not allowed to send data for carrier {carrier}
    '403':
      description: >-
        The request is understood, but it has been refused or access is not
        allowed. An accompanying error message will explain why.
    '404':
      description: >-
        The URI requested is invalid or the resource requested does not exists.
        Also returned when the requested format is not supported by the
        requested method.
  schemas:
    realisationUpdate:
      type: object
      description: ''
      properties:
        realisation:
          type: object
          xml:
            namespace: http://www.simacan.com/schemas/rct/transporter/v2/realisation
          required:
            - tripRealisation
          properties:
            tripRealisation:
              type: object
              required:
                - tripId
                - timestamp
              properties:
                tripId:
                  type: string
                  description: Unique reference for this trip
                  example: '123456'
                timestamp:
                  type: string
                  format: date-time
                  description: Timestamp when record was created
                  example: '2020-12-31T14:13:22.11823+01:00'
                activity:
                  type: string
                  description: A choice of activity
                  enum:
                    - LADEN
                    - LOSSEN
                    - WACHTEN
                    - PAUZE
                    - TANKEN
                    - WASSEN
                    - RIJDEN
                    - FILE
                    - KOPPELEN
                    - VEERBOOT
                  example: RIJDEN
                heading:
                  type: number
                  format: double
                  minimum: 0
                  maximum: 360
                  description: Amount in degrees the vehicle is heading to
                  example: '180'
                mileage:
                  type: number
                  format: double
                  minimum: 0
                  description: Mileage for the vehicle
                  example: 209923.27
                speed:
                  type: number
                  description: Speed of the vehicle in kilometers per hour
                  example: 75
                x:
                  type: number
                  format: double
                  description: X-coordinate or longitude of the vehicle
                  example: '4.89145'
                'y':
                  type: number
                  format: double
                  description: Y-coordinate or latitude of the vehicle
                  example: '52.37376'
                trailers:
                  type: array
                  items:
                    $ref: '#/components/schemas/trailer'
    trailer:
      type: object
      properties:
        trailerId:
          type: string
          description: Unique id for the trailer
          example: 508818951RR
        licensePlate:
          type: string
          description: License plate for the trailer
          example: 12-ABC-3
tags: []
security:
  - BearerAuth: []
