.. _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.

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.

Currently we expose the following fields that are populated asynchronously via the API. This is a small subset of the total
of properties with which an advertisement is enriched. In the future we might expose more of these properties

+-------------------------+----------+---------------------------------------------------------------------------------------+
| Field name              | Format   | Remarks                                                                               |
+=========================+==========+=======================================================================================+
| makeDescription         | string   | When specified this field is displayed instead of the category name.                  |
+-------------------------+----------+---------------------------------------------------------------------------------------+
| modelDescription        | string   | When specified this field is displayed instead of the value model of the model        |
|                         |          | attribute, which is a list of values.                                                 |
+-------------------------+----------+---------------------------------------------------------------------------------------+
| trim                    | string   |                                                                                       |
+-------------------------+----------+---------------------------------------------------------------------------------------+
| apkExpirationDate       | string   | date in iso-8601 format                                                               |
+-------------------------+----------+---------------------------------------------------------------------------------------+
| apkOnDelivery           | string   | Ja or Nee                                                                             |
+-------------------------+----------+---------------------------------------------------------------------------------------+
| energyLabel             | string   | A ... G                                                                               |
+-------------------------+----------+---------------------------------------------------------------------------------------+
| fuelConsumption         | numeric  | consumption in liters per 100 km                                                      |
+-------------------------+----------+---------------------------------------------------------------------------------------+

.. _ad_fields:

Fields
------

Each advertisement has a unique identifier by which it can be retrieved and a set of
required fields, like ``title``, ``description`` (or ``translations`` for multilingual Ads) 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 <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 <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: title
        :type: string
        :constraints: max. 60 chars
        :required: true
        :updateable: true
        :writable: true

        Any string with a minimum of 3 characters, up to 60 characters. Urls are not allowed as part of the title.

    .. apifield::
        :name: description
        :type: string
        :constraints: max. 65535 chars
        :required: true
        :updateable: true
        :writable: true

        The description field of the ad. All HTML elements except for the ones below
        will be removed:

        .. code-block:: html

            <i> <em> <b> <strong> <ul> <li> <u> <br/>

        The description can also contain Wiki-formatting. It is recommended to not rely on this feature, since it is probably
        going to change in the future. But since it has impact on how the description is rendered, it is mentioned here.

        We support the following Wikiformatting:

        - Bold: \*\*bold\*\*
        - Italic: //italic//
        - Underline: \_\_underline\_\_
        - Lists:
            ::

                * item1
                * item2

        The result of this support is that it is currently not possible to add the character combinations needed for the
        Wiki formatting literally in the description. So for example, there is currently no way of including ``**hi**``
        in a description, because this will be rendered as bold.

    .. 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 <price_models>`
        :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: true
        :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

        The "opvalsticker" to be displayed with the advertisement - Will only be displayed on Marktplaats if the
        opvalsticker feature is active.
        See :doc:`advertisement-features` and :doc:`buy-advertisement-feature`.

    .. 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: <property>
        :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 <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: locale
        :type: string
        :constraints: for Marktplaats only `nl-NL` allowed, for 2dehands: `nl-BE` and `fr-BE` allowed
        :required: false
        :updateable: true
        :writable: true

        Locale (language) of the Ad. Mainly Title and description. This is only relevant for advertisements on the 2dehands platform.

.. 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 /v1/advertisements/{itemId}

Retrieve a single advertisement with the given itemId.

.. endpoint:: PATCH /v1/advertisements/{itemId}

Modify an existing advertisement, using the Json Patch format. See `updating-advertisements`_ for details.

.. endpoint:: PUT /v1/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: <field name>
        :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: <field name>
        :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: <field name>
        :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: <field name>
        :code: missing-required-field
        :description: A required field is missing or empty (while that is not allowed).
    .. error::
        :field: <field name>
        :code: unknown-field
        :description: The specified field does not exist or is not allowed for the given category.
    .. error::
        :field: <field name>
        :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: <field name>
        :code: field-not-editable
        :description: The specified field may not be edited by the current authenticated user.
    .. error::
        :field: <field name>
        :code: too-many-field-values
        :description: There are too many values given for the field.
    .. error::
        :field: <field name>
        :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: <field name>
        :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 <https://tools.ietf.org/html/rfc6902>`_.
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