Концепции

Асинхронные задачи

Как отслеживать долгие операции через Job API

Некоторые операции занимают время: публикация объявления требует перевода описания, обработки геолокации и оптимизации фотографий. Вместо того чтобы заставлять вас ждать, API запускает эти задачи в фоне и возвращает jobId для отслеживания.

Когда возвращается jobId

Операция	Что происходит в фоне
Публикация объявления	Перевод описания, обработка локации, анализ фото
Загрузка медиафайлов	Оптимизация, генерация превью

Как это работает

1. Запрос возвращает jobId

При публикации объявления статус меняется на pending_active, и возвращается jobId:

{
  "id": 42,
  "externalId": "APT-001",
  "status": "pending_active",
  "publicUrl": "https://rentix.md/announcement/42",
  "updated": true,
  "jobId": 789
}

2. Проверяйте статус задачи

Используйте GET /job/status для отслеживания прогресса:

async function waitForJob(jobId) {
  while (true) {
    const response = await fetch(
      `https://crm.rentix.md/api/v1/job/status?id=${jobId}`,
      { headers: { 'Authorization': 'ApiKey YOUR_API_KEY' } }
    );

    const job = await response.json();

    if (job.status === 'completed') {
      console.log('Задача завершена:', job.resultData);
      return job;
    }

    if (job.status === 'failed') {
      throw new Error(job.publicErrorMessage);
    }

    // Ждём секунду перед следующей проверкой
    await new Promise(r => setTimeout(r, 1000));
  }
}

const job = await waitForJob(789);

curl "https://crm.rentix.md/api/v1/job/status?id=789" \
  -H "Authorization: ApiKey YOUR_API_KEY"

function waitForJob($jobId) {
    while (true) {
        $ch = curl_init("https://crm.rentix.md/api/v1/job/status?id=$jobId");
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: ApiKey YOUR_API_KEY']);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $response = curl_exec($ch);
        $job = json_decode($response, true);

        if ($job['status'] === 'completed') {
            return $job;
        }

        if ($job['status'] === 'failed') {
            throw new Exception($job['publicErrorMessage']);
        }

        sleep(1);
    }
}

3. Статусы задач

Статус	Описание	Что делать
`pending`	В очереди	Ждать
`processing`	Выполняется	Ждать
`completed`	Успешно	Проверить `resultData`
`failed`	Ошибка	Проверить `publicErrorMessage`
`failed_retryable`	Временная ошибка	Можно повторить операцию

Примеры ответов

Задача в очереди

{
  "id": 789,
  "type": "announcement_finalize",
  "status": "pending",
  "queuePosition": 3,
  "createdAt": "2026-02-08T12:00:00.000Z"
}

queuePosition: 3 — перед вашей задачей ещё 3 в очереди.

Задача выполняется

{
  "id": 789,
  "type": "announcement_finalize",
  "status": "processing",
  "queuePosition": null,
  "createdAt": "2026-02-08T12:00:00.000Z"
}

Задача завершена

{
  "id": 789,
  "type": "announcement_finalize",
  "status": "completed",
  "resultData": {
    "announcementId": 42,
    "completedOperations": ["translate_description", "process_location", "analyze_images"],
    "finalStatus": "active"
  },
  "createdAt": "2026-02-08T12:00:00.000Z",
  "completedAt": "2026-02-08T12:00:15.000Z"
}

После успешной финализации статус объявления станет active.

Задача с ошибкой

{
  "id": 789,
  "type": "announcement_finalize",
  "status": "failed",
  "publicErrorMessage": "Не удалось обработать изображения",
  "isRetryable": true,
  "createdAt": "2026-02-08T12:00:00.000Z",
  "completedAt": "2026-02-08T12:00:10.000Z"
}

При isRetryable: true можно повторить операцию — отправьте тот же запрос на публикацию.

Поля ответа

Поле	Тип	Описание
`id`	number	ID задачи
`type`	string	Тип операции
`status`	string	Текущий статус
`resultData`	object	Результат (при `completed`)
`publicErrorMessage`	string	Сообщение об ошибке
`isRetryable`	boolean	Можно ли повторить
`queuePosition`	number	Позиция в очереди
`createdAt`	string	Время создания
`completedAt`	string	Время завершения

Типичный сценарий публикации

1. PUT /listings { externalId: "APT-001", announcementStatus: "active" }
   → status: "pending_active", jobId: 789

2. GET /job/status?id=789
   → status: "pending", queuePosition: 3

3. GET /job/status?id=789 (через 5 сек)
   → status: "processing"

4. GET /job/status?id=789 (через 10 сек)
   → status: "completed", resultData.finalStatus: "active"

5. Объявление опубликовано на rentix.md

Upsert паттерн

Один endpoint для создания и обновления — без проверки существования

Обзор объявлений

Типы недвижимости, статусы и жизненный цикл объявлений