openapi: 3.1.0
info:
  title: Jigcar Public APIs
  description: Public APIs for interacting with Jigcar
  version: 1.0.0-alpha
  contact:
    email: engineering@jigcar.com
    url: https://jigcar.com/
  license:
    name: MIT
    url: https://opensource.org/license/mit/
servers:
  - url: https://public-api.jigcar.com/v1
paths:
  /movement-requests/create-in-planning-pool:
    post:
      summary: Create vehicle movement request
      description: >-
        Creates a movement request for the provided vehicle and sends it to an
        internal planning pool
      operationId: createVehicleMovementRequestInPlanningPool
      tags:
        - Movement Requests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVehicleMovementRequestBody'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehicleMovementRequest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
  /movement-requests/{requestId}:
    get:
      summary: Get vehicle movement request
      parameters:
        - $ref: '#/components/parameters/RequestId'
      description: Retrieves the current state of a vehicle movement request by id
      operationId: getVehicleMovementRequestById
      tags:
        - Movement Requests
      responses:
        '200':
          description: Vehicle movement request retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehicleMovementRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFailure500Response'
    patch:
      summary: Update vehicle movement request
      parameters:
        - $ref: '#/components/parameters/RequestId'
      description: >-
        Updates specific details of a vehicle movement request by id. Omitting a
        property will leave it unchanged.
      operationId: updateVehicleMovementRequestById
      tags:
        - Movement Requests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVehicleMovementRequestBody'
      responses:
        '200':
          description: Vehicle movement request updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehicleMovementRequest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFailure500Response'
  /infrastructure/sites:
    get:
      summary: Get all sites
      description: Retrieves all dealership locations stored within Jigcar
      operationId: getAllSites
      tags:
        - Infrastructure
      responses:
        '200':
          description: All sites retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Site'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiFailure500Response'
components:
  schemas:
    ApiFailure500Response:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - INTERNAL_SERVER_ERROR
        message:
          type: string
          example: >-
            We encountered an unexpected error trying to service your request.
            Please try again later.
    Address:
      type: object
      required:
        - line1
        - postcode
      properties:
        line1:
          type: string
          description: 1st line of the address
          example: 123 Main St
        line2:
          type: string
          description: 2nd line of the address
        line3:
          type: string
          description: 3rd line of the address
        postcode:
          type: string
          description: Postal code of the addres
          example: GU1 4UT
    Site:
      type: object
      properties:
        id:
          readOnly: true
          type: string
          example: some-site-id
          description: The identifier for the site
        externalId:
          readOnly: true
          type: string
          example: some-external-id
          description: The external identifer for the site
        label:
          readOnly: true
          type: string
          example: Kingston Audi
          description: The label for the site
        address:
          readOnly: true
          $ref: '#/components/schemas/Address'
    Vehicle:
      type: object
      properties:
        vin:
          type: string
          description: The chassis number of the vehicle
        vrm:
          type: string
          description: The car reg of the vehicle
        make:
          type: string
          description: The make of the vehicle
          example: Mercedes-Benz
        model:
          type: string
          description: The model of the vehicle
          example: A-Class
        modelVariant:
          description: the extended description of the vehicle
          example: A 180 AMG Line Executive Hatchback
          type: string
    Timeslot:
      type: string
      example: AM
      enum:
        - ANYTIME
        - AM
        - PM
    VehicleMovementRequestStatus:
      type: string
      example: IN_PROGRESS
      enum:
        - CREATED
        - SENT_TO_DRIVER
        - SENT_TO_3PL
        - SENT_TO_MARKETPLACE
        - SENT_TO_MULTIPLE_DRIVERS
        - ACCEPTED
        - ACCEPTED_SENT_TO_DRIVER
        - ACCEPTED_SENT_TO_3PL
        - ACCEPTED_SENT_TO_MARKETPLACE
        - PARTIALLY_PLANNED
        - PLANNED
        - IN_PROGRESS
        - DELIVERED
        - ABORTED
    TransportMethod:
      type: string
      example: DRIVEN
      enum:
        - DRIVEN
        - TRANSPORTED
    BusinessArea:
      type: string
      example: Retail
      enum:
        - Retail
        - Fleet
    InternalLocation:
      type: object
      required:
        - type
        - siteId
      properties:
        type:
          type: string
          enum:
            - INTERNAL
        siteId:
          type: string
          example: some-site-id
    ExternalLocation:
      type: object
      required:
        - type
        - address
        - contactDetails
      properties:
        type:
          type: string
          enum:
            - EXTERNAL
        externalLocationType:
          type: string
          description: >-
            whether the external location is a customers address or external
            organisation location
          enum:
            - CUSTOMER
            - ORGANISATION
        address:
          $ref: '#/components/schemas/Address'
        contactDetails:
          type: object
          required:
            - name
            - phoneNumber
          properties:
            name:
              type: string
              description: The location contacts name
            phoneNumber:
              type: string
              description: the location contacts phone number
    DriverProvider:
      type: object
      required:
        - type
        - id
        - firstname
        - surname
      properties:
        type:
          type: string
          enum:
            - DRIVER
        id:
          type: string
          example: some-driver-id
          description: The driver's id
        firstname:
          type: string
          description: The driver's first name
          example: John
        surname:
          type: string
          description: The driver's surname
          example: Wick
    ThirdPartyLogisticsProvider:
      type: object
      required:
        - type
        - id
        - name
        - primaryContactInformation
      properties:
        type:
          type: string
          enum:
            - THIRD_PARTY_LOGISTICS
        id:
          type: string
          example: some-third-party-id
          description: The logistic providers id
        name:
          type: string
          description: The logistics providers name
          example: ACME Ltd
        primaryContactInformation:
          type: object
          required:
            - name
            - email
          properties:
            name:
              type: string
              description: The primary contacts name
              example: Jane Doe
            email:
              type: string
              description: The primary contacts email address
              example: jane.doe@acme.com
    MarketplaceProvider:
      type: object
      required:
        - type
        - name
        - externalId
      properties:
        type:
          type: string
          enum:
            - MARKETPLACE
        name:
          type: string
          description: The marketplace provider name
          example: ACME Marketplace
        externalId:
          type: string
          description: >-
            The external identifier for the movement with the marketplace
            provider
          example: some-external-id
    Date:
      type: string
      format: date
      example: '2023-10-29'
    DateTime:
      type: string
      format: datetime
      example: '2025-07-01T09:00:00.000Z'
    Email:
      description: An email address
      type: string
      format: email
      example: jigcar@example.com
    Error:
      type: object
      properties:
        code:
          type: string
          example: INVALID_VRM
          description: Machine-readable error code
        message:
          type: string
          example: The provided VRM is invalid
          description: Human-readable error message
    NotFoundError:
      type: object
      properties:
        code:
          type: string
          example: VEHICLE_MOVEMENT_REQUEST_NOT_FOUND
          description: Machine-readable error code
        message:
          type: string
          example: A vehicle movement request with the provided ID cannot be found
          description: Human-readable error message
    OriginForCreate:
      description: The origin of the movement request
      type: object
      required:
        - location
        - readyToCollectFromTimeslot
        - readyToCollectFromDate
      properties:
        location:
          description: The location the vehicle should be collected from
          oneOf:
            - $ref: '#/components/schemas/InternalLocation'
            - $ref: '#/components/schemas/ExternalLocation'
        readyToCollectFromTimeslot:
          description: The time of day the vehicle should be collected on
          $ref: '#/components/schemas/Timeslot'
        readyToCollectFromDate:
          description: The date the vehicle can be collected from
          $ref: '#/components/schemas/Date'
    OriginForUpdate:
      description: The origin of the movement request
      type: object
      properties:
        location:
          description: The location the vehicle should be collected from
          oneOf:
            - $ref: '#/components/schemas/InternalLocation'
            - $ref: '#/components/schemas/ExternalLocation'
        readyToCollectFromTimeslot:
          description: The time of day the vehicle should be collected on
          $ref: '#/components/schemas/Timeslot'
        readyToCollectFromDate:
          description: The date the vehicle can be collected from
          $ref: '#/components/schemas/Date'
    DestinationForCreate:
      description: The destination of the movement request
      type: object
      required:
        - location
        - deliveryByTimeslot
        - deliveryByDate
      properties:
        location:
          description: The location the vehicle should be delivered to
          oneOf:
            - $ref: '#/components/schemas/InternalLocation'
            - $ref: '#/components/schemas/ExternalLocation'
        deliveryByTimeslot:
          description: The time of day the vehicle should be delivered on
          $ref: '#/components/schemas/Timeslot'
        deliveryByDate:
          description: The date the vehicle should be delivered by
          $ref: '#/components/schemas/Date'
        deliverOnSpecifiedDate:
          description: >-
            Whether the vehicle should be delivered on the specified date.
            Defaults to false.
          type: boolean
    DestinationForUpdate:
      description: The destination of the movement request
      type: object
      properties:
        location:
          description: The location the vehicle should be delivered to
          oneOf:
            - $ref: '#/components/schemas/InternalLocation'
            - $ref: '#/components/schemas/ExternalLocation'
        deliveryByTimeslot:
          description: The time of day the vehicle should be delivered on
          $ref: '#/components/schemas/Timeslot'
        deliveryByDate:
          description: The date the vehicle should be delivered by
          $ref: '#/components/schemas/Date'
        deliverOnSpecifiedDate:
          description: Whether the vehicle should be delivered on the specified date.
          type: boolean
    CreateVehicleMovementRequestBody:
      type: object
      required:
        - vehicle
        - origin
        - destination
        - businessArea
        - transportMethod
      properties:
        vehicle:
          $ref: '#/components/schemas/Vehicle'
        origin:
          $ref: '#/components/schemas/OriginForCreate'
        destination:
          $ref: '#/components/schemas/DestinationForCreate'
        businessArea:
          $ref: '#/components/schemas/BusinessArea'
        notes:
          type: string
          example: Talk to Kevin for keys
          description: Any important notes relating to the movement request
        externalId:
          type: string
          example: some-external-identifier
          description: Any external identifier you want to link with this movement request
        moDelInformation:
          type: object
          description: Key information for linking a Jigcar movement request to a MoDel job
          required:
            - pin
          properties:
            pin:
              type: string
              description: the associated MoDel job pin
              example: some-model-pin
        transportMethod:
          $ref: '#/components/schemas/TransportMethod'
    UpdateVehicleMovementRequestBody:
      type: object
      properties:
        origin:
          $ref: '#/components/schemas/OriginForUpdate'
        destination:
          $ref: '#/components/schemas/DestinationForUpdate'
        notes:
          type: string
          example: I left snacks in the glove compartment
          description: Any important notes relating to the movement request
    VehicleMovementRequest:
      type: object
      required:
        - id
        - vehicle
        - origin
        - destination
        - status
        - businessArea
        - transportMethod
      properties:
        id:
          type: string
          format: ulid
          example: 01K4NNVBR6J323BY6X26J62WA5
          description: The identifier for the vehicle movement request
        vehicle:
          $ref: '#/components/schemas/Vehicle'
        origin:
          allOf:
            - $ref: '#/components/schemas/OriginForCreate'
            - type: object
              properties:
                estimatedCollectionTimeslot:
                  description: The estimated collection timeslot for the vehicle
                  $ref: '#/components/schemas/Timeslot'
                estimatedCollectionDate:
                  description: The estimated collection date for the vehicle
                  $ref: '#/components/schemas/Date'
        destination:
          allOf:
            - $ref: '#/components/schemas/DestinationForCreate'
            - type: object
              properties:
                estimatedDeliveryTimeslot:
                  description: The estimated delivery timeslot for the vehicle
                  $ref: '#/components/schemas/Timeslot'
                estimatedDeliveryDate:
                  description: The estimated delivery date for the vehicle
                  $ref: '#/components/schemas/Date'
        status:
          description: The status of the movement request
          $ref: '#/components/schemas/VehicleMovementRequestStatus'
        completedOn:
          description: The date that the movement request was completed, if applicable
          $ref: '#/components/schemas/DateTime'
        businessArea:
          $ref: '#/components/schemas/BusinessArea'
        notes:
          type: string
          example: Talk to Kevin for keys
          description: Any important notes relating to the movement request
        externalId:
          type: string
          example: some-external-identifier
          description: Any external identifier you want to link with this movement request
        moDelInformation:
          type: object
          description: Key information for linking a Jigcar movement request to a MoDel job
          required:
            - pin
          properties:
            pin:
              type: string
              description: the associated MoDel job pin
              example: some-model-pin
        transportMethod:
          $ref: '#/components/schemas/TransportMethod'
        provider:
          oneOf:
            - $ref: '#/components/schemas/DriverProvider'
            - $ref: '#/components/schemas/ThirdPartyLogisticsProvider'
            - $ref: '#/components/schemas/MarketplaceProvider'
  securitySchemes:
    JigcarAPIAuth:
      type: apiKey
      in: header
      name: X-Jigcar-API-Key
  parameters:
    RequestId:
      name: requestId
      in: path
      description: Identifier for a movement request
      required: true
      schema:
        type: string
        format: ulid
        example: 01K4NNVBR6J323BY6X26J62WA5
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
    Unauthorized:
      description: Unauthorized.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
tags:
  - name: Movement Requests
    description: Endpoints for creating/retrieving Jigcar movement requests
  - name: Infrastructure
    description: Endpoints for retrieving Logistics specific infrastructure within Jigcar
security:
  - JigcarAPIAuth: []
