Skip to main content

Keyloop

Introduction​

This document describes the integration of Keyloop DMS with the platform.

Configuration at service Unit Level​

Example

"liveDiaryProvider": {
    "supplierMappingId": "digitalinnk",
    "provider": "KEYLOOP",
    "groupMappingId": "31100",
    "serviceTypeMapping": {
        "SERVICE": "bb839fac-f6a2-4b6a-9ed6-a14af0829c78",
        "MOT": "a5307eef-5a92-42cb-8117-96c7c2ecb66d",
        "REPAIR": "17d6a156-be82-4100-8a4c-544993c7df0c",
        "TYRE": "e245d957-b652-4edc-adef-23837363e828",
        "GLASS": "b05b01e6-7bfc-42e7-b468-6ab59a56a317"
    },
    "optionalServiceMapping": {
        "COLLECTION_AND_DELIVERY": "38dd929d-9d92-4267-9eb8-d1336f572e2c",
        "COURTESY_CAR": "a9bf204a-6035-45f5-8be7-8bc66091b514",
        "WHILE_YOU_WAIT": "4e7f2880-afd7-4d65-b10e-3320b52de4df"
    }
}

Important: supplierMappingId, groupMappingId, serviceTypeMapping, and optionalServiceMapping will change depending on the supplier, these will be provided by Keyloop.

These mappings translate between internal service types and Keyloop DMS-specific identifiers.

Authentication​

To access Keyloop APIs, you must obtain an access token using your client credentials. The authentication process is as follows:

Obtaining an Access Token​

Send a POST request to the Keyloop authentication endpoint with client credentials (client_id and client_secret)

POST {{baseUrl}}/oauth/client_credential/accesstoken
headers:
    Authorization: Basic base64(client_id:client_secret)

Keyloop Client Credentials are stored in Google Secret Manager.

Using the Access Token​

We include the access token in the Authorization header for all API requests.

Refer to the Keyloop Developer Docs for more details.

Fetching Available Time Slots​

Endpoint:

POST {{baseUrl}}/appointment/{{groupMappingId}}/{{supplierMappingId}}/v1/appointments/availability

This endpoint is used to fetch available appointment slots for a given date. Required parameters include enterpriseId, storeId, and the date, and service Product(service type) is provided as the payload.

Steps:

  1. User selects a supplier with Keyloop DMS in the UI
  2. ViSN Web UI sends a request to Callables to get available dates and their slots
  3. Callables requests an access token from Keyloop DMS
  4. Keyloop DMS responds with the access token
  5. Callables requests appointment availability dates and slots from Keyloop DMS
  6. Keyloop DMS returns the available dates and time slots
  7. Callables formats the availability data
  8. The formatted available dates and slots are returned to the ViSN Web UI
  9. User sees the available dates and time slots displayed for the selected date

Creating an Appointment​

Endpoint:

POST {{baseUrl}}/appointment/{{groupMappingId}}/{{supplierMappingId}}/v1/appointments

This endpoint is used to create a new appointment in Keyloop DMS. The request body should include all required appointment details.

Steps:

  1. After selecting a time slot and filling all the required details in the UI to create a booking, when we click on "Submit"
  2. A request is sent to Callables with all the details
  3. A request is made to keyloop to get access token
  4. Next a request is made to keyloop to create an appointment with all the details
  5. Keyloop responds with a confirmation of the appointment created
  6. Then a enquiry is created in Visn
  7. If after a receiving a successful response from keyloop to create an appointment, if there is any error while creating an enquiry in Visn, a request is made to keyloop to cancel the appointment that was created in the previous step
  8. An error is shown in the UI if the booking fails

Cancelling an appointment​

Endpoint:

DELETE {{baseUrl}}/appointment/{{groupMappingId}}/{{supplierMappingId}}/v1/appointments/{{appointmentId}}

Cancellation Scenarios​

Cancellation of a booking in Keyloop DMS can occur in the following scenarios:

  1. Technical Failure After DMS Booking:

    • When a booking is created successfully in DMS, but the subsequent enquiry creation in ViSN fails due to a technical issue, the system automatically cancels the booking in DMS to maintain consistency.

  2. User-Initiated Cancellation in ViSN:

    • When a customer user cancels the booking from the ViSN platform for any reason, the system sends a cancellation request to Keyloop DMS to remove the booking.

  3. Rearranging a Booking Date:

    • When a customer user wants to rearrange (reschedule) the booking date, the original booking in DMS is cancelled, and a new booking is created in ViSN with the updated date.

This endpoint is used to cancel an existing appointment in Keyloop DMS. You must provide the appointmentId of the appointment to be cancelled.

References​

Status: Accepted
Category: Protected
Authored By: Gladson on Oct 14, 2025
Revisions