This is an old revision of the document!
Trucks for You API
Creation and registration
Hirer / Driver: Request TOTP
Request
API call
POST https://tfy.tech101.in/api/v1/totp
Headers:
Content-Type: application/json
Body
{ "phone": "phone-number" }
Response for a successful request
Headers
HTTP/1.1 202 ACCEPTED
Body: none
Response if the user doesn't exist
Headers
HTTP/1.1 404 USER-NOT-FOUND
Body: none
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
This is a sample error message.
Hirer / Driver: Login
Request
API call
POST https://tfy.tech101.in/api/v1/oauth/token
Headers
Content-Type: application/json
Body
{
"grant_type": "password"
, "username": "the-username"
, "password": "the-totp"
, "scope": "hirer:all" or "driver:all"
}
Response if successful
Headers
HTTP/1.1 200 OK
Content-Type: application/json
Body
{
"access_token": "the-access-token"
, "token_type": "bearer"
, "scope": "hirer:all" or "driver:all"
}
Response if user doesn't exist
Headers
HTTP/1.1 404 HIRER-NOT-FOUND or DRIVER-NOT-FOUND
Body: none
Response if TOTP is wrong
Headers
HTTP/1.1 401 INVALID-TOTP
Body: none
Response for other errors
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
This is a sample error message.
Admin: Login
Request
API call
POST https://tfy.tech101.in/api/v1/oauth/token
Headers
Content-Type: application/json
Body
{
"grant_type": "password"
, "username": "admin-username"
, "password": "admin-password"
, "scope": "all:all"
}
Response if successful
Headers
HTTP/1.1 200 OK
Content-Type: application/json
Body
{
"access_token": "the-access-token"
, "token_type": "bearer"
, "scope": "hirer:all" or "driver:all"
}
Response if admin user doesn't exist
Headers
HTTP/1.1 404 ADMIN-NOT-FOUND
Body: none
Response if password is wrong
Headers
HTTP/1.1 401 INVALID-PASSWORD
Body: none
Response for other errors
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
This is a sample error message.
List of cities / truck types / trucks / drivers
Request
API call
GET https://tfy.tech101.in/api/v1/<objects>
where <objects> is one of cities, truck-types, trucks or drivers
Headers
Authorization: Bearer <admin-token>
Response if request is successful
Headers
HTTP/1.1 200 OK
Content-Type: application/json
Body for cities
[
{
"id": "uuid-of-city",
"name": "name-of-city"
},
{ ... more cities ... }
]
Body for truck types
[
{
"id": "uuid-of-truck-type",
"name": "name-of-truck-type",
"img": "https://path/to/icon/of/truck/type"
},
{ ... more truck types ... }
]
Body for trucks
[
{
"id": "uuid-of-truck",
"status": <truck-status>,
"city": "current-city"
},
{ ... more trucks ... }
]
where <truck-status> is a status code indicating the role that the truck is playing right now. It can be one of the following numbers
0: Truck is free for hire
1: Truck is provisionally allotted to a trip
2: Truck is confirmed for a trip
3: Truck is at loading point
4: Truck is weighed and loaded
5: Truck is in transit
6: Truck is at unloading point
7: Truck is unloaded and weighed
Body for drivers
[
{
"id": "uuid-of-driver",
"name": "name-of-driver",
"license": "license-number-of-driver"
},
{ ... more drivers ... }
]
Response if admin token is invalid
Response if admin is not allowed to list objects
Response for some other error
Admin: Add a city / truck type / truck / driver
Request
API call
POST https://tfy.tech101.in/api/v1/cities
POST https://tfy.tech101.in/api/v1/truck-types
POST https://tfy.tech101.in/api/v1/trucks
POST https://tfy.tech101.in/api/v1/drivers
Headers
Authorization: Bearer <admin-token>
Content-Type: application/json
Body for city
{ "name": "city-name" }
Body for truck type
{
"name": "name-of-truck-type"
}
Body for truck
{
"registration": {
"id": "truck's-registration-number"
, "expiry": "expiry-date-of-registration"
}
, "type": "uuid-of-truck-type"
, "capacity": "capacity-in-tonnes"
, "city": "uuid-of-city-where-the-truck-is"
}
Body for driver
{
"name": "driver-name"
, "license: {
"id": "driver's-license-number"
, "expiry": "expiry-date-of-license"
}
, "phone": "phone-number-of-driver"
}
Response if successful
Headers
HTTP/1.1 200 OK
Content-Type: application/json
Body for city
{
"id": "uuid-of-city"
, "name": "name-of-city"
}
Body for truck type
{
"id": "uuid-of-truck-type"
, "name": "name-of-truck-type"
, "img": "https://path/to/truck/type/icon"
}
Body for truck
{
"id": "uuid-of-truck"
, "registration": {
"id": "registration-number-of-truck"
, "expiry": "expiry-date-for-registration"
}
, "type": "uuid-of-truck-type"
, "capacity": capacity-in-tonnes
, "img": {
"self": "https://path/to/image/of/truck"
, "rc": "https://path/to/image/of/rc/book"
}
, "driver": "uuid-of-driver-assigned"
}
}
Body for driver
{
"id": "uuid-of-driver"
, "name": "driver's name"
, "license": {
"id": "license-number-of-driver"
, "expiry": "expiry-date-of-license"
}
, "phone": "phone-number-of-driver"
, "img": {
"self": "https://path/to/image/of/driver"
, "license": "https://path/to/image/of/license"
}
, "truck": "uuid-of-truck-assigned"
}
Response if admin token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Body: none
Response if token doesn't have sufficient permissions
Headers
HTTP/1.1 403 FORBIDDEN
Body: none
Response if fields are missing or invalid
Headers
HTTP/1.1 400 INVALID-<field-name> e.g. INVALID-CITY-NAME
Content-Type: text/plain
Body
Validation message specific to invalid field
Response for some other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Admin: Hide / unhide city / truck type / truck / driver
Request
API call
PATCH https://tfy.tech101.in/api/v1/cities/uuid-of-city
PATCH https://tfy.tech101.in/api/v1/truck-types/uuid-of-truck-type
PATCH https://tfy.tech101.in/api/v1/trucks/uuid-of-truck
PATCH https://tfy.tech101.in/api/v1/drivers/uuid-of-truck
Headers
Authorization: Bearer admin-token
Content-Type: application/json
Body
{ "isHidden": true for hide / false for unhide }
Response if request is successful
Headers
HTTP/1.1 204 DONE
Body: none
Response if admin token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Body: none
Response if operation is forbidden for this user
Headers
HTTP/1.1 403 FORBIDDEN
Body: none
Response if underlying object is not found
Headers
HTTP/1.1 404 <object type>-NOT-FOUND e.g. CITY-NOT-FOUND, TRUCK-TYPE-NOT-FOUND
Body: none
Response for some other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message.
Request
API call
POST https://tfy.tech101.in/api/v1/media
Headers
Authorization: Bearer admin-token
Content-Type: image/jpeg or image/png
Body: byte array of image
Response if request is successful
Headers
HTTP/1.1 200 OK
Content-Type: text/plain
Body
https://path/of/uploaded/image
Response if admin token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if uploading is forbidden
Headers
HTTP/1.1 403 FORBIDDEN
Response if fields are missing or invalid
Headers
HTTP/1.1 400 INVALID-<field-name>, e.g. INVALID-MIME, INVALID-JPEG
Content-Type: text/plain
Body
Validation error specific to the error in the field
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Admin: Assign photo to truck / driver
Request
API call
PATCH https://tfy.tech101.in/api/v1/trucks/uuid-of-truck
PATCH https://tfy.tech101.in/api/v1/drivers/uuid-of-driver
PATCH https://tfy.tech101.in/api/v1/truck-types/uuid-of-truck-type
Headers
Authorization: Bearer admin-token
Content-Type: application/json
Body for truck
{
"img": {
"self": "https://path/to/truck/photo"
AND / OR
, "rc": "https://path/to/truck/rc/book/photo"
}
}
Body for driver
{
"img": {
"self": "https://path/to/driver/photo"
AND / OR
, "license": "https://path/to/license/photo"
}
}
Body for truck type
{ "img": "https://path/to/icon/of/truck/type" }
Response if request is successful
Headers
HTTP/1.1 204 DONE
Response if admin token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if assigning photos is forbidden
Headers
HTTP/1.1 403 FORBIDDEN
Response if fields are missing or invalid
Headers
HTTP/1.1 400 INVALID-<field-name>, e.g. INVALID-PATH
Content-Type: text/plain
Body
Validation error specific to the error in the field
Response if underlying objects (truck, driver or photo) doesn't exist
Headers
HTTP/1.1 404 <object-type>-NOT-FOUND, e.g. TRUCK-NOT-FOUND
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Administration
Admin: List of trip requests
Request
API call
GET https://tfy.tech101.in/api/v1/hire-requests
Headers
Authorization: Bearer admin-token
Response if request is successful
Headers
HTTP/1.1 200 OK
Body
[
{
"id": "hire-request-id",
"dates": {
"load": "desired-loading-date",
"delivery": "desired-delivery-date"
},
"cities": {
"load": {
"id": "uuid-of-city",
"name": "name-of-city"
},
"delivery": {
"id": "uuid-of-city",
"name": "name-of-city"
}
}
},
{ ... more requests ... }
]
Response if admin token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if listing trip requests is forbidden
Headers
HTTP/1.1 403 FORBIDDEN
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Admin: View one trip request
Request
API call
https://tfy.tech101.in/api/v1/hire-requests/uuid-of-request
Headers
Authorization: Bearer admin-token
Content-Type: application/json
Response if request is successful
Headers
HTTP/1.1 200 OK
Body
{
"id": "hire-request-id",
"hirer": {
"id": "uuid-of-hirer",
"name": "name-of-hirer",
"phone": "phone-number-of-hirer"
},
"dates": {
"load": "desired-loading-date",
"delivery": "desired-delivery-date"
},
"cities": {
"load": {
"id": "uuid-of-city",
"name": "name-of-city"
},
"delivery": {
"id": "uuid-of-city",
"name": "name-of-city"
}
},
"truckType": {
"id": "uuid-of-truck-type",
"name": "name-of-truck-type"
},
"capacity": capacity-in-tonnes,
"addresses": {
"load": "complete-loading-address",
"delivery": "complete-delivery-address"
},
"tariff": quoted-tariff
}
Response if token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if view a trip request is forbidden
Headers
HTTP/1.1 403 FORBIDDEN
Response if request UUID is not valid
Headers
HTTP/1.1 400 INVALID-REQUEST-ID
Content-Type: text/plain
Response if hire request doesn't exist
Headers
HTTP/1.1 404 HIRE-REQUEST-NOT-FOUND
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Admin: View trucks that fit a suggestion
Request
API call
GET https://tfy.tech101.in/api/v1/hire-requests/uuid-of-request/trucks
Headers
Authorization: Bearer admin-token
Response if request is successful
Headers
HTTP/1.1 200 OK
Content-Type: application/json
Body
[
"truck": {
"id": "uuid-of-truck",
"registration": "registration-number-of-truck"
},
"driver": {
"id": "uuid-of-driver",
"name": "name-of-driver",
"phone": ""
}
]
Response if token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if forbidden
Headers
HTTP/1.1 403 FORBIDDEN
Response if hire request is invalid
Headers
HTTP/1.1 400 INVALID-HIRE-REQUEST
Content-Type: text/plain
Body
Hire request must be a UUID.
Response if hire request doesn't exist
Headers
HTTP/1.1 404 HIRE-REQUEST-NOT-FOUND
where <object-type> can be HIRE-REQUEST or SUGGESTION
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Admin: Assign a truck to a request
Request
API call
POST https://tfy.tech101.in/api/v1/trips
Headers
Authorization: Bearer user-token
Content-Type: application/json
Body
{
"requestId": "uuid-of-hire-request",
"truckId": "uuid-of-assigned-truck"
}
Response if request is successful
Headers
HTTP/1.1 200 OK
Body
Response if token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if forbidden
Headers
HTTP/1.1 403 FORBIDDEN
Response if fields are missing or invalid
Headers
HTTP/1.1 400 INVALID-<field-name>
Content-Type: text/plain
where <field-name> is one of
Body
Validation error specific to the error in the field
Response if underlying objects don't exist
Headers
HTTP/1.1 404 <object-type>-NOT-FOUND
where <object-type> can be one of
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
<hidden snip>
Hiring a truck
Hirer: Request for a truck
Request
API call
POST https://tfy.tech101.in/api/v1/hire-requests
Headers
Authorization: Bearer hirer-token
Content-Type: application/json
Body
{
"id": "uuid-for-request-generated-by-app"
, "source": "uuid-of-source-city"
, "destination": "uuid-of-destination-city"
, "dateLoad": "YYYY-MM-DD"
, "dateDelivery": "YYYY-MM-DD"
, "weight": weight-in-tonnes
, "truckType": "uuid-of-truck-type"
}
Response if request is successful
Headers
HTTP/1.1 200 OK
Content-Type: application/json
Body
{
"requestId": "uuid-of-this-request-for-truck"
"suggestions": [
{
"id": "uuid-for-suggestion"
, "capacity": "capacity-in-tonnes"
, "dateSource": "unix timestamp with time 00:00:00, date on which truck leaves source city"
, "dateDestination": "unix timestamp with time 23:59:59, date on which truck reaches destination city"
, "tariff": tariff-in-rupees
}
, { ... more suggestions ... }
]
}
Response if token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if fields are invalid
Headers
HTTP/1.1 400 INVALID-<field-name>
Content-Type: text/plain
where field-name can be one of
SOURCE, DESTINATION, LOAD-DATE, DELIVERY-DATE, TRUCK-TYPE, WEIGHT
Body
Validation error specific to the error in the field
Response if one of the objects in the request does not exist
Headers
HTTP/1.1 404 <object type>-NOT-FOUND
where object-type can be one of CITY, TRUCK-TYPE
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Hirer: Pick a suggestion
Request
API call
PATCH https://tfy.tech101.in/api/v1/hire-requests/request-id
The request-id is the same as the one returned in the hiring request as requestId.
Headers
Authorization: Bearer hirer-token
Content-Type: application/json
Body
{
"suggestionId": "uuid-of-picked-suggestion"
, "addressSource": "complete address of source"
, "addressDestination": "complete address of destination"
}
Response if request is successful
Headers
HTTP/1.1 204 DONE
Response if token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if fields are invalid
Headers
HTTP/1.1 400 INVALID-<field-name>
Content-Type: text/plain
where field-name can be one of
SUGGESTION, SOURCE-ADDRESS, SOURCE-ADDRESS
Body
Validation error specific to the error in the field
Response if one of the objects does not exist
Headers
HTTP/1.1 404 <object>-NOT-FOUND
where <object> can be one of HIRE-REQUEST or SUGGESTION
Response if suggestion was not meant for this hire request
Headers
HTTP/1.1 403 NOT-OWNER
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Hirer: View truck's detailed page
Request
API call
GET https://tfy.tech101.in/api/v1/trucks/uuid-of-truck
Headers
Authorization: Bearer hirer-token
Response if request is successful
Headers
HTTP/1.1 200 OK
Content-Type: application/json
Body
{
"id": "uuid-of-truck"
, "registration": {
"id": "registration-number-of-truck"
, "expiry": "expiry-of-registration"
}
, "img": {
"self": "https://path/to/image/of/truck"
, "rc": "https://path/to/image/of/rc/book"
}
}
Response if token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if truck does not exist
Headers
HTTP/1.1 404 TRUCK-NOT-FOUND
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Hirer: View driver's detailed page
Request
API call
GET https://tfy.tech101.in/api/v1/drivers/uuid-of-driver
Headers
Authorization: Bearer hirer-token
Response if request is successful
Headers
HTTP/1.1 200 OK
Content-Type: application/json
Body
{
"id": "uuid-of-driver"
, "license": {
"id": "license-number-of-driver"
, "expiry": "expiry-of-license"
}
, "phone": "phone-number-of-driver" *
, "img": {
"self": "https://path/to/photo/of/driver"
, "license": "https://path/to/photo/of/license"
}
}
* Will be revealed ONLY if the driver is assigned on a trip to the requesting hirer. This field will be a blank string “” otherwise.
Response if token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if driver does not exist
Headers
HTTP/1.1 404 DRIVER-NOT-FOUND
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Hirer: Confirm trip
Request
API call
PATCH https://tfy.tech101.in/api/v1/trips/trip-id
Headers
Authorization: Bearer hirer-token
Content-Type: application/json
Body
{ "confirmed": true }
Response if request is successful
Headers
HTTP/1.1 204 DONE
Content-Type: application/json
Response if token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if fields are invalid
Headers
HTTP/1.1 400 INVALID-CONFIRMED-VALUE
Content-Type: text/plain
Body
Validation error specific to the error in the field
Response if hire request does not exist
Headers
HTTP/1.1 404 HIRE-REQUEST-NOT-FOUND
Response if hire request was not raised by this hirer
Headers
HTTP/1.1 403 NOT-OWNER
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Hirer: Cancel trip
Request
API call
PATCH https://tfy.tech101.in/api/v1/trips/trip-id
Headers
Authorization: Bearer hirer-token
Content-Type: application/json
Body
{ "cancelled": true }
Response if request is successful
Headers
HTTP/1.1 204 DONE
Content-Type: application/json
Body: none
Response if token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if fields are invalid
Headers
HTTP/1.1 400 INVALID-CANCELLED-VALUE
Content-Type: text/plain
Body
Validation error specific to the error in the field
Response if hire request does not exist
Headers
HTTP/1.1 404 HIRE-REQUEST-NOT-FOUND
Response if hire request was not raised by this hirer
Headers
HTTP/1.1 403 NOT-OWNER
Body: none
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
Hirer: View trip details
Request
API call
GET https://tfy.tech101.in/api/v1/trips/trip-id
Headers
Authorization: Bearer hirer-token
Response if request is successful
Headers
HTTP/1.1 200 OK
Content-Type: application/json
Body
{
"id": "uuid-for-trip"
, "dateLoad": "YYYY-MM-DD, date on which goods will be loaded and the trip starts"
, "dateDelivery": "YYYY-MM-DD, date on which goods will be delivered"
, "citySource": "uuid-of-pickup-city"
, "addressSource": "the-full-address-of-pickup"
, "cityDestination": "uuid-of-destination-city"
, "addressDestination": "the-full-address-of-delivery"
, "truck": "uuid-of-truck"
, "driver": "uuid-of-driver"
, "status": <trip-status>
}
where <trip-status> is a number that conveys at which stage the trip stage is. <trip-status> can be one of the following numbers.
0: Trip is unconfirmed by the hirer.
1: Trip is confirmed, but yet to begin.
2: The truck has arrived at the pickup address for loading.
3: Loading and weighing is finished.
4: The truck is on the route.
5: The truck has arrived at the destination address for unloading.
6: Unloading and weighing is finished.
7: Trip payment is done
8: Trip payment is in dispute
9: Trip is cancelled
Response if token is invalid
Headers
HTTP/1.1 401 INVALID-TOKEN
Response if the trip does not exist
Headers
HTTP/1.1 404 TRIP-NOT-FOUND
Response if the trip isn't requested by this hirer
Headers
HTTP/1.1 403 NOT-OWNER
Response for any other error
Headers
HTTP/1.1 500 ERROR
Content-Type: text/plain
Body
Sample error message
<hidden>