CityTrips API 1.0.0

Operations

Messages

CityTrips API 1.0.0

CityTrips's external API for operators.

Operator's data needed for integrating:

  • Terms and conditions link

.

Message structure

Every message must be a JSON object containing two root properties:

  {
    "command"(string): "this is one of the documented commands",
    "payload"(any): "this is the documented payload"
  }

.

Example:

{
  "command": "s_ext/authenticate",
  "payload": {
    "clientId": "730f8a96-a92c-4a74-8ce0-e7e4cdfff5ad",
    "apiKey": "a9eb2bc7-ab7b-40ed-ba01-0238f4b79e13"
  }
}

.

Support

Contact link: API Support Contact email: hola@gocitytrips.com

Servers

wss://api-sandbox.gocitytrips.com/v1 ws

Operations

Sub s_ext/error

Generic error.

Accepts the following message:

reason

Payload
object
reason
string

Additional properties are allowed.

Examples

reason
Payload 
{
  "reason": "string"
}
This example has been generated automatically.

Sub s_ext/must_authenticate

Received when you need to autheticate. Check "s_ext/authenticate" for more info.

Accepts the following message:

reason

Payload
object
reason
string

Additional properties are allowed.

Examples

reason
Payload 
{
  "reason": "string"
}
This example has been generated automatically.

Sub s_ext/auth_succesful

Received when authentication succeeded.

Accepts the following message:

empty

Empty payload

Payload
null

Examples

empty
Payload 
""
This example has been generated automatically.

Sub s_ext/auth_error

Received when authentication failed.

Accepts the following message:

reason

Payload
object
reason
string

Additional properties are allowed.

Examples

reason
Payload 
{
  "reason": "string"
}
This example has been generated automatically.

Pub s_ext/authenticate

You will need to authenticate before being able to do any other thing. You must authenticate everytime you receive a "must_authenticate" message (it may happen that the connection has been lost but your app didn't notice it).

  • If you know you are connecting the first time you can directly send the "authentication" message without waiting for a "must_authenticate", doing so you will accelerate things.

Accepts the following message:

auth

Authentication payload

Payload
object
clientId
string
apiKey
string

Additional properties are allowed.

Examples

auth
Payload 
{
  "clientId": "string",
  "apiKey": "string"
}
This example has been generated automatically.

Sub s_user/new

IMPORTANT: CityTrips system will not authenticate against the Operator using user's email and password, instead it will request actions on Operator's system (reserve, open vehicle, user reservations, etc) in behalf of an user managed by CityTrips. As CityTrips system authenticates the user, Operator's system must trust CityTrips authentication.

You are responsible of checking if the user already exists on your platform. If it already exists, you just need to return its ID and mark it as a CityTrips user, so we are allowed to do actions on his behalf. Otherwise a new account must be created.

Accepts the following message:

new_user

Payload
object
terms_accepted
boolean

Terms and conditions of Operator will be shown to the user and he will be requested to accept them. (If the user do not accept Terms and conditions from Operator, account will not be created, so this will be always true, it is send for legal reasons)

username
string
email
string
password
string
  • A random strong password will be generated.
  • This password will be unknown for everyone.
  • This password will never be used by CityTrips API.
  • If the user wants to login directly into the operator, he will need to recover his password.
firstname
string
lastname
string
nif
string
phone
number
birthdate
number
zipcode
string
city
string
country
string
address
string
driver_license_number
string
license_expiration
number

Timestamp

nif_front_img
string
nif_back_img
string
license_front_img
string
license_back_img
string

Additional properties are allowed.

Examples

new_user
Payload 
{
  "terms_accepted": true,
  "username": "string",
  "email": "string",
  "password": "string",
  "firstname": "string",
  "lastname": "string",
  "nif": "string",
  "phone": 0,
  "birthdate": 0,
  "zipcode": "string",
  "city": "string",
  "country": "string",
  "address": "string",
  "driver_license_number": "string",
  "license_expiration": 0,
  "nif_front_img": "string",
  "nif_back_img": "string",
  "license_front_img": "string",
  "license_back_img": "string"
}
This example has been generated automatically.

Sub s_vehicle/full_request

When you receive this command, send a "s_vehicle/full" command with all vehicles available.

Accepts the following message:

reason

Payload
object
reason
string

Additional properties are allowed.

Examples

reason
Payload 
{
  "reason": "string"
}
This example has been generated automatically.

Pub s_vehicle/full

Send all vehicles available. A message will be send to indicate that this action is needed.

Accepts the following message:

vehicles

Payload
array<object>
id
string
battery
integer
>= 0 <= 100
plate
string
country
string
Enum: "Chile" "Spain" "Australia"
city
string
location
object
latitude
integer
longitude
integer

Additional properties are allowed.

Additional items are allowed.

Examples

vehicles
Payload 
[
  {
    "id": "string",
    "battery": 0,
    "plate": "string",
    "country": "Chile",
    "city": "string",
    "location": {
      "latitude": 0,
      "longitude": 0
    }
  }
]
This example has been generated automatically.

Pub s_vehicle/incremental

Send modified vehicles only.

Accepts the following message:

vehicles

Payload
array<object>
id
string
battery
integer
>= 0 <= 100
plate
string
country
string
Enum: "Chile" "Spain" "Australia"
city
string
location
object
latitude
integer
longitude
integer

Additional properties are allowed.

Additional items are allowed.

Examples

vehicles
Payload 
[
  {
    "id": "string",
    "battery": 0,
    "plate": "string",
    "country": "Chile",
    "city": "string",
    "location": {
      "latitude": 0,
      "longitude": 0
    }
  }
]
This example has been generated automatically.

Messages

#1 reason

Payload
object
reason
string

Additional properties are allowed.

#2 empty

Empty payload

Payload
null
#3 auth

Authentication payload

Payload
object
clientId
string
apiKey
string

Additional properties are allowed.

#4 new_user

Payload
object
terms_accepted
boolean

Terms and conditions of Operator will be shown to the user and he will be requested to accept them. (If the user do not accept Terms and conditions from Operator, account will not be created, so this will be always true, it is send for legal reasons)

username
string
email
string
password
string
  • A random strong password will be generated.
  • This password will be unknown for everyone.
  • This password will never be used by CityTrips API.
  • If the user wants to login directly into the operator, he will need to recover his password.
firstname
string
lastname
string
nif
string
phone
number
birthdate
number
zipcode
string
city
string
country
string
address
string
driver_license_number
string
license_expiration
number

Timestamp

nif_front_img
string
nif_back_img
string
license_front_img
string
license_back_img
string

Additional properties are allowed.

#5 vehicles

Payload
array<object>
id
string
battery
integer
>= 0 <= 100
plate
string
country
string
Enum: "Chile" "Spain" "Australia"
city
string
location
object
latitude
integer
longitude
integer

Additional properties are allowed.

Additional items are allowed.

#6 todo

ToDo

Payload
string