Приложение 9. Работа с API ФинГрада

9.1. Общие сведения об API ФинГрада

API (англ. Application Programming Interface) — это набор функций, предоставляемых ФинГрадом для обмена данными. Используя методы API, вы можете автоматически получать список аналитик и их значений, редактировать справочники аналитик и проводить проводки.

примечание

Этот раздел предназначен только для программистов. Неправильное использование методов API может привести к искажению данных.

Чаще всего API применяют, когда нужно связать проводки ФинГрада с внешними событиями. Например, при создании документа в 1С или Axapta вы хотите автоматически генерировать нужные проводки в ФинГраде. Или генерировать проводки при наступлении конкретной даты. Условия могут быть разными. Суть в том, что с помощью API это можно делать автоматически.

Функции API ФинГрада написаны на языке C#. API-приложение состоит из трёх основных блоков:

Подключение необходимых модулей. Это общая часть для всех приложений API ФинГрада.
Формирование списка запросов (команд) к базе данных ФинГрада. Это ядро приложения. Отвечает за получение и изменение данных.
Подключение к базе данных. Это тоже общая часть для всех API-приложений ФинГрада. Используя название базы данных, логин и пароль пользователя, вы устанавливаете соединение с базой данных.

Условия работы. Для работы API ФинГрада должны выполняться три условия:

На компьютере, где вы будете запускать API-приложение, должен быть установлен ФинГрад.
База данных, к которой вы будете подключаться, должна быть зарегистрирована в ФинГраде. Иначе говоря, можно запустить ФинГрад, выбрать эту базу данных и зайти в неё, используя логин и пароль пользователя.
К проекту в Microsoft Visual Studio должны быть подключены ссылки на библиотеки:
- Finance.dll
- Fingrad.Authentication.dll
- Fingrad.Core.dll
- Fingrad.DbManagement.dll
- Fingrad.DbManagement.BaseServer.dll

Эти файлы лежат в папке с установкой ФинГрада. По умолчанию это C:\Program Files (x86)\ФинГрад\.

9.2. Примеры использования API ФинГрада

примечание

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

Подключение к базе данных

// Подключаем необходимые модули
using System;
using Fingrad;
using Fingrad.DbManagement;

namespace FingradAPI
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                // Загружаем список баз данных
                DbManager dbAdmin = new DbManager();
                dbAdmin.LoadConfig();

                // Находим базу
                var db = dbAdmin.FindDatabase("demo", DatabaseType.MSSQL);

                // Заходим в выбранную базу данных
                int userId = new Fingrad.Authentication.DesktopLogin(db.ConnectionString).Login("root", "root");
                var uc = UserContext.StartNewSession(
                    db.ConnectionString,
                    userId,
                    new UserContext.Properties
                    {
                        ProgressEvent = (description, percent) => { Console.WriteLine("{0} {1}%", description, (int)(percent * 100)); }
                    });
                Console.WriteLine("Подключено");
            }
            catch (Exception e)
            {
                Console.WriteLine(e.ToString());
                Console.ReadKey();
            }
        }
    }
}

Здесь demo — это имя базы данных, а root — логин и пароль пользователя.

Проведение проводки

Этот пример включает все три блока: подключение модулей, список запросов и подключение к базе данных.

// Подключаем необходимые модули
using System;
using Fingrad;
using Fingrad.DbManagement;
using Fingrad.TransactionsIO;

namespace FingradAPI
{
    class Program
    {
        // Проводим проводку
        static void CommitTran(UserContext gl)
        {
            var t = new EditableTransaction(gl.Id);

            // Выбираем счета
            t.DebitAccount = Account.ByName(gl.Id, "Касса");
            t.CreditAccount = Account.ByName(gl.Id, "Безналичные");

            // Указываем аналитики
            var analytic = Analytic.ByName(gl.Id, "Компания (ЦФО)");
            t.SetValue(EditableAnalyticValue.EditOrNew(gl.Id, analytic.Id, "Облако"));

            // Указываем сумму
            t.SetAmount(GB_CURRENCY_ID.RUR_ID, 10000.0m, AmountDirection.Forward);

            // Сохраняем проводку
            var res = t.Commit(gl.Id);

            // Проверяем ошибки
            foreach (var err in res.Errors)
                Console.WriteLine(err.Description);
        }

        static void Main(string[] args)
        {
            try
            {
                // Загружаем список баз данных
                DbManager dbAdmin = new DbManager();
                dbAdmin.LoadConfig();

                // Находим базу
                var db = dbAdmin.FindDatabase("demo", DatabaseType.MSSQL);

                // Заходим в выбранную базу данных
                int userId = new Fingrad.Authentication.DesktopLogin(db.ConnectionString).Login("root", "root");
                var uc = UserContext.StartNewSession(
                    db.ConnectionString,
                    userId,
                    new UserContext.Properties
                    {
                        ProgressEvent = (description, percent) => { Console.WriteLine("{0} {1}%", description, (int)(percent * 100)); }
                    });

                CommitTran(uc);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.ToString());
                Console.ReadKey();
            }
        }
    }
}

С помощью этого приложения мы подключаемся к базе данных demo с использованием логина и пароля root. Далее мы со счёта Касса переводим на счёт Безналичные сумму 10000 рублей. В проводке мы также указываем аналитику Компания (ЦФО) со значением Облако.

подсказка

Если в значении аналитики есть двойные кавычки, например, ООО "Рассвет", используйте экранирование символов: ООО \"Рассвет\".

Редактирование справочника аналитики

Этот пример включает все три блока: подключение модулей, список запросов и подключение к базе данных.

// Подключаем необходимые модули
using System;
using System.Linq;
using Fingrad;
using Fingrad.DbManagement;

namespace FingradAPI
{
    class Program
    {
        // Редактируем справочник аналитики
        static void UpdateValue(UserContext gl)
        {
            // Находим аналитику по имени и колонку "Город"
            var analytic = Analytic.ByName(gl.Id, "бик");
            var cityColumn = analytic.EnumerateFields(gl.Id).Where(f => f.Name == "Город").FirstOrDefault();

            // Отредактируем значение и колонку
            var editableValue = EditableAnalyticValue.EditOrNew(gl.Id, analytic.Id, "044525225");
            editableValue.SetLinked(cityColumn.Id, "Москва");

            // Сохраняем
            var op = new AnalyticValueCommitOperation(editableValue);
            var result = op.ExecuteBatch(gl.Id);

            // Выводим ошибки в консоль
            foreach (var error in result)
                Console.WriteLine(error.Description);
        }

        static void Main(string[] args)
        {
            try
            {
                // Загружаем список баз данных
                DbManager dbAdmin = new DbManager();
                dbAdmin.LoadConfig();

                // Находим базу
                var db = dbAdmin.FindDatabase("demo", DatabaseType.MSSQL);

                // Заходим в выбранную базу данных
                int userId = new Fingrad.Authentication.DesktopLogin(db.ConnectionString).Login("root", "root");
                var uc = UserContext.StartNewSession(
                    db.ConnectionString,
                    userId,
                    new UserContext.Properties
                    {
                        ProgressEvent = (description, percent) => { Console.WriteLine("{0} {1}%", description, (int)(percent * 100)); }
                    });

                UpdateValue(uc);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.ToString());
                Console.ReadKey();
            }
        }
    }
}

С помощью этого приложения мы подключаемся к базе данных demo с использованием логина и пароля root. Далее мы находим аналитику БИК и присваиваем ей значение 044525225, а её колонке Город присваиваем значение Москва.

Получение значения справочника аналитики

Этот пример включает все три блока: подключение модулей, список запросов и подключение к базе данных.

// Подключаем необходимые модули
using System;
using System.Linq;
using Fingrad;
using Fingrad.DbManagement;

namespace FingradAPI
{
    class Program
    {
        // Получаем значения справочника аналитики     
        static void ListValues(UserContext gl)
        {
            // Находим аналитику по имени
            var analytic = Analytic.ByName(gl.Id, "бик");

            // Получаем все её значения
            var avf = new Fingrad.Completion.AnalyticValueFilter(gl.Id) { Analytic = analytic };
            var allValues = Fingrad.Completion.CompletionEngine.AnalyticCompletion(avf, "", null);

            // Найти колонку "Город"
            var cityColumn = analytic.EnumerateFields(gl.Id).Where(f => f.Name == "Город").FirstOrDefault();
            AnalyticFieldAccessor cityColumnAccessor = new AnalyticFieldAccessor(gl.Id, cityColumn.Id, DateTime.Now);

            // Выводим первые 10 значений
            foreach (var val in allValues.Take(10))
            {
                Console.WriteLine(String.Format("{0}={1}, {2}={3}"
                    , analytic.Name, val.ToString(),
                    cityColumn.Name, val.GetLinkedString(cityColumnAccessor)));
            }
        }

        static void Main(string[] args)
        {
            try
            {
                // Загружаем список баз данных
                DbManager dbAdmin = new DbManager();
                dbAdmin.LoadConfig();

                // Находим базу
                var db = dbAdmin.FindDatabase("demo", DatabaseType.MSSQL);

                // Заходим в выбранную базу данных
                int userId = new Fingrad.Authentication.DesktopLogin(db.ConnectionString).Login("root", "root");
                var uc = UserContext.StartNewSession(
                    db.ConnectionString,
                    userId,
                    new UserContext.Properties
                    {
                        ProgressEvent = (description, percent) => { Console.WriteLine("{0} {1}%", description, (int)(percent * 100)); }
                    });

                ListValues(uc);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.ToString());
                Console.ReadKey();
            }
        }
    }
}

С помощью этого приложения мы подключаемся к базе данных demo с использованием логина и пароля root. Далее мы находим аналитику БИК и выводим все её значения на консоль. Также, мы находим колонку Город этой аналитики и выводим на консоль первые 10 значений этой колонки.

Получение списка проводок

Этот пример включает все три блока: подключение модулей, список запросов и подключение к базе данных.

// Подключаем необходимые модули
using System;
using System.Linq;
using Fingrad;
using Fingrad.DbManagement;

namespace FingradAPI
{
    class Program
    {
        // Получаем список проводок 
        static void GetExtract(UserContext gl)
        {
            // Создаём параметры
            var ep = new ExtractParams(gl.Id);

            // Задаём дату от начала времен до сегодня
            ep.Constraints.OnDate.StartDate = new DateTime(2015, 05, 21);
            ep.Constraints.OnDate.FinishDate = DateTime.Now;

            // Фильтруем по счету "Касса"
            ep.Constraints.OnAccounts.AddAccount(Account.ByName(gl.Id, "Касса"));

            // Ограничиваем по аналитике "Компания (ЦФО)"
            var company = ep.Constraints.OnAnalytics[Analytic.ByName(gl.Id, "Компания (ЦФО)").Id];
            company.SelectAllValues = true;
            company.SelectDbNull = true;

            // Получаем выписку
            var transactions = ReportGenerator.GetExtract(gl.Id, ep);
            // Выводим на консоль первые 10 проводок
            foreach (var t in transactions.Take(10))
                Console.WriteLine("TranId = {0} ", t.Id);
        }

        static void Main(string[] args)
        {
            try
            {
                // Загружаем список баз данных
                DbManager dbAdmin = new DbManager();
                dbAdmin.LoadConfig();

                // Находим базу
                var db = dbAdmin.FindDatabase("demo", DatabaseType.MSSQL);

                // Заходим в выбранную базу данных
                int userId = new Fingrad.Authentication.DesktopLogin(db.ConnectionString).Login("root", "root");
                var uc = UserContext.StartNewSession(
                    db.ConnectionString,
                    userId,
                    new UserContext.Properties
                    {
                        ProgressEvent = (description, percent) => { Console.WriteLine("{0} {1}%", description, (int)(percent * 100)); }
                    });

                GetExtract(uc);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.ToString());
                Console.ReadKey();
            }
        }
    }
}

С помощью этого приложения мы подключаемся к базе данных demo с использованием логина и пароля root. Далее мы задаём начальную дату отчёта 2015, 05, 21. Затем ограничиваем отчёт по счёту Касса и аналитике Компания (ЦФО). И, наконец, получаем список проводок, удовлетворяющих этим условиям. Первые 10 из них выводим на консоль.

В этом примере найдена одна проводка. Её ID равен 24891. Это проводка, которую мы создали в примере Проведение проводки.

Чтобы сбросить начальную дату отчёта, то есть получить проводки за весь период, замените строку

ep.Constraints.OnDate.StartDate = new DateTime(2015, 05, 21);

на строку

ep.Constraints.OnDate.StartDate = null;

Чтобы включить в отчёт проводки с незаданным значением аналитики Компания (ЦФО), замените строку

company.SelectDbNull = false;

на строку

company.SelectDbNull = true;

9.1. Общие сведения об API ФинГрада​

9.2. Примеры использования API ФинГрада​

Подключение к базе данных​

Проведение проводки​

Редактирование справочника аналитики​

Получение значения справочника аналитики​

Получение списка проводок​

9.1. Общие сведения об API ФинГрада

9.2. Примеры использования API ФинГрада

Подключение к базе данных

Проведение проводки

Редактирование справочника аналитики

Получение значения справочника аналитики

Получение списка проводок