DealerFX

Spec for Steamops team to takeover DealerFX

Notes:

• Currently uses in-memory API token - we recommend storing this in an external DB

We recommned using a Redis cache to maintain a mapping of integration to current working access token that will be refreshed as needed (on an instance of a 400 response, for example, with retry mechanism).

Deliverable

The deliverable we require is a low latency API with the following endpoints:

• GET /lookup_customer
  • Returns customer details such as name, vehicle information, and appointment history.
• POST /create_account (if an account is required to book an appointment or doesn't happen during appointment booking)
• GET /get_availability
  • Returns availability for a given time range given time, vehicle, and opcodes. Should return availability data in an LLM friendly format (ie. {"available_times": "Friday, February 4th at 10am"}

Parameter	Type	Required	Description
opCodes	string or array	Yes	Comma-separated op codes or array
transportationType	string	Yes	Type of transportation
startDate	string	Yes	Start date for availability search (YYYY-MM-DD or ISO)
endDate	string	Yes	End date for availability search (YYYY-MM-DD or ISO)
firstName	string	No	Customer's first name
lastName	string	No	Customer's last name
phoneNumber	string	No	Customer's phone number
advisorId	string	No	Service advisor ID
vehicle	object	No	Vehicle info (defaults to dealership default)
vehicle.make	string	No	Vehicle make
vehicle.model	string	No	Vehicle model
vehicle.year	string	No	Vehicle year (defaults to "2023")

---

• POST /book_appointment

Parameter	Type	Required	Description
opCodes	string or array	Yes	Comma-separated op codes (e.g., "OIL,TIRE") or array of op codes
transportationType	string	Yes	Type of transportation (e.g., "WAITER")
dateTime	string	Yes	Appointment datetime (ISO format)
dealerId	string	No	Dealer ID (usually retrieved from path)
firstName	string	No	Customer's first name (can be looked up from existing customer)
lastName	string	No	Customer's last name (can be looked up from existing customer)
comment	string	No	Additional comment for the appointment
phoneNumber	string	Yes	Customer's phone number (used for customer lookup)
email	string	No	Customer's email
vehicle	object	No	Vehicle info (defaults to dealership default)
vehicle.make	string	No	Vehicle make
vehicle.model	string	No	Vehicle model
vehicle.year	string	No	Vehicle year (defaults to "2023")
appointmentId	number	No	Existing appointment ID (used for rescheduling)
advisorId	number	No	Service advisor ID

• POST /reschedule

Parameter	Type	Required	Description
appointmentId	string or number	Yes	The ID of the appointment to reschedule
...all bookappointment params	—	—	Reschedule calls book_appointment internally, so it accepts all the same parameters listed above

• POST /cancel_appointment (open to interpretation, should only need to send appointment ID that we need to cancel)

Note

I want to highlight that these parameters/processes are subject to change based on the requirements of the end API. Also - our goal is to minimize the possible errors that could happen due to a faulty payload to this API. A concrete example is: Let's say booking an appointment requires a vehicle year, but the AI decided to hit this API without a vehicle year. At that point, we should hardcode a year and just send it to the API to ensure the appointment booking goes through.

Error responses

If this isn't possible to fake the data (or doesn't make sense), make sure to return an actionable error response. For example, lets say we need the customer phone number but the AI didn't include it. DO NOT fake this. Isntead, the response should be "error": "You must include the customer phone number in the paylaod to book the appointment". Keep in mind responses are fed directly back to the LLM.

By Dealership Note

Keep in mind that each of these endpoints will use different keys and might have custom logic depending on which dealership is consuming it. We will need to hit like /book_appointment/{dealership_id}, and will need to define dealership_ids ---> access/refresh token mapping via an API (so that we can use an autodeployer and scale this without having to change source code on the wrapper). This can be stored via a DB or, better yet, a Redis Cache.