# Formhunt

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

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

## Публичный приём
POST https://app.formhunt.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. 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, не создавайте новую заявку автоматически.

## Ограничения и ошибки
Тело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.formhunt.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 означают сохранение без обычной внешней доставки.
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.