openapi: 3.0.0
info:
  title: Carrier Planning API
  version: '5.1'
  description: >-
    The Carrier Planning API enables you to update a part of the transport
    planning for a trip and add optional eCMR delegation
servers:
  - url: https://sct-web-api-prod.simacan.com/api/public
    description: Production Environment
  - url: https://sct-web-api-stg.simacan.com/api/public
    description: Staging Environment
paths:
  /{shipper_code}/transporter/v3/{carrier_code}/planning:
    post:
      summary: Planning update
      description: >-
        The planning endpoint enables you to update the transport planning for a
        trip and add optional eCMR delegation.


        An important notice: all data in the message will be visible to all
        parties with access to the planning of the specific trip
      operationId: setPlanningUpdate
      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: >-
          For the `ecmrDelegate` field, the subaccount value should be equal to
          the formatting as known at the e-CMR-provider. Any updates to the
          field, will revoke the previous assigned subaccount delegations by
          Simacan.


          When the `ecmrDelegate` value is left empty or is absent, we will try
          to delegate based on `licensePlateTractor`, however we prefer that you
          explicit fill the value for `ecmrDelegate`.


          &nbsp;
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/planningUpdate'
            examples:
              with customer data:
                summary: With customer data
                value: >-
                  <?xml version="1.0" encoding="UTF-8" ?>

                  <tripPlanning
                  xmlns="http://www.simacan.com/schemas/rct/transporter/v3/planning">
                      <tripId>800099</tripId>
                      <timestamp>2023-10-31T04:43:00.000+02:00</timestamp>
                      <driver>William de Vries</driver>
                      <fuelType>EURO_6_DIESEL</fuelType>
                      <licensePlateTractor>TE-ST-02</licensePlateTractor>
                      <tractorType>TREKKER</tractorType>
                      <customer>peterson</customer>
                      <subcontractor>jansson</subcontractor>
                      <trailers>
                          <trailer>
                              <trailerId>KDZ-Opl1</trailerId>
                              <licensePlate>KDZ-Opl1</licensePlate>
                              <trailerType>EURO_13_60_KOEL</trailerType>
                          </trailer>
                          <trailer>
                              <trailerId>KDZ-Opl2</trailerId>
                              <licensePlate>KDZ-Opl2</licensePlate>
                              <trailerType>EURO_13_60_KOEL</trailerType>
                          </trailer>
                      </trailers>
                      <customerData>
                          <customerDataItem>
                              <name>Plan Group</name>
                              <value>Fast Moving</value>
                          </customerDataItem>
                      </customerData>
                  </tripPlanning>
              eCMR:
                summary: With eCMR delegate
                value: >-
                  <?xml version="1.0" encoding="UTF-8" ?>

                  <tripPlanning
                  xmlns="http://www.simacan.com/schemas/rct/transporter/v3/planning">
                      <tripId>800099</tripId>
                      <timestamp>2023-10-31T04:43:00.000+02:00</timestamp>
                      <driver>William de Vries</driver>
                      <fuelType>EURO_6_DIESEL</fuelType>
                      <licensePlateTractor>TE-ST-02</licensePlateTractor>
                      <tractorType>TREKKER</tractorType>
                      <customer>peterson</customer>
                      <subcontractor>jansson</subcontractor>
                      <trailers>
                          <trailer>
                              <trailerId>KDZ-Opl1</trailerId>
                              <licensePlate>KDZ-Opl1</licensePlate>
                              <trailerType>EURO_13_60_KOEL</trailerType>
                          </trailer>
                          <trailer>
                              <trailerId>KDZ-Opl2</trailerId>
                              <licensePlate>KDZ-Opl2</licensePlate>
                              <trailerType>EURO_13_60_KOEL</trailerType>
                          </trailer>
                      </trailers>
                      <ecmrDelegate>subaccountName</ecmrDelegate>
                  </tripPlanning>
              no-eCMR:
                summary: Without eCMR delegate
                value: >-
                  <?xml version="1.0" encoding="UTF-8" ?>

                  <tripPlanning
                  xmlns="http://www.simacan.com/schemas/rct/transporter/v3/planning">
                      <tripId>800099</tripId>
                      <timestamp>2023-10-31T04:43:00.000+02:00</timestamp>
                      <driver>William de Vries</driver>
                      <fuelType>EURO_6_DIESEL</fuelType>
                      <licensePlateTractor>TE-ST-02</licensePlateTractor>
                      <tractorType>TREKKER</tractorType>
                      <customer>peterson</customer>
                      <subcontractor>jansson</subcontractor>
                      <trailers>
                          <trailer>
                              <trailerId>KDZ-Opl1</trailerId>
                              <licensePlate>KDZ-Opl1</licensePlate>
                              <trailerType>EURO_13_60_KOEL</trailerType>
                          </trailer>
                          <trailer>
                              <trailerId>KDZ-Opl2</trailerId>
                              <licensePlate>KDZ-Opl2</licensePlate>
                              <trailerType>EURO_13_60_KOEL</trailerType>
                          </trailer>
                      </trailers>
                  </tripPlanning>
      responses:
        '204':
          description: The post message was successfully processed.
        '400':
          description: >-
            The request was invalid or cannot be otherwise served. Possible
            causes are invalid XML or invalid parameters. An accompanying error
            message will explain further.
        '401':
          description: The request was not accompanied by valid credentials
          headers:
            WWW-Authenticate:
              schema:
                type: string
              description: Bearer realm="simacan_transport_cloud", error="invalid_token"
        '404':
          description: >-
            Either the trip, carrier or shipper could not be found in our
            platform.
          content:
            application/problem+json:
              schema:
                example:
                  detail: Entity of type shipper was not found for `unknown_shipper'.
                  title: notFound
                  entity: shipper
                  status: 404
                allOf:
                  - $ref: '#/components/schemas/notFound'
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:
    notFound:
      type: object
      properties:
        title:
          type: string
          enum:
            - notFound
        status:
          type: integer
          format: int32
          enum:
            - 404
        entity:
          type: string
          enum:
            - trip
            - carrier
            - shipper
        detail:
          type: string
      required:
        - title
        - status
        - entity
        - detail
    planningUpdate:
      type: object
      description: ''
      properties:
        planning:
          type: object
          xml:
            namespace: http://www.simacan.com/schemas/rct/transporter/v3/planning
          required:
            - tripId
            - timestamp
            - fuelType
            - licensePlateTractor
            - tractorType
            - customer
          properties:
            tripId:
              type: string
              description: Unique reference for this trip
              example: '800099'
            timestamp:
              type: string
              format: date-time
              description: Timestamp when record was created
              example: '2014-08-13T12:20:00+02:00'
            driver:
              type: string
              description: >-
                Driver name.<br>***Important:*** Visible to all parties with
                access to the planning of the specific trip
              example: William de Vries
            fuelType:
              type: string
              description: A choice of fuelType
              enum:
                - EURO_5_DIESEL
                - EURO_5_DIESEL_EEV
                - EURO_6_DIESEL
                - HYBRIDE_DIESEL_EURO_5
                - HYBRIDE_DIESEL_EURO_6
                - CNG
                - LNG
                - LBM
                - CBG
                - EV
                - DUAL_FUEL_LNG_DIESEL
                - DUAL_FUEL_CNG_DIESEL
                - DUAL_FUEL_LBM_DIESEL
                - DUAL_FUEL_CBG_DIESEL
              example: EURO_6_DIESEL
            licensePlateTractor:
              type: string
              description: License plate for the tractor
              example: TE-ST-02
            tractorType:
              type: string
              description: The specific type of tractor
              enum:
                - BAKWAGEN
                - BAKWAGEN_KOEL
                - BAKWAGEN_KOEL_COMBI
                - BAKWAGEN_KLEIN
                - BAKWAGEN_KLEIN_KOEL
                - BAKWAGEN_KLEIN_KOEL_COMBI
                - TREKKER
            customer:
              type: string
              description: Specify for which customer is being driven
              example: peterson
            subcontractor:
              type: string
              description: >-
                Name of the subcontractor. By using this optional field, the
                trip is subcontracted/chartered to another carrier. The
                subcontractor is then enabled to send in data for this trip and
                see it in control tower
              example: jansson
            trailers:
              type: array
              items:
                $ref: '#/components/schemas/trailer'
            phoneNumber:
              type: string
              description: The phone number of the driver
              example: '+31612345678'
            ecmrDelegate:
              type: string
              description: Exact subaccountname as used in TransFollow portal
              example: subaccount
            customerData:
              type: array
              items:
                $ref: '#/components/schemas/customerDataItem'
    customerDataItem:
      type: object
      description: Any custom datafields that the carrier might like to add
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: |-
            The name or key for the custom field
            For example: `Plan Group`
          example: Business Unit
        value:
          type: string
          description: |-
            The value for the custom field
            For example: `Fast moving`
          example: Any
    trailer:
      type: object
      required:
        - trailerId
        - licensePlate
        - trailerType
      properties:
        trailerId:
          type: string
          description: Unique id for the trailer
          example: KDZ-Opl1
        licensePlate:
          type: string
          description: License plate for the trailer
          example: KDZ-Opl1
        trailerType:
          type: string
          description: The specific type of trailer
          example: EURO_13_60_KOEL
          enum:
            - BAKWAGEN
            - BAKWAGEN_KOEL
            - BAKWAGEN_KOEL_COMBI
            - BAKWAGEN_KLEIN
            - BAKWAGEN_KLEIN_KOEL
            - BAKWAGEN_KLEIN_KOEL_COMBI
            - CITY_8_00
            - CITY_8_00_KOEL
            - CITY_8_00_KOEL_COMBI
            - CITY_9_80
            - CITY_9_80_KOEL
            - CITY_9_80_KOEL_COMBI
            - CITY_10_50
            - CITY_10_50_KOEL
            - CITY_10_50_KOEL_COMBI
            - CITY_11_20
            - CITY_11_20_KOEL
            - CITY_11_20_KOEL_COMBI
            - CITY_11_60
            - CITY_11_60_KOEL
            - CITY_11_60_KOEL_COMBI
            - EURO_13_60
            - EURO_13_60_KOEL
            - EURO_13_60_KOEL_COMBI
            - KORTE_CITY_8_85
            - KORTE_CITY_8_85_KOEL
            - KORTE_CITY_8_85_KOEL_COMBI
            - TREKKER
tags: []
security:
  - BearerAuth: []
