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 | Поиск по названию, адресу и тегам |
filters | JSON: числовые поля — {"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 | Метод не поддерживается по этому адресу |
| 409 | external_id уже занят другим объектом аккаунта; поле, которое в Метраже не правится (или любое поле из Модуля в пробном режиме), либо удаление объекта из Модуля Риэлтор (source_owned, список полей в fields) |
| 429 | Превышен лимит запросов в минуту; повторите через Retry-After секунд |