erv-ticket-dev/docs/n8n_webhook_response.md

Формат ответа N8N Webhook для проверки SMS кода

URL Webhook

https://n8n.clientright.pro/webhook/erv_sms_verify

Входящие данные (POST)

{
  "phonenumber": "+79262306381",
  "code": "106574"
}

---

Формат ответа

✅ Успешная проверка (HTTP 200)

{
  "success": true,
  "message": "Код подтвержден"
}

Поля:

• success (boolean, обязательное) - true при успехе
• message (string, обязательное) - сообщение для пользователя

---

❌ Ошибки (HTTP 400)

1. Неверный код

{
  "success": false,
  "error": "invalid_code",
  "message": "Неверный код"
}

Поля:

• success (boolean) - false
• error (string) - код ошибки: "invalid_code"
• message (string) - сообщение для пользователя

---

2. Код не найден или истек

{
  "success": false,
  "error": "code_not_found",
  "message": "Код не найден или истек. Запросите новый код."
}

Поля:

• success (boolean) - false
• error (string) - код ошибки: "code_not_found"
• message (string) - сообщение для пользователя

---

3. Превышен лимит попыток

{
  "success": false,
  "error": "rate_limit_exceeded",
  "message": "Превышено количество попыток. Попробуйте позже."
}

Поля:

• success (boolean) - false
• error (string) - код ошибки: "rate_limit_exceeded"
• message (string) - сообщение для пользователя

---

4. Номер телефона или код не указаны

{
  "success": false,
  "error": "missing_data",
  "message": "Номер телефона или код не указаны"
}

Поля:

• success (boolean) - false
• error (string) - код ошибки: "missing_data"
• message (string) - сообщение для пользователя

---

5. Внутренняя ошибка сервера (HTTP 500)

{
  "success": false,
  "error": "internal_error",
  "message": "Сервис временно недоступен. Попробуйте позже."
}

Поля:

• success (boolean) - false
• error (string) - код ошибки: "internal_error"
• message (string) - сообщение для пользователя

---

Коды ошибок

Код ошибки	HTTP Status	Описание
invalid_code	400	Введенный код не совпадает с сохраненным
code_not_found	400	Код не найден в Redis или истек (TTL)
rate_limit_exceeded	400	Превышен лимит попыток проверки (10 за 15 минут)
missing_data	400	Не указан номер телефона или код
internal_error	500	Внутренняя ошибка (Redis недоступен и т.д.)

---

Примеры использования в n8n

Успешная проверка

Workflow шаги:

1. Webhook Trigger → получает phonenumber и code
2. Function Node → нормализация номера
3. Redis Node (GET) → чтение кода: sms:code:9262306381
4. Function Node → сравнение кодов
5. Redis Node (DEL) → удаление кода и счетчика попыток
6. Respond to Webhook → возвращает успешный ответ

Код для Respond to Webhook:

{
  "success": true,
  "message": "Код подтвержден"
}

---

Ошибка: Неверный код

Workflow шаги:

1. ... (аналогично успешной проверке)
2. Function Node → сравнение кодов
3. IF Node → если коды не совпадают
4. Respond to Webhook → возвращает ошибку

Код для Respond to Webhook:

{
  "success": false,
  "error": "invalid_code",
  "message": "Неверный код"
}

---

Ошибка: Код не найден

Workflow шаги:

1. ... (аналогично)
2. Redis Node (GET) → чтение кода
3. IF Node → если код = null
4. Respond to Webhook → возвращает ошибку

Код для Respond to Webhook:

{
  "success": false,
  "error": "code_not_found",
  "message": "Код не найден или истек. Запросите новый код."
}

---

Совместимость с текущим кодом

Текущий JS код (common.js) ожидает:

success: function(data) {
    if (data.success) {
        // Успех - сохраняем токен
        sms_verify_token = data.token;
        // ... показываем форму
    } else {
        // Ошибка - показываем сообщение
        $('.modal .form-item__warning').text(data.message || "Неверный код");
    }
}

Предложенный формат полностью совместим! ✅

---

Дополнительные рекомендации

1. HTTP Status Codes:

   • Успех: 200 OK
   • Ошибки клиента: 400 Bad Request
   • Ошибки сервера: 500 Internal Server Error

2. Content-Type:

   • Всегда: application/json; charset=utf-8

3. Логирование:

   • Логировать все попытки проверки (успешные и неуспешные)
   • Логировать ошибки с деталями

4. Безопасность:

   • Не возвращать детали внутренних ошибок в production
   • Не возвращать реальные коды в ответах