Introduction
Used to interact with sharebox... WIP
Event
Called when a locker is opened by a customer to pick up key
curl -X POST "API_BASE/v1/events/content_picked_up_by_receiver" -H "Authorization: Bearer $token" -H "Content-Type: application/json"
Called when a locker is opened by a member and the reservation's exchange method is set to out.
HTTP Request
POST /v1/events/content_picked_up_by_receiver
The request Body payload is:
{
"locker_no": 0,
"subscription_id": 0,
"reservation_id": 0,
"event_type": "",
"event_timestamp": "0001-01-01T00:00:00Z",
"subscription_name": ""
}
The request JSON response is:
This endpoint does not return anything, only the HTTP status code matters.
Request schema
| Parameter | Type | Required | Description |
|---|---|---|---|
| locker_no | int | true | |
| subscription_id | SubscriptionID | true | |
| reservation_id | int | true | |
| event_type | string | true | |
| event_timestamp | time.Time | true | |
| subscription_name | string | true |
Response schema
This endpoint does not return anything, only the HTTP status code matters.
Called when a locker is opened by a customer to drop a key
curl -X POST "API_BASE/v1/events/content_delivered_by_receiver" -H "Authorization: Bearer $token" -H "Content-Type: application/json"
Called when a locker is opened by a member and the reservation's exchange method is set to in.
HTTP Request
POST /v1/events/content_delivered_by_receiver
The request Body payload is:
{
"locker_no": 0,
"subscription_id": 0,
"reservation_id": 0,
"event_type": "",
"event_timestamp": "0001-01-01T00:00:00Z",
"subscription_name": ""
}
The request JSON response is:
This endpoint does not return anything, only the HTTP status code matters.
Request schema
| Parameter | Type | Required | Description |
|---|---|---|---|
| locker_no | int | true | |
| subscription_id | SubscriptionID | true | |
| reservation_id | int | true | |
| event_type | string | true | |
| event_timestamp | time.Time | true | |
| subscription_name | string | true |
Response schema
This endpoint does not return anything, only the HTTP status code matters.
Called when a locker is opened by an employee to pick up key
curl -X POST "API_BASE/v1/events/content_picked_up_by_employee" -H "Authorization: Bearer $token" -H "Content-Type: application/json"
Called when a locker is opened by a member marked as is_employee and the reservation's exchange method is set to in.
HTTP Request
POST /v1/events/content_picked_up_by_employee
The request Body payload is:
{
"locker_no": 0,
"subscription_id": 0,
"reservation_id": 0,
"event_type": "",
"event_timestamp": "0001-01-01T00:00:00Z",
"subscription_name": ""
}
The request JSON response is:
This endpoint does not return anything, only the HTTP status code matters.
Request schema
| Parameter | Type | Required | Description |
|---|---|---|---|
| locker_no | int | true | |
| subscription_id | SubscriptionID | true | |
| reservation_id | int | true | |
| event_type | string | true | |
| event_timestamp | time.Time | true | |
| subscription_name | string | true |
Response schema
This endpoint does not return anything, only the HTTP status code matters.
Called when a locker is opened by an employee to drop a key
curl -X POST "API_BASE/v1/events/content_delivered_by_employee" -H "Authorization: Bearer $token" -H "Content-Type: application/json"
Called when a locker is closed by a member marked as is_employee and the reservation's exchange method is set to out.
HTTP Request
POST /v1/events/content_delivered_by_employee
The request Body payload is:
{
"locker_no": 0,
"subscription_id": 0,
"reservation_id": 0,
"event_type": "",
"event_timestamp": "0001-01-01T00:00:00Z",
"subscription_name": ""
}
The request JSON response is:
This endpoint does not return anything, only the HTTP status code matters.
Request schema
| Parameter | Type | Required | Description |
|---|---|---|---|
| locker_no | int | true | |
| subscription_id | SubscriptionID | true | |
| reservation_id | int | true | |
| event_type | string | true | |
| event_timestamp | time.Time | true | |
| subscription_name | string | true |
Response schema
This endpoint does not return anything, only the HTTP status code matters.
Employee
Opens a Sharebox Locker for an Employee who wants to pick up a key
curl -X POST "API_BASE/v1/employees/pickup" -H "Authorization: Bearer $token" -H "Content-Type: application/json"
Opens a Sharebox Locker for an Employee who wants to pick up a key. This will call Sharebox to update their subscription name, which allows events/door_opened to identify which request to ignore. Then open the locker for the employee. Claire appointment is updated
HTTP Request
POST /v1/employees/pickup
The request Body payload is:
{
"appointment_id": 0,
"sharebox_location_id": ""
}
The request JSON response is:
This endpoint does not return anything, only the HTTP status code matters.
Request schema
| Parameter | Type | Required | Description |
|---|---|---|---|
| appointment_id | AppointmentID | true | Appointment Identifier for an Employee to pick up key |
| sharebox_location_id | string | true | Sharebox Location Identifier for an Employee to pick up key |
Response schema
This endpoint does not return anything, only the HTTP status code matters.
Opens a Sharebox Locker for an Employee who wants to drop a key
curl -X POST "API_BASE/v1/employees/drop_key_back" -H "Authorization: Bearer $token" -H "Content-Type: application/json"
Opens a Sharebox Locker for an Employee who wants to drop a key. This will call Sharebox to update their subscription name, which allows events/door_opened to identify which request to ignore. Then open the locker for the employee. Claire appointment is updated
HTTP Request
POST /v1/employees/drop_key_back
The request Body payload is:
{
"location_id": 0,
"appointment_id": 0,
"appointment_note_id": null
}
The request JSON response is:
This endpoint does not return anything, only the HTTP status code matters.
Request schema
| Parameter | Type | Required | Description |
|---|---|---|---|
| location_id | int | true | Sharebox Keylocker Identifier |
| appointment_id | AppointmentID | true | Appointment Identifier for an Employee to pick up key |
| appointment_note_id | AppointmentNoteID | false | Identifier for a temp driver appointment note, if someone was at the location on behalf of the actual driver |
Response schema
This endpoint does not return anything, only the HTTP status code matters.
Opens a Sharebox Locker for an Employee who wants to pickup a key for a Customer
curl -X POST "API_BASE/v1/employees/assist_pick_up" -H "Authorization: Bearer $token" -H "Content-Type: application/json"
Opens a Sharebox Locker for an Employee who wants to pickup a key for a Customer. This will call Sharebox to update their subscription name, which allows events/door_opened to identify which request to ignore. Then open the locker for the employee. Claire appointment is updated
HTTP Request
POST /v1/employees/assist_pick_up
The request Body payload is:
{
"appointment_id": 0,
"sharebox_location_id": ""
}
The request JSON response is:
This endpoint does not return anything, only the HTTP status code matters.
Request schema
| Parameter | Type | Required | Description |
|---|---|---|---|
| appointment_id | AppointmentID | true | Appointment Identifier for an Employee to pick up key |
| sharebox_location_id | string | true | Sharebox Location Identifier for an Employee to pick up key |
Response schema
This endpoint does not return anything, only the HTTP status code matters.
Cabinet
Get a list of cabinets that are available
curl -X POST "API_BASE/v1/cabinets/list_available" -H "Authorization: Bearer $token" -H "Content-Type: application/json"
Get a list of cabinets that are available They must be of the DealerLocation and have at least one active, empty locker
HTTP Request
POST /v1/cabinets/list_available
The request Body payload is:
{
"appointment_id": 0
}
The request JSON response is:
{
"cabinets": []
}
Request schema
| Parameter | Type | Required | Description |
|---|---|---|---|
| appointment_id | AppointmentID | true | Appointment Identifier to locate available cabinets |
Response schema
This endpoint return an object with the following fields, please refer to the JSON response column on the right for an example.
| Parameter | Type |
|---|---|
| cabinets | []entities.Cabinet |
Log
List Sharebox Logs
curl -X POST "API_BASE/v1/logs/list" -H "Authorization: Bearer $token" -H "Content-Type: application/json"
This endpoint returns a paginated list of sharebox logs that have occurred for a location.
HTTP Request
POST /v1/logs/list
The request Body payload is:
{
"dealer_location_id": 0,
"page": 0
}
The request JSON response is:
{
"items": [],
"nb_pages": 0
}
Request schema
| Parameter | Type | Required | Description |
|---|---|---|---|
| dealer_location_id | DealerLocationID | true | Location Identifier |
| page | int | true | Page to display, default value is 1 |
Response schema
This endpoint return an object with the following fields, please refer to the JSON response column on the right for an example.
| Parameter | Type |
|---|---|
| items | []model.ShareboxLog |
| nb_pages | int |
Models and Enumeration
ShareboxResult Enumeration
| Value | Description |
|---|---|
| 1 | The event was not handled correctly and resulted in an error |
| 2 | The event could not be identified |
| 3 | Event was handled |
ShareboxTrigger Enumeration
| Value | Description |
|---|---|
| 1 | Whenever the door is opened. This is legacy and not logged anymore |
| 2 | Customer has dropped key |
| 3 | Employee has picked up the key |
| 4 | Employee dropped back the key |
| 5 | Customer has picked back up the key |
ShareboxLog Model
| Field | Type | Description |
|---|---|---|
| created_on | time.Time | Creation date in Claire |
| id | ShareboxLogID | Sharebox Log ID |
| trigger_id | ShareboxTrigger | Sharebox Event type |
| result_id | ShareboxResult | Result of handling the Sharebox Event |
| reason | string | Reason for a Sharebox Event failing |
| locker_no | int | Sharebox Locker number |
| subscription_id | int | Sharebox Subscription ID |
| subscription_name | string | Sharebox Subscription Name |
| reservation_id | int | Sharebox Reservation ID |
| event_type | string | Sharebox Event Type |
| event_timestamp | time.Time | Sharebox Event timestamp |
| dealer_location_id | DealerLocationID | Location Identifier from which the Sharebox Event originates |
Schemas
The types below are used in the request and response bodies of the endpoints above but are not database models. Their fields are described here for reference.
Cabinet
| Field | Type | Description |
|---|---|---|
| id | int | |
| subscription_id | int | |
| subscription_name | string | |
| cabinet_id | int | |
| locker_id | int | |
| locker_no | int | |
| location_id | int | |
| location | string | |
| location_serial_no | string | |
| is_cabinet_online | int | |
| is_cabinet_error | int | |
| is_locker_active | int | |
| is_locker_open | int | |
| is_locker_error | int |
Changelog
This section contains changes related to the Sharebox service. Changes will be included if:
- A new endpoint is added
- A new field is added to an existing endpoint
- Field description changes
- A field is deprecated
CLA-I5365 - Employee Controller - 08.10.2023.
A new field called appointment_note_id has been added to the /v1/employees/drop_key_back endpoint. It identifies a temp driver appointment note, used when someone was at the location on behalf of the actual driver.
CLA-I4401 - Log Controller - 27.04.2023.
The following endpoint has been added:
/v1/logs/list- returns the Sharebox log of a dealer location
CLA-I4547 - Event Controller - 27.04.2023.
/v1/events/door_opened has been removed and replaced by four endpoints, one per Sharebox content transfer:
/v1/events/content_delivered_by_receiver/v1/events/content_picked_up_by_employee/v1/events/content_delivered_by_employee/v1/events/content_picked_up_by_receiver
CLA-I4518 - Employee Controller - 25.04.2023.
A new field called sharebox_location_id has been added to the /v1/employees/pickup and /v1/employees/assist_pick_up endpoints
CLA-I4349 - Employee Controller - 06.03.2023.
The following endpoint has been added:
/v1/employees/assist_pick_up- registers that an employee assisted in picking up the key of an appointment
CLA-I4336 - Employee Controller - 02.03.2023.
/v1/employees/drop_key has been renamed to /v1/employees/drop_key_back.
CLA-I4249 - Cabinet and Employee Controllers - 28.02.2023.
The following endpoints have been added:
/v1/cabinets/list_available- returns all cabinets that have at least one locker available for an appointment/v1/employees/drop_key- registers that an employee dropped the key of an appointment back into a Sharebox locker
CLA-I4011 - Employee Controller - 18.01.2023.
The following endpoint has been added:
/v1/employees/pickup- registers that an employee picked up the key of an appointment
Initial release - 16.01.2023.
The following endpoint is included with initial release:
/v1/events/door_opened- Sharebox door event