From 11b6ca98354b19cf558bb987427cd81668c60827 Mon Sep 17 00:00:00 2001
From: "Zimin A.N." <zimin.an@nstart.space>
Date: Wed, 20 May 2026 11:40:19 +0300
Subject: [PATCH] =?UTF-8?q?docs(api):=20=D0=BB=D0=BE=D0=BA=D0=B0=D0=BB?=
 =?UTF-8?q?=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D1=8F=20=E2=80=94=20=D1=82=D0=BE?=
 =?UTF-8?q?=D0=BB=D1=8C=D0=BA=D0=BE=20Accept-Language=20header=20(=D0=BD?=
 =?UTF-8?q?=D0=B5=20=3Flocale=3D=20query)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

После testing на staging выявлено: backend парсит локаль ТОЛЬКО из
Accept-Language header. ?locale=en-US query param сейчас игнорируется
(сервер возвращает default ru-RU вне зависимости от значения).

Реальный demo (spacecraft/1999-068A):
  default (без header):           operator: "НАСА"
  Accept-Language: en-US:         operator: "NASA"
  ?locale=en-US (без header):     operator: "НАСА"  ← не работает

Cheatsheet + quickstart обновлены. Postman collection тоже (используется
header). ?locale= query — отдельный backend feature request в roadmap.
---
 docs/integration/api-cheatsheet.md |  3 ++-
 docs/integration/api-quickstart.md | 11 +++++++----
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/docs/integration/api-cheatsheet.md b/docs/integration/api-cheatsheet.md
index ccad079..2c6373d 100644
--- a/docs/integration/api-cheatsheet.md
+++ b/docs/integration/api-cheatsheet.md
@@ -47,7 +47,8 @@ Scopes: `PUBLIC` (anon ok) · `INTERNAL` (auth) · `RESTRICTED` (admin).
 ```
 ?as_scope=PUBLIC,INTERNAL    (required) CSV scope filter
 ?at=2026-03-15T00:00:00Z     bitemporal: запись на конкретный момент (validFrom <= at < validTo)
-?locale=en-US                локаль (или Accept-Language header)
+Accept-Language: en-US       (header) локаль — единственный рабочий путь
+                             ⚠️ ?locale= query param backend сейчас игнорирует
 ?bbox=lon1,lat1,lon2,lat2    geo: bounding box (для geo-dicts)
 ?polygon=<GeoJSON>           geo: polygon-фильтр
 ```
diff --git a/docs/integration/api-quickstart.md b/docs/integration/api-quickstart.md
index 1b33243..14df136 100644
--- a/docs/integration/api-quickstart.md
+++ b/docs/integration/api-quickstart.md
@@ -197,10 +197,13 @@ curl "$ORDINIS/api/v1/spacecraft/records/1999-068A?as_scope=PUBLIC"
 ### 4.3 Фильтры
 
 ```bash
-# Locale — для x-localized полей сервер вернёт только указанную локаль
-curl "$ORDINIS/api/v1/spacecraft/records/1999-068A?as_scope=PUBLIC&locale=en-US"
-# или через стандартный header:
-curl -H "Accept-Language: en-US" "$ORDINIS/api/v1/spacecraft/records?as_scope=PUBLIC"
+# Locale — для x-localized полей (name, mission, operator etc).
+# ⚠️ Сейчас работает ТОЛЬКО через Accept-Language header. ?locale= query
+# param backend игнорирует — TODO в roadmap.
+curl -H "Accept-Language: en-US" \
+  "$ORDINIS/api/v1/spacecraft/records/1999-068A?as_scope=PUBLIC"
+# default ru-RU:    "mission": "Глобальный мониторинг суши и атмосферы"
+# с Accept-Language en-US:  "mission": "Global land and atmosphere monitoring"
 
 # Time-travel: состояние на конкретный момент (validFrom <= at < validTo)
 curl "$ORDINIS/api/v1/spacecraft/records/1999-068A?as_scope=PUBLIC&at=2026-01-01T00:00:00Z"