Avito Targeting API

openapi: 3.2.0
info:
  description: API для агентств Авито Promo
  title: Авито Promo Targeting API
  version: 1.0.0
servers:
- url: https://api.avito.ru/
tags:
- description: С помощью API данного раздела вы можете узнать статус клиентов, проверив их ИНН.
  name: Targeting
  x-displayName: Проверка ИНН клиентов
paths:
  /api/1/agency/clients/target/create:
    post:
      description: 'Данный метод запускает задачу на проверку ИНН клиентов.


        ### Параметры запроса


        - `innList` — не пустой список до 100 ИНН.


        ### Успешный ответ


        Метод возвращает назад идентификатор задачи `result.taskId`,

        с помощью которого можно будет получить её статус и результаты проверки

        (см. метод Получение результата проверки ИНН клиентов).'
      operationId: agencyClientsTargetCreate
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                innList:
                  description: Список ИНН
                  items:
                    $ref: '#/components/schemas/inn'
                  maxItems: 100
                  minItems: 1
                  type: array
              required:
              - innList
              type: object
        description: Тело запроса
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  result:
                    $ref: '#/components/schemas/targetTaskId'
                  status:
                    $ref: '#/components/schemas/okResponseStatus'
                required:
                - status
                - result
                type: object
          description: Успешный ответ
        '400':
          $ref: '#/components/responses/badRequestFieldsWithStatus'
        '401':
          $ref: '#/components/responses/unauthorizedWithStatus'
        '403':
          $ref: '#/components/responses/forbiddenWithStatus'
        '404':
          $ref: '#/components/responses/notFoundWithStatus'
        '429':
          $ref: '#/components/responses/defaultTooManyRequests'
        '500':
          $ref: '#/components/responses/defaultInternalServerError'
      security:
      - ClientCredentials: []
      summary: Создание задачи на проверку ИНН клиентов
      tags:
      - Targeting
  /api/1/agency/clients/target/result:
    post:
      description: 'Данный метод позволяет получить по идентификатору статус задачи проверки ИНН клиентов,

        а также результаты этой проверки, если задача завершилась успешно.


        ### Параметры тела запроса


        - `taskId` — идентификатор задачи

        (см. метод Создание задачи на проверку ИНН клиентов).


        ### Успешный ответ


        Метод возвращает назад статус задачи `result.status` и итог проверки `result.items`,

        если задача успешно завершена.


        #### Статус задачи


        - `pending` — задача ещё в процессе выполнения.

        - `success` — задача успешно завершена.


        #### Итог проверки


        Итог проверки представлен массивом результатов по каждому из исходного списка ИНН:


        - `inn` — проверенный ИНН.

        - `isError` — была ли ошибка при проверке.

        Если да, то результат проверки такого ИНН следует игнорировать.

        - `results` — результаты проверки ИНН по категориям.


        Результаты представлены массивом статусов в категориях:


        - `category` — категория.

        - `status` — статус ИНН в категории.


        #### Категория


        - `goods` — Товары.

        - `services` —Услуги.

        - `machinery` — Спецтехника.

        - `jobs` — Работа.


        #### Статус ИНН


        - `new` — «Новый»: клиент,

        у которого были нулевые или незначительные траты на Авито до подключения к агентству.

        - `uplift` — «Аплифт»: клиент, который уже пользовался платными услугами до подключения к агентству,

        комиссия может начисляться только с роста его расходов на услуги размещения.

        - `unavailable` — «Недоступен»: клиент недоступен для работы с агентствами в данной категории.

        Для подключения клиента в других категориях свяжитесь с менеджером.'
      operationId: agencyClientsTargetResult
      parameters:
      - $ref: '#/components/parameters/authHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/targetTaskId'
        description: Тело запроса
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  result:
                    additionalProperties: false
                    description: Информация о проверке ИНН клиентов
                    properties:
                      items:
                        description: Список результатов проверки ИНН клиентов
                        items:
                          additionalProperties: false
                          description: Результат проверки ИНН клиента
                          properties:
                            inn:
                              $ref: '#/components/schemas/inn'
                            isError:
                              description: Наличие ошибки при проверке ИНН клиента
                              example: false
                              type: boolean
                            results:
                              description: Результаты проверки ИНН клиента по категориям
                              items:
                                additionalProperties: false
                                description: Результат проверки ИНН клиента в категории
                                properties:
                                  category:
                                    description: Категория
                                    enum:
                                    - goods
                                    - services
                                    - machinery
                                    - jobs
                                    example: goods
                                    type: string
                                  status:
                                    description: Статус ИНН клиента в категории
                                    enum:
                                    - new
                                    - uplift
                                    - unavailable
                                    example: new
                                    type: string
                                required:
                                - category
                                - status
                                type: object
                              type: array
                          required:
                          - inn
                          - isError
                          - results
                          type: object
                        type: array
                      status:
                        description: Статус задачи проверки ИНН клиентов
                        enum:
                        - pending
                        - success
                        example: success
                        type: string
                    required:
                    - status
                    - items
                    type: object
                  status:
                    $ref: '#/components/schemas/okResponseStatus'
                required:
                - status
                - result
                type: object
          description: Успешный ответ
        '400':
          $ref: '#/components/responses/badRequestFieldsWithStatus'
        '401':
          $ref: '#/components/responses/unauthorizedWithStatus'
        '403':
          $ref: '#/components/responses/forbiddenWithStatus'
        '404':
          $ref: '#/components/responses/notFoundWithStatus'
        '429':
          $ref: '#/components/responses/defaultTooManyRequests'
        '500':
          $ref: '#/components/responses/defaultInternalServerError'
      security:
      - ClientCredentials: []
      summary: Получение результата проверки ИНН клиентов
      tags:
      - Targeting
components:
  schemas:
    inn:
      description: ИНН
      example: 1234567890
      maxLength: 12
      minLength: 10
      type: string
    targetTaskId:
      additionalProperties: false
      description: Идентификатор задачи проверки ИНН клиентов
      properties:
        taskId:
          $ref: '#/components/schemas/id'
      required:
      - taskId
      type: object
    badRequestResponseStatus:
      description: Статус ответа
      enum:
      - bad-request
      example: bad-request
      type: string
    notFoundResponseStatus:
      description: Статус ответа
      enum:
      - not-found
      example: not-found
      type: string
    okResponseStatus:
      description: Статус результата ответа
      enum:
      - ok
      example: ok
      type: string
    unauthorizedResponseStatus:
      description: Статус ответа
      enum:
      - unauthorized
      example: unauthorized
      type: string
    errorField:
      description: Наименование поля
      example: userId
      type: string
    errorResult:
      additionalProperties: false
      description: Результат с ошибкой
      properties:
        message:
          $ref: '#/components/schemas/errorMessage'
      required:
      - message
      type: object
    forbiddenResponseStatus:
      description: Статус ответа
      enum:
      - forbidden
      example: forbidden
      type: string
    defaultErrorResponse:
      additionalProperties: false
      properties:
        error:
          additionalProperties: false
          description: Ошибка
          properties:
            code:
              description: Код ошибки
              example: 1001
              type: integer
            message:
              $ref: '#/components/schemas/errorMessage'
          required:
          - code
          - message
          type: object
      required:
      - error
      type: object
    errorFields:
      description: Ошибки валидации
      items:
        additionalProperties: false
        description: Ошибка валидации поля
        properties:
          field:
            $ref: '#/components/schemas/errorField'
          message:
            $ref: '#/components/schemas/errorMessage'
        required:
        - field
        - message
        type: object
      type: array
    id:
      description: Идентификатор
      example: 123456
      minimum: 1
      type: integer
    errorMessage:
      description: Сообщение об ошибке
      example: Ошибка
      type: string
  responses:
    defaultInternalServerError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/defaultErrorResponse'
      description: Ошибка сервера
    notFoundWithStatus:
      content:
        application/json:
          schema:
            additionalProperties: false
            properties:
              result:
                $ref: '#/components/schemas/errorResult'
              status:
                $ref: '#/components/schemas/notFoundResponseStatus'
            required:
            - status
            - result
            type: object
      description: Не найдено
    badRequestFieldsWithStatus:
      content:
        application/json:
          schema:
            additionalProperties: false
            properties:
              result:
                $ref: '#/components/schemas/errorFields'
              status:
                $ref: '#/components/schemas/badRequestResponseStatus'
            required:
            - status
            - result
            type: object
      description: Неверный запрос
    unauthorizedWithStatus:
      content:
        application/json:
          schema:
            additionalProperties: false
            properties:
              result:
                $ref: '#/components/schemas/errorResult'
              status:
                $ref: '#/components/schemas/unauthorizedResponseStatus'
            required:
            - status
            - result
            type: object
      description: Требуется авторизация
    defaultTooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/defaultErrorResponse'
      description: Превышено количество запросов
    forbiddenWithStatus:
      content:
        application/json:
          schema:
            additionalProperties: false
            properties:
              result:
                $ref: '#/components/schemas/errorResult'
              status:
                $ref: '#/components/schemas/forbiddenResponseStatus'
            required:
            - status
            - result
            type: object
      description: Действие запрещено
  parameters:
    authHeader:
      description: Токен для авторизации
      in: header
      name: Authorization
      required: true
      schema:
        example: Bearer ACCESS_TOKEN
        type: string
  securitySchemes:
    ClientCredentials:
      description: 'Используйте OAuth2 с механизмом `client_credentials` для доступа к возможностям учётной записи агентства. [Подробнее](#tag/Access)

        '
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://api.avito.ru/token
      type: oauth2