# Субмито (Submito)

Form backend для HTML, React и Astro. Первый шаг: создайте форму в личном кабинете, скопируйте публичный access_key и добавьте его в body существующей формы.

## Материалы
- Личный кабинет: https://app.submito.ru/
- Быстрое подключение: /docs/quickstart/
- HTML: /integrations/html/
- React: /integrations/react/
- Astro: /integrations/astro/
- Актуальный OpenAPI: https://app.submito.ru/openapi.json

## Публичный приём
POST https://app.submito.ru/v1/submit
JSON, application/x-www-form-urlencoded или multipart/form-data с текстовыми полями.
access_key — обязательный body/hidden input, публичный и только для приёма. Он не даёт management-доступа. Management token не передавайте в browser, snippet или репозиторий.
Пример JSON: {"access_key":"YOUR_ACCESS_KEY","email":"synthetic@example.test","message":"Синтетическая проверка","test":true}
Accept: application/json выбирает JSON. credentials: omit. При captcha_mode=off Native POST работает без JavaScript и после commit получает303 на allowed redirect либо receipt.
Успех: HTTP201/200, success:true, status:accepted, submission_id, request_id, test, replay. Это durable сохранение, не подтверждение доставки.
Idempotency-Key:1..128 printable ASCII, область формы,24 часа. Повтор неизменных данных с тем же ключом возвращает прежний ID; изменённые данные409. После потерянного ответа сохраняйте ключ и payload, не создавайте новую заявку автоматически.

## Опциональная защита ALTCHA
По умолчанию защита выключена. Владелец может включить ALTCHA в настройках формы и обновить код сайта из инструкции кабинета. Для защищённой формы нужны JavaScript и HTTPS; widget и проверка размещаются у Субмито без сторонних сервисов.
POST https://app.submito.ru/v1/captcha/challenge принимает только JSON {"access_key":"YOUR_ACCESS_KEY"}, body1024 bytes, без cookies; ключ не передаётся в URL. Возвращается подписанное ALTCHA PoW v2 задание со сроком5min. Скрипт https://app.submito.ru/assets/captcha/3.5.0/submito.js подключает локальные widget/ru assets и использует POST challenge.
Отправляйте singleton строковый captcha_token в обычный POST /v1/submit. Proof не является бизнес-полем и не входит в payload hash, сохранение, экспорт или доставку; общий бюджет100 полей включает proof. Missing/invalid proof возвращает400 с details code captcha_required/captcha_invalid; повтор ранее принятой заявки с тем же Idempotency-Key проходит без нового proof. Public test=true не обходит капчу.
Challenge budgets: source10/refill0.2 в секунду, form30/refill1,429 Retry-After5. Submit limits остаются прежними. При ошибке проверки сохраняйте поля и ключ бизнес-попытки.

## Ограничения и ошибки
Тело65536 bytes,100 имён, имя64 ASCII символа, значение8192 UTF-8 bytes,20 значений на имя. Files/nesting/duplicate JSON control/authority поля отклоняются. botcheck отсутствует или пуст; заполненный honeypot400 без сохранения.
400 invalid_request;404 неизвестный/отозванный/отключённый ключ;409 idempotency_conflict;413 payload_too_large;415 unsupported_media_type;429 rate_limited с Retry-After:1;503 intake_unavailable. Не показывайте success при HTTP/JSON/network error. Сохраняйте ввод и используйте безопасный request_id, не логируйте payload/keys/IP.
Технические shared limits: source burst60/refill1 в секунду; форма burst120/refill2 в секунду. Повторы и test также расходуют request budget; это не коммерческая квота.

## MCP проверка подключения
POST https://app.submito.ru/mcp — stateless Streamable HTTP с Bearer управляющим токеном. Workspace определяется токеном. Не передавайте этот токен в сайт: браузеру нужен только публичный access_key.
Инструменты управления: list_forms, create_form, update_form, get_integration_snippet, rotate_form_key. create_form требует request_key для безопасного повтора; ключ показывается один раз, replay его не восстанавливает.
submit_test(access_key,payload,idempotency_key) требует submissions:test и сохраняет только synthetic test. Повторяйте те же поля с тем же ключом при потерянном ответе. saved/side_effects_disabled означают сохранение без обычной внешней доставки. Этот доверенный тест возвращает captcha_checked:false: он не доказывает прохождение публичной капчи. Проверьте защищённую форму отдельно настоящим браузером.
get_test_status(submission_id) возвращает только metadata теста своего workspace, без payload и реальных заявок. correlation_id равен стабильному submission_id, это не исходный HTTP request_id.
test_owner_notification(form_id,request_id UUIDv4) требует отдельного delivery:test, не выбранного по умолчанию. Он создаёт отдельный synthetic test и возвращает его submission_id/event_id со status=queued. Передайте этот ID в get_test_status: delivered показывается только после результата фонового провайдера, failed не отменяет saved. Произвольного получателя передать нельзя.
canary/обычные заявки не читаются диагностикой. Ошибки token/key/idempotency/budget/storage имеют безопасный code/request_id и следующий шаг. Provider failure требует проверки настроек и фонового worker; webhook not_configured не означает доставку.

## Проверка и доставка
Для synthetic проверки передавайте test:true (JSON boolean или hidden input value=true). Заявка сохраняется с kind=test, не создаёт commercial usage и обычных внешних side effects. Canary нельзя включить публичным полем.
Проверьте поля сохранённой заявки в кабинете. Доставку владельцу проверяйте отдельным явным тестом на подтверждённый адрес. Не объявляйте webhook/email доставленным по одному accepted.
Не читайте реальные заявки без отдельного разрешения. Не включайте server credentials в клиентский bundle.