Table of Contents

This document is for third party Picture Providers or Providers that manage Dealer Ratings who want to integrate via OAuth2.0. In this document we call them simply Providers.

Vehicle Images, Auto-Panoramas or Dealer Ratings can be managed even though the dealer account may be already assigned to another Transfer Service Provider. Dealers can grant permissions to registered Providers on their own via the OAuth 2.0 protocol. As soon as the Provider was granted permissions by the Dealer it can manage images on their behalf via the Seller API. Be aware that the Dealer can choose which permissions to grant, currently it’s either permissions to manage Auto-Panoramas, Vehicle Images and/or Dealer Ratings.

Prerequisites

To register as Picture Provider or as a Provider that manage Dealer Ratings please send the following information to service@team.mobile.de:

If you have a Transfer Service Provider Contract with mobile.de already you just have to provide the required OAuth 2.0 parameters below.

  • The name, email and telephone number of the person who handles contractual issues for the requesting company.

  • The name, email and telephone number of the person who handles technical issues for the requesting company.

  • What kind of software applications or tools are currently used (commercial software applications)?

  • The complete company address.

  • The VAT ID of the requesting company.

And additionally the Following OAuth 2.0 parameters:

Table 1. OAuth 2.0 required parameters
Parameters Description

Company Name

The company name that will be displayed on the oauth approval page

Redirect URL

One or more redirect URLs. The redirect URL is the authorization callback of the OAuth 2.0 protocol, which redirects the Dealer back to the site of the Provider and contains the authorization code.

scopes

The permissions that should be requested from the Dealer.
Table 2. Currently the following permissions can be requested:

Scopes

Description

read_inventory write_image

Can manage Vehicle Images.(read_inventory is mandatory)

read_inventory write_autopanorama

Can manage Auto-Panoramas. (read_inventory is mandatory)

read_inventory write_autopanorama write_image

Can manage Auto-Panoramas and Vehicle Images. (read_inventory is mandatory)

write_dealer_rating read_dealer_rating

Can manage Dealer Ratings.

read_dealer_rating

Can read Dealer Ratings.

Mobile.de will then create the corresponding OAuth 2.0 client and will provide client_id and secret.

Integrate mobile.de OAuth 2.0 Flow

To manage Vehicle Images, Auto-Panorama and/or Dealer Ratings on behalf of the dealer, approval needs to be requested from the dealer. At mobile.de the OAuth 2.0 protocol, defined in RFC 6749, is used. The grant type is the Authorization Code Flow for confidential clients. After the Authorization Code Flow completed, a token is received, which can be used to access resources on behalf of the dealer. Please make your self familiar with the OAuth 2.0 protocol before continuing, good resources to learn are RFC 6749 and https://www.oauth.com.

To integrate, you need the provided client_id and secret.

Name Description

client_id

The client Id is issued by mobile.de and identifies the Picture Provider or Provider that manages Dealer Ratings.

secret

The secret is used to authenticate the Provider for token and refresh token retrieval and must be kept secret.

Authorize

In order to receive authorization from the dealer you need to direct the dealer to the following URL.

https://handel.mobile.de/oauth/authorize?client_id=<client_id>&response_type=code&scope=<scope>&state=<state>&redirect_uri=<redirect_uri>
Table 3. OAuth 2.0 authorization parameters
Name Description

response_type

Must be code

client_id

The provided client_id that identifies the picture provider

scope

A space seperated list of requested scopes. Requested scopes will be preselected on the dealers approval page. Currently we support read_inventory, write_image , write_autopanorama, write_dealer_rating and read_dealer_rating (read_inventory is mandatory for managing Images or Auto-Panoramas)

state

optional client state

redirect_uri

The redirect URL where the authorization response will be redirected to. (must be https)

After the dealer has authorized the request his browser is redirected to:

redirect_uri?code=R31wbp&state=123

The redirect contains the authorization code and an optional client state. The authorization code is valid for 1 minute and needed to retrieve the access token.

Error Response

In case the dealer does not authorize the request, there will be no redirect or notification to the redirect uri. Other error cases will be handled as described in RFC 6749 4.1.2.1. Error Response.

Token Exchange

With the access token resources can be accessed on behalf of the dealer. To retrieve the access token a POST request to https://handel.mobile.de/oauth/token with the following parameters has to be done.

Table 4. OAuth 2.0 token request parameters
Name Description

grant_type

must be authorization_code

code

The received authorization code

redirect_uri

URL encoded registered redirect uri

client_id

the client id

Example

curl -u client_id:secret -XPOST https://handel.mobile.de/oauth/token -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=authorization_code&code=<code>&redirect_uri=<redirect_uri>&client_id=<client_id>'


{
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "bearer",
  "expires_in": 86269,
  "refresh_token": "xxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "read_inventory write_autopanorama write_image",
  "tsp_name": "ddl_image_tsp"
}

Error Response

In case of basic authentication failure or wrong authorization code the server will respond with HTTP/1.1 403 Forbidden. Other error cases will be handled as described in RFC 6749 5.2. Error Response.

Resource Authorization

To access supported resources on behalf of the dealer, simply add the access token as bearer token to the Authorization header as described in RFC 6750.

Example

curl 'https://services.mobile.de/seller-api/ads/<ad_id>/auto-panorama/exterior'
    -H 'Accept: application/vnd.de.mobile.api+json'
    -H 'Authorization: Bearer <access_token>'

Refresh Token

The access token expires after 24 hours. You will notice that an access token has expired, when you receive a HTTP/1.1 401 Unauthorized response code while accessing resources. To get a new access token without interaction with the dealer the refresh token grant type should be used.

To receive a new valid access token a POST request to https://handel.mobile.de/oauth/token with the following parameters has to be done.

Table 5. OAuth 2.0 refresh token parameters
Name Description

grant_type

must be refresh_token

refresh_token

The previously retrieved refresh token

client_id

the client id

Example

curl -s -u client_id:secret -XPOST https://handel.mobile.de/oauth/token -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>'

{
  "access_token": "xxxxxxxx",
  "token_type": "bearer",
  "refresh_token": "xxxxxxxxxxxx",
  "expires_in": 86399,
  "scope": "read_inventory write_autopanorama write_image",
  "tsp_name": "ddl_image_tsp"
}

Error Response

In case of basic authentication failure the server will respond with HTTP/1.1 403 Forbidden. Other error cases will be handled as described in RFC 6749 5.2. Error Response.

Supported Endpoints

Picture Providers and Providers that manage Dealer Ratings will use the Seller API with OAuth 2.0 to upload and manage Vehicle Images, Auto-Panoramas or Dealer Ratings. To use the Seller-API with OAuth 2.0, new endpoints have been created. These endpoints work similar to the corresponding TSP endpoints, except the access has to be authorized via an OAuth 2.0 token (see Resource Authorization). For more details how these endpoints work see section Resource Reference of the seller API documentation.

Base URL : https://services.mobile.de/seller-api

Picture Providers

Endpoint for getting seller information

Name Method Endpoint Scope

Retrieve seller information

GET

/seller

read_inventory

This endpoint provide basic information about the seller, including how many vehicle images the seller is allowed to upload.

Sample response
HTTP/1.1 200 OK
Content-Type: application/vnd.de.mobile.api+json

{
  "mobileSellerId": "12",
  "customerNumber": "8",
  "type": "DEALER",
  "settings": {
    "maxImages": 30
  },
  "companyName": "Smoke AG"
}

Endpoints for reading inventory

Name Method Endpoint Scope

List all seller ads

GET

/ads

read_inventory

Retrieve a single ad

GET

/ads/:mobileAdId

read_inventory

Endpoints for Autopanorama

Name Method Endpoint Scope

Upload Interior Image

POST

/ads/:mobileAdId/auto-panorama/interior-image

write_autopanorama

Create Interior Auto Panorama

PUT

/ads/:mobileAdId/auto-panorama/interior

write_autopanorama

Get Interior Auto Panorama

GET

/ads/:mobileAdId/auto-panorama/interior

read_inventory

Delete Interior Auto Panorama

DELETE

/ads/:mobileAdId/auto-panorama/interior

write_autopanorama

Upload Exterior Image

POST

/ads/:mobileAdId/auto-panorama/exterior-image

write_autopanorama

Create Exterior Auto Panorama

PUT

/ads/:mobileAdId/auto-panorama/exterior

write_autopanorama

Get Exterior Auto Panorama

GET

/ads/:mobileAdId/auto-panorama/exterior

read_inventory

Delete Exterior Auto Panorama

DELETE

/ads/:mobileAdId/auto-panorama/exterior

write_autopanorama

Endpoints for Vehicle Images

Name Method Endpoint Scope

Upload Image

POST

/images

write_autopanorama

Associate images

PUT

/ads/:mobileAdId/images

write_autopanorama

Upload images multipart

PUT

/ads/:mobileAdId/images

write_autopanorama

Get all image URLs

GET

/ads/:mobileAdId/images

read_inventory

Delete all images

DELETE

/ads/:mobileAdId/images

write_autopanorama

Providers that manage Dealer Ratings

Endpoints for reading and managing Dealer Ratings

Name Method Endpoint Scope

Retrieve dealer rating overview

GET

/rating/overview

read_dealer_rating

Retrieve dealer ratings

GET

/rating/ratings

read_dealer_rating

Retrieve single dealer rating

GET

/rating/ratings/:ratingId

read_dealer_rating

Reply on dealer rating

PUT

/rating/ratings/:ratingId/comment

write_dealer_rating

Retrieve dealer rating invites and inviteables

GET

/rating/invites

read_dealer_rating

Invite buyers to submit dealer rating

POST

/rating/invites/:mobileAdId

write_dealer_rating

FAQ for existing Transfer Service Providers

How do I know if one of my customers is having a provider in parallel?

Currently this information can only be given to you from the mobile.de customer service team. We will also advise the dealers / providers to inform you in case they have someone else managing picture data or dealer ratings. There are plans to enhance the SellerAPI the way that this information can be either retrieved or it is in general only possible for one provider to manage certain data and the other will get an error message.

How do I know what permissions a provider my customer is using has?

This information can be given to you from customer service.

Can I get images / image information for images that I have not uploaded?

You can use the seller API functionality as before. So you are able to retrieve images references for Auto-Panorama to in general know if there is an Auto-Panorama interior or exterior. For normal images you are able to retrieve the picture server images references to get the real images data.

Is anything changing in my permissions?

No. You will still be able to manage the complete ad data including images. You should be aware of the case that a customer gets image data from another provider while you are managing the vehicle data. In this case you should not delete/overwrite the vehicles image data.

Can I also be a picture provider for customer where I do not manage the vehicle data?

Yes. In order to do so, please provide the OAuth 2.0 details mentioned in the Prerequisites to the customer service team.

Who is responsible in case of issues/reclamations?

As a TSP/Rating manager/Picture provider you signed a contract saying that you are responsible for the changes you are doing. We are able to see who did a certain change to an ad. So whoever did a change by accident is the responsible provider.

Who has the data sovereignty?

Every provider (either TSP or Picture Provider) who has a certain permission for example managing normal vehicle images can do changes to these type of vehicle data independent to the fact who uploaded the image data.

Why are you using OAuth for your rating/picture provider solution?

OAuth 2.0 is an industry standard. Furthermore it’s a very good solution to have a permission management for your customer that can be directly managed starting within your product.

What happens if images were removed by accident from ad data?

After removing the references the images will not be deleted straight away. So you can add the existing references back a short time period after this happened.

How do I avoid overwriting/deleting image data?

For Autopanorama there is a separate endpoint. If you are not doing any call to this endpoint the Auto-Panorama data will not be touched. For normal vehicle images you should either get the complete ad data before updating an ad (including the image references) or you should not send the image element at all in case you are only managing the ad data for your customer.