10. API и вебхуки

10.1. Общая концепция

Платформа позволяет создавать REST API эндпоинты без написания кода. Все эндпоинты обслуживаются автоматически на порту 8080.

Возможности API:

• GET/POST/PUT/DELETE методы
• Валидация входящих данных через схемы
• Аутентификация по паролю (заголовок X-API-Key)
• Вызов процедур или прямое чтение коллекций
• Отправка вебхуков через HTTP_ЗАПРОС внутри процедур

10.2. Базовый синтаксис API

API ИмяБлока
    API_ЭНДПОИНТ "/путь/к/эндпоинту"
        МЕТОД GET
        ОБЪЕКТ ИмяКоллекции
        ПАРОЛЬ "секретный_пароль"
    КОНЕЦ_ЭНДПОИНТА
КОНЕЦ_API

10.3. Типы эндпоинтов

Тип	Ключевое слово	Что делает
Чтение коллекции	ОБЪЕКТ ИмяКоллекции	Возвращает список записей (с учётом RLS)
Вызов процедуры	ОБЪЕКТ Процедура.Имя	Выполняет процедуру, возвращает результат
POST с валидацией	ОБЪЕКТ ... СХЕМА ...	Проверяет входящие JSON, затем создаёт запись

10.4. Схемы данных для валидации

Схема — это описание структуры JSON, которую ожидает эндпоинт. Платформа автоматически проверяет типы и обязательность полей.

Синтаксис схемы:

СХЕМА_ДАННЫХ ИмяСхемы
    ПОЛЕ ИмяПоля ТИП ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ ИмяДругогоПоля ТИП
КОНЕЦ

Пример схемы:

СХЕМА_ДАННЫХ СхемаКонтрагента
    ПОЛЕ Наименование СТРОКА ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ Телефон СТРОКА
    ПОЛЕ Email СТРОКА
    ПОЛЕ ИНН СТРОКА
    ПОЛЕ СкидкаПроцент ЧИСЛО ЗНАЧЕНИЕ_ПО_УМОЛЧАНИЮ 0
КОНЕЦ

10.5. Простые примеры

Пример 1: GET эндпоинт для чтения коллекции

API МойAPI
    API_ЭНДПОИНТ "/api/v1/clients"
        МЕТОД GET
        ОБЪЕКТ Клиенты
        ПАРОЛЬ "secret123"
    КОНЕЦ_ЭНДПОИНТА
КОНЕЦ_API

Запрос:

curl -X GET "http://localhost:8080/api/v1/clients" -H "X-API-Key: secret123"

Пример 2: GET эндпоинт с параметрами фильтрации

API_ЭНДПОИНТ "/api/v1/clients/filter"
    МЕТОД GET
    ОБЪЕКТ Клиенты
    ПАРОЛЬ "secret123"
    ФИЛЬТР "Телефон LIKE '%{{phone}}%'"
КОНЕЦ_ЭНДПОИНТА

Пример 3: POST эндпоинт со схемой

СХЕМА_ДАННЫХ СхемаНовогоКлиента
    ПОЛЕ Наименование СТРОКА ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ Телефон СТРОКА ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ Email СТРОКА
КОНЕЦ

API_ЭНДПОИНТ "/api/v1/client"
    МЕТОД POST
    ОБЪЕКТ Клиенты
    ПАРОЛЬ "secret123"
    СХЕМА СхемаНовогоКлиента
КОНЕЦ_ЭНДПОИНТА

10.6. Вызов процедур через API

ПРОЦЕДУРА СоздатьКлиентаИзAPI
    ВЫЧИСЛИТЬ Данные = ПОЛУЧИТЬ(args, 0)
    
    ВЫЧИСЛИТЬ НовыйКлиент = СОЗДАТЬ("Клиенты")
    ЗАПОЛНИТЬ НовыйКлиент.Наименование = Данные.name
    ЗАПОЛНИТЬ НовыйКлиент.Телефон = Данные.phone
    ЗАПОЛНИТЬ НовыйКлиент.Email = Данные.email
    
    ВЫЧИСЛИТЬ Успех = ЗАПИСАТЬ(НовыйКлиент)
    
    ЕСЛИ Успех ТО
        ВОЗВРАТ {"status": "ok", "id": НовыйКлиент.id}
    ИНАЧЕ
        ВОЗВРАТ {"status": "error", "message": "Ошибка сохранения"}
    КОНЕЦ
КОНЕЦ_ПРОЦЕДУРЫ

API_ЭНДПОИНТ "/api/v1/client/create"
    МЕТОД POST
    ОБЪЕКТ Процедура.СоздатьКлиентаИзAPI
    ПАРОЛЬ "secret123"
КОНЕЦ_ЭНДПОИНТА

10.7. Параметры в пути (path params)

В эндпоинтах можно использовать :id для передачи параметров в URL:

API_ЭНДПОИНТ "/api/v1/clients/:id"
    МЕТОД GET
    ОБЪЕКТ Процедура.ПолучитьКлиента
    ПАРОЛЬ "secret123"
КОНЕЦ_ЭНДПОИНТА

ПРОЦЕДУРА ПолучитьКлиента
    ВЫЧИСЛИТЬ ID = ПОЛУЧИТЬ(args, 0)  # 123 из URL
    ВЫЧИСЛИТЬ Клиент = ПРОЧИТАТЬ("Клиенты", ID)
    ВОЗВРАТ Клиент
КОНЕЦ_ПРОЦЕДУРЫ

10.8. HTTP_ЗАПРОС — вызов внешних API

Синтаксис:

HTTP_ЗАПРОС(МЕТОД, URL, ТЕЛО, [ЗАГОЛОВКИ])

Примеры:

# GET запрос
ВЫЧИСЛИТЬ Ответ = HTTP_ЗАПРОС("GET", "https://api.example.com/data", {})

# POST с JSON
ВЫЧИСЛИТЬ Ответ = HTTP_ЗАПРОС("POST", "https://api.example.com/create", {
    "name": "Test",
    "value": 100
})

# POST с заголовками
ВЫЧИСЛИТЬ Ответ = HTTP_ЗАПРОС("POST", "https://api.example.com/secure", {
    "data": "secret"
}, {
    "Authorization": "Bearer token123"
})

10.9. Отправка вебхуков

ПРОЦЕДУРА ОтправитьВебхукПриПроведении
    ВЫЧИСЛИТЬ Заказ = ПРОЧИТАТЬ("ЗаказНаряд", ЗаказID)
    
    ВЫЧИСЛИТЬ Данные = {
        "event": "order_posted",
        "order_id": Заказ.id,
        "order_number": Заказ.Номер,
        "total_amount": Заказ.ИтогоСумма
    }
    
    ПОПЫТКА
        ВЫЧИСЛИТЬ Ответ = HTTP_ЗАПРОС("POST", "https://external.com/webhook", Данные)
        ВЫВЕСТИ "Вебхук отправлен"
    ИСКЛЮЧЕНИЕ Ошибка
        ВЫВЕСТИ "Ошибка: " + Ошибка
    КОНЕЦ_ПОПЫТКИ
КОНЕЦ_ПРОЦЕДУРЫ

10.10. Аутентификация

Все эндпоинты защищены паролем. Клиент должен передавать его в заголовке:

X-API-Key: ваш_пароль

Разные пароли для разных эндпоинтов:

API_ЭНДПОИНТ "/api/v1/internal"
    ПАРОЛЬ "internal_secret"
    ...

API_ЭНДПОИНТ "/api/v1/public"
    ПАРОЛЬ "public_secret"
    ...

10.11. Полный пример: интеграция с внешним сайтом

СХЕМА_ДАННЫХ СхемаЗаявкиССайта
    ПОЛЕ name СТРОКА ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ phone СТРОКА ОБЯЗАТЕЛЬНОЕ
    ПОЛЕ description СТРОКА
КОНЕЦ

ПРОЦЕДУРА ОбработкаЗаявкиССайта
    ВЫЧИСЛИТЬ Данные = ПОЛУЧИТЬ(args, 0)
    
    # Ищем или создаём клиента
    ВЫЧИСЛИТЬ Клиент = НАЙТИ("Клиенты", "Телефон = '" + Данные.phone + "'")
    ЕСЛИ ПУСТО(Клиент) ТО
        ВЫЧИСЛИТЬ Клиент = СОЗДАТЬ("Клиенты")
        ЗАПОЛНИТЬ Клиент.Наименование = Данные.name
        ЗАПОЛНИТЬ Клиент.Телефон = Данные.phone
        ВЫЧИСЛИТЬ _ = ЗАПИСАТЬ(Клиент)
    КОНЕЦ
    
    # Создаём заказ
    ВЫЧИСЛИТЬ Заказ = СОЗДАТЬ("ЗаказНаряд")
    ЗАПОЛНИТЬ Заказ.Клиент = Клиент.id
    ЗАПОЛНИТЬ Заказ.Статус = "Заявка с сайта"
    ЗАПОЛНИТЬ Заказ.Описание = Данные.description
    ВЫЧИСЛИТЬ Успех = ЗАПИСАТЬ(Заказ)
    
    ЕСЛИ Успех ТО
        ВОЗВРАТ {"status": "success", "order_id": Заказ.id}
    ИНАЧЕ
        ВОЗВРАТ {"status": "error", "message": "Ошибка сохранения"}
    КОНЕЦ
КОНЕЦ_ПРОЦЕДУРЫ

API СайтИнтеграция
    API_ЭНДПОИНТ "/api/v1/webhook/zayavka"
        МЕТОД POST
        ОБЪЕКТ Процедура.ОбработкаЗаявкиССайта
        ПАРОЛЬ "webhook_secret_2024"
        СХЕМА СхемаЗаявкиССайта
    КОНЕЦ_ЭНДПОИНТА
    
    API_ЭНДПОИНТ "/api/v1/public/status/:order_id"
        МЕТОД GET
        ОБЪЕКТ Процедура.ПолучитьСтатусЗаказа
        ПАРОЛЬ "webhook_secret_2024"
    КОНЕЦ_ЭНДПОИНТА
КОНЕЦ_API

10.12. Best Practices

• Всегда ставьте пароль на эндпоинт — иначе API будет доступен всем
• Используйте разные пароли для разных типов эндпоинтов — публичные и внутренние
• Всегда валидируйте входящие данные через схемы — это защищает от мусора и атак
• В процедурах, вызываемых через API, обрабатывайте ошибки и возвращайте понятный JSON
• Для вебхуков используйте ПОПЫТКА...ИСКЛЮЧЕНИЕ — внешний сервер может быть недоступен
• Документируйте API для внешних разработчиков
• Не передавайте чувствительные данные в URL — используйте POST и тело запроса