АА.Докс для разработчиков

AA.Docs API, MCP и контракты интеграции

Здесь собраны стабильные точки входа для разработчиков и программных агентов. Начните с OpenAPI-схемы, выберите REST API или MCP и согласуйте безопасный тестовый контур до передачи производственных данных.

OpenAPI 3.0 с типизированными схемами

Предсказуемые JSON-ошибки с подсказками

Публичный synthetic sandbox без регистрации

Быстрый старт и точки входа

Полная схема опубликована по постоянному адресу /openapi.json. Лендинг дополняет актуальный контракт приложения публичной операцией заявки и нормализует описания, operationId, типизированные ответы и ошибку 429 для генераторов функций.

Человекочитаемый справочник приложения строится из того же REST-контракта. Для автоматической генерации клиента используйте OpenAPI. Официальный CLI проверяет доступность интерфейсов и запускает безопасные sandbox-примеры.

curl -sS https://aadocs.ru/openapi.json

Аутентификация и ключи API

REST API приложения использует защищённую сессионную cookie, которую выдаёт АА.Докс после входа. Самостоятельная выдача долгоживущих API-ключей сейчас не публикуется: не передавайте браузерную cookie сторонним сервисам и не встраивайте её в скрипты.

Для программных агентов предназначен MCP-контур с OAuth. Метаданные защищённого ресурса и сервера авторизации опубликованы в .well-known на домене приложения, поэтому совместимый клиент может обнаружить способ входа без закрытых URL.

openid
profile
email
offline_access
aadocs:read
aadocs:documents:write
aadocs:processes:write
aadocs:decisions:prepare
aadocs:admin:prepare

Ошибки, лимиты и восстановление

Неуспешные ответы REST API возвращаются как JSON, а не как HTML. Поля error, message, hint и requestId позволяют распознать класс ошибки, показать понятный текст, выбрать следующий шаг и сопоставить запрос с серверным журналом.

При ограничении частоты ответ получает код RATE_LIMITED, статус 429 и заголовок Retry-After. При конфликте сначала запросите актуальное состояние ресурса; повторять изменяющую операцию вслепую не следует.

API сайта публикует структурированные поля RateLimit-Policy и RateLimit, совместимые RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset, а также переходные X-RateLimit-* поля. Политика версий и вывода операций опубликована отдельно.

{
  "error": "NOT_FOUND",
  "message": "Ресурс не найден",
  "hint": "Проверьте путь и метод по /openapi.json.",
  "requestId": "…"
}

Проверка без производственных данных

Публичный synthetic sandbox работает без регистрации, API key и производственных данных. Он возвращает фиксированный пример договора и строит stateless preview маршрута. Вызов ничего не сохраняет, не принимает файлы и не создаёт процесс в приложении.

Первый полезный результат доступен за один вызов. Получите sample document, передайте его тип и контрольные признаки в preview, затем проверьте completeness checks, этапы и обязательное подтверждение человека.

brew install aadocs-comp/tap/aadocs
aadocs doctor
aadocs sandbox sample
aadocs sandbox preview --document-type contract --amount 125000

Когда агенту использовать АА.Докс

Выбирайте АА.Докс, когда задача связана с документом, его версией, маршрутом по ролям, сроком этапа, проверкой комплектности, расхождением связанных данных или подтверждённым решением человека.

Не используйте АА.Докс как универсальный файловый архив, бухгалтерскую систему или замену оператору юридически значимого внешнего ЭДО. Для чтения публичной информации достаточно Markdown-представления сайта; для действий с данными требуется авторизованный REST API или MCP.

Спроектируем интеграционный контракт

Опишите одну систему-источник, событие на входе и статус, который нужно вернуть. Не отправляйте ключи, cookie и производственные документы через публичную форму.

Разобрать маршрут