Starting and ending a trip¶

Starting a trip¶

In order to start a trip in the name of a Cyclist, he needs to have all those requirements checked

his registration to the program is active
his abonnement status is either active or waiting_validation with the forfait allowing to rent during the validation period
you send a POST request to /trips

Body parameters¶

{
    "cyclist": "cycl_1234567890",
    "origin": "web",
    "auto_unlock": false,
    "vehicule": "vhcl_1234567890"
}

Response¶

We only present here the main data of the response, to get the full response data list, check the api-maas/trips

{
    "pin": 1234,
    "cyclist": "cycl_abcd12345",
    "vehicule_number": 16,
    "forfait": "forf_abcd12345"
}

End of the trip¶

A trip is ended when the cyclist secure a bike on a dock. Here is what’s happening then.

The vehicle first closes its lock
Then reads the RFID tag of the dock
Finally it sends the lock status and the RFID via iot, triggering a termination request.

Warning

If trip is ended with a duration less than 2 minutes (user doesn’t remove the chain or anything), it’s not charged.

Termination request¶

The termination request is the only way to end a trip. As many problems car occur during the process (failing connexion, failing hardware, etc.), we are dividing it in a few steps.

A termination request can be created by the system like in this case, or by a cyclist through the app. Here we will only see the termination request by the system when everything works fine. To learn more about the full process, check the termination request section here.

The lock = locked information arrives in our API-IOT, a termination request is created
The RFID tag is received by API-IOT, the termination request is accepted
The trip status is completed (but not billed yet)
A webhook trip.terminated is sent
A webhook trip.updated is sent once the billing is done

Trip completed webhooks¶

Here is an example of a trip.terminated webhook. You can see that the amount field isn’t filled yet. If you want to know more about our events, check out the wekhook documentation

{
    "code": 200,
    "created": 1631188768,
    "data": {
        "agent": null,
        "agent_email": null,
        "agent_name": null,
        "agent_phone_number": null,
        "agent_role": null,
        "amount": null,
        "amount_cyclist": null,
        "amount_discounted": null,
        "amount_live": 600,
        "amount_organization": null,
        "amount_refundable_max": null,
        "amount_refunded": null,
        "assist": null,
        "assist_level": null,
        "created": 1631185383,
        "cyclist": "cycl_abcd1234",
        "cyclist_email": "foo@bar.com",
        "cyclist_name": "Foo Bar",
        "cyclist_phone_number": "+33683859355",
        "cyclist_role": "cyclist",
        "deposit": null,
        "duration": 3361,
        "duration_total": 3361,
        "end_caddie": null,
        "end_dock": null,
        "end_dockless_area": null,
        "end_name": "Showroom Ecovelo",
        "end_photo": null,
        "end_station": "stn_9MBLkbA8vPV5hMvkvjbYHH",
        "end_timestamp": 1631188744,
        "error_code": null,
        "error_message": null,
        "facture": null,
        "forfait": "forf_RwrGaDVPjGGEvceS58JZaZ",
        "forfait_name": "Flash",
        "id": "trip_dtLiRpoXyhV3QTrTM3T5JC",
        "invoice_item": null,
        "number": 14203,
        "object": "trip",
        "organization": null,
        "organization_percent": null,
        "origin": "web",
        "payment_status": null,
        "pin": "4596",
        "positions": {
        "data": [],
        "has_more": false,
        "object": "list",
        "total": 0
        },
        "price_rent": null,
        "price_total": null,
        "program": "preprod",
        "refunded": false,
        "simultaneous_rent_counter": null,
        "simultaneous_reservation_counter": null,
        "start_caddie": null,
        "start_dock": null,
        "start_dockless_area": null,
        "start_name": "2, Boulevard Saint-Aignan, Mellinet, Dervallières - Zola",
        "start_station": null,
        "start_timestamp": 1631185383,
        "status": "completed",
        "termination_requested_timestamp": 1631188744,
        "termination_requests": {
        "data": [
            {
            "cancelled_at": null,
            "cancelled_reason": null,
            "created": 1631188774,
            "description": "caddie_with_station | Le véhicule a été rattaché à un autre véhicule, lui même rattaché à une station.",
            "end_code": null,
            "id": "treq_dtPYAi6vKMikGVnLeBJa6q",
            "latitude": null,
            "longitude": null,
            "object": "termination_request",
            "origin": "system",
            "photo": null,
            "status": "accepted",
            "trip": "trip_dtLiRpoXyhV3QTrTM3T5JC"
            },
            {
            "cancelled_at": null,
            "cancelled_reason": null,
            "created": 1631188767,
            "description": "boitier_fdl | Le véhicule a terminé son trajet.",
            "end_code": null,
            "id": "treq_AQt5MmHqjs9BNb6a6uxQgM",
            "latitude": null,
            "longitude": null,
            "object": "termination_request",
            "origin": "system",
            "photo": null,
            "status": "accepted",
            "trip": "trip_dtLiRpoXyhV3QTrTM3T5JC"
            },
            {
            "cancelled_at": null,
            "cancelled_reason": null,
            "created": 1631188744,
            "description": "boitier_fdl | Le véhicule a terminé son trajet.",
            "end_code": null,
            "id": "treq_cMeii3uf6GiEZYzPyccUC5",
            "latitude": null,
            "longitude": null,
            "object": "termination_request",
            "origin": "system",
            "photo": null,
            "status": "accepted",
            "trip": "trip_dtLiRpoXyhV3QTrTM3T5JC"
            }
        ],
        "has_more": false,
        "object": "list",
        "total": 3
        },
        "time_discounted": null,
        "user": "cycl_abcd1234",
        "user_email": "foo@bar.com",
        "user_name": "Foo Bar",
        "user_phone_number": "+33683859355",
        "user_role": "cyclist",
        "vehicule": "vhcl_5agr5XFQ2Hxu9c6E6MXpC4",
        "vehicule_number": 468,
        "vehicule_type": "vae"
    },
    "error": null,
    "expiration": 1640865578,
    "id": "event_mx4kPXFmdLZfKNeLKhE98V",
    "object": "event",
    "previous": {},
    "program": "preprod",
    "related_objects": [
        "cycl_abcd1234",
        "forf_RwrGaDVPjGGEvceS58JZaZ",
        "trip_dtLiRpoXyhV3QTrTM3T5JC",
        "vhcl_5agr5XFQ2Hxu9c6E6MXpC4"
    ],
    "topic": "trip.terminated",
    "updated": {}
}