API Метража

Объекты вашего аккаунта Метража для своих систем: сайт, 1С, собственная CRM.

Доступ

Ключ выдаёт администратор amoCRM: Настройки → Метраж → вкладка «API». У ключа своя область: read — только чтение, write — чтение и изменения. Ключ показывается один раз; потеряли — выпустите новый и отзовите старый.

Authorization: Bearer mtz_...

Адрес API — тот, на котором открыта эта страница. Все ответы — JSON в UTF-8. Ключ видит все объекты аккаунта, включая закрытые. Изменения через API попадают в историю объекта с источником «api».

Методы

МетодПутьЧто делает
GET/v1/objectsСписок объектов, по возрастанию времени изменения
GET/v1/objects/{id}Объект с фото
POST/v1/objectsСоздать объект (ключ write)
PATCH/v1/objects/{id}Изменить поля (ключ write)
DELETE/v1/objects/{id}Удалить объект, как из интерфейса (ключ write)
GET/v1/fieldsПоля объекта: колонка, подпись, единица, тип, справочник; типы объектов (object_types: id и название)

Список

ПараметрЗначение
pageСтраница, с 1
limitОбъектов на странице, до 200 (по умолчанию 50)
updated_sinceТолько изменённые с этой даты, 2026-09-01 или 2026-09-01T10:00:00Z. Удобно для синхронизации
qПоиск по названию, адресу и тегам
filtersJSON: числовые поля — {"free_area": {"min": 1000, "max": 3000}}, списки — {"temperature": ["Теплый"]}, даты — {"created_at": {"min": "2026-09-01"}}, остальное — равенство, например {"external_id": "A-17"}. Тип объекта лучше задавать id из object_types: {"object_type": [7092, 7091]}. Названия типов 29.10.2026 сверены со справочником Модуля Риэлтор, а название в фильтре читается по-старому, чтобы прежние фильтры находили те же объекты: «Готовый бизнес» в фильтре — тип 7108 (теперь «Помещение общественного питания»)
curl -H "Authorization: Bearer mtz_..." "https://<адрес>/v1/objects?updated_since=2026-09-01&limit=100"
{
  "items": [{"id": 495078, "name": "Логопарк «Северный»", "free_area": 3200, "updated_at": "2026-09-21T10:12:00+00:00", ...}],
  "total": 8,
  "page": 1,
  "next_page": null
}

Создание и изменение

Тело — {"fields": {...}}, колонки из /v1/fields. Для создания обязательно name. Номер объекта в вашей системе храните в external_id: он уникален в аккаунте, по нему удобно находить объект при синхронизации.

curl -X POST -H "Authorization: Bearer mtz_..." -H "Content-Type: application/json" \
  -d '{"fields": {"name": "Склад, Подольск", "deal_type": "rent", "total_area": 5200, "free_area": 1800}}' \
  "https://<адрес>/v1/objects"

{"id": 495100}

Цена в другой валюте: price и price_currency с кодом ISO 4217 (USD, CNY). Без price_currency цена — в основной валюте аккаунта. В ответе price_main — цена в основной валюте по курсу ЦБ РФ; только для чтения.

Фото через API пока только читаются: ссылки в ответе GET /v1/objects/{id} действуют час.

Объекты из Модуля Риэлтор

У объекта с mr_id поля приходят из Модуля. Править их можно, как в карточке Метража: правка остаётся в Метраже, в Модуль не уходит, и синхронизация её больше не перезаписывает. Такие поля перечислены в local_edits объекта, последнее значение Модуля по каждому — в mr_values. Вернуть полю значение Модуля — {"reset": ["free_area"]} в теле PATCH, можно вместе с fields, но не для того же поля; такой PATCH применяется целиком или никак. Поле Модуля, присланное с прежним значением, в local_edits не попадает. Не правятся никогда mr_id, lead_id, responsible_amo_id, object_type, object_type_id, is_storage, available_now, free_date_raw и extra. Правка free_date очищает available_now и free_date_raw, а reset даты возвращает и их. В пробном режиме поля из Модуля закрыты. Удаляется такой объект только в Модуле.

curl -X PATCH -H "Authorization: Bearer mtz_..." -H "Content-Type: application/json" \
  -d '{"reset": ["free_area"]}' "https://<адрес>/v1/objects/495078"

Лимиты

На аккаунт — 120 запросов в минуту; с опцией «Расширенный API» — 3000. Каждый ответ несёт X-RateLimit-Limit и X-RateLimit-Remaining; сверх лимита — 429 с Retry-After в секундах. Для синхронизации хватает updated_since и страниц по 200 объектов. Нужно больше — напишите на help@bps.nz.

Ошибки

{"error": "unknown_column", "message": "неизвестные поля: area; список — GET /v1/fields"}
КодКогда
400Неверное тело, параметр, колонка или значение не того типа
401Нет ключа, ключ неверный или отозван
402Лицензия Метража недействительна
403Ключ только для чтения, а метод меняет данные; аккаунт в пробном режиме (trial_mode)
404Нет такого объекта или адреса
405Метод не поддерживается по этому адресу
409external_id уже занят другим объектом аккаунта; поле, которое в Метраже не правится (или любое поле из Модуля в пробном режиме), либо удаление объекта из Модуля Риэлтор (source_owned, список полей в fields)
429Превышен лимит запросов в минуту; повторите через Retry-After секунд

Вопросы

help@bps.nz