## General Hi, i am the CallABike Bikesharing API implemented in [TOMP](https://github.com/TOMP-WG/TOMP-API). ## Basic Usage The basic usage is described in each section of the requests. Please check the detailed usage there. ## Changelog.

Show the changelog

### 1.6.1 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.

Show show me the quickstart

### 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```. Fetch the *customerId* from that response. This is the customer Id for your booking request. This customer is then created for your MaaS platform. ### 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. ### 4. Close a bike To close the bike, simply close the lock on your bike. If you use a simulated bike, see the ```/extensions``` endpoint at the TEST stage. ### 5. 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" } ``` 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 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 * PAUSE * FINISH A Leg Event is pushed to `/legs//events` and structured as follows: ``` { "time": "1970-01-01T00:00:00.000Z", "event": "FINISH", "position": { "type": "Point", "coordinates": [100.0, 0.0] } } ``` ## 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" } ```