openapi: 3.0.0
info:
  title: Theft Case Portal API
  description: API for managing theft cases for 3rd party tracking providers.
  version: 1.0.0
servers:
  - url: https://integrations.theftcases.tech/theft/{integrator}/v1
    description: Production
    variables:
      integrator:
        default: integrator_name
        description: The name of the integrator
  - url: https://integrations.staging.theftcases.tech/theft/{integrator}/v1
    description: Staging
    variables:
      integrator:
        default: integrator_name
        description: The name of the integrator

paths:
  /createTheftCase:
    post:
      summary: Create a new theft case
      description: |
        Allow an external party to create a new theft case in the theft case portal.
        
        **Validations:**
        1. The `integrator` route parameter is used to validate if the client has permission to create a theft case for that integrator.
        2. The device and theft case will be created under the integrator's organization.
        3. Object validation on the request body.

        **Webhook:**

        Every theft case can have a notification webhook URL. When a Theft Case has been resolved, the URL will be called with a POST-request containing all relevant data of the Theft Case. 

        When the webhook endpoint responds with a 420, 429 or 5xx, the webhook will be retried with a backoff strategy. Any other non-2xx status code will cause the webhook request to fail.

        The webhook will be retried with a 2* multiplying backoff strategy. Every subsequent failure will be retried with a twice as long delay as the previous one.
        The maximum retry delay is 18 hours.

        **Webhook request body example:**
        ```
        {
          "theft_case_id": <case_id>,
          "theft_case_name": "<case_name>",
          "status": {
            "major":"found", //one of ["found", "not_found", "cancelled"]
            "minor":"" //optional string with extra details
          },
          "resolved_at": <ISO8601>
        }
        ```
      operationId: createTheftCase
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - theft_case_details
                - device_type
              properties:
                webhook_url:
                  type: string
                  format: uri
                  example: https://example.com/webhook/caseid
                theft_case_details:
                  type: object
                  required:
                    - device_id
                    - vehicle_characteristics
                    - insurance
                    - contact_info
                  properties:
                    device_id:
                      type: string
                      description: |
                        Identifier for the device/vehicle that is unique in your entire system. 
                        
                        This ID must remain the same across all cases created for the same vehicle.
                      example: '3822a2fe-3b3e-4dc7-b3ad-ab91eaef1128'
                    vehicle_characteristics:
                      allOf:
                        - $ref: '#/components/schemas/vehicleCharacteristics'
                        - type: array
                          items:
                            required:
                              - vehicle_id
                              - make

                    insurance:
                      type: object
                      required:
                        - insurer
                      properties:
                        insurer:
                          type: string
                          example: enra
                        policy_number:
                          type: string
                          description: identifier for the insurance policy
                          example: 18619034
                    contact_info:
                      type: object
                      required:
                        - phone
                      properties:
                        phone:
                          type: string
                          description: telephone number to contact the user on
                          format: E.123
                          nullable: true
                          examples:
                            - "+22 607 123 4567"
                            - "+22 6071234567"
                device_type:
                  type: string
                  description: |
                    A device type is used to differentiate between different devices and their capabilities. 

                    This provides context for the Theft Case Portal to show specific information based on device functionality.

                    For instance; if a device supports WiFi-localisation, the Theft Case Portal will show contextual information based on the presence of WiFi related data.
                    
                    These device types will be pre-determined.
                  example: '{integrator}:2'
      responses:
        '201':
          description: Theft case created
          content:
            application/json:
              schema:
                type: object
                properties:
                  theft_case_id:
                    type: string
                  theft_case_name:
                    type: string
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      security:
        - Basic: []
  /theft-case/{id}/telemetry:
    post:
      summary: Publish device telemetry to a theft case
      description: |
        Allow an external party to publish device telemetry to a specific theft case.
        **Validations:**
        1. Validate if the client has permission to publish telemetry for the theft case.
        2. Validate if the theft case is still unresolved.
        3. Validate if the published device telemetry's date time is not older than 31 days before theft case creation.
      operationId: publishTelemetry
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Telemetry'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '429':
          description: Too Many Requests. Rate limit of 600 requests per minute
      security:
        - Basic: []
  /theft-case/{id}:
    patch:
      summary: Modify a theft case
      description: |
        Allow an external party to modify a theft case's details.
        **Validations:**
        1. Validate if the client has permission to modify the theft case.
        2. Validate if the theft case is still unresolved.
        3. Object validation on the request body.

        Vehicle characteristics will be overriden on its fieldname. Any existing characteristics-fields that are not present in this request are kept
      operationId: modifyTheftCase
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                police_report_number:
                  type: string
                vehicle_characteristics:
                  $ref: '#/components/schemas/vehicleCharacteristics'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  theft_case_id:
                    type: string
                  theft_case_name:
                    type: string
                  status:
                    type: object
                    properties:
                      major:
                        type: string
                      minor:
                        type: string
                      resolved_at:
                        type: string
                        format: date-time
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
        - Basic: []
    delete:
      summary: Cancel a theft case
      description: |
        Allow an external party to cancel a theft case
        **Validations:**
        1. Validate if the client has permission to modify the theft case.
        2. Validate if the theft case is still unresolved.
      operationId: cancelTheftCase
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: OK
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
        - Basic: []
    get:
      summary: Request a theft case's details
      description: |
        Allow an external party to request a theft case's details.
        **Validations:**
        1. Validate if the client has permission to request the theft case details.
      operationId: getTheftCase
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  theft_case_id:
                    type: string
                  theft_case_name:
                    type: string
                  status:
                    type: object
                    properties:
                      major:
                        type: string
                      minor:
                        type: string
                      resolved_at:
                        type: string
                        format: date-time
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
      security:
        - Basic: []
components:
  securitySchemes:
    Basic:
      name: Basic auth
      type: http
      scheme: basic
      description: client-id/secret as username/password
  schemas:
    vehicleCharacteristics:
      type: array
      description: list of characteristics of the vehicle. Free form and formatted as key=[value]. Only some fields are required, all other fields listed in these docs are highly recommended. Feel free to add more characteristics
      items:
        type: object
        properties:
          vehicle_id:
            type: array
            description: VIN or frame number of the vehicle. Also used to retrieve/validate insurance info if possible
            items:
              type: string
              example: QW18175923
          license_plate:
            type: array
            description: License plate of the vehicle if applicable
            items:
              type: string
              example: DE-123-AA
          make:
            type: array
            description: Brand name of the vehicle. Also used to retrieve/validate insurance info if possible
            items:
              type: string
              example: Qwic
          model:
            type: array
            description: Model name of the vehicle
            items:
              type: string
              example: F7012Z
          vehicle_name:
            type: array
            description: Any given name of the vehicle, could be the make and model concatenated
            items:
              type: string
              example: Qwic F7012Z (QW18175923)
          color:
            type: array
            description: US English name of the primary color of the vehicle
            items:
              type: string
              example: Black
    Telemetry:
      type: object
      required:
        - dtd
        - tracker
        -
      properties:
        dtd:
          type: string
          format: date-time
          example: 2019-01-25T12:47:22Z
        event:
          type: object
          properties:
            dte:
              type: string
              format: date-time
              example: 2019-01-25T12:47:22Z
            key:
              type: string
              example: ride_start
        tracker:
          type: object
          required:
            - loc
          properties:
            loc:
              type: object
              required:
                - geo
                - sp
              properties:
                dtg:
                  type: string
                  format: date-time
                  description: date of gps fix
                  example: 2019-01-25T12:47:22Z
                alt:
                  type: integer
                  format: int32
                  description: altitude in meters
                  example: 39
                ang:
                  type: integer
                  description: angle
                  format: int32
                  example: 54
                hdop:
                  type: integer
                  format: int32
                  description: HDOP value of gps accuracy
                  example: 1
                sp:
                  type: integer
                  format: int32
                  example: 12
                  description: speed in km/h
                geo:
                  type: object
                  description: geopoint
                  required:
                    - coordinates
                    - type
                  properties:
                    coordinates:
                      type: array
                      example:
                        [4.894409179687499,52.373922404495474]
                    type:
                      type: string
                      example: Point
            gsm:
              type: object
              properties:
                cid:
                  type: integer
                  format: int32
                  example: 4651
                  description: cell tower ID
                lac:
                  type: integer
                  format: int32
                  example: 10173
                mcc:
                  type: integer
                  format: int32
                  example: 460
                mnc:
                  type: integer
                  format: int32
                  example: 0
            metric:
              type: object
              properties:
                bbatp:
                  type: integer
                  format: int32
                  example: 99
            config:
              type: object
              properties:
                blename:
                  type: string
                  example: CK300-20A6C123
                blemac:
                  type: string
                  example: 20:a6:c1:23:45:67
            wifi:
              type: object
              properties:
                mac_1:
                  type: string
                  example: 2e:d1:c6:4f:9d:9c
                rssi_1:
                  type: integer
                  format: int32
                  example: -52
                mac_2:
                  type: string
                  example: 7c:39:53:a2:3b:43
                rssi_2:
                  type: integer
                  format: int32
                  example: -73
                mac_3:
                  type: string
                  example: 34:12:98:04:9f:48
                rssi_3:
                  type: integer
                  format: int32
                  example: -79
                mac_4:
                  type: string
                  example: b4:18:d1:df:f1:96
                rssi_4:
                  type: integer
                  format: int32
                  example: -81
                mac_5:
                  type: string
                  example: c6:18:d1:df:f1:96
                rssi_5:
                  type: integer
                  format: int32
                  example: -81
        device:
          type: object
          properties:
            metric:
              type: object
              properties:
                bsocp:
                  type: integer
                  format: int32
                  example: 90
                deculock:
                  type: boolean
                dodom:
                  type: integer
                  format: int32
                  example: 8400
                drange:
                  type: integer
                  format: int32
                  example: 90
                dstatus:
                  type: boolean
                charging:
                  type: boolean
