erv-ticket-dev/docs/n8n_webhook_response.md

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

## URL Webhook
`https://n8n.clientright.pro/webhook/erv_sms_verify`

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

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

---

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

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

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

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

---

### ❌ Ошибки (HTTP 400)

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

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

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

---

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

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

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

---

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

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

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

---

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

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

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

---

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

```json
{
  "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:**
```json
{
  "success": true,
  "message": "Код подтвержден"
}
```

---

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

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

**Код для Respond to Webhook:**
```json
{
  "success": false,
  "error": "invalid_code",
  "message": "Неверный код"
}
```

---

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

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

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

---

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

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

```javascript
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
   - Не возвращать реальные коды в ответах