Автоматизація рахунків: Бітрікс + Контур.Ельба
Ельба — хмарний сервіс податкового обліку для ФОП на УСН та патенті. На відміну від МоєДіло та Контур.Бухгалтерії, Ельба заточена під мікробізнес зі спрощеними операціями. API Ельби дає доступ до документів (рахунки, акти) та контрагентів, але не до керування платежами. Це визначає можливості та обмеження інтеграції з Бітрікс.
Наша команда має 10+ років досвіду, реалізувала 500+ проєктів на 1С-Бітрікс. Середній чек інтеграції — 35 000 грн, середній час виконання — 3 тижні. Інтеграція вирішує задачу автоматичного виставлення рахунків та актів із замовлень інтернет-магазину напряму в Ельбу. Економія на зарплаті менеджера складає 12 000 грн/міс, окупність — за 3 місяці. Приклад: за 3 місяці економія 36 000 грн, а за рік — 144 000 грн.
Проблеми, які вирішуємо
Ручне введення рахунків. Без інтеграції менеджер вручну копіює дані з Бітрікс в Ельбу — помилки, затримки, втрата клієнтів. Наше рішення виключає людський фактор, економлячи до 15 годин на тиждень.
OAuth 2.0 без помилок. Неправильне кешування токенів призводить до блокувань API. Ми реалізуємо коректний Client Credentials flow з превентивним оновленням та використовуємо exponential backoff для повторних спроб при помилках.
Обмежене API Ельби. Відсутність API платежів та ліміти запитів — ми пропонуємо обхідні шляхи: вебхуки від платіжних систем, чергу через агенти Бітрікса. Завдяки цьому обробляємо до 1000 замовлень на день без блокувань, використовуючи асинхронне опрацювання.
Як налаштувати OAuth 2.0 для Ельби
Авторизація виконується за протоколом OAuth 2.0 (Client Credentials). Для серверної інтеграції достатньо отримати client_id та client_secret в особистому кабінеті Ельби.
class ElbaOAuthService
{
private string $clientId;
private string $clientSecret;
private string $redirectUri;
private string $tokenUrl = 'https://auth.kontur.ru/connect/token';
public function getClientCredentialsToken(): string
{
$ch = curl_init($this->tokenUrl);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'grant_type' => 'client_credentials',
'client_id' => $this->clientId,
'client_secret' => $this->clientSecret,
'scope' => 'elba.api',
]),
CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'],
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
$this->cacheToken($response['access_token'], $response['expires_in'] - 60);
return $response['access_token'];
}
}
Клієнт API Ельби на PHP
class ElbaApiClient
{
private ElbaOAuthService $auth;
private string $baseUrl = 'https://api.e-kontur.ru/api/v1';
public function request(string $method, string $path, array $data = []): array
{
$token = $this->auth->getCachedToken();
$ch = curl_init($this->baseUrl . $path);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
"Authorization: Bearer {$token}",
],
CURLOPT_POSTFIELDS => in_array($method, ['POST', 'PUT'])
? json_encode($data) : null,
]);
$json = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode >= 400) {
throw new \RuntimeException("Elba API error {$httpCode}: {$json}");
}
return json_decode($json, true) ?? [];
}
}
Як автоматично виставляти рахунки з Бітрікса?
Основний сценарій: при створенні замовлення автоматично формуємо рахунок в Ельбі та надсилаємо його покупцю по email. Для цього спочатку знаходимо або створюємо контрагента за ІНН, потім формуємо масив товарних позицій.
public function findOrCreateCounterparty(\Bitrix\Sale\Order $order): string
{
$props = $order->getPropertyCollection();
$inn = $props->getItemByOrderPropertyCode('INN')?->getValue();
$email = $props->getUserEmail();
if ($inn) {
$list = $this->client->request('GET', '/counterparties?inn=' . urlencode($inn));
if (!empty($list)) {
return $list[0]['id'];
}
}
$isLegal = !empty($inn);
$payload = $isLegal ? [
'fullName' => $props->getItemByOrderPropertyCode('COMPANY')?->getValue() ?? '',
'inn' => $inn,
'kpp' => $props->getItemByOrderPropertyCode('KPP')?->getValue() ?? '',
'email' => $email,
] : [
'fullName' => $props->getBuyerName(),
'email' => $email,
'type' => 'individual',
];
$created = $this->client->request('POST', '/counterparties', $payload);
return $created['id'];
}
public function createInvoiceForOrder(\Bitrix\Sale\Order $order): array
{
$counterpartyId = $this->findOrCreateCounterparty($order);
$items = [];
foreach ($order->getBasket() as $item) {
$items[] = [
'name' => $item->getField('NAME'),
'count' => $item->getQuantity(),
'price' => $item->getPrice(),
'unit' => 'шт.',
'ndsRate' => 'NoNds',
];
}
$deliveryPrice = $order->getField('PRICE_DELIVERY');
if ($deliveryPrice > 0) {
$items[] = [
'name' => 'Доставка',
'count' => 1,
'price' => $deliveryPrice,
'unit' => 'ум.',
'ndsRate' => 'NoNds',
];
}
$invoice = $this->client->request('POST', '/invoices', [
'number' => $order->getField('ACCOUNT_NUMBER'),
'date' => date('Y-m-d'),
'counterpartyId' => $counterpartyId,
'items' => $items,
'comment' => 'Замовлення з сайту #' . $order->getField('ACCOUNT_NUMBER'),
'paymentDueDate' => date('Y-m-d', strtotime('+3 days')),
]);
return $invoice;
}
Як обійти ліміти API Ельби?
Обмежене API Ельби. Відсутність API платежів та ліміти запитів — ми пропонуємо обхідні шляхи: вебхуки від платіжних систем, чергу через агенти Бітрікса. Для магазину з великою кількістю замовлень застосовуємо чергу відправки через \Bitrix\Main\Agent або окремий воркер. Також використовуємо idempotency ключі для запобігання дублюванню.
Немає API для реєстрації платежів. Коли замовлення оплачене в Бітрікс, автоматично відмітити рахунок оплаченим в Ельбі через API неможливо. Обхід: webhook від платіжних систем → повідомлення по email бухгалтеру з номером рахунку. Або використовувати банківську інтеграцію Ельби — при надходженні грошей на розрахунковий рахунок Ельба сама зіставляє платіж з виставленим рахунком.
Тільки рахунки та акти, не накладні. Для відвантаження товарів документ акта не цілком коректний юридично. Для ФОП на УСН це зазвичай несуттєво, але для ТОВ — розгляньте Контур.Бухгалтерію.
Акт виконаних робіт для послуг
Для послуг (не товарів) формуємо акт замість рахунку:
public function createActForOrder(\Bitrix\Sale\Order $order, string $counterpartyId): array
{
return $this->client->request('POST', '/acts', [
'date' => date('Y-m-d'),
'counterpartyId' => $counterpartyId,
'items' => $this->buildItems($order),
'comment' => 'Послуги за замовленням #' . $order->getField('ACCOUNT_NUMBER'),
]);
}
Порівняння сервісів
| Критерій | Ельба (СКБ Контур) | Контур.Бухгалтерія | МоєДіло |
|---|---|---|---|
| Орієнтація | ФОП на УСН, патент | ФОП та ТОВ будь-які режими | ФОП та ТОВ |
| API для рахунків | Єсть | Єсть | Єсть |
| API для платежів | Немає | Єсть | Єсть |
| Підтримка накладних | Немає | Єсть | Єсть |
| Вартість | Низька (від 1200 грн/рік) | Середня (від 3600 грн/рік) | Середня (від 3000 грн/рік) |
Ельба в 3 рази дешевша за Контур.Бухгалтерію, але поступається за функціоналом. Автоматизація рахунків в 5 разів прискорює виставлення документів.
Маппінг полів Бітрікс → Ельба
| Поле в Бітрікс | Поле в Ельба (counterparty/invoice) |
|---|---|
| Властивість замовлення INN | counterparty.inn |
| Назва компанії (COMPANY) | counterparty.fullName |
| Email покупця | counterparty.email |
| Назва товару (Basket.NAME) | invoice.items[].name |
| Кількість (Basket.QUANTITY) | invoice.items[].count |
| Ціна (Basket.PRICE) | invoice.items[].price |
| Вартість доставки | invoice.items (окрема позиція) |
Типові помилки інтеграції
- Закінчення токена під час тривалої сесії — вирішується кешуванням із запасом.
- Невірний scope при запиті токена — використовуйте
elba.api. - Помилка 400 при створенні контрагента — можливо, не вказаний ІНН або email.
- Перевищення ліміту запитів — додайте чергу через
CAgent.
Що входить в роботу
- OAuth 2.0 інтеграція з кешуванням токенів
- PHP-клієнт для API Ельби
- Пошук та створення контрагентів
- Автоматичне виставлення рахунків при створенні замовлення
- Обробка помилок, логування, повторні спроби
- Документація та навчання персоналу
- Гарантія 3 місяці на коректну роботу
Процес роботи та терміни
- Аналітика — вивчаємо вашу схему документообігу, виявляємо точки інтеграції (1-2 дні).
- Проектування — розробляємо архітектуру, узгоджуємо стек (2-3 дні).
- Розробка — пишемо код, налаштовуємо агенти, тестуємо на стенді (1-2 тижні).
- Тестування — перевіряємо повний цикл: замовлення → рахунок → оплата → повідомлення (3-5 днів).
- Деплой — викочуємо на бойовий сервер, моніторимо перші дні (1-2 дні).
Терміни: від 2 до 4 тижнів, вартість від 35 000 грн. Інтеграція окупається в середньому за 3 місяці за рахунок економії 12 000 грн/міс на зарплаті менеджера. Отримайте консультацію інженера — ми розрахуємо точну вартість та терміни під ваш проект.
Офіційна документація API Ельби доступна за адресою https://api.e-kontur.ru.