.. _ISO 4217: http://en.wikipedia.org/wiki/ISO_4217 .. _ISO 8601: http://en.wikipedia.org/wiki/ISO_8601 .. index:: Advertisements, Advertisement .. _advertisement: Advertisement ============= Advertisements or ads are the main resource on the Marktplaats API. You can create, update and delete them, change the status and get a list of your ads. Through the API you only have access to your own ads. Ads from other advertisers are not accessible. How to know an advertisement json model --------------------------------------- The json model to POST an advertisement consists of two parts, common fields and category-specific fields. You can find an overview of the common fields (such as price, and sellerName) below. To look up the category-specific fields, please do the `v2/categories` call to get the Ids of the category you want to post in. For example, for Volkswagen, you will find that the Ids are 91/157, 91 being the level-1 id for cars, and 157 the level-2 for Volkswagen. Next, you can do an attributes call for this category: `v2/categories/91/157/attributes`. The attributes you can supply in the json are those with `"writable": true` (for posting a new advertisement) and `"updateable": true` (for updating an advertisement). The endpoint will also tell you acceptable values for each attribute. As an example, on category 157 you will find `trim` as a writable attribute. This means that in your advertisement json, you can simply add a json field `"trim" : "trim goes here"`. It is not necessary to call the attributes endpoint for every ad post. We only change attributes a few times per year, and usually in a backwards compatible way (e.g. add new car models). If we make a backwards incompatible change or another change that will have major impact on your business we will inform you by e-mail ahead of time. User-dependent attribute statuses --------------------------------- Please be aware that the status of certain attributes may depend on the user. For many categories, the fields **manufacturerTradename**, **manufacturerAddress**, **manufacturerEmail** are required for any business user that is a DSA trader. This is the case if they allow on-platform transactions. This is a legal requirement due to the GPSR (General Product Safety Regulation). Sellers are legally responsible for providing correct data. To make things easier for yourself as an API partner, we recommend marking these fields required on your side for all of your users. That way, ad inserts/updates will keep working even if an existing user's DSA trader status changes. If you want to know which fields are mandatory for a specific user, make sure to call the attributes endpoint with their **USER token** rather than a CLIENT token. Automotive advertisements ------------------------- Advertisements placed in any of the automotive categories are special in that, if a valid license plate is provided, they will be enriched with data from a third party partner after posting. This process is asynchronous and it can take some time for this data to show up as attributes of an advertisement. If you provide the values for these fields yourself in the HTTP POST then this data is used instead of the data we receive as part of the enrichment process. Please note that specifically for cars, we have some fields that are editable only by API partners that are configured on our side as "Car Dealer API partner". If you are signed up as an API partner for other categories and would like to start advertising cars, please contact us. Another important point: * The categoryId field will decide in which brand category your ad is posted * the `model` attribute contains a different list of acceptable values for each brand and decides the model search filter. * The `makeDescription` and `modelDescription` are free text fields that will show on the advertisement page but are not used for search. For the best visibility of ads, we recommend you supply all of them. The available attributes are somewhat different for vans (bestelauto's), please check the attributes endpoint for details. .. _ad_fields: Fields ------ Each advertisement has a unique identifier by which it can be retrieved and a set of required fields, like ``translations`` (to specify title and descriptions) and ``priceModel``. An advertisement also has a set of optional fields, which are depending on the ``categoryId`` in which the advertisement is placed. To get a list of the optional fields for an advertisement (which are not listed below), the :ref:`category-attributes ` could be used. .. apifields:: .. apifield:: :name: itemId :type: string :constraints: -- :required: false :updateable: false :writable: false Unique reference to the Marktplaats advertisement, needs to be omitted in a POST action. .. apifield:: :name: categoryId :type: int :constraints: positive :required: true :updateable: true :writable: true The category in which the advertisement is placed. An integer value from the category list. Must be a L2 category (see :ref:`categories `). In some cases the categoryId can be updated as well as written. The rules for moving a category are: * An L2 category can only be moved within the same L1 * MUST have a special privilege allowing category changes in the system * Can only change the category of an advertisement once * Can only change it in a specific time period (usually 7 days) of the startdate of the advertisement .. apifield:: :name: startDate :type: ISO 8601 string :constraints: -- :required: false :updateable: false :writable: false The date the advertisement has been published. .. apifield:: :name: closeDate :type: ISO 8601 string :constraints: -- :required: false :updateable: false :writable: false The date the advertisement will be closed. .. apifield:: :name: priceModel :type: :ref:`Price Model ` :constraints: one of supported price models. :required: true :updateable: true :writable: true .. apifield:: :name: licensePlate :type: string :constraints: 6 chars or 8 chars :required: false :updateable: true :writable: true .. apifield:: :name: seller :type: object :constraints: -- :required: false :updateable: true :writable: true The seller is inferred from the currently authenticated user. .. apifield:: :name: seller.sellerId :type: int :constraints: positive :required: false :updateable: false :writable: false .. apifield:: :name: seller.sellerName :type: string :constraints: max. 30 chars (60 for API partner) :required: false :updateable: true :writable: true .. apifield:: :name: seller.phoneNumber :type: string :constraints: max. 12 chars, has to be valid :required: false :updateable: true :writable: true .. include:: reference/phonenumber-requirements.rst .. apifield:: :name: seller.acceptPaypal :type: boolean :constraints: ``true`` or ``false`` (default ``false``) :required: false :updateable: true :writable: true Accept bank or creditcard payments via PayPal .. apifield:: :name: seller.kvkNumber :type: long :constraints: a positive number greater than 0 :required: false :updateable: true :writable: true .. apifield:: :name: seller.vestiging :type: string :constraints: can contain numbers and letters :required: false :updateable: true :writable: true .. apifield:: :name: seller.showEmail :type: boolean :constraints: ``true`` or ``false`` (default ``true``) :required: false :updateable: true :writable: true Enable/disable the ability of a user to contact seller by email .. apifield:: :name: location :type: object :constraints: -- :required: true :updateable: false :writable: true .. apifield:: :name: location.postcode :type: string :constraints: max. 6 chars :required: true :updateable: false :writable: true Either provide postcode or cityName, if both are provided, the cityName is used and postcode ignored. For example: .. code-block:: JSON "location":{"postcode":"1097DN"} Will result in an advertisement with the postcode 1097 DN and cityName "Amsterdam". .. code-block:: JSON "location":{"cityName":"Amsterdam"} Will result in an advertisement with no postcode, cityName "Amsterdam" and extra remark "Buitenland" (Dutch for abroad). .. code-block:: JSON "location":{"postcode":"1097DN","cityName":"Amsterdam"} Will result in an advertisement with the postcode 1097 DN and cityName "Amsterdam". This is because the provided cityName matches with the given postcode. .. code-block:: JSON "location":{"postcode":"1097DN","cityName":"Utrecht"} Will result in an advertisement with no postcode, cityName "Utrect" and extra remark "Buitenland" (Dutch for abroad). This is because the postcode does not match the given cityName, which will cause the system to ignore the postcode and take the supplied cityName. The examples above work for both POST request as well as PUT request. When updating an advertisement using PATCH the most reliable way to change the postcode is using the following request: .. code-block:: JSON [ {"op":"remove", "path":"/location/cityName"}, {"op":"replace","path":"/location/postcode","value":"8388MA"} ] This will first remove the cityName, followed by updating the postcode. The system will then automatically add the correct cityName to the advertisement based on the given postcode. .. apifield:: :name: location.cityName :type: string :constraints: max. 60 chars (not all chars allowed) :required: false :updateable: false :writable: true Either provide postcode or cityName, if both are provided, the cityName is used and postcode ignored. This should only be done when the postcode is really unknown, since if only a cityName is provided, it is assumed that the location of the seller is abroad, and as a result, the advertisement will not be displayed on the map. The city may only contain letters, numbers, dashes, underscores and commas. .. apifield:: :name: url :type: string :constraints: valid URL :required: false :updateable: true :writable: true The URL to be displayed with the advertisement - Will only be displayed on Marktplaats if the URL feature is active. For the URL http, https and ftp protocols allowed. See :doc:`advertisement-features` and :doc:`buy-advertisement-feature`. .. apifield:: :name: stickerText :type: string :constraints: max 18 chars :required: false :updateable: true :writable: true .. _stickerText: The custom "opvalsticker" (or "microtip") to be displayed with the advertisement - Will only be displayed on Marktplaats if the microtip feature is active in the user's bundle/package. See :doc:`advertisement-features` .. apifield:: :name: videoUrl :type: string :constraints: max 150 chars :required: false :updateable: true :writable: true The URL of the video to be displayed with the advertisement. This can only be set when you are a dealer with the scope for ``dealer_video``. When the dealer bought the ``video`` feature, it will be visible in the search pages that there is a video added to this advertisement. See :doc:`advertisement-features` and :doc:`buy-advertisement-feature`. The URL should have marktplaats.carviewer.nl or marktplaats.movieplayer.nl as hostname. .. apifield:: :name: showOnMap :type: boolean :constraints: ``true`` or ``false`` (default ``false``) :required: false :updateable: true :writable: true Enable/disable the display of an advertisement on the map. .. apifield:: :name: status :type: string :constraints: ``online`` or ``deactivated`` :required: false :updateable: false :writable: false The status of the advertisement, deactivated advertisements are not visible on the site .. apifield:: :name: :type: undefined :constraints: -- :required: false :updateable: true :writable: true Optional fields for an advertisement (attributes). The field name (key) of a property is always a camel cased word. For example: "jaarOorspr" for the field which is on the website displayed as: "Jaar (Oorspr.)". A list of all the allowed fields and the type of the field can be retrieved by getting the :ref:`category-attributes `. The type of the field is depending on the field, see the list of allowed fields for the type. .. apifield:: :name: partNumber :type: string :constraints: max 25 chars :required: false :updateable: true :writable: true A manufacturer part number is a series of numbers and/or letters that has been given to a part by the manufacturer. An MPN identifies the part as belonging to and originating from that one manufacturer. .. apifield:: :name: renewPossible :type: boolean :constraints: -- :required: false :updateable: false :writable: false Shows if advertisement can be renewed with the renew operation. .. apifield:: :name: translations :type: array[:ref:`Translation `] :constraints: -- :required: false :updateable: true :writable: true List of Ad translations in multiple languages. For more details refer :ref:`Ad Translation `. .. include:: ad-attributes.rst Relations --------- .. relations:: .. relation:: :name: mp:category .. relation:: :name: mp:seller .. relation:: :name: mp:advertisement-features .. relation:: :name: mp:advertisement-images :embedded: yes .. relation:: :name: mp:advertisement-statistics .. relation:: :name: mp:bids .. relation:: :name: mp:advertisement-transactions .. relation:: :name: mp:upcall-confirmations :availability: Client credentials are provided and confirm_upcall has been granted .. relation:: :name: mp:advertisement-website-link Reference --------- .. endpoint:: GET /v2/advertisements/{itemId} Retrieve a single advertisement with the given itemId. .. endpoint:: PATCH /v2/advertisements/{itemId} Modify an existing advertisement, using the Json Patch format. See `updating-advertisements`_ for details. .. endpoint:: PUT /v2/advertisements/{itemId} Modify an existing advertisement, by supplying the entire updated advertisement Json. See `updating-advertisements`_ for details. Errors ------ .. errors:: .. error:: :http: 400 :code: invalid-item-id :description: The item id provided does not match [a-z][0-9]* .. error:: :http: 400 :code: validation-failure Validation of the advertisement failed. There should be more information in the field errors .. error:: :http: 400 :code: invalid-json :description: The provided json is invalid (it is not json) .. error:: :http: 400 :code: incorrect-content-type :description: The used content-type for the request-body is not supported. At the moment we only support application/json .. error:: :http: 404 :code: advertisement-not-found :description: The advertisement with the provided itemId does not exist. .. error:: :http: 409 :code: conflicting-state :description: When trying to patch an advertisement, this error is returned when the patch is not possible. For example, when trying to replace a field which does not exists. .. error:: :http: 500 :code: internal-server-error :description: Oops! Sorry, something went wrong on our side. Field errors ------------ .. fielderrors:: .. error:: :field: :code: input-invalid :description: The value for this field is invalid. Most of the time, this is because the field only accept a value of a predefined set of values or there are constraints on the value. For example, in the title field, URLs are not allowed. :value: The allowed values. .. error:: :field: :code: input-too-long :description: The length of the supplied value exceeds the maximum allowed length for this field :value: The maximum allowed length. .. error:: :field: :code: input-too-short :description: The length of the supplied value is less then the minimum required length for this field :value: The minimum required length. .. error:: :field: :code: missing-required-field :description: A required field is missing or empty (while that is not allowed). .. error:: :field: :code: unknown-field :description: The specified field does not exist or is not allowed for the given category. .. error:: :field: :code: field-value-out-of-range :description: The specified field value is out of range. This only happens with numeric values. :value: The allowed range for the field. .. error:: :field: :code: field-not-editable :description: The specified field may not be edited by the current authenticated user. .. error:: :field: :code: too-many-field-values :description: There are too many values given for the field. .. error:: :field: :code: input-not-allowed :description: It is not allowed to set this field given the other fields. This message is returned when you try to set for example an ``askingPrice`` for a ``priceModel`` which doesn't support that. .. error:: :field: :code: input-not-numeric :description: It is not allowed to give a non-numeric value for fields which are numeric. .. error:: :field: categoryId :code: ad-change-or-placement-not-allowed :description: Not allowed to change or place ad in category. .. error:: :field: categoryId :code: category-change-not-allowed :description: Not allowed to change the category of an advertisement. Categories can only be changed when you have a special privilege, it can be changed only once and only within a specific time period since starting the advertisement Examples -------- .. include:: examples/get-ad-example.rst .. include:: examples/delete-ad-example.rst .. _updating-advertisements: Updating an advertisement ------------------------- In order to modify an existing advertisement, the ``PATCH`` or ``PUT`` method should be used on an advertisement. If you use ``PUT``, the body is the same as for the ``POST`` call. You need to provide the full advertisement. For a ``PATCH``, you only need to provide the fields you want to change. The body of the request should be a document according to the `JSON Patch RFC `_. This means that even when only one field is changed, an array of objects should be supplied in the JSON, where the array will only contain a single element. We currently support the _operations_ ``replace``, ``add``, ``copy``, ``move`` and ``remove`` for the following fields: * ``title`` (``remove`` and ``move`` are meaningless on these, because title is mandatory) * ``description`` (``remove`` and ``move`` are meaningless on these, because description is mandatory) * ``priceModel`` * all optional fields (attributes) The ``test`` operation will not be supported for the time being. It is possible to modify multiple fields with one PATCH request. This is done by sending an array with individual JSON Patch documents. A successful PATCH call returns ``OK (200)`` with the advertisement as body. .. note:: Officially, the content-type for a PATCH call which is formatted according to the JSON Patch RFC, should be ``application/json-patch+json``. The Marktplaats API accepts this, but also accept PATCH calls with content-type ``application/json``. Example ^^^^^^^ .. include:: examples/patch-ad-example.rst .. include:: examples/put-ad-example.rst