erv-clientright/API_REFERENCE.md

# Справочник API

## CRM WebService API

### Базовый URL
```
https://crm.clientright.ru/webservice.php
```

### Авторизация

#### 1. Получение токена (getchallenge)
```php
GET ?operation=getchallenge&username=api
```

**Ответ:**
```json
{
  "success": true,
  "result": {
    "token": "временный_токен"
  }
}
```

#### 2. Получение sessionId (login)
```php
POST
operation=login
username=api
accessKey=md5(challengeToken + userAccessKey)
```

**Где:**
- `userAccessKey = '4r9ANex8PT2IuRV'`
- `accessKey = md5(challengeToken + userAccessKey)`

**Ответ:**
```json
{
  "success": true,
  "result": {
    "sessionName": "session_id_для_дальнейших_запросов"
  }
}
```

### Операции с клиентами

#### CreateContact - Создание/обновление клиента

**Параметры:**
```php
operation = CreateContact
sessionName = полученный_sessionId
firstname = Имя (обязательно)
lastname = Фамилия (обязательно)
secondname = Отчество
mobile = Телефон (обязательно)
email = Email
tgid = Telegram ID (число)
birthday = Дата рождения в формате ГГГГ-ММ-ДД (обязательно)
birthplace = Место рождения
mailingstreet = Адрес проживания
inn = ИНН (обязательно)
requisites = Реквизиты для перечисления средств
code = СМС код
```

**Пример запроса:**
```php
$params = array(
    'operation' => 'CreateContact',
    'sessionName' => $sessionId,
    'firstname' => 'Василий',
    'lastname' => 'Пупкинидзе',
    'secondname' => 'Алибабаевич',
    'mobile' => '+7(949) 123-45-11',
    'email' => 'rrrr@mail.ru',
    'birthday' => '1986-11-15',
    'mailingstreet' => 'г. Калининград',
    'inn' => '321654987654',
    'code' => '4568'
);
```

**Ответ:**
```json
{
  "success": true,
  "result": "83859"
}
```
Где `result` - это ID созданного или обновленного клиента.

### Операции с контрагентами

#### CreateAccount - Создание/обновление контрагента

**Параметры:**
```php
operation = CreateAccount
sessionName = полученный_sessionId
accountname = Наименование юрлица (обязательно)
address = Юридический адрес
email = Email
website = Сайт
phone = Телефон
inn = ИНН (обязательно)
ogrn = ОГРН (обязательно)
```

**Пример запроса:**
```php
$params = array(
    'operation' => 'CreateAccount',
    'sessionName' => $sessionId,
    'accountname' => 'ООО "Три бобра"',
    'address' => 'г. Москва, Кремль',
    'email' => 'qqqqq@ya.ru',
    'website' => 'https://pikabu.ru',
    'phone' => '+7 928 664-66-11',
    'inn' => '1234567899',
    'ogrn' => '32165498711'
);
```

**Ответ:**
```json
{
  "success": true,
  "result": "83837"
}
```
Где `result` - это ID созданного или обновленного контрагента.

### Операции с проектами

#### CreateProject - Создание проекта

**Параметры:**
```php
operation = CreateProject
sessionName = полученный_sessionId
contactid = ID клиента (обязательно)
offenderid = ID контрагента-обидчика (обязательно)
agentid = ID контрагента-посредника (опционально)
sms = Код из СМС
ip = IP пользователя
source = Откуда пришли
region = Регион пользователя
formid = ID формы
category = Категория обращения
direction = Направление обращения
agrprice = Цена договора (число)
subject = Предмет договора
agrdate = Дата заключения договора (ГГГГ-ММ-ДД)
startdate = Срок начальный (ГГГГ-ММ-ДД)
finishdate = Срок конечный (ГГГГ-ММ-ДД)
loss = Убыток (число)
servicecost = Стоимость услуги (число)
progress = Прогресс в % (число)
country = Страна путешествия
hotel = Средство размещения
transport = Транспортные услуги ("да" или "нет")
insurance = Страховка ("да" или "нет")
other = Прочее
description = Описание
independently = Самостоятельно соблюден претензионный порядок ("да" или "нет")
claimdate = Дата направления претензии (ГГГГ-ММ-ДД)
returned = Вернули в претензионном порядке (число)
```

**Пример запроса:**
```php
$params = array(
    'operation' => 'CreateProject',
    'sessionName' => $sessionId,
    'contactid' => 83834,
    'offenderid' => 84675,
    'sms' => '1234',
    'ip' => '192.168.0.1',
    'source' => 'с улицы',
    'region' => 'Владивосток',
    'formid' => 1376,
    'category' => 'Абидили!!',
    'direction' => 'Путину',
    'description' => 'какое-то описание'
);
```

**Ответ:**
```json
{
  "success": true,
  "result": "83839"
}
```
Где `result` - это ID созданного проекта.

### Получение списка файлов

#### GetFilesList - Получение списка файлов клиента

**Параметры:**
```php
operation = GetFilesList
sessionName = полученный_sessionId
inn = ИНН клиента (обязательно)
sms = СМС-код (обязательно)
```

**Пример запроса:**
```php
$params = array(
    'operation' => 'GetFilesList',
    'sessionName' => $sessionId,
    'inn' => '643922466250',
    'sms' => '795372'
);
```

**Ответ при успехе:**
```json
{
  "success": true,
  "result": {
    "status": "ok",
    "files": [
      {
        "title": "договор",
        "path": "storage/2023/December/week4/9e84c3f86209302799f46d0136e93ab6.pdf"
      },
      {
        "title": "подтверждение оплаты",
        "path": "storage/2023/December/week4/cf65c58a01e7db0b19c8e1fe119c0e32.pdf"
      }
    ]
  }
}
```

**Ответ при ошибке:**
```json
{
  "success": true,
  "result": {
    "status": "failed",
    "message": "Клиент с указанным СМС-кодом и ИНН не найден"
  }
}
```

## WebForms Capture API

### Базовый URL
```
https://crm.clientright.ru/modules/Webforms/capture.php
```

### Параметры формы

**Обязательные системные параметры:**
```php
__vtrftk = 'sid:ec649134ad232e44c3ad71bbd321cee986f05545,1688385374'
publicid = '3ddc71c2d79ef101c09b0d4e9c6bd08b'
urlencodeenable = '1'
name = 'websiteticket'
```

**Кастомные поля:**
Все поля с атрибутом `data-crmname` отправляются как отдельные параметры.

## File Upload API

### Базовый URL
```
https://form.clientright.ru/fileupload_v2.php
```

### Параметры
```php
POST multipart/form-data
lastname = Фамилия клиента
sub_dir = ID сессии
files_names[] = Массив имен полей для файлов
docs_names[] = Массив названий документов
field_name-0 = Файл 1
field_name-1 = Файл 2
...
```

**Ответ:**
```json
{
  "success": "true",
  "empty_file": "путь_к_пустышке",
  "real_file": "путь_к_реальному_файлу",
  "message": "Файл успешно загружен"
}
```

## DaData API

### Базовый URL
```
https://suggestions.dadata.ru/suggestions/api/4_1/rs/suggest/party
```

### Авторизация
```
Authorization: Token f5d6928d7490cd44124ccae11a08c7fa5625d48c
Content-Type: application/json
```

### Запрос
```json
POST
{
  "query": "название организации или ИНН"
}
```

### Ответ
```json
{
  "suggestions": [
    {
      "value": "ООО Рога и Копыта",
      "data": {
        "inn": "1234567890",
        "address": {
          "value": "г. Москва, ул. Ленина, д. 1"
        }
      }
    }
  ]
}
```

## IP Geolocation API

### Базовый URL
```
http://ip-api.com/json/{IP}?lang=ru
```

### Пример запроса
```
GET http://ip-api.com/json/192.168.1.1?lang=ru
```

### Ответ
```json
{
  "status": "success",
  "country": "Россия",
  "regionName": "Москва",
  "city": "Москва",
  "lat": 55.7558,
  "lon": 37.6173
}
```

## Обработка ошибок

### Стандартный формат ошибки
```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Описание ошибки"
  }
}
```

### HTTP коды статуса
- `200` - Успешный запрос
- `400` - Неверные параметры
- `401` - Ошибка авторизации
- `404` - Ресурс не найден
- `500` - Внутренняя ошибка сервера

### Важные замечания

1. **SessionId** имеет ограниченное время жизни (15 минут)
2. **Поле success** в ответе означает только техническую успешность запроса
3. Для проверки бизнес-логики используйте поле **status** внутри **result**
4. Все даты должны быть в формате **ГГГГ-ММ-ДД**
5. При работе с файлами используйте **multipart/form-data**

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

### Полный цикл создания обращения

```php
// 1. Получение токена
$ch = curl_init();
$url = "https://crm.clientright.ru/webservice.php?operation=getchallenge&username=api";
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
$response = curl_exec($ch);
$jsonResponse = json_decode($response, true);
$challengeToken = $jsonResponse['result']['token'];

// 2. Получение sessionId
$userAccessKey = '4r9ANex8PT2IuRV';
$generatedKey = md5($challengeToken . $userAccessKey);
curl_setopt_array($ch, array(
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_URL => 'https://crm.clientright.ru/webservice.php',
    CURLOPT_POST => 1,
    CURLOPT_POSTFIELDS => array(
        'operation' => 'login',
        'username' => 'api',
        'accessKey' => $generatedKey
    )
));
$response = curl_exec($ch);
$jsonResponse = json_decode($response, true);
$sessionId = $jsonResponse['result']['sessionName'];

// 3. Создание клиента
$clientParams = array(
    'operation' => 'CreateContact',
    'sessionName' => $sessionId,
    'firstname' => 'Иван',
    'lastname' => 'Иванов',
    'mobile' => '+79991234567',
    'email' => 'ivan@example.com',
    'birthday' => '1990-01-01',
    'inn' => '123456789012',
    'code' => '123456'
);
curl_setopt_array($ch, array(
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_POST => 1,
    CURLOPT_URL => 'https://crm.clientright.ru/webservice.php',
    CURLOPT_POSTFIELDS => $clientParams
));
$response = curl_exec($ch);
$jsonResponse = json_decode($response, true);
$contactId = $jsonResponse['result'];

// 4. Создание контрагента
$accountParams = array(
    'operation' => 'CreateAccount',
    'sessionName' => $sessionId,
    'accountname' => 'ООО "Пример"',
    'inn' => '9876543210',
    'ogrn' => '1234567890123'
);
curl_setopt_array($ch, array(
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_POST => 1,
    CURLOPT_URL => 'https://crm.clientright.ru/webservice.php',
    CURLOPT_POSTFIELDS => $accountParams
));
$response = curl_exec($ch);
$jsonResponse = json_decode($response, true);
$accountId = $jsonResponse['result'];

// 5. Создание проекта
$projectParams = array(
    'operation' => 'CreateProject',
    'sessionName' => $sessionId,
    'contactid' => $contactId,
    'offenderid' => $accountId,
    'description' => 'Описание обращения'
);
curl_setopt_array($ch, array(
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_POST => 1,
    CURLOPT_URL => 'https://crm.clientright.ru/webservice.php',
    CURLOPT_POSTFIELDS => $projectParams
));
$response = curl_exec($ch);
$jsonResponse = json_decode($response, true);
$projectId = $jsonResponse['result'];

curl_close($ch);
```