# CreateTGContact API - Документация

## Описание
Отдельный эндпоинт для создания контактов из Telegram с минимальными данными.

## URL
```
POST https://crm.clientright.ru/webservice.php
```

## Параметры

### Обязательные
- **`operation`** = `CreateTGContact`
- **`sessionName`** — токен сессии (получается через login)
- **`tgid`** — ID пользователя в Telegram

### Опциональные
- **`mobile`** — номер мобильного телефона
- **`firstname`** — имя (по умолчанию: "Telegram")
- **`lastname`** — фамилия (по умолчанию: "User_" + последние 4 цифры tgid)

## Пример запроса

### 1. Получение токена
```bash
curl -X POST "https://crm.clientright.ru/webservice.php" \
  -d "operation=getchallenge&username=api"
```

### 2. Авторизация
```bash
curl -X POST "https://crm.clientright.ru/webservice.php" \
  -d "operation=login&username=api&accessKey=GENERATED_KEY"
```

### 3. Создание контакта
```bash
curl -X POST "https://crm.clientright.ru/webservice.php" \
  -d "operation=CreateTGContact&sessionName=SESSION_TOKEN&tgid=123456789&mobile=79261234567&firstname=Иван&lastname=Петров"
```

## Пример ответа

### Успех
```json
{
  "success": true,
  "result": "123456"
}
```

### Ошибка
```json
{
  "success": false,
  "error": {
    "code": "INVALIDID",
    "message": "Не заполнено обязательное поле: tgid"
  }
}
```

## Особенности

### Форматирование телефона
- Автоматически очищается от нецифровых символов
- Приводится к формату 7XXXXXXXXXX
- Поддерживает форматы: 8XXXXXXXXXX, XXXXXXXXXX, 7XXXXXXXXXX

### Дефолтные значения
- **Имя:** "Telegram" (если не указано)
- **Фамилия:** "User_" + последние 4 цифры tgid (если не указана)
- **Email:** пустой
- **Дата рождения:** 01-01-1900
- **ИНН:** пустой
- **Адрес:** пустой

### Логика дублирования
- Проверка по полю `phone` (где хранится tgid)
- Если контакт с таким tgid существует — обновляется
- Если не существует — создается новый

## Логирование
Все операции записываются в файл `logs/CreateTGContact.log`

## Регистрация операции
Операция `CreateTGContact` зарегистрирована в базе данных CRM с ID: 47

## Отличия от CreateContact

| Параметр | CreateContact | CreateTGContact |
|----------|---------------|-----------------|
| Обязательные поля | firstname, lastname, birthday, mobile, inn | tgid |
| Дублирование | По mobile | По tgid (в поле phone) |
| Дефолтные значения | Нет | Есть |
| Логи | CreateContact.log | CreateTGContact.log |

## Интеграция с Telegram

```php
// Пример для Telegram бота
$tgid = $message['from']['id'];
$mobile = $message['contact']['phone_number'] ?? '';
$firstname = $message['from']['first_name'] ?? '';
$lastname = $message['from']['last_name'] ?? '';

$contact_id = vtws_createtgcontact($tgid, $mobile, $firstname, $lastname);
```

## Автор
Фёдор - 2025-09-29