## General Hi, i am the CallABike Bikesharing API implemented in [TOMP](https://github.com/TOMP-WG/TOMP-API). ## Changelog. ### 1.6.26 New data provided * New callback: Callback send after booking started * Bookings can be filtered by `customer-id` (`GET /bookings?customer-id=...`) ### 1.6.25 New data provided * New indication: Is a bike positioned at a station while the rent is paused? (`isAtStation` in the `PAUSE` leg event) * New bike limit in pricing plans: how many bikes can a customer rent at a time? (`extraInfo.bikeLimit` in `GET /operator/pricing-plans`) ### 1.6.23 Provided leg event examples More leg event examples. ### 1.6.22 Provided leg event details Leg events contains more details in the ```comment```field. ### 1.6.16 Provided test locks Provided test locks and explanation via ```/extensions``` endpoint (only exposed on test stage) ### 1.6.0 TOMP 1.6 introduced. We adapted the TOMP 1.6 Standard, please change the version `Api-Version: 1.6.0` in the HTTP Headers. ## Quickstart guide: open a lock. ### 0. Very important When creating a new organisation in the API Marketplace, talk to DB Connect about the correct naming. Each organization has a technical name which is derived from the org name and can not be changed. We use the technical name for internal and *hardcoded* mapping. ### 1. Fetch a tariff To prepare a customer for your booking, please fetch the available tariffs first. Done via ```GET /operator/pricing-plans```. Fetch the *planId* from the response. That is the tariff the customer gets registered later on in step 2. ### 2. Register a customer To register a customer for your booking, use the following endpoint: ```POST /customers```. The MaaS platform must provide a unique *customer.Id* within its system, that we receive with this call. This is the customer id for all your requests, e.g. *one-stop-booking* . You _can_ provide a callback url that then will be informed, once the customer has been successfully created. The information in the extraInfo response is are internal ids from the TO that might be stored on the MaaS provider side for reference. ### 3. Open a bike To open a bike, use the following endpoint: ```POST /one-stop-booking```. On TEST environment, you can use one of the simulated locks, on production real bikes gets opened. Remember the booking UID from the response. #### Distance check Depending how bikes are opened with the *accessMethod* of the user, a distance check is done, i.e. distance between bike position and user is validated. This include all actions that will open the lock (i.e. one-stop-booking and resume pause event). If the user position is too far away from the bike, opening the bike will fail with an error (see Trip execution errors). The threshold varies depending on the bike and city. The accessMethod: _QRCODE_ will open *without* distance check. The accessMethod *NUMBERPAD* will execute a distance check. ### 4. Pause and resume Pause and resume of the booking is done via ```POST /legs/id/events```. Distance Check is done here during the opening of a bike, depending on the _accessMethod_ of the booking. ### 5. Close a bike To close the bike, simply physically Done via ```GET /operator/pricing-plans```.close the lock on your bike. If you use a simulated bike, see the ```/extensions``` endpoint at the TEST stage. ### 6. Fetch the Booking Fetch your finished booking via ```/bookings/{uid}``` from step 3. ## Error Handling Errors are marked by the HTTP response codes. HTTP codes 40x, 500x mark those. ### Requests take too long - HTTP Error 503 On several requests, we support a retry pattern: if a request takes too long, we respond with HTTP 503, you can re-send your request once. ### Error Responses The error responses follows the [TOMP Error Code Definitions](https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP#module-number-table) Error Responses are grouped by errorCodes (numbered) and more detailed with error details (string) ``` { "errorCode": 4204, "type": "Illegal operation", "title": "Bicycle not available.", "detail": "bicycle.not-available" } ``` ### Error Code List

▶ Show the detailed list of error codes

We support the following types of error code ranges and specialized error keys within that: ### Possible Error Code Numbers and their meanings 3004 - Booking Error (Illegal Operation) 4004 - Trip Execution Errors (Illegal Operation) 4005 - Trip Execution Errors (Technical) 4202 - Trip Expiration Errors 4204 - Trip Functional Errors 7005 - Internal Error 8001 - Missing Payload Error 8002 - Invalid Payload Error 8003 - Already exists/canceled Error 8004 - Illegal operation Error #### `3004` - Booking Error (Illegal Operation) auth.unauthorized - this request was unauthorized - http 400 #### `4004` - Trip Execution Errors (Illegal Operation) bike.out-of-range - bike could not be opened, out of rage - http 400 #### `4005` - Trip Execution Errors (Technical) bike.open-error - bike could not be opened, technical reason - http 400 #### `4202` - Trip Expiration Errors leg.set-in-pause.duplicated - there is already a pause leg - http 409 leg.set-in-use.expired - the leg expired - http 406 booking.expired - the booking expired - http 400 leg.set-state-change.duplicated - the leg state is duplicated - http 409 leg.set-in-pause.expired - the leg set in pause expired - http 406 user.not-found - the user was not found - http 400 bicycle.not-available - the bicycle is not available - http 400 customer.is-blocked - the customer is blocked and not allowed to book a bicycle - http 400 customer.bike-limit-reached - the customer has reached it's limit of rental bikes - http 400 #### `4204` - Trip Functional Errors user.not-found - the user was not found for creating this trip - http 400 bicycle.not-available - the bicycle is not available - http 400 bicycle.not-found - the bicycle was not found - http 400 #### `7005` - Internal Error error.unknown - unspecified internal error #### `8001` - Customer Missing Payload Error customer.missing-payload-param - missing parameter for customer - http 400 #### `8002` - Customer Invalid Payload Error customer.field-does-not-match-required-pattern - customer parameter does not match - http 400 #### `8003` - Customer Already exists/canceled Error customer.already-exists - customer already exists - http 409 customer.already-canceled - customer already canceled - http 409 #### `8004` - Customer Illegal operation Error customer.value-does-not-exists - customer value not exists - http 400

## Callbacks

▶Show me the Callbacks details

We provide several PushEvents if the MaasProvider provides a CallbackUrl. Currently Callbacks for the following Event types are implemented: ## Booking Events * CANCEL * DENY * EXPIRED A Booking Event is pushed to `/bookings//events` structured as follows: ``` { "operation": DENY, "origin": "TO" } ``` ## Leg Events * SET_IN_USE * FINISH * PAUSE A Leg Event is pushed to `/legs//events` and can used to receive events from the bike. ### SET_IN_USE The event `SET_IN_USE` is sent in two cases. We provide the following information in the `comment` field to tell them apart: * comment=`null` - the booking has started. * comment=`RESUMED` - regular resume of the pause. Lock opens. **1. Booking started** (`comment` is `null`): the bike was opened and the booking has started. ``` { "time": "2025-10-05T15:28:25.480965612Z", "event": "SET_IN_USE", "comment": null, "asset": { "overriddenProperties": { "location": { "coordinates": { "lng": 12.28997778, "lat": 53.43872889 } }, "meta": null } } } ``` **2. Resumed from pause** (`comment`=`RESUMED`): the customer resumed a paused booking, the lock opens. ``` { "time": "2025-10-05T15:28:25.480965612Z", "event": "SET_IN_USE", "comment": "RESUMED", "asset": { "overriddenProperties": { "location": { "coordinates": { "lng": 12.28997778, "lat": 53.43872889 } }, "meta": null } } } ``` #### FINISH The event `FINISH` marks the end of a booking by closing the lock by the user: ``` { "time": "1970-01-01T00:00:00.000Z", "event": "FINISH", "position": { "type": "Point", "coordinates": [100.0, 0.0] } } ``` #### PAUSE The event `PAUSE` informs the MP about the start of a pause. We distinguish three assetClasses: * Regular pause of the booking, initiated by the user. * Resume of a pause was rejected, for example because the lock did not open. * Start of a forced pause because the user locked the bike at an illegal position. ``` { "time": "1970-01-01T00:00:00.000Z", "event": "PAUSE", "comment:"", "position": { "type": "Point", "coordinates": [100.0, 0.0] }, "asset": { "overriddenProperties": { "meta": { "isAtStation": false } } } ``` We provide the following information in the `comment` field: * comment=`RESUME_REJECTED` - resume of pause failed because bike cannot be opened - retry required. Lock stays closed. * comment=`FORCED` - user closed lock, but bike was returned on illegal position. This event informs the MP that the booking is not finished and the user is running into a forced pause. After 24 hours, this booking will finish. Lock stays closed. Additionally, `isAtStation`=`true`|`false` indicates whether the bike is currently positioned at a station, i.e. whether ending the rent would result in a service fee. ## Payment Events A Payment Event is pushed to `/payment//claim-extra-costs` and structured as follows: ``` { "amount": 1.5, "amountExVat": 0.19, "currencyCode": "EUR", "vatRate": 0.19, "vatCountryCode": "DE", "category": "FARE", } ``` ## Registration Events * CREATED * TO_PENDING_VALIDATION * BLOCKED * ACTIVE A Registration Event is pushed to `/customers//events` and structured as follows: ``` { "id": , "status": "TO_PENDING_VALIDATION" } ```