RealtyCloud API Documentation

Quick Start

Если нужно быстро запустить интеграцию, обычно достаточно пройти этот сценарий. Он покрывает большинство продуктов с асинхронной моделью работы.

Минимальный сценарий для обычного заказа

curl -X GET "https://apirc.ru/balance" \
-H "API-Key: YOUR_API_KEY"

curl -X POST "https://apirc.ru/order" \
-H "Content-Type: application/json" \
-H "API-Key: YOUR_API_KEY" \
-d '{
  "order_items": [
    {
      "product_name": "CheckOwnerV2",
      "metadata": {
        "ownersData": [
          {
            "first": "Иван",
            "surname": "Иванов",
            "birthday": "1997-04-07T00:01:00.0Z",
            "passport": "9217285273"
          }
        ]
      }
    }
  ]
}'

curl -X POST "https://apirc.ru/orders" \
-H "Content-Type: application/json" \
-H "API-Key: YOUR_API_KEY" \
-d '{
  "order_item_ids": ["YOUR_ORDER_ITEM_ID"]
}'Copy

Минимальный сценарий для подписок

curl -X GET "https://apirc.ru/subscriptions/current?only_active=true&has_requests_left=true" \
-H "API-Key: YOUR_API_KEY"

curl -X GET "https://apirc.ru/subscriptions/usage?limit=20" \
-H "API-Key: YOUR_API_KEY"Copy

Сценарии интеграции

Ниже короткая карта типовых сценариев. Она помогает быстро понять, какой метод использовать и чего ожидать от результата.

Статусы заказов

Большинство асинхронных продуктов работают через создание заказа и последующий опрос статуса. Эти статусы стоит интерпретировать одинаково во всех интеграциях.

Ошибки и диагностика

Ниже список типовых проблем, которые чаще всего встречаются на этапе интеграции и в боевой эксплуатации.

Глоссарий

Эти термины стоит одинаково трактовать и в коде интеграции, и в интерфейсе для операторов.

Обязательные поля и качество результата

Чтобы снизить количество пустых или спорных результатов, важно разделять: что необходимо для технического принятия запроса и что повышает точность проверки.

Хорошие и плохие запросы

Один хороший и один плохой пример обычно ускоряют интеграцию лучше, чем длинный текстовый список ограничений.

Проверка физлица: хороший пример

{
  "order_items": [
    {
      "product_name": "CheckOwnerV2",
      "metadata": {
        "ownersData": [
          {
            "first": "Иван",
            "surname": "Петров",
            "patronymic": "Александрович",
            "birthday": "1978-08-01T00:00:00.000Z",
            "passport": "1809370925",
            "inn": "123456789012",
            "region": "50",
            "owner_type": 0
          }
        ]
      }
    }
  ]
}Copy

Почему хорошо: есть базовые идентификаторы и дата рождения, что уменьшает количество ложных совпадений.

Проверка физлица: плохой пример

{
  "order_items": [
    {
      "product_name": "CheckOwnerV2",
      "metadata": {
        "ownersData": [
          {
            "first": "Иван",
            "surname": "Иванов"
          }
        ]
      }
    }
  ]
}Copy

Почему плохо: запрос может быть принят, но точность будет низкой, особенно для распространённых ФИО.

Проверка юрлица: хороший пример

{
  "order_items": [
    {
      "product_name": "CounterAgent",
      "metadata": {
        "ownersData": [
          {
            "first": "АО Компания",
            "inn": "1640011322",
            "region": "16",
            "owner_type": 1
          }
        ]
      }
    }
  ]
}Copy

Почему хорошо: заполнены ключевые поля для точной идентификации контрагента.

Проверка юрлица: плохой пример

{
  "order_items": [
    {
      "product_name": "CounterAgent",
      "metadata": {
        "ownersData": [
          {
            "first": "Компания"
          }
        ]
      }
    }
  ]
}Copy

Почему плохо: отсутствуют ИНН и регион, из-за чего вероятность релевантного результата резко падает.

Поиск по адресу: хороший и плохой варианты

# Хорошо:
GET /search?query=Москва,+пр-кт.+Рязанский,+д.+97,+корп.+2,+кв.+74

# Плохо:
GET /search?query=РязанскийCopy

Почему плохо: короткий и неструктурированный запрос возвращает шум или слишком широкий список объектов.

Риск-отчёт: хороший и плохой варианты

{
  "order_items": [
    {
      "product_name": "RiskAssessmentV2",
      "object_key": "50:11:0050501:2982",
      "object_address": "Московская область, ...",
      "metadata": {
        "ownersData": [
          {
            "owner_type": 0,
            "first": "Иван",
            "surname": "Петров",
            "passport": "1809370925",
            "birthday": "1978-08-01T00:00:00.000Z",
            "region": "50",
            "registration_number": "50-50/011-50/011/002/2016-5561/1"
          }
        ]
      }
    }
  ]
}Copy

{
  "order_items": [
    {
      "product_name": "RiskAssessmentV2",
      "object_key": "50:11:0050501:2982"
    }
  ]
}Copy

Почему второй вариант хуже: отчёт может построиться, но часть проверок по участникам сделки будет недоступна или неполна.

Как работать с подписками

Раздел нужен для нового интегратора, чтобы быстро понять, активна ли подписка, есть ли лимит, и когда лучше использовать подписочный сценарий.

Когда использовать подписку, а когда обычный заказ

• Подписка лучше, когда нужен регулярный поток однотипных запросов и контроль лимита по тарифу.
• Обычный заказ лучше, когда нужны разовые проверки или продукты, не входящие в текущую подписку.
• Если сомневаетесь, сначала проверьте /subscriptions/current и убедитесь, что нужный kind действительно активен.

Быстрая проверка статуса подписки

curl -X GET "https://apirc.ru/subscriptions/current?only_active=true&has_requests_left=true" \
-H "API-Key: YOUR_API_KEY"Copy

Ожидания по результату

Часть интеграционных проблем возникает из-за ожидания «всегда полный ответ». Ниже практическая норма по поведению API.

Webhooks: интеграция

Webhook отправляет событие order.final_status_changed, когда order_item переходит в терминальный статус: DONE, REFUND, DELETED, ACTION_REQUIRED.

Кроме событий по заказам, для продуктов мониторинга объекта доступны отдельные webhook-события семейства objectinfo_monitoring.*.

Текущий и планируемый путь интеграции

Минимальный flow через API-Key (доступен уже сейчас)

1. Создайте/получите API-ключ в личном кабинете.
2. Создайте подписку: POST /webhooks.
3. Сохраните secret и настройте проверку подписи на своей стороне.
4. Проверьте endpoint командой POST /webhooks/{webhookID}/ping.
5. Мониторьте GET /webhooks и при авто-отключении вызывайте POST /webhooks/{webhookID}/reset.

Быстрые команды

# 1) Создать подписку
curl -X POST "https://apirc.ru/webhooks" \
  -H "API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://client.example.com/hooks/realtycloud",
    "active": true
  }'

# 2) Тестовый вызов (ping)
curl -X POST "https://apirc.ru/webhooks/{webhookID}/ping" \
  -H "API-Key: YOUR_API_KEY"

# 3) Проверить состояние подписок
curl -X GET "https://apirc.ru/webhooks" \
  -H "API-Key: YOUR_API_KEY"Copy

Какие события и для каких продуктов приходят

JSON-модель: order.final_status_changed

{
  "delivery_id": "f1f33ec5-3645-4b31-bc4a-1df2bb1b4267",
  "type": "order.final_status_changed",
  "occurred_at": "2026-03-04T18:20:00Z",
  "order_id": "e2e0e58d-cf26-48fe-8b1d-7f533ef455a4",
  "order_item_id": "30947b06-3eb1-4c4c-8f13-2cc53ff63c93",
  "person_id": "e9d99ec7-1b8f-4f19-bb4c-206cc8404c65",
  "status": "DONE",
  "order": {
    "order_id": "e2e0e58d-cf26-48fe-8b1d-7f533ef455a4",
    "owner_id": "e9d99ec7-1b8f-4f19-bb4c-206cc8404c65",
    "owner_email": "client@example.com",
    "owner_phone": "+79990000000",
    "paid": true,
    "created_at": "2026-03-04T17:55:00Z",
    "source": "https://partner.example.com",
    "transaction_id": "7d2b73b8-a4fb-4a40-9f7a-f1f8db8829c8",
    "transaction_status_id": 4,
    "item": {
      "order_item_id": "30947b06-3eb1-4c4c-8f13-2cc53ff63c93",
      "order_id": "e2e0e58d-cf26-48fe-8b1d-7f533ef455a4",
      "product_id": "30b9fa1e-27e7-4976-ba73-b4c4b03a1559",
      "product_name": "CheckOwnerV2",
      "amount": 1,
      "price": "249",
      "discount": "0",
      "status": "done",
      "comment": "",
      "metadata": {
        "ownersData": [
          {
            "first": "Иван",
            "surname": "Иванов",
            "patronymic": "Иванович",
            "birthday": "1997-04-07T00:01:00.0Z",
            "passport": "9217285273",
            "region": "16",
            "owner_type": 0
          }
        ]
      },
      "rosreestr_request_id": "",
      "item_metadata": {
        "order_item_id": "30947b06-3eb1-4c4c-8f13-2cc53ff63c93"
      },
      "is_order_paid": true,
      "download_link_pdf": "https://apirc.ru/download?orderID=30947b06-3eb1-4c4c-8f13-2cc53ff63c93&fileType=pdf",
      "download_link_zip": "https://apirc.ru/download?orderID=30947b06-3eb1-4c4c-8f13-2cc53ff63c93&fileType=signed_zip",
      "item_statuses": [
        {
          "status": "done",
          "created_at": "2026-03-04T18:20:00Z"
        }
      ]
    }
  }
}Copy

Поля payload для order.final_status_changed

JSON-модель: webhook.ping

{
  "type": "webhook.ping",
  "occurred_at": "2026-03-04T18:22:00Z",
  "webhook_subscription_id": "0f58cd3c-2d8a-4f57-8d0d-a4bc570c9c62",
  "message": "ping"
}Copy

JSON-модель: objectinfo_monitoring.changes_detected

{
  "type": "objectinfo_monitoring.changes_detected",
  "occurred_at": "2026-03-16T09:45:00Z",
  "person_id": "e9d99ec7-1b8f-4f19-bb4c-206cc8404c65",
  "monitoring": {
    "monitoring_id": "11111111-1111-1111-1111-111111111111",
    "cadastr": "77:04:0002010:1101",
    "frequency": "weekly",
    "status": "active",
    "duration_days": 0,
    "tracking_keys": ["rights", "encumbrances"],
    "has_unread_changes": true,
    "successful_checks": 7,
    "failed_checks": 1,
    "charged_total_rub": "18.72",
    "next_check_at": "2026-03-16T10:00:00Z",
    "last_success_at": "2026-03-15T09:30:00Z",
    "expires_at": "2026-04-01T00:00:00Z"
  },
  "check": {
    "check_id": "22222222-2222-2222-2222-222222222222",
    "status": "success_with_changes",
    "http_status": 200,
    "app_status": "success",
    "success": true,
    "consumed": true,
    "amount_rub": "2.16",
    "diff_summary": "Изменились права",
    "diff_result": [
      {
        "key": "rights"
      }
    ],
    "created_at": "2026-03-16T09:45:00Z"
  }
}Copy

Changelog документации

Короткий changelog помогает интеграторам быстро понимать, что изменилось и нужно ли дорабатывать клиента.