FORMAT: 1A HOST: http://api.staging-ecotaco.com/ # api.ecota.co v2 The API ecotaco allows you to connect, create an account, manage your credit cards and order rides. # Authentication Ecotaco API use a system of application key and authentification token. ## Application key : The application key is generated by Ecota.co and unique to an application. Before accessing EcoTa.co APIs, you need to register your application. Please supply the following information to dev@ecota.co: - Application name - Company (if appropriate) - Contact name, phone and address - Contact email - Is this a web application, a desktop application, or an application running on a device? - Short description of your application It **must** be passed on request : "accounts -> login", "accounts -> facebook login" and "accounts -> register" . ## Authentification token : The authentification token is retrieved at login or register of an user. It **must** be passed in request for authenticate action in Authorization HTTP header. Example : Authorization: Token token=e55887022c1aca4c86abcc49e85ceb8a0c855d2af4d9fac75c08040a583dcde4 # Language On some of our resources, we filter the content displayed based on the Accept-Language header. If the language is not defined or if we don't use the language defined in this header, we automatically use French as the default language. EcoTa.co currently support two languages: English, French. ("en" and "fr") # Encoding All requests and answers on EcoTa.co are in UTF-8. # Group EcoTa.co API Root ## Version [/] This resource does not have any attributes. Instead it offers the list of API versions. ### Retrieve the version API [GET] + Response 200 (application/vnd.siren+json) { "links": { "self": "https://api.ecota.co", "v2": "https://api.ecota.co/v2" } } ## Endpoint [/{version}] This resource does not have any attributes. Instead it offers the initial API affordances. ## Retrieve the Entry Point on Version [GET] + Parameters + version (required, string) ... Ecotaco API version + Response 200 (application/vnd.siren+json) { "links": { "self": "https://api.ecota.co/v2", "accounts": "https://api.ecota.co/v2/accounts", "promotional_codes": "https://api.ecota.co/v2/promotional_codes", "rides": "https://api.ecota.co/v2/rides", "catchement_areas": "https://api.ecota.co/v2/catchement_areas", "products": "https://api.ecota.co/v2/products", "addresses": "https://api.ecota.co/v2/addresses" } } # Group Accounts The account methods use the User ressource. The User ressource has the following attributes : - **id** (required, unique, integer) : ID of the User - **name** (required, string) : Name of the User - **first_name** (required, string) : First name of the User - **email** (required, unique, string) : Email of the User - **phone** (required, string) : Phone of the User - **birth_date** (optional, string) : Birth date of the User - **language** (required, string) : Language of the User (fixed by the application) - **referral_code** (optional, string) : Driver referal code - **avatar_url** (optional, string) : Avatar Url of the User (fixed by the application, gravatar or facebook) - **newsletter** (required, boolean) : True if User want to receive the newsletter - **addresses** : An Array of addresses (see *Addresses*) - **companies** : An Array of companies (see *Companies*) The User have a array of **Addresses** with the following attributes : - **city** (required, string) : City - **country** (required, string) : Country - **latitude** (required, float) : Latitude of the Address - **longitude** (required, float) : Longitude of the Address - **postal_code** (required, integer) : Postal Code - **type_address** (required, string) : Address Type (HOME of User) - **address_complement** (optional, string) : Address complement - **label** (optional, string) : Address Type (HOME of User) The User have a array of **Companies** with the following attributes : - **id** (required, string) : Id - **user_id** (required, string) : Id of user attached to the company - **type_relation** (required, float) : Relation and role in the company - **name** (required, float) : Name of company **type_relation** : - company_manager : Can manage user and reserve for others user with relation on the company - visitor : Visitor of the company - collaborator : Collaborator of the company ## Login [/accounts/sign_in] Login to the application with : - **email** (required, string) : email of the user - **password** (required, string) : password of the user - **application_key** (required, string) : Ecotaco application key This request return an auth_token necessary to call authenticate action ### Login with email, password and application key [POST] + Request + Headers Accept: application/json Content-type: application/json Accept-Language: en + Body { "application_key":"2b5f29cf6b0791d9a499676499dd75d3", "user":{ "password":"ecotaco", "email":"contact@ecota.co" } } + Response 200 (application/json) { "user":{ "birth_date": "1983-05-12", "created_at": "2015-05-25T13:37:43+02:00", "email": "maxime.lenne@ecota.co", "first_name": "Lenne", "free_km_counter": 0, "free_used_km_counter": 0, "id": 18, "language": "fr", "name": "Maxime", "referral_code": "v8dlb", "phone": "0629453814", "updated_at": "2015-05-25T15:41:11+02:00", "avatar_url": "https://gravatar.com/avatar/45def3303a8c2b379605f3db4f61ebcc.png?s=200&d=http%3A%2F%2Fapp.ecota.co%2Fassets%2Fguest.png", "newsletter": "1", "auth_token": "c1cb860b4fa68ff9f3d94791d28a8c89f89f4b4eceded8eec9f1e6fc10ee4e8c", "addresses":[ { "address_complement":null,"city":null,"company_id":null,"country":null,"id":29,"label":null,"latitude":null,"longitude":null,"postal_code":null,"street":null,"type_address":"home" }], "companies": [ { "id": 10, "user_id": 18, "type_relation": "company_manager", "name": "EcoTa.co" } ] } } ## Register [/accounts] Register an user to ecotaco with : - **name** (required, string) : name of the user - **first_name** (required, string) : first name of the user - **email** (required, string) : email of the user (unique) - **phone** (required, string) : phone of the user in international format - **password** (required, string) : password of the user - **password_confirmation** (optionnal, string) : password confirmation of the user - **birth_date** (optionnal, string) : birth date of the user - **language** (optionnal, string) : language of the user ("en" or "fr") - **newsletter** (required, boolean) : true if the user subscribe to the ecotaco newsletter - **application_key** (required, string) : Ecotaco application key ### Create a new account with an application key [POST] + Request + Headers Accept: application/json Content-type: application/json Accept-Language: en + Body { "application_key": "d889b35a4d207d8a2805638022511f61", "newsletter":true, "user":{ "name":"Lenne", "password":"ecotaco", "password_confirmation":"ecotaco", "phone":"+33629453814", "first_name":"Maxime", "email":"maxime@ecota.co", "birth_date": "1982-01-05" } } + Response 201 (application/json) { "user":{ "birth_date": "1983-05-12", "created_at": "2015-05-25T13:37:43+02:00", "email": "maxime.lenne@ecota.co", "first_name": "Lenne", "free_km_counter": 0, "free_used_km_counter": 0, "id": 18, "language": "fr", "name": "Maxime", "referral_code": "v8dlb", "phone": "0629453814", "updated_at": "2015-05-25T15:41:11+02:00", "avatar_url": "https://gravatar.com/avatar/45def3303a8c2b379605f3db4f61ebcc.png?s=200&d=http%3A%2F%2Fapp.ecota.co%2Fassets%2Fguest.png", "newsletter": "1", "auth_token": "c1cb860b4fa68ff9f3d94791d28a8c89f89f4b4eceded8eec9f1e6fc10ee4e8c", "addresses":[ { "address_complement":null,"city":null,"company_id":null,"country":null,"id":29,"label":null,"latitude":null,"longitude":null,"postal_code":null,"street":null,"type_address":"home" }], "companies": [ { "id": 10, "user_id": 18, "type_relation": "company_manager", "name": "EcoTa.co" } ] } } ## Forget password [/accounts/password] Used to recover the password from the email, send an email to the address retrieval of the user. ### Forget password with email [POST] + Request + Headers Accept: application/json Content-type: application/json Accept-Language: en + Body { "user":{ "email":"admin@ecota.co" } } + Response 201 (application/json) ## Current User [/accounts] Get or update the current user. **Must be authenticate** ### Get current user [GET] + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Response 200 (application/json) { "user":{ "birth_date": "1983-05-12", "created_at": "2015-05-25T13:37:43+02:00", "email": "maxime.lenne@ecota.co", "first_name": "Lenne", "free_km_counter": 0, "free_used_km_counter": 0, "id": 18, "language": "fr", "name": "Maxime", "referral_code": "v8dlb", "phone": "0629453814", "updated_at": "2015-05-25T15:41:11+02:00", "avatar_url": "https://gravatar.com/avatar/45def3303a8c2b379605f3db4f61ebcc.png?s=200&d=http%3A%2F%2Fapp.ecota.co%2Fassets%2Fguest.png", "newsletter": "1", "auth_token": "c1cb860b4fa68ff9f3d94791d28a8c89f89f4b4eceded8eec9f1e6fc10ee4e8c", "addresses":[ { "address_complement":null,"city":null,"company_id":null,"country":null,"id":29,"label":null,"latitude":null,"longitude":null,"postal_code":null,"street":null,"type_address":"home" }], "companies": [ { "id": 10, "user_id": 18, "type_relation": "company_manager", "name": "EcoTa.co" } ] } } ### Update User [PUT] + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Body { "user":{ "name":"Lenne", "phone":"0629453814", "first_name":"Maxime", "birth_date":"1974-05-03T01:00:00+0100", "language":"en" "addresses":[{ "address_complement":null, "city":"Tourcoing", "country":"France", "id":13, "label":"test", "latitude":50.7211813, "longitude":3.1629418, "postal_code":59200, "street":"83 Rue de Tournai", "type_address":"home"}], "newsletter":false } } + Response 200 (application/json) { "user":{ "birth_date": "1983-05-12", "created_at": "2015-05-25T13:37:43+02:00", "email": "maxime.lenne@ecota.co", "first_name": "Lenne", "free_km_counter": 0, "free_used_km_counter": 0, "id": 18, "language": "fr", "name": "Maxime", "referral_code": "v8dlb", "phone": "0629453814", "updated_at": "2015-05-25T15:41:11+02:00", "avatar_url": "https://gravatar.com/avatar/45def3303a8c2b379605f3db4f61ebcc.png?s=200&d=http%3A%2F%2Fapp.ecota.co%2Fassets%2Fguest.png", "newsletter": "1", "auth_token": "c1cb860b4fa68ff9f3d94791d28a8c89f89f4b4eceded8eec9f1e6fc10ee4e8c", "addresses":[ { "address_complement":null,"city":null,"company_id":null,"country":null,"id":29,"label":null,"latitude":null,"longitude":null,"postal_code":null,"street":null,"type_address":"home" }], "companies": [ { "id": 10, "user_id": 18, "type_relation": "company_manager", "name": "EcoTa.co" } ] } } ## Password [/accounts/update_password] Update the current user password. **Must be authenticate** ### Update Password [PUT] + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Body { "user":{ "password":"ecotaco", "password_confirmation":"ecotaco", "current_password":"ecotaco" } } + Response 200 (application/json) { "user":{ "birth_date": "1983-05-12", "created_at": "2015-05-25T13:37:43+02:00", "email": "maxime.lenne@ecota.co", "first_name": "Lenne", "free_km_counter": 0, "free_used_km_counter": 0, "id": 18, "language": "fr", "name": "Maxime", "referral_code": "v8dlb", "phone": "0629453814", "updated_at": "2015-05-25T15:41:11+02:00", "avatar_url": "https://gravatar.com/avatar/45def3303a8c2b379605f3db4f61ebcc.png?s=200&d=http%3A%2F%2Fapp.ecota.co%2Fassets%2Fguest.png", "newsletter": "1", "auth_token": "c1cb860b4fa68ff9f3d94791d28a8c89f89f4b4eceded8eec9f1e6fc10ee4e8c", "addresses":[ { "address_complement":null,"city":null,"company_id":null,"country":null,"id":29,"label":null,"latitude":null,"longitude":null,"postal_code":null,"street":null,"type_address":"home" }], "companies": [ { "id": 10, "user_id": 18, "type_relation": "company_manager", "name": "EcoTa.co" } ] } } ## Settings [/accounts/settings] Configure the ecotaco newsletter. **Must be authenticate** ### Settings [POST] + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Body { "newsletter":true } + Response 200 (application/json) { "user":{ "birth_date": "1983-05-12", "created_at": "2015-05-25T13:37:43+02:00", "email": "maxime.lenne@ecota.co", "first_name": "Lenne", "free_km_counter": 0, "free_used_km_counter": 0, "id": 18, "language": "fr", "name": "Maxime", "referral_code": "v8dlb", "phone": "0629453814", "updated_at": "2015-05-25T15:41:11+02:00", "avatar_url": "https://gravatar.com/avatar/45def3303a8c2b379605f3db4f61ebcc.png?s=200&d=http%3A%2F%2Fapp.ecota.co%2Fassets%2Fguest.png", "newsletter": "1", "auth_token": "c1cb860b4fa68ff9f3d94791d28a8c89f89f4b4eceded8eec9f1e6fc10ee4e8c", "addresses":[ { "address_complement":null,"city":null,"company_id":null,"country":null,"id":29,"label":null,"latitude":null,"longitude":null,"postal_code":null,"street":null,"type_address":"home" }], "companies": [ { "id": 10, "user_id": 18, "type_relation": "company_manager", "name": "EcoTa.co" } ] } } ## Payment Methods [/accounts/payment_methods] Payment method available for the logged user, you can be used in ride reserve action. **Must be authenticate** ### Payment Methods [GET] + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Response 200 (application/json) { "payment_methods": [ { "method": "credit_card", "by_type": "User", "by_id": 13, "to": "ecotaco", "at": "ride_end", "credit_card_id": 1, "credit_card_label": "perso" }, { "method": "credit_card", "by_type": "Company", "by_id": 7, "to": "ecotaco", "at": "ride_end", "credit_card_id": 2, "credit_card_label": "Pro entrep" }, { "method": "transfer", "by_type": "Company", "by_id": 7, "to": "ecotaco", "at": "month_end" }, { "method": "cash", "by_type": "User", "by_id": 13, "to": "driver", "at": "ride_end" } ] } # Group CreditCards CreditCards resource The Credit Card ressource has the following attributes : - **id** (required, unique, integer) : ID of the credit card - **card_id** (required, string) : External stripe ID - **card_type** (required,string) : Card Type - **client** (required,string) : External stripe Customer ID - **expire_month** (required, integer) : Expire Mouth - **expire_year** (required, integer) : Expire Year - **label** (required, string) : Label of the Card - **last4** (required, string) : Last four digit in the card - **type_transaction** (required, string) : Type transaction (default : card) - **user_id** (required, integer) : ID of the User ## User Credit Cards [/credit_cards] For register a credit card to ecotaco you must fill : - **type_transaction** (required, string) : Type transaction (default : card) - **card_type** (required, string) : Stripe Card Type - **label** (required, string) : Label of the Card - **last4** (required, string) : Last four digit in the card - **expire_year** (required, integer) : Expire Year - **expire_month** (required, integer) : Expire Mouth **Must be authenticate** ### List all CreditCards for the current User [GET] + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Response 200 (application/json) [ { "credit_card":{, "id":4, "user_id": 18, "company_id": null, "card_type":"Visa", "expire_month":8, "expire_year":2015, "label":"pro", "last4":"4242", "type_transaction":"card", } } ] ## Credit card [/credit_cards/{id}] To change the credit card must belong to the connected user. **Must be authenticate** ### Get a CreditCard [GET] + Parameters + id (required, number, `1`) ... Numeric `id` of the Credit Card + Response 200 (application/json) { "credit_card":{, "id":4, "user_id": 18, "company_id": null, "card_type":"Visa", "expire_month":8, "expire_year":2015, "label":"pro", "last4":"4242", "type_transaction":"card", } } # Group Rides The Ride resource has the following attributes : - **id** (required, unique, integer) : ID of the Ride - **booking_user_id** (integer) : ID of user who have create the ride - **company_id** (integer) : ID of company who have create the ride - **requested_start** (required, date) : Requested date of the ride - **flight_number** (string) : Fligth number - **train_number** (string) : Train number - **nb_passengers** (required, integer) : Number of passengers (de 1 à 8) - **pick_up_or_tacking_out** (boolean) : If pick up or tacking out in station or other - **comment** (string) : Comment of ride forward to driver - **points** : Array of Points (see *Points*) one start point and one end point is required to create a ride - **passengers** : Array of Passengers (see *Passengers*) One passenger (attribute main: true) is mandatory to book a ride - **distance** (float) : Distance in Km - **driver_arrival** (date) : Date of real driver arrival - **duration** (integer) : Duration of the Ride in seconds - **price** (float) : price of the ride (without promotion) - **total_price** (float) : total price of the Ride - **real_end** (date) : Date of real end of ride - **real_start** (date) : Date of real start of ride - **refused_label** (string) : Refused Label (see *REFUSED_LABELS*) - **status** (string) : Status of the ride (see *STATUSES*) - **eta** (integer) : Estimated Time of arrival - **driver** (hash) : Information about driver (see *Driver*) - **vehicle** (hash) : Information about vehicle (see *Vehicle*) - **estimated_start** (date) : Estimated Start date of the ride - **estimated_end** (date) : Estimated End date of the ride - **promotional_code_used** : Promotional code use if any **STATUSES** : - NONE = '' - REFUSED = 'refused' The ride can not be reserved - ESTIMATED = 'estimated' We have availability for the ride, it can be reserved - RESERVED = 'reserved' - AFFECTED = 'affected' - SENT = 'sent' - IN_PROGRESS = 'in_progress' - CANCELLED = 'cancelled' - CUSTOMER_MISSING = 'customer_missing' - FINISHED = 'finished' - FAILED = 'failed' **REFUSED_LABELS** : - NOT_IN_A_CATCHEMENT_AREA = 'not_in_a_catchement_area' - ROUTE_COULD_NOT_BE_CALCULATE = 'route_could_not_be_calculate' - NO_DRIVER_AVAILABLE_WITH_MORE_THAN_4_PLACES = 'no_driver_available_with_vehicle_with_more_4_places' - NO_DRIVER_AVAILABLE = 'no_driver_available' - PLANNED_DRIVERS_BUT_NOT_CONNECTED = 'planned_drivers_but_not_conected' - ERROR_ON_ONLINE_AND_NEAR_OF = 'error_on_online_and_near_of' - TOMTOM_QUOTA_REACHED = 'tomtom_error_request_quota_reached' - AUTHORIZATION_REFUSED = 'authorization_refused' The Ride have a array of **Points** with the following attributes : Only one point with type start and only one point with type start - **id** (required, unique, integer) : ID of the Point - **longitude** (required, float) : Longitude of the Point - **latitude** (required, float) : Latitude of the Point - **type_point** (required, string) : Point Type ( 'start' or 'end' ) - **address** (optional, string) : Address of the Point - **address_complement** (optional, string) : Address Complement of the Point - **postal_code** (optional, integer) : Postal Code of the Point - **city** (optional, string) : City of the Point - **country** (optional, string) : Country of the Point - **user_input** (optional, string) : User Input for the Point - **catchement_areas_id** (required, string) : Catchement Areas ID of the Point (fixed by the application) - **ride_id** (required, integer) : The Ride ID (fixed by the application) - **comment** (optional, string): Additionnals informations or comment - **contacts** (optional, array): Array of Contacts (see *Contacts*) The Point may have a array of **Contacts** with the following attributes : The contact on the pick up or drop off point - **email** (optional, string) : Email of the Contact - **first_name** (optional, string) : Fist Name of the Contact - **last_name** (optional, string) : Name of the Contact - **phone** (optional, string) : Phone number of the Contact The Ride have a array of **Passengers** with the following attributes : One main passenger (with main attribute at true) is required to book a ride - **main** (required, boolean) : If the passenger is the main passenger - **first_name** (optional, string) : Fist Name of the Passenger - **name** (optional, string) : Last Name of the Passenger - **phone** (optional, string) : Phone number of the Passenger (in international format) - **email** (optional, string) : Email of the Passenger (required for create user) - **user_id** (optional, integer) : The User ID related to the passenger if exist - **company_relation** (optional, integer) : The type of relation with the company for the passenger (if register is true) - **register** (optional, integer) : for register the passenger The Ride have a hash of **Driver** with the following attributes : This information is provided when the ride is in_progress status - **first_name** (optional, string) : Fist Name of the driver - **phone** (optional, string) : Phone number of the driver - **latitude** (optional, string) : Latitude of driver - **longitude** (optional, string) : Longitude of driver The Ride have a hash of **Vehicle** with the following attributes : This information is provided when the ride is in_progress status - **manufacturer** (optional, string) : Manufacturer of the vehicle - **color** (optional, string) : Color of the vehicle - **model** (optional, string) : Model of the vehicle ## User Rides [/rides?page={page}&per_page={per_page}] **Must be authenticate** ### Get all user rides [GET] + Parameters + page (optional, number, `1`) ... Number of the page to load + per_page (optional, number, `1`) ... Number of items per page to load + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Response 200 (application/json) + Headers Current-Page: 1 Per-Page: 10 Total-Page: 4 Total-Entries: 36 Link: ; rel="first", ; rel="last", ; rel="next" + Body [ { "ride":{ "booking_user_id":11, "company_id":null, "product_id":1, "distance":5.491, "driver_arrival":null, "duration":501, "flight_number":null, "id":25, "nb_passengers":1, "pick_up_or_tacking_out":false, "price":13.2, "real_end":null, "real_start":null, "refused_label":"", "requested_start":"2014-08-13T11:09:00+02:00", "reserved_by_phone":false, "status":"reserved", "train_number":null, "comment":"Siége bébé", "total_price":13.2, "eta":0, "driver": {"first_name":"C\u00e9line", "phone":"0629453814"}, "vehicle": {"manufacturer":"Audi", "color":"gris", "model":"A4"}, "estimated_start":"2014-08-13T11:09:00+02:00", "estimated_end":"2014-08-13T11:17:21+02:00", "promotional_code_used":null, "points":[ { "city":"Villeneuve-d'Ascq", "address":"Rue de l'Harmonie", "type_point":"start", "user_input":"Rue de l'Harmonie Villeneuve-d'Ascq France", "country":"France", "longitude":3.15199, "latitude":50.60511, "postal_code":59650, "comment":"Sonner", "contacts": [ {"last_name":"", "first_name":"", "phone":"", "email":""} ] }, { "city":"Mouscron", "address":"101 Rue de l'Echauffour..e", "type_point":"end", "user_input":"101 Rue de l'Echauffour..e", "country":"Belgium", "longitude":3.181706, "latitude":50.75434, "postal_code":7700, "comment":"Sonner" } ], "passengers":[ { "email":"admin@ecota.co", "first_name":"Jean-Phil", "id":25, "main":true, "name":"Monslip", "phone":"0629453814", "user_id":11 } ] } }, { ... } ] ### Create a ride [POST] + Request + Headers Accept: application/json Content-type: application/json Accept-Language: en + Body { "ride":{ "requested_start":"2014-06-12T16:23:02+02:00", "points":[ { "city":"Villeneuve-d'Ascq", "address":"Rue de l'Harmonie", "type_point":"start", "user_input":"Rue de l'Harmonie Villeneuve-d'Ascq France", "country":"France", "longitude":3.15199, "latitude":50.60511, "postal_code":59650, "comment":"Sonner", "contacts": [ {"last_name":"", "first_name":"", "phone":"", "email":""} ] }, { "city":"Mouscron", "address":"101 Rue de l'Echauffour..e", "type_point":"end", "user_input":"101 Rue de l'Echauffour..e", "country":"Belgium", "longitude":3.181706, "latitude":50.75434, "postal_code":7700, "comment":"Sonner" } ], "booking_user_id":11, "company_id":null, "product_id":1, "nb_passengers":1, "pick_up_or_tacking_out":false, "comment":"Sonner", "flight_number":null, "train_number":null } } + Response 201 (application/json) { "ride":{ "booking_user_id":11, "comment":null, "company_id":null, "created_at":"2014-07-02T17:33:55+02:00", "distance":null, "driver_arrival":null, "duration":null, "flight_number":null, "id":378, "nb_passengers":1, "pick_up_or_tacking_out":false, "price":null, "real_end":null, "real_start":null, "refused_label":null, "requested_start":"2014-07-02T17:33:35+02:00", "reserved_by_phone":false, "status":null, "train_number":null, "updated_at":"2014-07-02T17:33:55+02:00", "total_price":0, "eta":0, "driver": {"first_name":"C\u00e9line", "phone":"0629453814"}, "vehicle": {"manufacturer":"Audi", "color":"gris", "model":"A4"}, "estimated_start":"2014-07-02T17:33:35+02:00", "estimated_end":null, "promotional_code_used":null, "points":[ { "city":"Villeneuve-d'Ascq", "address":"Rue de l'Harmonie", "type_point":"start", "user_input":"Rue de l'Harmonie Villeneuve-d'Ascq France", "country":"France", "longitude":3.15199, "latitude":50.60511, "postal_code":59650, "comment":"Sonner", "contacts": [ {"last_name":"", "first_name":"", "phone":"", "email":""} ] }, { "city":"Mouscron", "address":"101 Rue de l'Echauffour..e", "type_point":"end", "user_input":"101 Rue de l'Echauffour..e", "country":"Belgium", "longitude":3.181706, "latitude":50.75434, "postal_code":7700, "comment":"Sonner" } ], "passengers":[] } } ## User Ride [/rides/{id}] **Must be authenticate** ### Get a ride [GET] + Parameters + id (required, number, `1`) ... Numeric `id` of Ride + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Response 200 (application/json) { "ride":{ "booking_user_id":11, "comment":null, "company_id":null, "product_id":1, "distance":10.079, "driver_arrival":null, "duration":1096, "flight_number":null, "id":322, "nb_passengers":1, "pick_up_or_tacking_out":false, "price":19.8, "real_end":null, "real_start":null, "refused_label":"", "requested_start":"2014-06-12T16:23:02+02:00", "reserved_by_phone":false, "status":"in_progress", "train_number":null, "total_price":19.8, "eta":1357, "driver": {"first_name":"C\u00e9line", "phone":"0629453814"}, "vehicle": {"manufacturer":"Audi", "color":"gris", "model":"A4"}, "estimated_start":"2014-06-12T16:45:39+02:00", "estimated_end":"2014-06-12T17:03:55+02:00", "promotional_code_used":null, "points":[ { "address":"53-57 Rue Mass\u00e9na", "address_complement":null, "catchement_areas_id":[1], "city":"Lille", "country":"France", "id":631, "latitude":50.63217, "longitude":3.054924, "postal_code":59800, "type_point":"start", "user_input":"53-57 Rue Mass\u00e9na", "comment":null, "contacts": [ {"last_name":"", "first_name":"", "phone":"", "email":""} ] }, { "address":"Rue de l'Harmonie", "address_complement":null, "catchement_areas_id":[1], "city":"Villeneuve-d'Ascq", "country":"France", "id":632, "latitude":50.60511, "longitude":3.15199, "postal_code":59650, "ride_id":322, "type_point":"end", "user_input":"Rue de l'Harmonie" } ], "passengers":[ { "email":"admin@ecota.co", "first_name":"Jean-Phil", "id":315, "main":true, "name":"Monslip", "phone":"0629453814", "user_id":11 } ] } } ## Estimate Ride [/rides/{id}/estimate] ### Estimate a ride [GET] + Parameters + id (required, number, `1`) ... Numeric `id` of Ride + Request + Headers Accept: application/json Content-type: application/json Accept-Language: en + Response 200 (application/json) { "ride":{ "booking_user_id":11, "comment":null, "company_id":null, "created_at":"2014-07-02T17:33:55+02:00", "distance":24.248, "driver_arrival":null, "duration":1424, "flight_number":null, "id":378, "nb_passengers":1, "pick_up_or_tacking_out":false, "price":39.8, "real_end":null, "real_start":null, "refused_label":"", "requested_start":"2014-07-02T17:33:35+02:00", "reserved_by_phone":false, "status":"estimated", "train_number":null, "updated_at":"2014-07-02T17:34:02+02:00", "total_price":39.8, "eta":397, "driver": {"first_name":"C\u00e9line", "phone":"0629453814"}, "vehicle": {"manufacturer":"Audi", "color":"gris", "model":"A4"}, "estimated_start":"2014-07-02T17:40:12+02:00", "estimated_end":"2014-07-02T18:03:56+02:00", "promotional_code_used":null, "points":[ { "address":"53-57 Rue Mass\u00e9na", "address_complement":null, "catchement_areas_id":[1], "city":"Lille", "country":"France", "id":631, "latitude":50.63217, "longitude":3.054924, "postal_code":59800, "type_point":"start", "user_input":"53-57 Rue Mass\u00e9na", "comment":null, "contacts": [ {"last_name":"", "first_name":"", "phone":"", "email":""} ] }, { "address":"Rue de l'Harmonie", "address_complement":null, "catchement_areas_id":[1], "city":"Villeneuve-d'Ascq", "country":"France", "id":632, "latitude":50.60511, "longitude":3.15199, "postal_code":59650, "ride_id":322, "type_point":"end", "user_input":"Rue de l'Harmonie" } ] } } ## Reserve Ride [/rides/{id}/reserve] ### Reserve a ride [POST] To book, the ride must belong to the connected user. The ride must have a main passenger at least, the booking user id and the payment hash must be set. **Must be authenticate** + Parameters + id (required, number, `1`) ... Numeric `id` of Ride + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Body { "ride":{ "company_id":3, "comment":"", "flight_number": "", "train_number": "", "payment":{ "method":"transfer", "by":"company", "to":"ecotaco", "credit_card_id":null, "token"=>"tok_15zPLk2ANDqoHcakJbw6B43p", "label"=>"Perso", "save_card"=>"yes" }, "passengers":[ { "main":true, "user_id":11 }, { "email":"passager@gmail.com", "first_name":"Non registered", "main":false, "name":"Passenger", "phone":"0606060606", "company_relation": null, "register": false }, { "email":"passager2@gmail.com", "first_name":"To registered", "main":false, "name":"Passenger", "phone":"0606060606", "company_relation": "collaborator", "register": true } ] } } + Response 200 (application/json) { "ride":{ "booking_user_id":11, "comment":null, "company_id":null, "created_at":"2014-07-02T17:33:55+02:00", "distance":24.248, "driver_arrival":null, "duration":1424, "flight_number":null, "id":378, "nb_passengers":1, "pick_up_or_tacking_out":false, "price":39.8, "real_end":null, "real_start":null, "refused_label":"", "requested_start":"2014-07-02T17:35:27+02:00", "reserved_by_phone":false, "status":"sent", "train_number":null, "updated_at":"2014-07-02T17:35:30+02:00", "total_price":39.8, "eta":397, "driver": {"first_name":"C\u00e9line", "phone":"0629453814"}, "vehicle": {"manufacturer":"Audi", "color":"gris", "model":"A4"}, "estimated_start":"2014-07-02T17:42:04+02:00", "estimated_end":"2014-07-02T18:05:48+02:00", "promotional_code_used":null, "points":[ { "address":"53-57 Rue Mass\u00e9na", "address_complement":null, "catchement_areas_id":[1], "city":"Lille", "country":"France", "id":631, "latitude":50.63217, "longitude":3.054924, "postal_code":59800, "type_point":"start", "user_input":"53-57 Rue Mass\u00e9na", "comment":null, "contacts": [ {"last_name":"", "first_name":"", "phone":"", "email":""} ] }, { "address":"Rue de l'Harmonie", "address_complement":null, "catchement_areas_id":[1], "city":"Villeneuve-d'Ascq", "country":"France", "id":632, "latitude":50.60511, "longitude":3.15199, "postal_code":59650, "ride_id":322, "type_point":"end", "user_input":"Rue de l'Harmonie" } ], "passengers":[ { "main":true, "user_id":11 }, { "email":"passager@gmail.com", "first_name":"Non registered", "main":false, "name":"Passenger", "phone":"0606060606", "company_relation": null, "register": false }, { "email":"passager2@gmail.com", "first_name":"To registered", "main":false, "name":"Passenger", "phone":"0606060606", "company_relation": "collaborator", "register": true } ] } } ## Cancel Ride [/rides/{id}/cancel] ### Cancel a Ride [GET] **Must be authenticate** + Parameters + id (required, number, `1`) ... Numeric `id` of Ride + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Response 200 (application/json) { "ride":{ "booking_user_id":11, "comment":null, "company_id":null, "created_at":"2014-07-02T17:33:55+02:00", "distance":24.248, "driver_arrival":null, "duration":1424, "flight_number":null, "id":378,"nb_passengers":1, "pick_up_or_tacking_out":false, "price":39.8, "real_end":null, "real_start":null, "refused_label":"", "requested_start":"2014-07-02T17:35:27+02:00", "reserved_by_phone":false, "status":"cancelled", "train_number":null, "updated_at":"2014-07-02T17:35:34+02:00", "total_price":39.8, "eta":397, "driver": {"first_name":"C\u00e9line", "phone":"0629453814"}, "vehicle": {"manufacturer":"Audi", "color":"gris", "model":"A4"}, "estimated_start":"2014-07-02T17:42:04+02:00", "estimated_end":"2014-07-02T18:05:48+02:00", "promotional_code_used":null, "points":[ { "address":"53-57 Rue Mass\u00e9na", "address_complement":null, "catchement_areas_id":[1], "city":"Lille", "country":"France", "id":631, "latitude":50.63217, "longitude":3.054924, "postal_code":59800, "type_point":"start", "user_input":"53-57 Rue Mass\u00e9na", "comment":null, "contacts": [ {"last_name":"", "first_name":"", "phone":"", "email":""} ] }, { "address":"Rue de l'Harmonie", "address_complement":null, "catchement_areas_id":[1], "city":"Villeneuve-d'Ascq", "country":"France", "id":632, "latitude":50.60511, "longitude":3.15199, "postal_code":59650, "ride_id":322, "type_point":"end", "user_input":"Rue de l'Harmonie" } ], "passengers":[ { "main":true, "user_id":11 }, { "email":"passager@gmail.com", "first_name":"Non registered", "main":false, "name":"Passenger", "phone":"0606060606", "company_relation": null, "register": false }, { "email":"passager2@gmail.com", "first_name":"To registered", "main":false, "name":"Passenger", "phone":"0606060606", "company_relation": "collaborator", "register": true } ] } } ## Cancel fee [/rides/{id}/cancel_fees] ### Cancel fee of a Ride [GET] **Must be authenticate** + Parameters + id (required, number, `1`) ... Numeric `id` of Ride + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Response 200 (application/json) { "fee_percent": 0, "fee_total": 0, "message": "No cancellation fee." } # Group Promotional Codes Promotional Codes resource The Promotional Codes ressource has the following attributes : - **id** (required, unique, integer) : ID of the affected promotional code - **status** (required, string) : Status of the affected promotional code ('used' or 'notused') - **code** (required, string) : The code of the promotional code - **label** (required, string) : Label of the promotional code - **promotional_type** (required, string) : The type of promotional code ('pourcent', 'amount' or 'km') - **value** (required, float) : the value of the promotional code - **start_date** (required, date) : Start Date for the promotional code - **end_date** (required, date) : End Date for the promotional code ## User Promotional Codes [/promotional_codes] **Must be authenticate** ### Get all promotional codes for user [GET] + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx Accept-Language: en + Response 200 (application/json) [ { "promotional_code":{ "id":4, "created_at":"2014-07-02T17:38:42+02:00", "status":"notused", "code":"PROMOCODE", "label":"Parrainage chauffeur", "promotional_type":"pourcent", "value":10.0, "start_date":"2012-11-01T00:00:00+01:00", "end_date":"2099-01-31T00:00:00+01:00" } } ] ### Add a promotional code [POST] + Request + Headers Accept: application/json Content-type: application/json Authorization: Token token=xxxx + Body { "promotional_code":{ "code":"PROMOCODE" } } + Response 201 # Group Adresses The Addresses use google API for searching places, and also user favorite or best places. ## Autocomplete places [/addresses/places_autocomplete] The Autocomplete places ressource has the following attributes : - **description** (required, string) : The description of the place - **reference** (required, string) : The identifier of the place - **type** (required, string) : The type of places (only 'places' available today) ### Get autocomplete places [POST] For searching places just send the following attributes : - **longitude** (optional, float) : The location longitude for the seach - **latitude** (optional, float) : The location latitude for the seach - **search** (required, string) : The search text (most than 3 char) + Request + Headers Accept: application/json Content-type: application/json Accept-Language: en + Body { "longitude":3.151989877223969, "latitude":50.60510937879743, "search":"Gare lille" } + Response 200 (application/json) [ { "description":"Gare Lille Flandres, Lille, France", "reference":"CmRbAAAAOI8tIyPFtrk_6DbYRY6GWJnrDEbG9TW_gfr2wHXBdUSK72LNE7AQ8c6COyxeIiylJpkiIcY3_4zXPVxuTP4bdWXdYVelU469ZfsFne5yv2-oUHC2sSRZmgPMRnWluTrAEhAPiIR9rqOkkz0HVlgfuZcBGhQWIkPEpQ7t795b7Z1Pbm8FRk61MQ", "type":"places" },{ ... } ] ## Autocomplete places details [/addresses/places_details] The Autocomplete places details ressource has the following attributes : - **reference** (required, string) : The identifier of the place - **lat** (required, float) : The location latitude of the place - **lng** (required, float) : The location longitude of the place - **street_number** (optional, string) : The street number of the place - **street** (optional, string) : The street of the place - **city** (optional, string) : The city of the place - **region** (optional, string) : The region of the place - **postal_code** (optional, string) : The postal code of the place - **country** (optional, string) : The country of the place - **name** (required, string) : The name of the place - **vicinity** (optional, string) : The vicinity of the place - **formatted_address** (optional, string) : The formated address of the place ### Get autocomplete places details [POST] + Request + Headers Accept: application/json Content-type: application/json Accept-Language: en + Body { "reference":"CmRbAAAAOI8tIyPFtrk_6DbYRY6GWJnrDEbG9TW_gfr2wHXBdUSK72LNE7AQ8c6COyxeIiylJpkiIcY3_4zXPVxuTP4bdWXdYVelU469ZfsFne5yv2-oUHC2sSRZmgPMRnWluTrAEhAPiIR9rqOkkz0HVlgfuZcBGhQWIkPEpQ7t795b7Z1Pbm8FRk61MQ" } + Response 200 (application/json) { "lat":50.637528, "lng":3.070923, "street_number":null, "street":null, "city":"Lille", "region":null, "postal_code":"59800", "country":"France", "name":"Gare Lille Flandres", "reference":"CnRtAAAAnFiSmz9OFYi4ee_IeN8WgX0kjB50NtCCTTxJdTQzz9F33kC5eit_Z2DIW-MyrbwN9_cJ7lkBznVZ6o_Da52wCTzmKvbHvImkYTD24su-vjUfszNnJRWnV2M0ckZEdJ5vpG1S02m6jgzJ_FmOnImI2BIQh6x7kos53RZHQujnMlRkABoU28Ivbhnf72dh3L6yfqeB-oaIHYs", "vicinity":"Lille", "formatted_address":"Lille, France" } # Group Catchement Areas Catchement area resource The catchement area ressource has the following attributes : - **id** (required, unique, integer) : ID of the catchement area - **label** (required, string) : Label - **launch_at** (required, date) : Launch date of catchement area - **coordinates** (required, array) : coordinates **Coordinates** : - **id** (required, unique, integer) : ID of the coordinates - **latitude** (required, float) : Latitude of the coordinates - **longitude** (required, float) : Longitude of the coordinates - **rank** (required, integer) : Rank to order coordinates of th catchement area We provide json or geojson format ## Collection of catchement areas [/catchement_areas] ### List all catchement areas [GET] + Request + Headers Accept: application/json Content-type: application/json Accept-Language: en + Response 200 (application/json) [ { "catchement_area":{ "id":1, "label":"Lille", "launch_at":"2014-06-03T10:20:59+02:00", "lat_lngs": [ {"lat_lng":{"id":1,"latitude":50.7209296468011,"longitude":2.85468817138667,"rank":1}}, {"lat_lng":{"id":2,"latitude":50.6948395473376,"longitude":2.82172918701167,"rank":2}}, {"lat_lng":{"id":3,"latitude":50.6582890133086,"longitude":2.75512457275386,"rank":3}}, {"lat_lng":{"id":4,"latitude":50.6391321348964,"longitude":2.69401312255854,"rank":4}}, {"lat_lng":{"id":5,"latitude":50.5240267810597,"longitude":2.80318975830073,"rank":5}}, {"lat_lng":{"id":6,"latitude":50.4803527849672,"longitude":2.92953253173823,"rank":6}}, {"lat_lng":{"id":7,"latitude":50.4742352023462,"longitude":3.02772283935542,"rank":7}}, {"lat_lng":{"id":8,"latitude":50.4571891900493,"longitude":3.25980902099604,"rank":8}}, {"lat_lng":{"id":9,"latitude":50.5558832982945,"longitude":3.31817388916011,"rank":9}}, {"lat_lng":{"id":10,"latitude":50.6039001101805,"longitude":3.43709230804438,"rank":10}}, {"lat_lng":{"id":11,"latitude":50.6888041447647,"longitude":3.34576845550532,"rank":11}}, {"lat_lng":{"id":12,"latitude":50.7431491302235,"longitude":3.32585573577876,"rank":12}}, {"lat_lng":{"id":13,"latitude":50.8208614514023,"longitude":3.11780214691157,"rank":13}}, {"lat_lng":{"id":14,"latitude":50.7431491302235,"longitude":2.89120912933345,"rank":14}} ], "authorization_level":"authorized", } }, { ... } ] + Response 200 (application/vnd.geo+json) { "type":"FeatureCollection", "features":[ { "type":"Feature", "properties":{ "id":4, "label":"Lille forbidden" }, "geometry":{ "type":"Polygon", "coordinates":[[ [2.653829,50.642377],[2.648937,50.627461],[2.780256,50.586548],[2.900204,50.663704],[2.831196,50.705252],[2.778325,50.700468],[2.653829,50.642377] ]] } }, { "type":"Feature", "properties":{ "id":1, "label":"Lille" }, "geometry":{ "type":"Polygon", "coordinates":[[ [2.85468817138667,50.7209296468011],[2.82172918701167,50.6948395473376],[2.75512457275386,50.6582890133086],[2.69401312255854,50.6391321348964],[2.80318975830073,50.5240267810597],[2.92953253173823,50.4803527849672],[3.02772283935542,50.4742352023462],[3.25980902099604,50.4571891900493],[3.31817388916011,50.5558832982945],[3.43709230804438,50.6039001101805],[3.34576845550532,50.6888041447647],[3.32585573577876,50.7431491302235],[3.11780214691157,50.8208614514023],[2.89120912933345,50.7431491302235],[2.85468817138667,50.7209296468011] ]] } }, { "type":"Feature", "properties":{ "id":2, "label":"Toulouse" }, "geometry":{ "type":"Polygon", "coordinates":[[ [1.34239196777344,43.665388118352],[1.37603759765625,43.7284369679607],[1.54838562011719,43.6713483259687],[1.54220581054688,43.4947753137023],[1.34925842285156,43.5002543647898],[1.22085571289062,43.5788986029537],[1.34239196777344,43.665388118352] ]] } }, { "type":"Feature", "properties":{ "id":3, "label":"Lille exclusive" }, "geometry":{ "type":"Polygon", "coordinates":[[ [2.874408,50.702182],[2.918353,50.753905],[2.833212,50.772398],[2.812956,50.702651],[2.861475,50.656127],[2.979921,50.661786],[2.874408,50.702182] ]] } } ] } ## Catchement Area [/catchement_areas/{id}] + Parameters + id (required, number, `1`) ... Numeric `id` of the Catchement Area ### Get a Catchement Area [GET] + Request + Headers Accept: application/json Content-type: application/json Accept-Language: en + Response 200 (application/json) { "catchement_area":{ "id":1, "label":"Lille", "launch_at":"2014-06-03T10:20:59+02:00", "lat_lngs": [ {"lat_lng":{"id":1,"latitude":50.7209296468011,"longitude":2.85468817138667,"rank":1}}, {"lat_lng":{"id":2,"latitude":50.6948395473376,"longitude":2.82172918701167,"rank":2}}, {"lat_lng":{"id":3,"latitude":50.6582890133086,"longitude":2.75512457275386,"rank":3}}, {"lat_lng":{"id":4,"latitude":50.6391321348964,"longitude":2.69401312255854,"rank":4}}, {"lat_lng":{"id":5,"latitude":50.5240267810597,"longitude":2.80318975830073,"rank":5}}, {"lat_lng":{"id":6,"latitude":50.4803527849672,"longitude":2.92953253173823,"rank":6}}, {"lat_lng":{"id":7,"latitude":50.4742352023462,"longitude":3.02772283935542,"rank":7}}, {"lat_lng":{"id":8,"latitude":50.4571891900493,"longitude":3.25980902099604,"rank":8}}, {"lat_lng":{"id":9,"latitude":50.5558832982945,"longitude":3.31817388916011,"rank":9}}, {"lat_lng":{"id":10,"latitude":50.6039001101805,"longitude":3.43709230804438,"rank":10}}, {"lat_lng":{"id":11,"latitude":50.6888041447647,"longitude":3.34576845550532,"rank":11}}, {"lat_lng":{"id":12,"latitude":50.7431491302235,"longitude":3.32585573577876,"rank":12}}, {"lat_lng":{"id":13,"latitude":50.8208614514023,"longitude":3.11780214691157,"rank":13}}, {"lat_lng":{"id":14,"latitude":50.7431491302235,"longitude":2.89120912933345,"rank":14}} ], "authorization_level":"authorized", } } + Response 200 (application/vnd.geo+json) { "type":"Feature", "properties":{ "id":1, "label":"Lille" }, "geometry":{ "type":"Polygon", "coordinates":[[ [2.85468817138667,50.7209296468011], [2.82172918701167,50.6948395473376], [2.75512457275386,50.6582890133086], [2.69401312255854,50.6391321348964], [2.80318975830073,50.5240267810597], [2.92953253173823,50.4803527849672], [3.02772283935542,50.4742352023462], [3.25980902099604,50.4571891900493], [3.31817388916011,50.5558832982945], [3.43709230804438,50.6039001101805], [3.34576845550532,50.6888041447647], [3.32585573577876,50.7431491302235], [3.11780214691157,50.8208614514023], [2.89120912933345,50.7431491302235], [2.85468817138667,50.7209296468011] ]] } } # Group Products Product resource The product ressource has the following attributes : - **id** (required, unique, integer) : ID of the product - **product_type** (required, string) : Product type (See *TYPES*) - **name** (required, dastringte) : Name of product - **description** (required, string) : Description of product **TYPES** : - transport_person : On demand transport person - package_delivery : Package delivery ## Collection of products [/products] ### List all products [GET] + Request + Headers Accept: application/json Content-type: application/json Accept-Language: en + Response 200 (application/json) [ { "product":{ "id":1, "product_type":"transport_person", "name":"Transport \u00e0 la demande", "description":"Transport de personne \u00e0 la demande (VTC / DREAL / Taxi)" } }, { "product":{ "id":2, "product_type":"package_delivery", "name":"Transport de colis", "description":"Transport de colis" } } ] ## Product [/products/{id}] + Parameters + id (required, number, `1`) ... Numeric `id` of the Product ### Get a Product [GET] + Request + Headers Accept: application/json Content-type: application/json Accept-Language: en + Response 200 (application/json) { "product":{ "id":1, "product_type":"transport_person", "name":"Transport \u00e0 la demande", "description":"Transport de personne \u00e0 la demande (VTC / DREAL / Taxi)" } }