# Emmy

[Emmy](https://emmy-sharing.de/) is a german rental service for electric 
motorbikes 🛵 (also called scooter, the wording is a mess). Currently, Emmy 
offers its service in Berlin, Hamburg and Munich.

## General stuff
API is based on exchanging json messages.
**Base url**: `https://api.emmy.ninja`

Below you find most API calls that the official emmy android app uses. However, 
some of them are not really tested. Additionally, there are even more API calls 
mostly related to the verification process (Upload video etc).

## Auth

### Login
```bash
curl --location --request POST 'https://api.emmy.ninja/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "password": "pass",
    "username": "email"
}'
```

You'll receive a bunch of information related to your user. For authentication 
the `accessToken` is needed. With that, you can create the authorization header 
as following: `Authorization: Bearer $ACCESS_TOKEN`. Sometimes you need the 
`signupToken` instead of the accessToken. When ever this is needed the 
authorization is written that way: `Authorization: Bearer $SIGNUP_TOKEN`

### Logout
There is also an option to log out (invalidate the accessToken?)
tbc

### Reset Password

```bash
curl --location --request POST 'https://api.emmy.ninja/reset-password' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "mail@example.org"
}'
```

### Renew Password

```bash
curl --location --request POST 'https://api.emmy.ninja/users/$USER_ID/password' \
--header 'Authorization: Bearer $SIGNUP_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "mail@example.org",
    "oldPassword": "foo",
    "newPassword": "bar"
}'
```


## Vehicle related information
Some requests work without suppling authorization as they are public 
information.

### List vehicles
Lists all vehicles that are available for renting.

```bash
curl --location --request GET 'https://api.emmy.ninja/vehicles'
```

### Show vehicle

Show information for a specific vehicle by `$VEHICLE_ID`. Get the ID by 
calling the general `vehicles` endpoint. Note: The ID seems to be 
auto-increment. You'll find more vehicles by simply incrementing the ID - even 
those that are currently not available for rental.

```bash
curl --location --request GET 'https://api.emmy.ninja/vehicles/$VEHICLE_ID'
```

### List Vehicle Types

```bash
curl --location --request GET 'https://api.emmy.ninja/vehicles/types'
```

### Send damage report

When you notice a damage on a vehicle before you go on a ride, you can send a 
damage report. Note, that you need a rentalId for it that you obtain when 
[creating a rental](#create-rental) on a vehicle.

```bash
curl --location --request POST 'https://api.emmy.ninja/vehicles/$VEHICLE_ID/damages' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data-raw '{
    "description": "A human readable description of the damage",
    "damages": [
        {
            "position": "foo",
            "type": "bar"
        }
    ],
    "rentalId": $RENTAL_ID
}' 
```


## Rental

### Create Rental
In order to create a rental, you need a `$VEHICLE_ID`.

```bash
curl --location --request POST 'https://api.emmy.ninja/vehicles/$VEHICLE_ID/rentals' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{}'
```
This starts a reservation and you have 15 min time to actually start the rental.
In the response you receive a rentalId that you have to store as `$RENTAL_ID` 
for later usage.

### Start Rental

:warning: Calling this method successfully will charge your account! You have to
pay the price that is given in the [vehicle information](#show-vehicle) as 
`pricingDuringRide`.

```bash
curl --location --request POST 'https://api.emmy.ninja/vehicles/$VEHICLE_ID/rentals/$RENTAL_ID/start' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "isCarClean": false,
    "isCarDamaged": false,
    "isDriversLicenceWithUser": false
}'
```

Note: you can set all values to `true` or `false`. The API doesn't care and will
start the rental either way.

### Stop Rental

```bash
curl --location --request POST 'https://api.emmy.ninja/vehicles/$VEHICLE_ID/rentals/$RENTAL_ID/stop' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{}'
```

### Pause Rental

You can also pause the rental if you want to park your vehicle and but want to 
use it later. This will reduce the price per minute as specified in 
`pricingDuringPark` in the [vehicle information](#show-vehicle)


```bash
curl --location --request POST 'https://api.emmy.ninja/vehicles/$VEHICLE_ID/rentals/$RENTAL_ID/park' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{}'
```


## User relatet stuff
The API exposes some information on the user.

### Create User
:warning: This Endpoint is not tested. No valid value for `languageId` is known
so far.

```bash
curl --location --request POST 'https://api.emmy.ninja/users' \
--header 'Content-Type: application/json' \
--data-raw '{
    "locationId": 1,
    "birthDate": "1980-01-01",
    "gender": 0,
    "firstName": "firstName",
    "lastName": "lastName",
    "email": "mail@example.org",
    "password": "password",
    "mobilePhone":"000000",
    "newsletterAccepted": false,
    "agbChecked": false,
    "planId": 1,
    "languageId": 0
}'
```

### User Information

```bash
curl --location --request GET 'https://api.emmy.ninja/users/$USER_ID' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
```

### User Statistics
Get interesting facts such as yout total number of rides or the total ridden 
distance in meters.

```bash
curl --location --request GET 'https://api.emmy.ninja/users/$USER_ID/stats' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
```

### List Rentals 

List all your previous rentals.

```bash
curl --location --request GET 'https://api.emmy.ninja/users/$USER_ID/rentals' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
```

### Show Rental

Show a specific rental by `$RENTAL_ID`.

```bash
curl --location --request GET 'https://api.emmy.ninja/users/$USER_ID/rentals/$RENTAL_ID' \
--header 'Authorization: Bearer $ACCESS_TOKEN' 
```

### Change Address

When you change you address, the old address is still stored and returnd as part
of the user information. The new address will become the new default.

```bash
curl --location --request POST 'https://api.emmy.ninja/users/$USER_ID/addresses' \
--header 'Authorization: Bearer $SIGNUP_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "firstName": "John",
    "lastName": "Doe",
    "street": "street name",
    "houseNumber": "99",
    "zipCode": "10000",
    "city": "city",
    "countryCode": "DE"
}'
```

### Show Payment Methods

List current payment options.

```bash
curl --location --request GET 'https://api.emmy.ninja/users/$USER_ID/payment-methods' \
--header 'Authorization: Bearer $SIGNUP_TOKEN'
```

### Payment Credit Card

:warning: This endpoint is not tested. Correct format of values are not known.

```bash
curl --location --request POST 'https://api.emmy.ninja/users/$USER_ID/payment-methods/cc' \
--header 'Authorization: Bearer $SIGNUP_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "number": "number",
    "expirationDate": "expDate",
    "cardHolder": "cardHolder",
    "type": "type",
    "cvc": "cvc"
}'
```

### Payment Bank Account

:warning: This endpoint is not tested. Correct format of values are not known.

```bash
curl --location --request POST 'https://api.emmy.ninja/users/$USER_ID/payment-methods/dd' \
--header 'Authorization: Bearer $SIGNUP_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "accountHolder": "accountHolder",
    "sepaMandateCheck": false,
    "iban": "iban",
    "bic": "bic"
}'
```


## Other stuff

### Plans

List available signup plan.

```bash
curl --location --request GET 'https://api.emmy.ninja/plans'
```

### Notifications

Sometimes, Emmy notifies its user about recent events such as an increase of 
prices, offline fleets because of bad weather condidition, etc.

```bash
curl --location --request GET 'https://api.emmy.ninja/notifications' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
```

### Locations

Get the business and non-parking territories.

```bash
curl --location --request GET 'https://api.emmy.ninja/locations'
```

### Buy Credit Packages

Emmy is offering prepaid credit packages so that you can lower the price per 
minute.

:warning: When submitting this request your account is charged depending on the
value of `$CREDIT_PACKAGE_CODE`.

:warning: This endpoint is not tested. No valid values for `$CREDIT_PACKAGE_CODE` are known so far. You may try one of the following: 
`["Asphalteuphoristen", "Gelegenheitsflaneure"]` cmp. 
[https://emmy-sharing.de/preise/](https://emmy-sharing.de/preise/)

```bash
curl --location --request POST 'https://api.emmy.ninja/credit-packages/buy' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "code": "$CREDIT_PACKAGE_CODE"
}'
```

### Validate Promotion Codes

:warning: This endpoint is not tested.

Check, if a promotion code is valid an can be redeemed. You need to have a
`$PROMOTION_CODE` that you might get from marketing actions. Use `SideMenu` for 
`$REDEMPTION_PURPOSE`. If you want to enter a promotion code from a friend,
use `Registration` instead

```bash
curl --location --request POST 'https://api.emmy.ninja/promotion-codes/validate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data-raw '{
    "code":"$PROMOTION_CODE",
    "redemptionPurpose": "$REDEMPTION_PURPOSE"
}'
```

### Redeem Promotion Codes

:warning: This endpoint is not tested.

```bash
curl --location --request POST 'https://api.emmy.ninja/promotion-codes/redeem' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $SIGNUP_TOKEN' \
--data-raw '{
    "code": "$PROMOTION_CODE",
    "redemptionPurpose": "$REDEMPTION_PURPOSE"
}'

```

### Verification

:warning: Currently no understanding, what this endpoint is used for. 

Variable `$PLATFORM` must be one of the following: `["android", "ios"]`

```bash
curl --location --request GET 'https://api.emmy.ninja/verification/onfido-token' \
--header 'Emmy-Application-Platform: $PLATFORM' \
--header 'Authorization: Bearer $SIGNUP_TOKEN'
verification/onfido-token
```

The response contains a JWT. But what is it used for?