Объявления

Bulk операции

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

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

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

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

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


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

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

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

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

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

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',
        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',
        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",
      "id": 42,
      "success": true,
      "created": true,
      "updated": false
    },
    {
      "op": "upsert",
      "externalId": "apt-002",
      "id": 43,
      "success": true,
      "created": true,
      "updated": false
    }
  ],
  "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": []
    }
  ]
}

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

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

{
  "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