Agentic API и открытый сервис бухгалтерского учёта
Для бухгалтерских услуг и процессов учёта
REST API с поддержкой ИИ
Инфраструктура электронных документов и финансовой отчётности по стандарту OpenAPI 3.0 для разработчиков, внешних ассистентов (LLM) и интеграций с ERP.
Система Vergi Merkezi | Mali Müşavirlik полностью синхронизирована с личным кабинетом клиента. Первичным учётом, доходами и расходами, а также электронными счетами (e-Fatura) можно управлять через стандартные конечные точки HTTP в формате JSON.
Модель интеграции
API использует запросы в формате JSON и стандартные методы HTTP. На стороне клиента Вы можете выбрать ChatGPT, Claude, корпоративного бота или собственный скрипт. На стороне сервера действует единый контракт (OpenAPI 3).
Любой совместимый HTTP-клиент может выполнять запросы с токеном. Зависимости от конкретного поставщика нет.
Профессиональные услуги оказываются в рамках 3568 sayılı Kanun, соответствующих профессиональных правил и Закона о защите персональных данных (KVKK). Профессиональные гарантии
Что Вы можете делать?
Бухгалтерия и электронные документы
Accounting & E-Invoice
Вы можете просматривать и подтверждать входящие электронные счета (inbox), выставлять новые счета, регистрировать поступления и платежи. Черновики можно официально отправить в GİB как электронные счета (e-Fatura) одной командой.
Финансовая отчётность
Financial Reporting
Оборотно-сальдовая ведомость, отчёт о доходах и расходах, баланс, сводка по НДС (KDV), выписки по контрагентам, банку и кассе, отчёты о задолженности по срокам и движении денежных средств возвращаются в формате JSON. Ассистент может проанализировать эти данные и подготовить сводку.
Соответствие законодательству
Regulatory Compliance
Бухгалтерские услуги оказываются в рамках 3568 sayılı Kanun и профессиональных правил. Записи через API основаны на настроенном плане счетов и данных пользователя. Автоматические консультации по законодательству не предоставляются.
Почему интерактивная документация вместо статичного PDF?
Традиционная документация API электронных счетов и бухгалтерского учёта в Турции обычно представляет собой длинные статичные файлы только для разработчиков. Наша «живая» документация Swagger UI — это современная инфраструктура, оптимизированная для разработчиков, поисковых систем и генеративного ИИ (GEO/SEO):
- Мгновенная проверка (Try it out): Вам не нужно писать код, чтобы проверить работу описанной на странице конечной точки бухгалтерского API. Вы можете выполнить запрос с собственными данными в реальном времени.
- Совместимость с LLM и ИИ-агентами: Инфраструктура создана в машиночитаемом формате по стандарту OpenAPI 3.0, чтобы ассистенты, такие как ChatGPT, Claude и Perplexity, могли самостоятельно понимать её и выполнять операции.
- Всегда актуально (Single Source of Truth): PDF устаревают, а Swagger UI напрямую отражает действующий код системы. При изменении налогового законодательства или параметров API документация синхронизируется сразу.
Информация: Читать руководство и изучать схемы данных (JSON) можно свободно, без пароля. Только для реальной операции с электронным документом или отчётом через функцию «Попробовать» Вам потребуется ввести API-токен из личного кабинета через значок замка. Это необходимо для Вашей безопасности.
Работа через кабинет и API
Типичные различия для одной учётной записи (кратко)
| Возможность | Традиционные программы | Через API |
|---|---|---|
| Ввод данных | Веб-интерфейс | HTTP-клиент или агент |
| Доступ | Браузер | Программный (с токеном) |
| Язык | Язык интерфейса | Документация и API преимущественно на турецком; язык ассистента задаётся на стороне клиента |
| Отчёты | Представления в кабинете | Конечные точки отчётов JSON |
| Интеграция | — | REST, OpenAPI 3, Bearer |
Подключите свой ИИ
Подключите свой ChatGPT или Claude к порталу и выставляйте счета в чате. Устанавливать дополнительную программу не нужно.
Портал также работает как сервер MCP (Model Context Protocol). Это общий стандарт подключения ИИ-ассистентов к системам. Достаточно один раз настроить портал в ассистенте, и писать код не потребуется. Вы описываете задачу обычными словами, а ассистент выполняет нужную операцию на портале.
Кто оплачивает ИИ?
Вы. Вы используете собственную подписку ChatGPT или Claude. Портал предоставляет только данные и операции, поэтому отдельной платы за ИИ при подключении нет. При отправке электронных документов единицы пакета документов списываются как обычно.
1. Данные подключения
| Адрес сервера | https://dijital.vergimerkezi.com.tr/api/v1/mcp |
| Транспорт | Streamable HTTP (JSON-RPC 2.0) |
| Аутентификация | Authorization: Bearer <token> |
| Token | Токен можно получить в разделе «API ИИ-агентов» Вашего профиля. Это тот же токен, что и для REST API. |
2. Настройте ассистента
В настольном приложении Claude достаточно добавить следующую запись в файл конфигурации (вместо <token> укажите Ваш токен):
{
"mcpServers": {
"vergi-merkezi": {
"type": "http",
"url": "https://dijital.vergimerkezi.com.tr/api/v1/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
Другим ассистентам с поддержкой пользовательских коннекторов нужны те же три параметра: адрес сервера, тип аутентификации Bearer и Ваш токен. Названия меню зависят от продукта и версии. Если возникнут сложности, напишите нам, и мы настроим подключение вместе.
3. Что можно сказать после подключения?
Выставление счёта
«Выставьте Ahmet Ticaret счёт на 12.000 TL за консультационные услуги.»
Проверка получателя
«Зарегистрирован ли этот налоговый номер в e-Fatura?»
Отчёт
«Какая у меня прибыль в этом году? Покажите по месяцам.»
Контрагент
«Какое сальдо у Mehmet Ltd? Подготовьте выписку.»
ИИ не может самостоятельно выставлять счета
- Сначала ассистент готовит черновик. На этом этапе ничего не отправляется в GİB, единицы пакета документов не расходуются.
-
Вам показывается сводка черновика. Для отправки Вы должны указать фразу подтверждения, которую дал ассистент (например,
GÖNDER-42). Ассистент не может сам сгенерировать эту фразу. - Отправленный электронный документ нельзя отозвать. Перед подтверждением прочитайте сводку.
- Отправка отклоняется, если единицы пакета документов закончились, документ уже отправлен или это счёт на закупку.
- Удаление документов также выполняется в два этапа и недоступно для закрытых периодов.
Инструменты, доступные ассистенту
| Тема | Инструменты |
|---|---|
| Компании и карточки | get_companies, lookup_caris, lookup_items, lookup_bank_accounts, lookup_cash_registers, lookup_chart_of_accounts |
| Бухгалтерский учёт | get_accounting_categories, record_invoice_draft, confirm_draft, update_document, propose_delete, confirm_delete, record_collection, record_payment |
| Отчёт | get_reports_summary, get_reports_documents, get_reports_vat, get_cari_statement |
| Электронные документы | get_einvoice_readiness, check_einvoice_recipient, create_sales_invoice_draft, send_einvoice, get_einvoice_status |
Актуальный список всегда доступен в самом ассистенте: при подключении он читает каталог инструментов. Инструменты электронных документов работают только для компаний с подключёнными услугами e-Fatura (электронный счёт), e-Arşiv (электронный архивный счёт) или e-SMM (электронная квитанция о профессиональных услугах).
Техническая документация
Адрес API, аутентификация и конечные точки — с примерами кода
1. Базовый адрес API (Base URL)
Все запросы отправляются на этот адрес. Измените его в соответствии с Вашей средой.
https://dijital.vergimerkezi.com.tr/api/v1
2. Аутентификация (Authentication)
Токен принадлежит Вашей клиентской учётной записи. Отдельного токена для каждой компании нет. Два способа: (A) В личном кабинете: Профиль — «Создать новый токен». (B) Программно: POST https://dijital.vergimerkezi.com.tr/api/v1/auth/login используется для отправки электронной почты и пароля; в ответе возвращается data.token . Каждый успешный вход создаёт новый токен и аннулирует предыдущий. В каждом запросе Authorization: Bearer <token> передавайте как заголовок.
Authorization: Bearer YOUR_API_TOKEN
3. Обзор конечных точек
| Метод | Путь | Описание |
|---|---|---|
| POST | /auth/login | Получить Bearer-токен по электронной почте/паролю (ограничение частоты; предыдущий токен аннулируется) |
| GET | /agent/companies | Компании этой учётной записи (далее company_id в запросе) |
| GET | /agent/products | Список товаров/услуг и пакетов документов |
| POST | /agent/orders | Создать заказ (возвращает checkout_url) |
| GET | /agent/orders/{id} | Статус заказа |
| — Заявка на регистрацию компании — | ||
| GET | /agent/formation | Список заявок на регистрацию |
| POST | /agent/formation | Создать заявку на регистрацию |
| GET | /agent/formation/{id} | Статус заявки |
| — Справочные данные (контрагенты / банк / касса / запасы / план счетов) — | ||
| GET | /agent/lookup/caris | Список клиентов/поставщиков (search, type?, has_balance?) |
| POST | /agent/lookup/caris | Создать контрагента |
| GET | /agent/lookup/caris/{id} | Данные одного контрагента |
| GET | /agent/lookup/bank-accounts | Банковские счета (currency?) |
| GET | /agent/lookup/cash-registers | Кассы (currency?) |
| GET | /agent/lookup/items | Карточка запасов / товар-услуга (search, type?) |
| POST | /agent/lookup/items | Создать карточку запасов |
| GET | /agent/lookup/chart-of-accounts | План счетов — компания с балансовым учётом (root_type?, search?) |
| — Бухгалтерские записи — | ||
| GET | /agent/accounting/categories | Категории расходов (регистрация счёта) |
| POST | /agent/accounting/record-invoice | Зарегистрировать счёт напрямую (без подтверждения) |
| POST | /agent/accounting/record-invoice-draft | Создать черновик → подтверждение пользователя → confirm-draft (рекомендуется) |
| POST | /agent/accounting/confirm-draft/{id} | Подтвердить черновик (document_id) |
| POST | /agent/accounting/propose-delete/{id} | Предложить удаление: возвращает сводку + фразу подтверждения |
| POST | /agent/accounting/confirm-delete/{id} | Подтвердить удаление — обязательна фраза confirmation |
| GET | /agent/accounting/document/{id} | Данные одного документа (?company_id=) |
| PATCH | /agent/accounting/document/{id} | Обновить документ draft/pending |
| POST | /agent/accounting/record-collection | Зарегистрировать поступление (поддержка Idempotency-Key) |
| POST | /agent/accounting/record-payment | Зарегистрировать платёж (поддержка Idempotency-Key) |
| POST | /agent/accounting/record-cash-transaction | Приход/расход по кассе |
| POST | /agent/accounting/record-bank-transfer | Перевод между банковскими счетами |
| POST | /agent/accounting/record-stock-movement | Движение запасов |
| — Выписки и отчёты — | ||
| GET | /agent/lookup/cari-statement | Выписка по контрагенту |
| GET | /agent/lookup/bank-statement | Банковская выписка |
| GET | /agent/lookup/cash-statement | Выписка по кассе |
| GET | /agent/reports/trial-balance | Оборотно-сальдовая ведомость (company_id, year, month?) |
| GET | /agent/reports/income-statement | Отчёт о доходах и расходах / прибыль (company_id, year) |
| GET | /agent/reports/vat | Сводка по НДС (KDV) (company_id, year, month?) |
| GET | /agent/reports/summary | Годовая сводка: доходы/расходы/чистый результат по месяцам |
| GET | /agent/reports/documents | Список документов (диапазон дат, фильтр по типу) |
| GET | /agent/reports/aged-receivables | Дебиторская задолженность по срокам |
| GET | /agent/reports/aged-payables | Кредиторская задолженность по срокам |
| GET | /agent/reports/balance-sheet | Сводный баланс |
| GET | /agent/reports/cash-flow | Сводка движения денежных средств |
4. Пример кода: Список компаний (cURL)
Сначала Bearer-токен подтверждает личность клиента. В ответе возвращаются компании этой учётной записи. В запросах заказов, бухгалтерских операций и отчётов используйте id нужной компании из списка как company_id. Тело успешного ответа: success, data (например, data.companies).
curl -s -X GET "https://dijital.vergimerkezi.com.tr/api/v1/agent/companies" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"
5. Пример кода: Зарегистрировать счёт в бухгалтерии (cURL)
Пример запроса, отправляемого, когда ассистент говорит «зарегистрируйте этот счёт». company_id получается через GET companies.
Примечание: Эта конечная точка сохраняет документ напрямую, без подтверждения пользователя. Если Вам нужно подтверждение, используйте последовательность record-invoice-draft + confirm-draft.
curl -s -X POST "https://dijital.vergimerkezi.com.tr/api/v1/agent/accounting/record-invoice" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"company_id": 1,
"type": "gider",
"invoice_date": "2026-06-15",
"amount": 1180.00,
"supplier_name": "Örnek Tedarikçi A.Ş.",
"supplier_tax_id": "1234567890",
"invoice_no": "FTR-2026-001",
"category": "other",
"description": "Ofis malzemeleri",
"matrah": 1000.00,
"kdv_amount": 180.00,
"kdv_rate": 18
}'
6. Пример кода: Черновик → Подтверждение
Сначала создайте черновик и покажите пользователю сводку. После подтверждения завершите операцию через confirm-draft.
# 1) Создать черновик
curl -s -X POST "https://dijital.vergimerkezi.com.tr/api/v1/agent/accounting/record-invoice-draft" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"company_id":1,"type":"gider","invoice_date":"2026-06-15","amount":1180}'
# Ответ (внутри data): document_id, draft_summary, confirm_url
# 2) Завершить после подтверждения пользователя (id = document_id)
curl -s -X POST "https://dijital.vergimerkezi.com.tr/api/v1/agent/accounting/confirm-draft/DOCUMENT_ID" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Тело запроса не требуется. Нужно использовать тот же Bearer-токен пользователя, который создал черновик (документ сопоставляется с user_id).
7. Пример кода: Удаление документа — подтверждение в два этапа
Ассистент никогда не может удалить документ одним действием. Сначала через propose-delete он получает сводку документа и фразу подтверждения и показывает их пользователю. После подтверждения пользователя удаление завершается через confirm-delete.
# 1) Предложить удаление (возвращает сводку документа + фразу подтверждения, НЕ УДАЛЯЕТ)
curl -s -X POST "https://dijital.vergimerkezi.com.tr/api/v1/agent/accounting/propose-delete/DOCUMENT_ID" \
-H "Authorization: Bearer YOUR_API_TOKEN"
# Ответ: data.confirm_phrase = "SİL-DOCUMENT_ID"
# Покажите эту фразу пользователю и получите подтверждение.
# 2) Удалить после подтверждения пользователя
curl -s -X POST "https://dijital.vergimerkezi.com.tr/api/v1/agent/accounting/confirm-delete/DOCUMENT_ID" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"confirmation": "SİL-DOCUMENT_ID"}'
Если фраза подтверждения не совпадает или период закрыт, возвращается 422. Проведённые (posted) записи периода удалить нельзя.
8. Пример кода: Годовой сводный отчёт (доходы/расходы/чистый результат)
Используется для вопросов «Какая у меня прибыль за год?» или «Показатели за июнь». Подходит для всех типов компаний.
curl -s -X GET "https://dijital.vergimerkezi.com.tr/api/v1/agent/reports/summary?company_id=1&year=2026" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"
Ответ внутри data: monthly[] (income, expense, net за каждый месяц), total_income, total_expense, total_net.
9. Пример кода: Python (requests)
import requests
BASE = "https://dijital.vergimerkezi.com.tr/api/v1"
TOKEN = "YOUR_API_TOKEN"
headers = {"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"}
# Список компаний
r = requests.get(f"{BASE}/agent/companies", headers=headers)
companies = r.json()["data"]["companies"]
# Годовая сводка (первая компания)
cid = companies[0]["id"]
r = requests.get(f"{BASE}/agent/reports/summary", params={"company_id": cid, "year": 2026}, headers=headers)
summary = r.json()["data"]
10. OpenAPI и обнаружение
- Интерактивная документация (Swagger UI): https://dijital.vergimerkezi.com.tr/api/v1/docs — Конечные точки по тегам, проверка (Try it out) и прямые ссылки на разделы.
- OpenAPI 3.0 (исходный JSON): https://dijital.vergimerkezi.com.tr/api/v1/openapi.json — Список конечных точек и схемы запросов/ответов.
- Обнаружение (Discovery): https://dijital.vergimerkezi.com.tr/.well-known/agent-api — Машиночитаемая сводка в JSON.
Быстрый старт (3 шага)
- Войдите — Вход для клиентов открывает доступ к личному кабинету.
- Создайте токен — В профиле, раздел «API ИИ-агентов»: токен принадлежит Вашей клиентской учётной записи и действует для всех связанных компаний. Выберите «Создать новый токен» или «Отправить токен на мою почту».
- Настройте ассистента — В Custom GPT, Claude или Вашей интеграции укажите Base URL =
https://dijital.vergimerkezi.com.tr/api/v1и Authorization: Bearer <token>; компания выбирается в вызовах API с помощьюcompany_id.
Если Вы не хотите писать код, вместо шага 3 откройте раздел «Подключите свой ИИ» : один раз настройте портал в ChatGPT или Claude, а всё остальное делайте в чате.
Если у Вас нет учётной записи, начните со страницы подать заявку или контактов и продолжите оттуда.