Agenda photo/sort

Changes the order of the ad photos and the main photo in one request. Neither the content of the photos nor their IDs change.

Agenda features

Name	Options
Supported methods	`PUT`/`POST` – any other method returns error `405`
Support for detail levels	✘
Support for filtering	✘
Support for full-text search	✘
Support for pagination	✘
Support for sorting	✘
Support for external identifiers	✔
Support for `schemas`	https://api.tipmoto.com/schemas/photo/sort-import.{xsd\|rng}
Support for `?fail-on-warning`	✘
Support for dry-run	✔
Returns `location`	✘

Address

https://api.tipmoto.com/c/{dealer ID}/{moto|dily|prislusenstvi}/{ad ID}/photo/sort.{xml|json}

Instead of the ad ID, you can use the external identifier api-{idApi}.

XML/JSON specification

Machine name	Name	Type	Information
`photos`	List of photos		Required. Contains one or more `photo` items in the required order.
`photo/id`	Photo ID	`integer`	Required. ID of the photo within the ad (see the agenda photo). The photo must belong to the ad and may appear in the list at most once.
`photo/main`	Main photo	`select`	Optional – the first item always becomes the main photo. Possible values: `1` or `true` Yes – allowed only for the first item `0` or `false` No – not allowed for the first item An invalid value is ignored and the response contains a `warning`.
`photo/sortOrder`	Photo order		Not sent – the order is given by the order of the items. Sending it returns error `406`. To change the position of one photo, use `PUT /photo/{id}` with `sortOrder`.
other	Elements from the photo output		Elements and attributes from the `photo.xml` output (`url`, `stamp`, `width`, `height`, `urlApi`, `stampApi`, `resize`, `@forceupdate`, `@modify`, `id@ref`) are allowed, but ignored.

How the order is determined

The order is given by the order of the photo items: the first item is the main photo (position 1), the others follow in the given order.
The list does not have to be complete: photos of the ad that are not in it are placed after the listed ones in their existing order.
Send only id, and main at most for the first item. So that the reordered photo.xml output can be sent back, its other elements are allowed and ignored, and main = 0 for the other items is accepted. Only sortOrder from the output has to be left out, and the photo items have to be wrapped in <photos> (the output returns them directly under <tipmoto>).
A request that does not change the order returns 200 with a notice that the order has not changed; the change is then not reported (it does not appear in the agenda change).
With the parameter ?dry-run=true nothing is saved and the response shows the order that would result.
The rules for the order and the main photo are the same for all paths, see Order and main photo.

Example

XML (PUT to …/photo/sort.xml) – photo 11 becomes the main photo, followed by photos 2 and 3, and the other photos of the ad after them:

<tipmoto>
  <photos>
    <photo><id>11</id><main>1</main></photo>
    <photo><id>2</id></photo>
    <photo><id>3</id></photo>
  </photos>
</tipmoto>

JSON (PUT to …/photo/sort.json):

{"tipmoto": {"photos": {"photo": [{"id": "11", "main": "1"}, {"id": "2"}, {"id": "3"}]}}}

The response contains result/photos with the resulting order of all photos of the ad (sortOrder = position, 1 = main photo) and, if any, result/warnings and result/infos:

<tipmoto>
  <success>true</success>
  <result>
    <photos>
      <photo><id>11</id><sortOrder>1</sortOrder><main>1</main></photo>
      <photo><id>2</id><sortOrder>2</sortOrder><main>0</main></photo>
      <photo><id>3</id><sortOrder>3</sortOrder><main>0</main></photo>
      <photo><id>1</id><sortOrder>4</sortOrder><main>0</main></photo>
    </photos>
  </result>
</tipmoto>

The whole procedure from reading the photos to reordering them is shown in the example.

Errors

HTTP code	When
`400`	invalid value of the parameter `dry-run`
`402`	the login has no write permission for the dealer's agendas, or the dealer does not have imports allowed
`404`	an agenda other than `moto`, `dily`, `prislusenstvi`; the ad does not exist or does not belong to the dealer
`405`	a method other than `PUT`/`POST`
`406`	invalid XML/JSON; `photos` with a list of `photo` is missing; an empty list; a missing or invalid `id`; a photo that does not belong to the ad; an `id` more than once in the list; a `sortOrder` is given; `main` = `1` other than for the first item; `main` = `0` for the first item. The message says which item and why. Nothing changes.
`503`	the order of the photos of the same ad is being changed by another request (or the photos could not be loaded); nothing has changed, repeat the request