Регистрация полей

Каждый спутниковый запрос относится к полю, которое ваше приложение зарегистрировало. При регистрации вы передаёте границу поля и свой идентификатор, а AgroSat начинает готовить историю поля.

Регистрация поля

Тело запроса POST /v1/fields содержит три свойства:

Свойство	Тип	Примечание
`name`	строка, до 200 символов	Название для людей.
`external_id`	строка, до 128 символов	Ваш идентификатор поля. Уникален в пределах организации.
`geometry`	GeoJSON `Polygon` или `MultiPolygon`	WGS84, координаты в порядке долгота, широта.

curl https://api.agrosat.uz/v1/fields \
  -H "X-API-Key: $AGROSAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Северный участок 3",
    "external_id": "f-1001",
    "geometry": {
      "type": "Polygon",
      "coordinates": [[[68.552, 40.3084], [68.560, 40.3084], [68.560, 40.3139], [68.552, 40.3139], [68.552, 40.3084]]]
    }
  }'

def register(session, name, external_id, geometry):
    r = session.post(
        "https://api.agrosat.uz/v1/fields",
        json={"name": name, "external_id": external_id, "geometry": geometry},
        timeout=30,
    )
    body = r.json()
    if not body["success"]:
        raise RuntimeError(f'{r.status_code} {body["error"]["code"]}: {body["error"]["message"]}')
    return body["data"]

async function register(name, externalId, geometry) {
  const res = await fetch("https://api.agrosat.uz/v1/fields", {
    method: "POST",
    headers: { "X-API-Key": process.env.AGROSAT_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ name, external_id: externalId, geometry }),
  });
  const body = await res.json();
  if (!body.success) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
  return body.data;
}

Новое поле возвращается с кодом 201:

{
  "success": true,
  "data": {
    "id": "cmgz7k2qv0004l8p3a9d1x6rt",
    "external_id": "f-1001",
    "name": "Северный участок 3",
    "area_ha": 41.53,
    "status": "pending",
    "created_at": "2026-04-28T09:14:03.512Z"
  }
}

Сохраните id: все остальные эндпоинты принимают его в пути. area_ha — площадь, которую AgroSat вычислил по геометрии, с округлением до сотых. status остаётся pending, пока готовится история; см. Готовность поля.

Безопасные повторы

Регистрация идемпотентна по external_id:

Что вы отправляете	Что получаете
Новый `external_id`	`201` и новое поле
Существующий `external_id` с той же геометрией	`200` и существующее поле; ничего нового не создаётся и не списывается
Существующий `external_id` с другой геометрией	`409 external_id_conflict`, id существующего поля в `error.existing_field_id`

Поэтому после тайм-аута или сетевой ошибки достаточно отправить тот же запрос ещё раз.

Изменить границу поля через API нельзя. Чтобы заменить её, удалите поле и зарегистрируйте новую границу; после удаления старого поля его external_id снова свободен. Новое поле получит новый id, его площадь будет списана полностью, а площадь удалённого поля останется израсходованной.

Что проверяется при регистрации

Проверка	Ошибка
Геометрия — корректный `Polygon` или `MultiPolygon` в WGS84 без самопересечений	`400 invalid_geometry`
Площадь поля не больше лимита на одно поле по договору (5000 га, если не оговорено иное)	`400 field_too_large`
В теле есть все свойства нужных типов	`400 invalid_request`
Поле помещается в остаток гектаров текущего периода договора	`403 quota_exceeded`
Поле не перекрывает уже зарегистрированное более чем на 80 % своей площади	`409 duplicate_geometry`, id существующего поля в `error.existing_field_id`

Чтение и удаление полей

GET /v1/fields/{id} возвращает одно поле с текущим status.
GET /v1/fields?external_id=f-1001 находит поле по вашему идентификатору.
GET /v1/fields выдаёт все поля постранично; см. Список полей.
DELETE /v1/fields/{id} удаляет поле и отвечает 204 без тела. После этого любой запрос к нему возвращает 404 field_not_found.

Запросы к полям не расходуют юниты.

Что дальше

Готовность поляКогда появляются данные и что означает 202.

Список полейКак обойти все страницы со списком полей.