Объявления

Bulk операции

Массовое создание, обновление и управление до 100 объявлений за запрос

Bulk-операции позволяют обрабатывать до 100 объявлений за один запрос. Используйте их для первичной синхронизации и массовых обновлений.

Зачем использовать bulk

ПодходЗапросов на 100 объявлений
Отдельные запросы100
Bulk-операция1

Bulk снижает накладные расходы на сеть и ускоряет синхронизацию.


Типы операций

Каждая операция должна содержать поле op, определяющее тип действия:

ОперацияОписание
upsertСоздать или обновить объявление
linkПривязать external ID к существующему объявлению
unlinkОтвязать external ID
deleteУдалить объявление
validateПроверить данные без сохранения
smart_createСоздать из текста + фото с помощью ИИ

Создайте или обновите объявления

Операция upsert создаёт новое объявление или обновляет существующее по externalId.

Используйте externalUrl для точной публичной страницы объявления на исходном сайте. Это должен быть абсолютный HTTPS URL без данных авторизации длиной не более 2048 символов. Передайте null, чтобы удалить ссылку.

const response = await fetch('https://crm.rentix.md/api/v1/listings/bulk', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    operations: [
      {
        op: 'upsert',
        externalId: 'apt-001',
        externalUrl: 'https://agency.example/listings/kvartira-v-centre',
        announcementType: 'rent',
        propertyType: 'residential',
        propertySecondaryType: 'apartment',
        announcementValue: 500,
        announcementCurrency: 'EUR',
        announcementDescription: 'Уютная квартира в центре...',
        files: [
          { url: 'https://example.com/photo1.jpg', externalFileId: 'apt-001-photo-1' },
          { url: 'https://example.com/photo2.jpg', externalFileId: 'apt-001-photo-2' },
          { url: 'https://example.com/photo3.jpg', externalFileId: 'apt-001-photo-3' }
        ],
        announcementStatus: 'active'
      },
      {
        op: 'upsert',
        externalId: 'apt-002',
        externalUrl: 'https://agency.example/listings/kvartira-s-balkonom',
        announcementType: 'rent',
        propertyType: 'residential',
        propertySecondaryType: 'apartment',
        announcementValue: 700,
        announcementCurrency: 'EUR',
        announcementDescription: 'Просторная квартира с балконом...',
        files: [
          { url: 'https://example.com/photo4.jpg', externalFileId: 'apt-002-photo-1' },
          { url: 'https://example.com/photo5.jpg', externalFileId: 'apt-002-photo-2' },
          { url: 'https://example.com/photo6.jpg', externalFileId: 'apt-002-photo-3' }
        ],
        announcementStatus: 'active'
      }
    ]
  })
});

const result = await response.json();
console.log(`Успешно: ${result.summary.succeeded}/${result.summary.total}`);
Ответ
{
  "results": [
    {
      "op": "upsert",
      "externalId": "apt-001",
      "externalUrl": "https://agency.example/listings/kvartira-v-centre",
      "id": 42,
      "success": true,
      "created": true,
      "updated": false
    },
    {
      "op": "upsert",
      "externalId": "apt-002",
      "externalUrl": "https://agency.example/listings/kvartira-s-balkonom",
      "id": 43,
      "success": true,
      "created": true,
      "updated": false
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

Обновление только исходных URL

upsert, содержащий только op, externalId и externalUrl, обновляет исходную ссылку, не изменяя само объявление:

{
  "operations": [
    {
      "op": "upsert",
      "externalId": "apt-001",
      "externalUrl": "https://agency.example/listings/kvartira-v-centre"
    },
    {
      "op": "upsert",
      "externalId": "apt-002",
      "externalUrl": null
    }
  ]
}
Ответ
{
  "results": [
    {
      "op": "upsert",
      "externalId": "apt-001",
      "externalUrl": "https://agency.example/listings/kvartira-v-centre",
      "id": 42,
      "success": true,
      "updated": true
    },
    {
      "op": "upsert",
      "externalId": "apt-002",
      "externalUrl": null,
      "id": 43,
      "success": true,
      "updated": true
    }
  ],
  "summary": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

Привяжите external ID

Операция link связывает ваш ID из CRM с существующим объявлением в Rentix. Используйте её для объявлений, созданных через веб-интерфейс.

{
  "operations": [
    { "op": "link", "id": 42, "externalId": "apt-001" },
    { "op": "link", "id": 43, "externalId": "apt-002" }
  ]
}
Ответ
{
  "results": [
    { "op": "link", "id": 42, "externalId": "apt-001", "success": true, "linked": true },
    { "op": "link", "id": 43, "externalId": "apt-002", "success": true, "linked": true }
  ]
}

Отвяжите external ID

Операция unlink удаляет связь между объявлением и external ID.

{
  "operations": [
    { "op": "unlink", "id": 42 },
    { "op": "unlink", "externalId": "apt-002" }
  ]
}

Удалите объявления

Операция delete удаляет объявления.

{
  "operations": [
    { "op": "delete", "externalId": "apt-old-001" },
    { "op": "delete", "id": 99 }
  ]
}
Ответ
{
  "results": [
    { "op": "delete", "externalId": "apt-old-001", "success": true, "deleted": true }
  ]
}

Проверьте данные

Операция validate проверяет данные без сохранения. Используйте для валидации форм в CRM.

{
  "operations": [
    {
      "op": "validate",
      "externalId": "apt-new",
      "announcementType": "rent",
      "propertyType": "residential",
      "propertySecondaryType": "apartment",
      "announcementValue": 500
    }
  ]
}
Ответ
{
  "results": [
    {
      "op": "validate",
      "externalId": "apt-new",
      "success": true,
      "valid": true,
      "errors": [],
      "warnings": []
    }
  ]
}

Smart Create

Операция smart_create создаёт объявление из текстового описания и фотографий с помощью ИИ. Принимает те же параметры, что и POST /listings/smart.

{
  "operations": [
    {
      "op": "smart_create",
      "description": "Уютная 2-комнатная квартира, 65 м², этаж 3/9. Евроремонт, тёплые полы.",
      "files": [
        { "url": "https://example.com/photo1.jpg", "externalFileId": "apt-001-photo-1" }
      ],
      "externalId": "apt-001",
      "externalUrl": "https://agency.example/listings/kvartira-v-centre",
      "targetStatus": "active"
    }
  ]
}
Ответ
{
  "results": [
    {
      "op": "smart_create",
      "externalId": "apt-001",
      "externalUrl": "https://agency.example/listings/kvartira-v-centre",
      "success": true,
      "jobId": 789,
      "status": "pending"
    }
  ]
}

Каждая операция smart_create создаёт асинхронную задачу. Отслеживайте прогресс через статус задачи. Подробнее о параметрах — в разделе Smart Create.


Комбинируйте операции

В одном запросе можно выполнить разные типы операций:

{
  "operations": [
    { "op": "upsert", "externalId": "apt-001", "announcementValue": 550 },
    { "op": "upsert", "externalId": "apt-002", "announcementStatus": "hidden" },
    { "op": "link", "id": 99, "externalId": "apt-003" },
    { "op": "delete", "externalId": "apt-old" }
  ]
}

HTTP-статусы ответа

HTTP-статус ответа bulk-запроса зависит от результата отдельных операций:

СтатусУсловиеОписание
200Все операции успешныКаждая операция имеет success: true
207Частичный успехЧасть операций успешна, часть — нет
422Все операции неуспешныКаждая операция имеет success: false

Всегда проверяйте поле summary и отдельные results независимо от HTTP-статуса.

Обработка ошибок

Ошибка в одной операции не останавливает остальные. Проверяйте success для каждого результата.

Ответ с ошибкой
{
  "results": [
    { "op": "upsert", "externalId": "apt-001", "id": 42, "success": true },
    {
      "op": "upsert",
      "externalId": "apt-002",
      "id": null,
      "success": false,
      "error": {
        "statusCode": 400,
        "body": {
          "error": "propertyType is required",
          "error_code": "VALIDATION_ERROR"
        }
      }
    },
    { "op": "upsert", "externalId": "apt-003", "id": 44, "success": true }
  ],
  "summary": {
    "total": 3,
    "succeeded": 2,
    "failed": 1
  }
}

Обработайте неуспешные операции:

Node.js
const result = await response.json();

const failed = result.results.filter(r => !r.success);
if (failed.length > 0) {
  console.error('Ошибки:', failed);
  // Логировать или повторить позже
}

Рекомендации

Отправляйте последовательно

Отправляйте пакеты последовательно, а не параллельно. Система обрабатывает операции в порядке очереди — параллельная отправка не ускорит обработку.

Обновляйте только изменённые данные

После первичной синхронизации отправляйте только изменённые объявления. Повторная отправка всех объявлений без изменений — неэффективное использование API.

Используйте частичные обновления

Передавайте только изменённые поля. Чтобы очистить поле, отправьте null:

{
  "op": "upsert",
  "externalId": "apt-001",
  "announcementValue": 600,
  "propertyFloorNumber": null
}

Ограничения

ПараметрЗначение
Максимум операций в запросе100
Поля операции upsertсм. PUT /listings

Коды ошибок

КодОписаниеРешение
VALIDATION_ERRORОшибка валидации полейПроверьте обязательные поля и форматы
USER_RESOLUTION_FAILEDАгент не найденПроверьте userId или externalUserId
NOT_FOUNDОбъявление не найденоИспользуйте externalId для upsert
EXTERNAL_ID_ALREADY_LINKEDExternal ID уже используетсяИспользуйте уникальный external ID
Copyright © 2026