Solavel Документы
Русский
Справочник разработчика

API финансов SolaCount

Версия: v1 Базовый URL: https://solavel.com/api/v1 (замените на свой домен) Формат: JSON 33 конечные точки

Finance API SolaCount позволяет программно читать и изменять бухгалтерские данные: клиентов, поставщиков, счета клиентам, счета поставщиков, платежи, проводки и финансовые отчёты. Все конечные точки возвращают JSON. Создать API-ключ →

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

Каждая защищённая конечная точка требует три заголовка:

X-API-Key: solabooks_<prefix>.<secret>
X-Organization-Id: 1
X-Client-Id: 4
  • X-API-Key — полный ключ, который показывается один раз при создании в разделе Настройки → Доступ к API
  • X-Organization-Id — целочисленный идентификатор вашей организации (виден на странице «Доступ к API»)
  • X-Client-Id — ваш идентификатор клиента (виден на странице «Доступ к API»)
Создайте ключ: Перейти к Настройки → API-доступ в SolaCount. Полный ключ показывается один раз. У каждого ключа есть области доступа — выдавайте только нужные.

Конечная точка GET /api/v1/health не требует аутентификации и может использоваться для проверки подключения.

Формат ответа

Все ответы используют единую структуру JSON.

Один объект

{
  "success": true,
  "data": { ... }
}

Постраничный список

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 100,
    "last_page": 4
  }
}

Ошибка

{
  "success": false,
  "error": {
    "code": "error_code",
    "message": "Human readable message."
  }
}

Быстрый тест

Замените your_key, 1 и 4 на ваш фактический API-ключ, ID организации и ID клиента.

Проверка работоспособности (авторизация не требуется)

curl https://solacount.com/api/v1/health

Список счетов

curl https://solacount.com/api/v1/invoices \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4"

Создать клиента

curl -X POST https://solacount.com/api/v1/customers \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4" \
  -H "Content-Type: application/json" \
  -d '{"name":"Demo Customer","email":"billing@example.com"}'

Создать бухгалтерскую запись

curl -X POST https://solacount.com/api/v1/journal-entries \
  -H "X-API-Key: your_key" \
  -H "X-Organization-Id: 1" \
  -H "X-Client-Id: 4" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-06-07",
    "reference": "JE-001",
    "description": "Manual accrual",
    "lines": [
      {"account_id": 101, "debit": 1000, "credit": 0},
      {"account_id": 202, "debit": 0, "credit": 1000}
    ]
  }'

Все конечные точки

Нажмите на любой эндпоинт, чтобы раскрыть его подробности. Всего 33 эндпоинта в 8 группах ресурсов.

Состояние

GET /api/v1/health без авторизации

Убедитесь, что API работает и отвечает. Аутентификация не требуется.

Ответ HTTP 200

{"success":true,"data":{"service":"finance-api","status":"ok","timestamp":"2026-06-07T12:00:00+00:00"}}

Клиенты

GET /api/v1/customers область: customers.get

Список всех клиентов. Поддерживает поиск и постраничный вывод.

Параметры запроса

ПараметрТипОписание
search string необязательно Фильтр по имени, электронной почте или телефону (частичное совпадение)
page integer необязательно Номер страницы (по умолчанию: 1)
per_page integer необязательно Результатов на странице (по умолчанию: 25, максимум: 100)

Ответ HTTP 200

{"success":true,"data":[{"id":1,"name":"Demo Customer","email":"billing@example.com","phone":"+1-555-0100","is_active":true}],"meta":{"current_page":1,"per_page":25,"total":3,"last_page":1}}
GET /api/v1/customers/{id} область: customers.get

Получить одного клиента по ID.

Ответ HTTP 200

{"success":true,"data":{"id":1,"name":"Demo Customer","email":"billing@example.com","phone":"+1-555-0100","is_active":true}}
POST /api/v1/customers область: customers.post

Создать нового клиента.

Тело запроса (JSON)

ПолеТипОписание
name string обязательно Имя клиента
email string необязательно Адрес e-mail (должен быть корректным адресом e-mail)
phone string необязательно Номер телефона (не более 50 символов)
is_active boolean необязательно Статус активности (по умолчанию: true)

Ответ HTTP 201

{"success":true,"data":{"id":42,"name":"Demo Customer","email":"billing@example.com","phone":null,"is_active":true}}

Поставщики

GET /api/v1/suppliers область: suppliers.get

Список всех поставщиков. Поддерживает поиск и постраничный вывод.

Параметры запроса

ПараметрТипОписание
search string необязательно Фильтр по имени (частичное совпадение)
page integer необязательно Номер страницы
per_page integer необязательно Результатов на странице (максимум 100)

Ответ HTTP 200

{"success":true,"data":[{"id":1,"name":"Demo Supplier","email":"ap@example.com","tax_id":"GB123456789","is_vat_registered":true}],"meta":{"current_page":1,"per_page":25,"total":1,"last_page":1}}
GET /api/v1/suppliers/{id} область: suppliers.get

Получить одного поставщика по ID.

Ответ HTTP 200

{"success":true,"data":{"id":1,"name":"Demo Supplier","email":"ap@example.com","phone":null,"tax_id":"GB123456789","is_overseas":false,"is_vat_registered":true,"reverse_charge":false}}
POST /api/v1/suppliers область: suppliers.post

Создайте нового поставщика.

Тело запроса (JSON)

ПолеТипОписание
name string обязательно Имя поставщика
email string необязательно Адрес электронной почты
phone string необязательно Номер телефона
tax_id string необязательно Номер регистрации НДС / налогоплательщика
is_overseas boolean необязательно Является ли поставщик зарубежным (по умолчанию: нет)
is_vat_registered boolean необязательно Зарегистрирован в качестве плательщика НДС (по умолчанию: да)
reverse_charge boolean необязательно Применяется реверсивный НДС (по умолчанию: false)

Ответ HTTP 201

{"success":true,"data":{"id":15,"name":"Demo Supplier","email":"ap@example.com","tax_id":"GB123456789","is_vat_registered":true}}

Счета

GET /api/v1/invoices область: invoices.get

Список всех счетов с привязкой к клиенту. Поддерживает фильтр по статусу и постраничный вывод.

Параметры запроса

ПараметрТипОписание
status string необязательно Фильтр: draft | unpaid | paid | void | overdue
page integer необязательно Номер страницы
per_page integer необязательно Результатов на странице (максимум 100)

Ответ HTTP 200

{"success":true,"data":[{"id":101,"number":"INV-00101","date":"2026-06-01","due_date":"2026-07-01","status":"unpaid","total":5000.00,"customer":{"id":1,"name":"Demo Customer"}}],"meta":{"current_page":1,"per_page":25,"total":48,"last_page":2}}
GET /api/v1/invoices/{id} область: invoices.get

Получить один счет-фактуру с данными клиента и строками.

Ответ HTTP 200

{"success":true,"data":{"id":101,"number":"INV-00101","date":"2026-06-01","due_date":"2026-07-01","status":"unpaid","subtotal":4347.83,"tax_total":652.17,"total":5000.00,"customer":{"id":1,"name":"Demo Customer"},"lines":[{"id":1,"description":"Consulting services","qty":10,"unit_price":434.78,"total":4347.83}]}}
POST /api/v1/invoices область: invoices.post

Создать новый счет. Создается со статусом draft и автоматически сформированным номером.

Тело запроса (JSON)

ПолеТипОписание
customer_id integer обязательно ID существующего клиента
date date обязательно Дата счета (ГГГГ-ММ-ДД)
due_date date необязательно Срок оплаты (ГГГГ-ММ-ДД)
notes string необязательно Внутренние или видимые клиенту заметки
subtotal decimal необязательно Итог без налога (по умолчанию: 0)
tax_total decimal необязательно Сумма налога (по умолчанию: 0)
discount_total decimal необязательно Сумма скидки (по умолчанию: 0)
total decimal необязательно Общий итог (по умолчанию: 0)

Ответ HTTP 201

{"success":true,"data":{"id":102,"number":"INV-00102","status":"draft","date":"2026-06-07","due_date":"2026-07-07","total":5000.00,"customer_id":1}}
PUT /api/v1/invoices/{id} область: invoices.update

Обновить существующий черновик инвойса. Все поля необязательны.

Тело запроса (JSON)

ПолеТипОписание
customer_id integer необязательно Новый ID клиента
date date необязательно Дата счета (ГГГГ-ММ-ДД)
due_date date необязательно Срок оплаты
notes string необязательно Примечания
subtotal decimal необязательно Итог без налога
tax_total decimal необязательно Сумма налога
total decimal необязательно Общий итог

Ответ HTTP 200

{"success":true,"data":{"id":102,"status":"draft","total":6000.00,"customer":{"id":1,"name":"Demo Customer"},"lines":[]}}
POST /api/v1/invoices/{id}/post область: invoices.post

Провести черновик счета-фактуры в главную книгу. Требуется сумма > 0 и дата. Меняет статус на «не оплачено».

Ответ HTTP 200

{"success":true,"data":{"id":102,"status":"unpaid","posted_at":"2026-06-07T12:00:00Z","total":5000.00}}

Возможные ошибки: invoice_already_posted, invoice_total_required, invoice_date_required

POST /api/v1/invoices/{id}/void область: invoices.void

Аннулировать проведённый счёт. Сторнирует все записи в журнале и помечает счёт как аннулированный.

Ответ HTTP 200

{"success":true,"data":{"id":102,"status":"void"}}
POST /api/v1/invoices/{id}/mark-sent область: invoices.send

Отметить черновик счета как отправленный клиенту (меняет статус с черновика на неоплаченный). Идемпотентно.

Ответ HTTP 200

{"success":true,"data":{"id":102,"status":"unpaid"}}
DELETE /api/v1/invoices/{id} область: invoices.delete

Безвозвратно удалить черновик счёта-фактуры и все его строки. Нельзя удалить проведённые счета-фактуры или счета с распределениями платежей.

Ответ HTTP 200

{"success":true,"data":{"message":"Invoice deleted."}}

Возможные ошибки: posted_invoice_not_deletable, invoice_has_allocations

Счета

GET /api/v1/bills область: bills.get

Список всех счетов поставщиков. Поддерживает фильтр по статусу и постраничный вывод.

Параметры запроса

ПараметрТипОписание
status string необязательно Фильтр: draft | unpaid | paid | void
page integer необязательно Номер страницы
per_page integer необязательно Результатов на странице (максимум 100)

Ответ HTTP 200

{"success":true,"data":[{"id":55,"number":"BILL-00055","date":"2026-06-01","status":"draft","total":2000.00,"supplier":{"id":3,"name":"Demo Supplier"}}],"meta":{"current_page":1,"per_page":25,"total":12,"last_page":1}}
GET /api/v1/bills/{id} область: bills.get

Получить один счет с данными поставщика и строками.

Ответ HTTP 200

{"success":true,"data":{"id":55,"number":"BILL-00055","date":"2026-06-01","due_date":"2026-07-01","status":"draft","reference":"PO-001","total":2000.00,"supplier":{"id":3,"name":"Demo Supplier"},"lines":[]}}
POST /api/v1/bills область: bills.post

Создайте новый счет поставщика. Создается со статусом status=draft и автоматически сгенерированным номером BILL-XXXXX.

Тело запроса (JSON)

ПолеТипОписание
supplier_id integer обязательно ID существующего поставщика
date date обязательно Дата счета (ГГГГ-ММ-ДД)
due_date date необязательно Срок оплаты
reference string необязательно Ссылка поставщика / номер заказа на закупку (макс. 120)
notes string необязательно Внутренние заметки
subtotal decimal необязательно Итог без налога (по умолчанию: 0)
tax_total decimal необязательно Сумма налога (по умолчанию: 0)
discount_total decimal необязательно Скидка (по умолчанию: 0)
total decimal необязательно Общий итог (по умолчанию: 0)

Ответ HTTP 201

{"success":true,"data":{"id":56,"number":"BILL-00056","status":"draft","date":"2026-06-07","total":2000.00,"supplier_id":3}}
PUT /api/v1/bills/{id} область: bills.update

Обновить существующий черновик счёта. Все поля необязательны.

Тело запроса (JSON)

ПолеТипОписание
supplier_id integer необязательно Новый ID поставщика
date date необязательно Дата счета
due_date date необязательно Срок оплаты
reference string необязательно Ссылка поставщика
total decimal необязательно Общий итог

Ответ HTTP 200

{"success":true,"data":{"id":56,"status":"draft","total":2500.00,"supplier":{"id":3,"name":"Demo Supplier"}}}
POST /api/v1/bills/{id}/post область: bills.post

Провести черновик счета поставщика в главную книгу, отразив кредиторскую задолженность.

Ответ HTTP 200

{"success":true,"data":{"id":56,"status":"unpaid","posted_at":"2026-06-07T12:00:00Z"}}

Возможные ошибки: bill_post_failed

DELETE /api/v1/bills/{id} область: bills.delete

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

Ответ HTTP 200

{"success":true,"data":{"message":"Bill deleted."}}

Возможные ошибки: posted_bill_not_deletable, bill_has_allocations

Платежи

GET /api/v1/payments область: payments.get

Список всех платежей (поступления и выплаты).

Параметры запроса

ПараметрТипОписание
type string необязательно Фильтр: receipt | disbursement
status string необязательно Фильтр: draft | posted
page integer необязательно Номер страницы
per_page integer необязательно Результатов на странице (максимум 100)

Ответ HTTP 200

{"success":true,"data":[{"id":20,"type":"receipt","payment_date":"2026-06-07","amount_total":5000.00,"status":"draft","customer_id":1}],"meta":{"current_page":1,"per_page":25,"total":8,"last_page":1}}
POST /api/v1/payments область: payments.post

Запишите платёжную квитанцию (клиент оплатил) или выплату (вы оплатили поставщику). При необходимости распределите её по счёту-фактуре или счёту.

Тело запроса (JSON)

ПолеТипОписание
type string обязательно receipt (платёж клиента) или disbursement (платёж поставщику)
payment_date date обязательно Дата выплаты (ГГГГ-ММ-ДД)
amount_total decimal обязательно Общая выплаченная сумма (должна быть > 0)
method string необязательно Способ оплаты, например bank_transfer, cash, card
reference string необязательно Банковский номер операции или номер чека (макс. 120)
description string необязательно Описание или заметка
customer_id integer усл. Обязательно для платежей-поступлений (определяется по счету-фактуре, если document_type=ar_invoice)
supplier_id integer усл. Обязательно для платежей на выплату (определяется по счету, если document_type=ap_bill)
document_type string необязательно "ar_invoice" или "ap_bill" — запускает автоматическое распределение
document_id integer необязательно ID счета или накладной, с которым нужно сопоставить (обязательно, если задан document_type)
allocated_amount decimal необязательно Сумма для распределения (по умолчанию amount_total)

Ответ HTTP 201

{"success":true,"data":{"id":21,"type":"receipt","payment_date":"2026-06-07","amount_total":5000.00,"status":"draft","allocations":[{"document_type":"ar_invoice","document_id":101,"allocated_amount":5000.00}]}}

Возможные ошибки: document_required, document_type_mismatch, invoice_not_found, bill_not_found, client_required, supplier_required

Бухгалтерские проводки

GET /api/v1/journal-entries область: journal_entries.get

Список журнальных записей со строками и счетами. Поддерживает фильтр по диапазону дат.

Параметры запроса

ПараметрТипОписание
status string необязательно Фильтр: draft | posted
from date необязательно Дата начала (ГГГГ-ММ-ДД)
to date необязательно Дата окончания (ГГГГ-ММ-ДД)
page integer необязательно Номер страницы
per_page integer необязательно Результатов на странице (максимум 100)

Ответ HTTP 200

{"success":true,"data":[{"id":5,"entry_date":"2026-06-07","reference":"JE-001","status":"posted","lines_count":2}],"meta":{"current_page":1,"per_page":25,"total":5,"last_page":1}}
POST /api/v1/journal-entries область: journal_entries.post

Создать и сразу провести сбалансированную проводку. Итог дебета должен равняться итогу кредита (допуск ±0,01).

Тело запроса (JSON)

ПолеТипОписание
date date обязательно Дата записи (ГГГГ-ММ-ДД)
reference string необязательно Справочный код, например JE-001 (не более 120)
description string необязательно Примечание / описание (макс. 2000)
lines array обязательно Минимум 2 строки. Каждая строка: account_id (обязательно), debit (десятичное), credit (десятичное), description (строка)

Ответ HTTP 201

{"success":true,"data":{"id":6,"entry_date":"2026-06-07","reference":"JE-001","status":"posted","posted_at":"2026-06-07T12:00:00Z","lines":[{"account_id":101,"account":{"code":"1100","name":"Cash"},"debit":1000,"credit":0},{"account_id":202,"account":{"code":"3000","name":"Equity"},"debit":0,"credit":1000}]}}

Возможные ошибки: journal_not_balanced

DELETE /api/v1/journal-entries/{id} область: journal_entries.delete

Удалить непроведенную проводку журнала. Проведенные проводки через API удалить нельзя.

Ответ HTTP 200

{"success":true,"data":{"message":"Journal entry deleted."}}

Возможные ошибки: posted_journal_not_deletable

Отчёты

Все конечные точки отчётов принимают ?from=YYYY-MM-DD&to=YYYY-MM-DD. Отчёты о балансе, пробный баланс и отчёты о сроках задолженности также принимают ?as_of=YYYY-MM-DD (эквивалентно to).

GET /api/v1/reports/income-statement область: reports.income_statement

Отчёт о прибылях и убытках. Показывает выручку, расходы и чистую прибыль за указанный период.

Параметры запроса

ПараметрТипОписание
from date необязательно Начало периода (ГГГГ-ММ-ДД)
to date необязательно Конец периода (ГГГГ-ММ-ДД)

Ответ HTTP 200

{"success":true,"data":{"revenue":150000,"expenses":85000,"net_income":65000}}
GET /api/v1/reports/balance-sheet область: reports.balance_sheet

Снимок баланса. Показывает активы, обязательства и капитал на указанную дату.

Параметры запроса

ПараметрТипОписание
to date необязательно Дата (ГГГГ-ММ-ДД). Также принимается как ?as_of=

Ответ HTTP 200

{"success":true,"data":{"assets":{"total":250000},"liabilities":{"total":80000},"equity":{"total":170000}}}
GET /api/v1/reports/cash-flow область: reports.cash_flow

Отчет о движении денежных средств за указанный период (прямой метод).

Параметры запроса

ПараметрТипОписание
from date необязательно Начало периода
to date необязательно Конец периода

Ответ HTTP 200

{"success":true,"data":{"operating":45000,"investing":-12000,"financing":-8000,"net_change":25000}}
GET /api/v1/reports/trial-balance область: reports.trial_balance

Оборотно-сальдовая ведомость по всем счетам с итогами по дебету и кредиту на дату.

Параметры запроса

ПараметрТипОписание
to date необязательно Дата (ГГГГ-ММ-ДД)

Ответ HTTP 200

{"success":true,"data":[{"account_code":"1100","account_name":"Cash","debit":50000,"credit":0},{"account_code":"2000","account_name":"Accounts Payable","debit":0,"credit":15000}]}
GET /api/v1/reports/ar-aging область: reports.ar_aging

Старение дебиторской задолженности. Неоплаченные счета клиентов, сгруппированные по степени просрочки.

Параметры запроса

ПараметрТипОписание
to date необязательно Дата отчета о старении (ГГГГ-ММ-ДД)

Ответ HTTP 200

{"success":true,"data":{"current":12000,"1_30":3500,"31_60":800,"61_90":0,"over_90":500,"total":16800}}
GET /api/v1/reports/ap-aging область: reports.ap_aging

Старение кредиторской задолженности. Неоплаченные счета поставщиков, сгруппированные по степени просрочки.

Параметры запроса

ПараметрТипОписание
to date необязательно Дата отчета о старении (ГГГГ-ММ-ДД)

Ответ HTTP 200

{"success":true,"data":{"current":8000,"1_30":1200,"31_60":0,"61_90":0,"over_90":0,"total":9200}}
GET /api/v1/reports/tax область: reports.tax

Сводка НДС / налогов. Показывает налог, собранный с продаж, и налог, уплаченный при закупках, за период.

Параметры запроса

ПараметрТипОписание
from date необязательно Начало периода
to date необязательно Конец периода

Ответ HTTP 200

{"success":true,"data":{"tax_collected":15000,"tax_paid":4200,"net_vat_payable":10800}}

Справочник ошибок

Код ошибки HTTP Значение
invoice_already_posted 422 Счет уже проведен в учете
invoice_total_required 422 Нельзя провести счет с нулевой или отрицательной суммой
invoice_date_required 422 Дата документа обязательна до проведения
posted_invoice_not_deletable 422 Аннулируйте или отмените проводку счёта перед удалением
invoice_has_allocations 422 Удалите распределения платежей перед удалением
posted_bill_not_deletable 422 Нельзя удалить проведенный или непроектный счет
bill_has_allocations 422 Удалите распределения платежей перед удалением
bill_post_failed 422 Счет не прошел внутреннюю проверку проведения
journal_not_balanced 422 Общий дебет не равен общему кредиту
posted_journal_not_deletable 422 Удалить можно только черновые (непроведённые) записи
document_required 422 document_id обязателен, когда задано document_type
document_type_mismatch 422 ar_invoice требует receipt; ap_bill требует disbursement
invoice_not_found 404 Счет с таким ID не существует
bill_not_found 404 Счет с таким ID не существует
client_required 422 customer_id обязателен для платежей receipt
supplier_required 422 supplier_id обязателен для платежей disbursement

Постраничная навигация

Все конечные точки списков возвращают постраничные результаты. Управляйте постраничной навигацией параметрами запроса:

ПараметрПо умолчаниюМакс.Описание
page1—Номер запрашиваемой страницы
per_page25100Количество результатов на странице

Объект meta в каждом ответе со списком содержит current_page, per_page, total и last_page.