Что такое API и зачем он нужен в 1С

API — это набор правил, по которым одна программа может обращаться к функциям или данным другой программы.

Например, интернет-магазину необходимо передать в 1С новый заказ. Вместо того чтобы сотрудник вручную переносил информацию из одной системы в другую, интернет-магазин может отправить HTTP-запрос в API 1С.

Упрощенно процесс выглядит так:

Интернет-магазин → HTTP-запрос → API 1С → обработка данных → ответ

Или в обратную сторону:

1С → HTTP-запрос → API внешнего сервиса → ответ → обработка в 1С

API может использоваться для самых разных задач:

• передачи заказов;
• синхронизации товаров;
• обмена ценами;
• получения остатков;
• передачи данных о клиентах;
• интеграции с CRM;
• подключения платежных систем;
• работы со службами доставки;
• отправки уведомлений;
• обмена данными с сайтами;
• интеграции с маркетплейсами;
• получения информации из внешних сервисов.

Для разработчика 1С API фактически становится связующим звеном между учетной системой и внешним программным обеспечением.

Как 1С взаимодействует с API

Большинство современных API работают поверх протокола HTTP или HTTPS.

Когда 1С обращается к API, она формирует запрос, отправляет его на сервер и получает ответ.

Например:

1С
 ↓
HTTP-запрос
 ↓
https://api.example.com/products
 ↓
API внешнего сервиса
 ↓
JSON-ответ
 ↓
1С

Сам запрос может содержать:

• URL;
• HTTP-метод;
• заголовки;
• параметры;
• тело запроса;
• данные авторизации.

Ответ сервера обычно содержит:

• HTTP-код;
• заголовки;
• данные;
• сообщение об ошибке, если запрос выполнить не удалось.

Какие HTTP-методы нужно знать разработчику 1С

При работе с API чаще всего используются четыре HTTP-метода:

Рассмотрим их подробнее.

GET

GET используется, когда необходимо получить информацию.

Например:

GET /api/products

Система может вернуть список товаров.

Другой пример:

GET /api/products/123

В этом случае запрашивается товар с идентификатором 123.

POST

POST обычно используется для создания нового объекта или отправки данных.

Например, 1С может отправить новый заказ:

POST /api/orders

В теле запроса передается информация о заказе:

{
    "customer": "Иван Петров",
    "product": "Ноутбук",
    "quantity": 1
}

PUT

PUT используется для полного обновления объекта.

Например:

PUT /api/products/123

В запросе передается новый набор данных товара.

PATCH

PATCH применяется, когда необходимо изменить только отдельные поля.

Например, если нужно поменять только цену:

PATCH /api/products/123

{
    "price": 1500
}

DELETE

DELETE используется для удаления объекта:

DELETE /api/products/123

Однако возможность удаления зависит от конкретного API.

Что такое REST API

Один из наиболее распространенных вариантов API — REST API.

REST (Representational State Transfer) — архитектурный подход, который широко используется при создании веб-сервисов.

REST API обычно работает через HTTP и активно использует JSON.

Например:

GET https://api.example.com/users/25

Ответ:

{
    "id": 25,
    "name": "Ivan",
    "email": "ivan@example.com"
}

Для 1С это особенно удобно, поскольку платформа позволяет работать с HTTP-запросами и преобразовывать JSON в структуры данных 1С.

JSON и XML: в каком формате передаются данные

При интеграции 1С с API разработчик должен понимать форматы данных.

На практике наиболее часто встречаются:

• JSON;
• XML;
• CSV;
• обычный текст.

Сегодня во многих REST API используется именно JSON.

Например:

{
    "id": 1001,
    "name": "Ноутбук",
    "price": 2500,
    "quantity": 5
}

В 1С эти данные можно преобразовать в структуру.

Например:

ЧтениеJSON = Новый ЧтениеJSON;
ЧтениеJSON.УстановитьСтроку(Ответ);

Данные = ПрочитатьJSON(ЧтениеJSON);

После этого можно обращаться к значениям:

Наименование = Данные.name;
Цена = Данные.price;
Количество = Данные.quantity;

Конкретный способ обработки зависит от структуры JSON и используемой версии платформы.

Как отправить HTTP-запрос из 1С

Для работы с HTTP в 1С используются специальные объекты платформы.

Один из базовых вариантов — объект:

HTTPСоединение

С его помощью можно установить соединение с сервером.

Например:

Соединение = Новый HTTPСоединение("api.example.com");

После этого создается HTTP-запрос:

Запрос = Новый HTTPЗапрос("/api/products");

И выполняется:

Ответ = Соединение.Получить(Запрос);

Полученный объект Ответ содержит информацию, которую вернул сервер.

Например, можно получить код состояния:

КодСостояния = Ответ.КодСостояния;

И тело ответа:

ТелоОтвета = Ответ.ПолучитьТелоКакСтроку();

Пример GET-запроса из 1С

Предположим, внешний сервис предоставляет API:

https://api.example.com/products

Нужно получить список товаров.

Примерная реализация:

Соединение = Новый HTTPСоединение("api.example.com");

Запрос = Новый HTTPЗапрос("/products");

Ответ = Соединение.Получить(Запрос);

Если Ответ.КодСостояния = 200 Тогда
    ТелоОтвета = Ответ.ПолучитьТелоКакСтроку();
    
    ЧтениеJSON = Новый ЧтениеJSON;
    ЧтениеJSON.УстановитьСтроку(ТелоОтвета);
    
    Данные = ПрочитатьJSON(ЧтениеJSON);
КонецЕсли;

В реальном проекте необходимо дополнительно учитывать:

• HTTPS;
• авторизацию;
• тайм-ауты;
• обработку ошибок;
• структуру ответа;
• логирование;
• повторные запросы.

Как отправить POST-запрос из 1С

Теперь рассмотрим более практический пример.

Допустим, 1С должна отправить заказ во внешнюю систему.

Сначала создадим структуру данных:

ДанныеЗаказа = Новый Структура;

ДанныеЗаказа.Вставить("number", "000123");
ДанныеЗаказа.Вставить("customer", "Иван Петров");
ДанныеЗаказа.Вставить("amount", 1500);

Затем преобразуем структуру в JSON:

ЗаписьJSON = Новый ЗаписьJSON;
ЗаписьJSON.УстановитьСтроку();

ЗаписатьJSON(ЗаписьJSON, ДанныеЗаказа);

JSONСтрока = ЗаписьJSON.Закрыть();

Создаем HTTP-запрос:

Запрос = Новый HTTPЗапрос("/api/orders");

Запрос.Заголовки.Вставить(
    "Content-Type",
    "application/json"
);

Запрос.УстановитьТелоИзСтроки(
    JSONСтрока,
    КодировкаТекста.UTF8,
    ИспользованиеByteOrderMark.НеИспользовать
);

После этого отправляем запрос:

Ответ = Соединение.ВызватьHTTPМетод("POST", Запрос);

Конкретный код может отличаться в зависимости от конфигурации, версии платформы и требований API.

Авторизация при подключении 1С к API

Практически любой реальный API требует авторизации.

Сервис должен понимать, кто обращается к нему и имеет ли клиент право выполнять определенные операции.

Наиболее распространенные варианты:

• API Key;
• Basic Authentication;
• Bearer Token;
• OAuth 2.0;
• JWT.

API Key

Один из простых вариантов — передавать специальный ключ в заголовке.

Например:

Authorization: Api-Key 123456789

В 1С:

Запрос.Заголовки.Вставить(
    "Authorization",
    "Api-Key " + APIКлюч
);

Реальный формат заголовка определяется документацией конкретного API.

Bearer Token

Другой распространенный вариант:

Authorization: Bearer eyJhbGciOi...

В 1С:

Запрос.Заголовки.Вставить(
    "Authorization",
    "Bearer " + Токен
);

Важно не хранить токены непосредственно в исходном коде конфигурации.

Например, не стоит делать так:

Токен = "123456789abcdef";

Безопаснее хранить секретные данные в настройках, защищенном хранилище или другом подходящем механизме.

Что такое OAuth 2.0

OAuth 2.0 используется, когда авторизация API требует более сложного механизма получения и обновления токенов.

Упрощенно схема может выглядеть так:

1С
 ↓
Запрос токена
 ↓
Сервер авторизации
 ↓
Access Token
 ↓
1С
 ↓
API

При этом access token может иметь ограниченный срок действия.

Разработчику необходимо учитывать:

• получение токена;
• срок его действия;
• обновление токена;
• хранение токена;
• обработку ошибки авторизации.

Заголовки HTTP-запроса

Заголовки позволяют передать дополнительную информацию серверу.

Например:

Content-Type: application/json
Authorization: Bearer TOKEN
Accept: application/json

В 1С заголовки можно установить следующим образом:

Запрос.Заголовки.Вставить(
    "Content-Type",
    "application/json"
);

Запрос.Заголовки.Вставить(
    "Accept",
    "application/json"
);

Какие именно заголовки нужны, всегда следует смотреть в документации API.

Параметры URL и Query Parameters

Иногда данные передаются непосредственно в URL.

Например:

/api/products?category=computer&limit=20

Здесь:

• category — категория;
• computer — значение параметра;
• limit — количество результатов.

Такие параметры часто используются при фильтрации и постраничной загрузке.

Например:

/api/orders?page=2&limit=100

Это может означать запрос второй страницы по 100 заказов.

Path Parameters

Еще один вариант — параметры непосредственно в пути.

Например:

/api/products/123

Здесь 123 — идентификатор товара.

В 1С URL может формироваться программно:

Идентификатор = 123;

Путь = "/api/products/" + Строка(Идентификатор);

Запрос = Новый HTTPЗапрос(Путь);

При этом важно корректно обрабатывать специальные символы и кодирование параметров.

Как обрабатывать ответ API в 1С

Получить ответ недостаточно. Необходимо проверить, успешно ли был выполнен запрос.

Для этого используется HTTP-код состояния.

Основные коды:

Например:

Если Ответ.КодСостояния >= 200
    И Ответ.КодСостояния < 300 Тогда
    
    // Успешный ответ
    
Иначе
    
    // Обработка ошибки
    
КонецЕсли;

Такой подход надежнее, чем проверять только один конкретный код.

Почему обработка ошибок особенно важна

Интеграция может работать идеально во время тестирования, но столкнуться с проблемами после запуска в рабочей среде.

Например:

• API временно недоступно;
• сервер вернул ошибку;
• токен истек;
• превышен лимит запросов;
• интернет-соединение прервалось;
• внешний сервис изменил формат ответа;
• обязательное поле отсутствует;
• переданы некорректные данные.

Поэтому код интеграции должен предусматривать обработку исключений.

Например:

Попытка
    
    Ответ = Соединение.Получить(Запрос);
    
Исключение
    
    ЗаписатьВЖурналРегистрации(
        "Ошибка при обращении к API: "
        + ОписаниеОшибки()
    );
    
КонецПопытки;

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

Логирование интеграции

Логирование помогает понять, что произошло во время обмена.

Например, полезно фиксировать:

• дату и время запроса;
• название операции;
• URL или endpoint;
• HTTP-метод;
• код ответа;
• идентификатор объекта 1С;
• идентификатор внешнего объекта;
• текст ошибки;
• время выполнения запроса.

Например:

12:45:03
Операция: Отправка заказа
Заказ 1С: 000123
HTTP: POST
Ответ: 201
Результат: успешно

При ошибке:

12:47:18
Операция: Отправка заказа
Заказ 1С: 000124
HTTP: POST
Ответ: 400
Ошибка: Некорректный формат даты

Такие журналы значительно упрощают поиск проблем.

Что делать, если API возвращает ошибку 401

Код 401 Unauthorized обычно связан с проблемами авторизации.

Проверить стоит:

1. Передается ли токен.
2. Не истек ли срок его действия.
3. Правильно ли указан заголовок Authorization.
4. Не требуется ли обновить токен.
5. Имеет ли пользователь или приложение доступ к API.
6. Не перепутаны ли тестовый и рабочий серверы.

Например, если API ожидает:

Authorization: Bearer TOKEN

а разработчик отправляет:

Authorization: TOKEN

сервер может отклонить запрос.

Что означает ошибка 429

Код 429 Too Many Requests означает, что клиент отправил слишком много запросов за определенный период.

Например, API может разрешать только:

100 запросов в минуту

Если 1С отправляет больше, сервер временно ограничивает доступ.

При проектировании интеграции необходимо учитывать rate limit — ограничение количества запросов.

Могут применяться:

• паузы между запросами;
• пакетная обработка;
• кеширование;
• повторные попытки через определенное время;
• получение нескольких объектов одним запросом.

Как подключить 1С к внешнему сервису: общий алгоритм

Практически любую интеграцию можно разбить на несколько этапов.

Шаг 1. Изучить документацию API

Перед написанием кода нужно понять:

• URL сервера;
• доступные методы;
• структуру запросов;
• структуру ответов;
• способы авторизации;
• обязательные параметры;
• ограничения API;
• возможные ошибки.

Шаг 2. Проверить API без 1С

Удобно сначала протестировать API с помощью инструментов вроде Postman или аналогичных клиентов.

Например:

GET
https://api.example.com/products

Если запрос работает вне 1С, разработчику будет проще перенести его логику в код 1С.

Шаг 3. Настроить авторизацию

Получить API Key или токен, если этого требует сервис.

Шаг 4. Создать HTTP-запрос

В 1С формируется:

• соединение;
• запрос;
• URL;
• HTTP-метод;
• заголовки;
• тело запроса.

Шаг 5. Отправить запрос

Например:

Ответ = Соединение.ВызватьHTTPМетод(
    "POST",
    Запрос
);

Шаг 6. Проверить HTTP-код

Необходимо определить, был ли запрос успешным.

Шаг 7. Распарсить ответ

Если API возвращает JSON, его необходимо преобразовать в структуру данных 1С.

Шаг 8. Записать данные в 1С

Полученные данные могут использоваться для:

• создания документов;
• записи в справочники;
• обновления регистров;
• изменения существующих объектов;
• запуска бизнес-логики.

Шаг 9. Добавить обработку ошибок

Интеграция должна корректно работать не только при успешном ответе.

Шаг 10. Добавить логирование

Это особенно важно для фонового обмена, который выполняется без участия пользователя.

Синхронный и асинхронный обмен

При интеграции важно понимать разницу между синхронным и асинхронным взаимодействием.

Синхронный обмен

1С отправляет запрос и ждет ответа.

1С → API → ответ → 1С

Такой подход удобен, если ответ необходим сразу.

Например:

• запросить курс валюты;
• проверить статус заказа;
• получить информацию о товаре.

Но если внешний сервис отвечает долго, пользователь может ждать завершения операции.

Асинхронный обмен

Запрос или обработка выполняется отдельно от пользовательского действия.

Например:

Пользователь
     ↓
1С
     ↓
Фоновое задание
     ↓
API
     ↓
Обработка ответа

Для больших объемов данных асинхронный подход часто оказывается более удобным.

В 1С для подобных задач могут использоваться фоновые задания, регламентные задания и другие механизмы платформы.

Как организовать обмен большими объемами данных

Представим, что необходимо передать из 1С 100 000 товаров.

Плохой вариант — отправлять каждый товар отдельным HTTP-запросом:

1 товар → запрос
1 товар → запрос
1 товар → запрос
...

Это может привести к:

• большой нагрузке;
• превышению лимитов API;
• длительному обмену;
• большому количеству ошибок.

Если API поддерживает пакетную обработку, лучше передавать данные группами:

100 товаров → запрос
100 товаров → запрос
100 товаров → запрос

Еще лучше — использовать предусмотренные API механизмы массовой загрузки.

Пагинация API

При получении большого списка данных API часто использует пагинацию.

Например:

/api/products?page=1&limit=100
/api/products?page=2&limit=100
/api/products?page=3&limit=100

1С должна последовательно получать страницы и объединять результаты.

Условно:

Получить страницу 1
        ↓
Есть следующая?
   ↓          ↓
 Да           Нет
 ↓             ↓
Страница 2   Завершить
 ↓
...

Важно учитывать, как именно конкретный API сообщает о наличии следующей страницы.

Это может быть:

• номер следующей страницы;
• next;
• nextPage;
• ссылка;
• общее количество записей;
• специальный токен.

Webhook и 1С

Не всегда 1С должна постоянно спрашивать внешний сервис:

Есть новый заказ?
Есть новый заказ?
Есть новый заказ?

Для некоторых интеграций используется webhook.

В этом случае внешний сервис сам отправляет HTTP-запрос, когда происходит определенное событие.

Например:

Покупатель оформил заказ
        ↓
Интернет-магазин
        ↓
Webhook
        ↓
1С
        ↓
Создание заказа

Это позволяет уменьшить количество постоянных запросов.

При использовании webhook 1С должна предоставить внешний HTTP-сервис, который сможет принимать входящие запросы.

HTTP-сервисы в 1С

Платформа 1С позволяет не только обращаться к внешним API, но и создавать собственные HTTP-сервисы.

Это означает, что 1С сама может выступать в роли API-сервера.

Например, внешний сайт может отправить запрос:

POST /api/order

а 1С получит данные и создаст документ.

Таким образом, интеграции можно строить в обе стороны:

1С → внешний API

или:

Внешняя система → API 1С

Это один из важных моментов, который должен понимать разработчик.

Безопасность при интеграции 1С с API

При работе с внешними сервисами нельзя забывать о безопасности.

Используйте HTTPS

Передача данных должна выполняться по защищенному соединению.

Вместо:

http://example.com

обычно следует использовать:

https://example.com

Не храните секреты в коде

API-ключи, пароли и токены не стоит жестко прописывать в модулях.

Плохо:

Пароль = "MySecretPassword123";

При публикации конфигурации такой подход создает дополнительный риск.

Не записывайте токены в обычный лог

Например, не следует сохранять:

Authorization: Bearer eyJhbGciOi...

в журнал, доступный большому количеству пользователей.

В логах лучше использовать маскирование:

Authorization: Bearer ******

Тестовый и рабочий контур

Многие API предоставляют отдельные среды:

Test
Production

Разработчику важно не перепутать их.

В тестовой среде можно безопасно проверять:

• авторизацию;
• создание объектов;
• обработку ошибок;
• формат данных;
• повторные запросы.

После завершения тестирования настройки меняются на рабочие.

Типичные ошибки при интеграции 1С с API

Ошибка №1. Не изучена документация

Разработчик начинает писать код, не разобравшись в формате API.

В результате возникают проблемы с:

• URL;
• параметрами;
• авторизацией;
• JSON;
• HTTP-методами.

Решение: сначала изучить документацию и протестировать основные запросы.

Ошибка №2. Проверяется только успешный сценарий

Код работает, пока API отвечает 200.

Но что произойдет при:

401
403
404
429
500

Если обработка отсутствует, пользователь может получить непонятную ошибку.

Решение: предусмотреть обработку различных групп HTTP-кодов.

Ошибка №3. Нет тайм-аутов

Внешний сервер может зависнуть или отвечать слишком долго.

Если интеграция не учитывает это, пользовательская операция может выполняться неопределенно долго.

Ошибка №4. Нет повторных попыток

Временная ошибка сервиса не всегда означает, что операция окончательно провалилась.

Для некоторых ошибок можно реализовать повторную попытку с задержкой.

Однако повторять запросы автоматически можно не всегда. Например, повторная отправка POST может привести к созданию дубликата.

Идемпотентность: важное понятие для разработчика

При интеграциях нужно понимать, может ли повторный запрос изменить результат.

Представим:

1С отправила заказ
↓
API создало заказ
↓
ответ потерялся
↓
1С повторяет запрос

Если API не умеет различать повторную операцию, могут появиться два одинаковых заказа.

Для защиты от таких ситуаций используются, например:

• уникальные идентификаторы;
• idempotency key;
• проверка существования объекта;
• специальные механизмы API.

Это особенно важно для финансовых операций, заказов и других критически важных данных.

Что должен уметь 1С-разработчик для работы с API

Для полноценной работы с интеграциями полезно знать несколько областей.

1. HTTP

Нужно понимать:

• GET;
• POST;
• PUT;
• PATCH;
• DELETE;
• HTTP-коды;
• заголовки;
• параметры;
• HTTPS.

2. JSON и XML

Разработчик должен уметь:

• читать JSON;
• формировать JSON;
• обрабатывать массивы и объекты;
• работать с XML;
• преобразовывать данные между форматами.

3. Авторизацию

Необходимо понимать:

• API Key;
• Basic Auth;
• Bearer Token;
• OAuth;
• JWT.

4. Архитектуру интеграции

Важно уметь проектировать:

• синхронный обмен;
• асинхронный обмен;
• фоновые задания;
• очереди;
• повторные попытки;
• логирование.

5. Безопасность

Нужно знать:

• зачем нужен HTTPS;
• как хранить секреты;
• почему нельзя передавать токены в открытом виде;
• как ограничивать доступ;
• как безопасно вести журналы.

Практический чек-лист перед запуском интеграции 1С и API

Перед публикацией интеграции стоит проверить:

• API работает в тестовой среде.

• Документация изучена.

• Настроена авторизация.

• Используется HTTPS.

• Правильно формируются URL.

• Заголовки передаются корректно.

• JSON формируется без ошибок.

• Ответ API корректно разбирается.

• Обрабатываются HTTP-ошибки.

• Предусмотрены тайм-ауты.

• Учитываются ограничения API.

• Реализована пагинация, если она необходима.

• Предусмотрена обработка повторных запросов.

• Есть логирование.

• Секретные данные не попадают в логи.

• Проверены большие объемы данных.

• Тестовый и рабочий контуры разделены.

• Проведены тесты на недоступность внешнего сервиса.

Что в итоге нужно знать разработчику

Подключение 1С к API — это не просто создание одного HTTP-запроса. Полноценная интеграция включает целый набор задач: от изучения документации и настройки авторизации до обработки ошибок, логирования и обеспечения безопасности.

Базовую схему можно представить так:

                 API
                  │
        ┌─────────┴─────────┐
        │                   │
       1С              Внешняя система
        │                   │
        └──── HTTP/JSON ────┘

Разработчику необходимо понимать, как:

1. сформировать HTTP-запрос;
2. выбрать правильный HTTP-метод;
3. передать параметры и заголовки;
4. авторизоваться в API;
5. сформировать JSON или XML;
6. отправить запрос из 1С;
7. обработать ответ;
8. проверить HTTP-код;
9. обработать ошибки;
10. организовать повторные попытки;
11. вести логирование;
12. защитить токены и другие секретные данные;
13. работать с большими объемами информации;
14. использовать фоновые и регламентные задания;
15. проектировать надежный двусторонний обмен.

Чем больше интеграций появляется в информационной системе, тем важнее становится не только умение написать код, но и понимание архитектуры обмена данными.

Интеграция 1С с API — один из востребованных навыков современного 1С-разработчика. С помощью API учетную систему можно связать практически с любым сервисом, который предоставляет программный интерфейс: интернет-магазином, CRM, сайтом, платежной системой, службой доставки или корпоративным приложением.

Для начала достаточно разобраться в базовых понятиях: HTTP, REST API, JSON, HTTP-запросы, авторизация и обработка ответов. После этого можно переходить к более сложным задачам — асинхронному обмену, webhook, пагинации, очередям, повторным запросам и оптимизации интеграций.

Главный принцип надежной интеграции прост: разработчик должен учитывать не только ситуацию, когда внешний API работает идеально, но и все сценарии, при которых сервис недоступен, возвращает ошибку или присылает неожиданные данные.

Хотите научиться разрабатывать на 1С?

В IT ШАГ можно изучить программирование и 1С-разработку на практике — от основ алгоритмов и работы с данными до создания реальных приложений и автоматизации бизнес-процессов.

Обучение помогает системно разобраться в программировании, базах данных, архитектуре приложений и инструментах, которые используются разработчиками в современных IT-проектах.

Если вы хотите связать обучение с будущей профессией в IT, изучение 1С и навыков интеграции с внешними сервисами может стать хорошей основой для дальнейшего развития в направлении разработки и автоматизации.