mobile.international Seller API Documentation for Transfer Service Providers (TSPs) Table of contents Seller-API Documentation for TSPs

Transcription

1 mobile.international Seller API Documentation for Transfer Service Providers (TSPs) Table of contents Document History...2 Introduction...3 Customer Support France...3 Additional documents...3 Developer Sandbox...3 API Overview...4 Example HTTP-request...5 HTTP-Responses (bad request) (unauthorized)...6 Handling Ads...7 Function: Create / Update Ad...7 Function: Adding / Deleting Images...7 Function: Retrieving Ad Details...8 Function: Delete Ad...8 mobile.international GmbH 1

2 Document History Date/Version Author Comments/Changes 10/26/2009 P. Laufer Initial version 11/16/2009 P. Laufer Fixed Sandbox URL, Seller-API base URL now starts with HTTPS, minor corrections 11/20/2009 P. Laufer Added some curl examples, removed deprecated X- MOBILE-SELLER-API-USER-ID http header mobile.international GmbH 2

3 Introduction The mobile.international Seller-API is an interface to store seller vehicle and user data to the mobile.international-database and make them available on the platform as classified ads. Technically it is a REST-API, which enables API partners to carry out all actions as if they were directly using the one of the mobile.international websites to post their ads. The API supports all necessary operations to manage the full lifecycle of listings from creation to deletion. This results in the following set of features for the mobile.international REST-API: Create an advertisement Update an advertisement Delete an advertisement Please note: In order to upload listings on behalf of mobile.international customers you ll need to register as a TSP on the mobile.international platform. Please contact Customer Support for further details about this activation process! Customer Support France Phone: support-client@ebay-automobile.fr Customer Support Italy Phone: info@ebay-automobile.it Additional documents In addition to this document you should read the mobile.international XML Ad Data Format documentation which describes the XML format used by the Seller-API. Please refer to for more information and download links. Developer Sandbox For testing purposes a sandbox is available at the IP: sandbox.mobile.de on Port 80. Please contact mobile.international for API user details, ids and tokens. mobile.international GmbH 3

4 API Overview In general the API follows the conventions for REST-APIs. All communication is done via HTTP, the correct combination of request methods and URL trigger the actions of the API. The API is available at the base URL The base URL is the same for all mobile.international marketplaces. All actions are executed in the context of a specific customer (recognized by the provided Seller ID) and thus directed to the mobile.international website the customer registered on. Please note: The seller-id is not the customer-number. Please ask customer support for the seller-ids of your customers. An interface for automatic lookup will be available in future API versions. Authentication and authorization is part of the HTTP-header, which has to be included for each call. The required token is unique for each API user, and not dependent on accounts or ads. HTTP header element Format Description X-MOBILE-SELLER-TOKEN String Static token of the registered API user Please refer to the following table for an overview of the methods and corresponding calls. Use Case URI Method Request content Create Ad /sellers/{sellerid}/ads POST application/xml Update Ad /sellers/{sellerid}/ads/{adid}/ PUT application/xml Delete Ad /sellers/{sellerid}/ads/{adid}/ DELETE none Upload Image /sellers/{sellerid}/ads/{adid}/images POST image/jpg, image/jpeg Upload Images /sellers/{sellerid}/ads/{adid}/images PUT multipart/form-data Delete Images /sellers/{sellerid}/ads/{adid}/images DELETE none Retrieve Ad /sellers/{sellerid}/ads/{adid}/ GET none Please note: The content type must be explicitly set for each request. mobile.international GmbH 4

5 Example HTTP-request The following is an example HTTP POST request issued to that creates a new ad for the customer with the Seller ID The ad details (defined in the mobile.international XML Ad Data Format) are sent within the request body. POST /seller-api/sellers/89064/ads HTTP/1.1 X-MOBILE-SELLER-TOKEN: vsdfv34refg543t5g5445g4tb4t6wat43g67tgdb45g User-Agent: Jakarta Commons-HttpClient/3.1 Host: services.mobile.de:80 Content-Length: 1330 Content-Type: application/xml; charset=utf-8 <?xml version="1.0" encoding="utf-8"?> <ad:ad xmlns:ad=" xmlns:price=" xmlns:types=" xmlns:vehicle=" xmlns:specifics=" xmlns:xsi=" xsi:schemalocation=" seller-ad-1.0.xsd"> <vehicle:vehicle> <vehicle:classification> <vehicle:vehicle-class key="car"/> <vehicle:category key="limousine"/> <vehicle:make key="bmw"/> <vehicle:model key="z3" /> </vehicle:classification> <vehicle:damage-and-unrepaired value="false" /> <vehicle:model-description value="cooles Auto"/> <vehicle:specifics> <vehicle:construction-year value="1999"/> <vehicle:mileage value="100000" /> </vehicle:specifics> <vehicle:site-specifics> <specifics:first-registration value=" " /> <specifics:emission-sticker key="emissionssticker_yellow" /> </vehicle:site-specifics> </vehicle:vehicle> <price:price currency="eur" type="fixed"> <price:gross-prices> <price:consumer-price-amount value="1000.0"/> </price:gross-prices> </price:price> </ad:ad> mobile.international GmbH 5

6 HTTP-Responses A successful call will be indicated by an http-status code 2xx (successful). This can either be 201 (created) or 200 (OK). Errors will also be indicated by the return code. Currently the API specifies two different types of errors: 400 (bad request) and 401 (unauthorized). In addition to the return codes the XML contains a section with details on the detected errors. 400 (bad request) This code is returned on content-validation errors (missing, erroneous or contradictory values in your ad specification). The response contains content of the type application/xml describing the validation errors. Please refer to the mobile.international XML Ad Data Format documentation for a complete list of ad validation errors. <?xml version="1.0" encoding="utf-8" standalone="yes"?> <errors> <error key="vehicle-empty"/> <error key="price-empty"/> </errors> 401 (unauthorized) This code is returned on a wrong/missing token for authentication or if the user tries to access an ad without being authorized to do so. <?xml version="1.0" encoding="utf-8" standalone="yes"?> <errors> <error key="wrong-token"/> </errors> If you keep getting authorization errors check the following list of possible error causes: Did you register as a TSP with mobile.international and has Customer Support properly activated your account? Call Customer Support to register as a TSP or ask whether your account has been properly activated. Do you send the correct Seller Token with your requests? Make sure your requests contain the HTTP Header X-MOBILE-SELLER-TOKEN and the Seller Token equals the one provided to you by Customer Support. If in doubt ask Customer Support to resend the token to you or let them generate a new one. Do you use the correct Seller ID in your requests URLs? Make sure you send your requests to the correct URL containing the Seller ID of the customer you are servicing. Ask Customer Support whether the customer has been properly set up for TSP servicing with your mobile.international TSP account. Do you use the correct HTTP method and API service URL? Take a look at the API Use Case table provided above and make sure you got the API base URL, API function URI and HTTP method right. mobile.international GmbH 6

7 Handling Ads Function: Create / Update Ad All operations to manipulate and/or create ads in the mobile.de database, are triggered via the interface sellers/{sellerid}/ads. Each request must contain the http-header element X-MOBILE-SELLER-TOKEN, which is used for authentication and authorization. Operation Method URL Create Ad POST sellers/{sellerid}/ads Update Ad PUT sellers/{sellerid}/ads/{adid} Delete Ad DELETE sellers/{sellerid}/ads/{adid} On success a create request returns the status code 201 (created) and the http-header Location: /sellers/{customerid}/ads/{adid}. Please note: The adid must be stored in order to make changes to the ad later on, and/or to delete the ad or to add images to it. In case of a successful update the http status code 200 (OK) is returned. In case you receive status code 400 (bad request) please refer to the mobile.international XML Ad Data Format documentation for a complete list of ad validation errors. API Usage Example: Create a New Ad curl -v -H "X-MOBILE-SELLER-TOKEN: foobar" -X POST {sellerid}/ads API Usage Example: Update an Ad curl -v -H "X-MOBILE-SELLER-TOKEN: foobar" -H "Content-Type: application/xml" -X PUT {adid} Function: Adding / Deleting Images Operation Method URL Add image POST sellers/{sellerid}/ads/{adid}/images Add images PUT sellers/{sellerid}/ads/{adid}/images Delete all images DELETE sellers/{sellerid}/ads/{adid}/images All images, which are related to a specific ad must be added to it via the API. API Usage Example: Add an Image to an Ad curl -v -H "X-MOBILE-SELLER-TOKEN: foobar" -H "Content-Type: image/jpg" X POST {adid}/images mobile.international GmbH 7

8 API Usage Example: Add Images to an Ad curl -v -H "X-MOBILE-SELLER-TOKEN: foobar" -H "Content-Type: multipart/form-data" -X PUT -F -F seller-api/sellers/{sellerid}/ads/{adid}/images API Usage Example: Delete all Images of an Ad curl -v -H "X-MOBILE-SELLER-TOKEN: foobar" X DELETE {adid}/images Function: Retrieving Ad Details Operation Method URL Get an ad GET sellers/{sellerid}/ads/{adid} Get all ads of a seller GET sellers/{sellerid}/ads The response contains xml describing the ad(s). Refer to the mobile.international XML Ad Data Format documentation for a complete reference of the returned XML. API Usage Example: Get Details of an Ad curl -v -H "X-MOBILE-SELLER-TOKEN: foobar" {adid} API Usage Example: Get Details of all Ads curl -v -H "X-MOBILE-SELLER-TOKEN: foobar" Function: Delete Ad For deleting an ad you must send a DELETE request to /sellers/{sellerid}/ads/{adid}. On success the status code 200 (OK) is returned. In case you receive the status code 404 (not found) the ad either has already been deleted or you provided the wrong ad id. Each request must contain the http-header element X-MOBILE-SELLER-TOKEN, which is used for authentication and authorization API Usage Example: Delete an Ad curl -v -H "X-MOBILE-SELLER-TOKEN: foobar" -X DELETE {adid} mobile.international GmbH 8