The Session API from Sheeva — 7 operation(s) for session.
openapi: 3.0.3
info:
title: SheevaConnect Authentication Session API
version: '2.0'
description: 'This SheevaConnect™ API Specification 2.0 is © 2024 Parkofon Inc. (d/b/a Sheeva.AI) and is proprietary information that may not be duplicated, redistributed, form the basis of derivative works, or publicly performed/displayed without the expressed written permission of Sheeva.AI. If you wish to use the SheevaConnect™ API Specification 2.0 and use the SheevaConnect™ cloud platform, please contact Sheeva.AI for a license.
SheevaConnect APIs enable connected vehicle payments & last-mile services for various use cases including Fueling, EV Charging, Parking and Retail. This solution allows automated & contactless payment in addition to proactive identification of user needs and last-mile navigation to the nearest Sheeva Pay enabled outlets.
All APIs follow HTTP status codes, return HTTP 200 OK when successful and following HTTP errors with a message. The message is self explaining to indicate the error in request. The example error codes include :
Error Code
Message
400
Bad Request : Check the parameter values
404
Resource not found
500
Internal Server Error
SheevaConnect creates a session when system detects that vehicle requires a service (FUEL, CHARGING, PARKING). Each session goes through various statuses.
Session Status Codes
Status
Description
LOW_FUEL_DETECTED
If vehicle was low on fuel and system has sent the notification to driver for low fuel or if vehicle is not low on fuel but driver clicks on fuel icon to pay.
LOW_CHARGE_DETECTED
If vehicle was low on charge and system has sent the notification to driver for low charged or if vehicle is not low on chrage but driver clicks on charge icon to pay.
AT_SERVICE_HUB
The driver has reached the fuel station / EV charge station / etc.
AT_SERVICE_POINT
The driver is at fuel pump / charging bay.
SERVICE_POINT_CONFIRMED
Driver confirms the fuel pump / charging bay.
SERVICE_IN_PROGRESS
When driver uses a parking service and vehicle is parked
SERVICE_COMPLETE
When user marks the fuel, charging, parking complete
SERVICE_CANCELLED_BY_DRIVER
When user cancel the service at the pump/ charging bay
SERVICE_ABORTED_BY_SYSTEM
When user does opt for service and move away from fuel pump/ charging bay
Payment Status Codes
Status
Description
PAYMENT_AUTHORIZED
When a payment is authorized. Only applicable for Credit Card, Wallet and Rewards.
PAYMENT_INITIATED
When a payment is in progress. Only applicable for UPI in India.
PAYMENT_COMPLETE
Payment has been processed for a g'
contact:
name: Sheeva.AI
url: https://sheeva.ai/contact-us
x-company: Parkofon Inc. (d/b/a Sheeva.AI)
servers:
- url: https://us-apis.sheeva.ai
description: Production (USA)
- url: https://in-apis.sheeva.ai
description: Production (India)
- url: https://dev-us-apis.sheeva.ai
description: Sandbox (USA)
- url: https://dev-in-apis.sheeva.ai
description: Sandbox (India)
security:
- bearerAuth: []
tags:
- name: Session
paths:
/v2/partner-apis/sessions/current-session:
get:
summary: Get Currently Active Sessions
operationId: getCurrentlyActiveSessions
tags:
- Session
responses:
'200':
description: OK
content:
application/json:
example:
vehicleLocation:
latitude: 19.16323715308841
longitude: 72.85860447032306
timestamp: 1668531651000
activeSessions:
- id: parking_payments_14141asdqwe
currentState: CONFIRMED
paymentStatus: PAYMENT_COMPLETED
serviceType: PARKING
description: "This request returns current fuel session state and details if there is any session with the specified type actively running in the system.\nIf successful, returns: HTTP 200 OK.\nResponse Body Field Description:\n\n\n\nField\nDescription\n\n\n\n\nvehicleLocation\nCurrent vehicle location latitude, longitude, timestamp ( in EPOCH )\n\n\nactiveSessions\nArray of active session(s) for the the vehicle - if there is any, otherwise it will come as empty\n\n\nactiveSessions[0].id\nUnique service hub identifier \n\n\nactiveSessions[0].currentState\nCurrent state of the session e.g. LOW_FUEL_DETECTED, AT_SERVICE_HUB\n\n\nactiveSessions[0].serviceType\nType of the service for which the session is created FUEL, CHARGING, PARKING, TOLL\n\n\n\n"
parameters:
- name: x-sheeva-program-code
in: header
required: true
schema:
type: string
description: Provided by Sheeva
/v2/partner-apis/sessions/{sessionId}:
get:
summary: Get Details of a Session
operationId: getDetailsOfASession
tags:
- Session
responses:
'200':
description: Response
content:
application/json:
example:
vehicleLocation:
latitude: 33.02031165
longitude: -96.83407293
timestamp: 1719587666391
session:
id: parking_UbnAGCt2fQItXcZHsrE8
currentState: SERVICE_COMPLETE
serviceType: PARKING
startTime: '2024-06-19 12:04:00'
endTime: '2024-06-19 13:04:00'
paymentStatus: COMPLETED
paymentInstrument:
type: CREDIT_CARD
id: pay_xzsN38mYF7zoMHqoO8iv
amount: 24.0
serviceHub:
paymentInstrument:
type: CREDIT_CARD
id: pay_xzsN38mYF7zoMHqoO8iv
amount: 24.0
displayName: Marina Lot 9
currency: USD
location: 33.982403360821465,-118.4560913004027
addressDetails:
city: N/A
state: N/A
zipCode: N/A
country: N/A
streetAddress: N/A
amenities:
- Convenience Store
- Free Air
- Washrooms
promotions:
- name: Reward Days
category: PARKING
discount: N/A
mediaURL: https://example.com/abc.jpg
polygon: 33.982144 -118.455279;33.982945 -118.456666;33.982662 -118.456904;33.981964 -118.455694;33.982008 -118.455657;33.981974 -118.455600;33.981971 -118.455538;33.981993 -118.455475;33.982082 -118.455331;33.982144 -118.455279
timezone: America/Los_Angeles
openingHours:
- day: '1'
hours:
- 5:00 - 22:00
- day: '2'
hours:
- 5:00 - 22:00
- day: '3'
hours:
- 5:00 - 22:00
- day: '4'
hours:
- 5:00 - 22:00
- day: '5'
hours:
- 5:00 - 22:00
- day: '6'
hours:
- 6:00 - 22:00
- day: '7'
hours:
- 8:00 - 22:00
id: '1100053'
parameters:
- name: sessionId
in: path
required: true
schema:
type: string
- name: x-sheeva-program-code
in: header
required: true
schema:
type: string
description: Provided by Sheeva
/v2/partner-apis/sessions/{sessionId}/rating:
post:
summary: Collect Rating for Completed Session
operationId: collectRatingForCompletedSession
tags:
- Session
responses:
'201':
description: Created
description: 'This API takes in the star rating for a given session and stores it on session and also against service hub (for example fuel station).
API will return HTTP Status Code 201
'
parameters:
- name: sessionId
in: path
required: true
schema:
type: string
- name: x-sheeva-program-code
in: header
required: true
schema:
type: string
description: Provided by Sheeva
requestBody:
content:
application/json:
example:
comments: Feedback of the customer about the service hub
/v2/partner-apis/sessions/{sessionId}/confirm-service-point:
post:
summary: Confirm Service Point
operationId: confirmServicePoint
tags:
- Session
responses:
'200':
description: Response
description: 'API to confirm the service point associated with service.
Fuel Pump in case of serviceType = "FUEL"
Charging connector in case of serviceType = "CHARGING"
Parking lot in case of serviceType = "PARKING"
Sending demoMode=1 would run a transaction with fake payment and will not activate the pump, charger or the parking lot. This helps with simulated testing in the sandbox / development.
'
parameters:
- name: sessionId
in: path
required: true
schema:
type: string
- name: x-sheeva-program-code
in: header
required: true
schema:
type: string
description: Provided by Sheeva
requestBody:
content:
application/json:
example:
servicePointId: '1'
parking:
duration: 30
/v2/partner-apis/sessions/{sessionId}/mark-service-complete:
post:
summary: Mark Service Complete
operationId: markServiceComplete
tags:
- Session
responses:
'201':
description: Response
description: 'NOTE: This api is applicable for serviceType="PARKING"
'
parameters:
- name: sessionId
in: path
required: true
schema:
type: string
- name: x-sheeva-program-code
in: header
required: true
schema:
type: string
description: Provided by Sheeva
requestBody:
content:
application/json:
example:
serviceType: PARKING
/v2/partner-apis/sessions/cancel:
post:
summary: Cancel the FUEL session by Vin( DEV environment only )
operationId: cancelTheFuelSessionByVin
tags:
- Session
responses:
'201':
description: Response
description: 'NOTE: This api is applicable for DEV environment and FUEL sessions only.
API is to help developer to cancel the session during integration for the given vin and serviceType(FUEL).
'
parameters:
- name: x-sheeva-program-code
in: header
required: true
schema:
type: string
description: Provided by Sheeva
requestBody:
content:
application/json:
example: {}
/v2/partner-apis/sessions/{sessionId}/cancel:
post:
summary: Cancel the FUEL session by sessionId ( DEV environment only )
operationId: cancelTheFuelSessionBySessionid
tags:
- Session
responses:
'201':
description: Response
description: 'NOTE: This api is applicable for DEV environment and FUEL sessions only.
API is to help developer to cancel the session during integration for the given sessionId. Use "Get Currently Active Sessions" API to retrieve action sessionId.
'
parameters:
- name: sessionId
in: path
required: true
schema:
type: string
- name: x-sheeva-program-code
in: header
required: true
schema:
type: string
description: Provided by Sheeva
requestBody:
content:
application/json:
example: {}
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Access token obtained from GET /v2/auth (exchange client-id/client-secret), sent in the Authorization header.
clientCredentials:
type: apiKey
in: header
name: client-id
description: client-id + client-secret headers on GET /v2/auth to obtain an access token.