Руководство по API для разработчиков готово. Открыть руководство Скачать PDF
Поиск компаний, PDF, UBL и 93 операции Turkcell доступны через подключение компании. Бухгалтерская запись отделена от официальной отправки.
Главная

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 и обнаружение

Быстрый старт (3 шага)

  1. Войдите — Вход для клиентов открывает доступ к личному кабинету.
  2. Создайте токен — В профиле, раздел «API ИИ-агентов»: токен принадлежит Вашей клиентской учётной записи и действует для всех связанных компаний. Выберите «Создать новый токен» или «Отправить токен на мою почту».
  3. Настройте ассистента — В Custom GPT, Claude или Вашей интеграции укажите Base URL = https://dijital.vergimerkezi.com.tr/api/v1 и Authorization: Bearer <token>; компания выбирается в вызовах API с помощью company_id.

Если Вы не хотите писать код, вместо шага 3 откройте раздел «Подключите свой ИИ» : один раз настройте портал в ChatGPT или Claude, а всё остальное делайте в чате.

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