OpenAPI

Каждый эндпоинт этой документации также публикуется как машиночитаемый документ OpenAPI 3.1, поэтому инструменты можно настраивать по контракту, а не переписывать таблицы вручную.

Копия	URL	Примечания
Документация	https://docs.zelnum.com/openapi.yaml	Стабильный, на этом домене. Канонический для читателей этого сайта.
Платформа	https://app.zelnum.com/docs/openapi.yaml	Вышестоящий источник. Копия в документации — побайтово идентичное зеркало.

Оба файла — один и тот же документ. Зеркало существует, чтобы спецификация лежала на хосте, который вы уже читаете, по пути, который найдут инструменты.

Что содержит документ

Часть	Количество	Содержимое
Servers	1	https://api.zelnum.com/api/v1
Paths	10	Девять задокументированных эндпоинтов плюс прежний псевдоним realtime
Tags	3	Common, Realtime, Bulk — то же разделение, что и в навигации
Schemas	9	Тела запросов и ответов, включая конверт ошибки
Схемы безопасности	2	X-API-Key и Authorization: Bearer

Детали уровня операций — в самом документе: обязательные заголовки, minItems/maxItems для массивов, перечисления для series, mode, status и billing_status, а также флаг deprecated: true у POST /v1/realtime/detect.

Импорт в инструменты API

Postman — Import → File → openapi.yaml. Postman создаёт коллекцию с переменной окружения для базового URL; задайте ключ как заголовок X-API-Key уровня коллекции, чтобы его наследовал каждый запрос.

Insomnia — Create → Import From → File, затем добавьте X-API-Key как заголовок коллекции.

Bruno / HTTPie / curl-генераторы — все работают с OpenAPI 3.1 напрямую:

curl -fsSL https://docs.zelnum.com/openapi.yaml -o zelnum.yaml

Сгенерировать типизированный клиент

Собственного SDK нет — API это обычный JSON поверх HTTPS, и сгенерированный клиент обычно подходит лучше написанного вручную, поскольку следует соглашениям вашего языка.

# Pick your generator: python, typescript-fetch, php, go, java, csharp, ruby, …
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.zelnum.com/openapi.yaml \
  -g python \
  -o ./zelnum-client

Сгенерированные клиенты берут базовый URL и схему безопасности из документа, поэтому во время выполнения вы задаёте только свой API-ключ.

Realtime требует заголовок, который генератор не может придумать

Idempotency-Key — обязательный заголовок у эндпоинтов realtime, и сгенерированный клиент вынесет его как параметр метода, который вы обязаны задать. Он должен быть уникальным для каждой отправки — см. Идемпотентность и повторы.

Достоверность зеркала

Зеркало следует за вышестоящим источником; здесь его никогда не правят. Поскольку расхождение между опубликованным контрактом и его документацией — именно тот сбой, который эта страница призвана предотвратить, копию сверяют с вышестоящим источником, а не доверяют ей:

npm run openapi:check   # fetch upstream and fail if the bytes differ
npm run openapi:sync    # re-vendor, printing which operations changed

openapi:check требует доступа к сети и намеренно не входит в сборку сайта — деплой не должен падать из-за того, что у хоста платформы выдалась плохая минута. Сборка обеспечивает офлайновую половину инварианта: каждый эндпоинт, описанный в этой документации, должен присутствовать в поставляемом документе, поэтому страница не может задокументировать операцию, которой нет в контракте.

Дальше

• Версионирование и устаревание — что флаг deprecated на прежнем эндпоинте означает для вас
• Формат ответа — конверт, общий для всех эндпоинтов