Приложение 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.DbManagement.dll:
Эти файлы лежат в папке с установкой ФинГрада. По умолчанию это c:\Program Files (x86)\ФинГрад\...
П9.2. Примеры использования API ФинГрада
Замечание. При копировании исходного кода из примеров этого раздела из-за экранирования некоторых символов могут возникать синтаксические ошибки.
Как подключиться к базе данных
//Подключаем необходимые модули using System; using System.Diagnostics; using System.Linq; using Fingrad; using Fingrad.DbManagement; namespace FingradAPI { class Program { static void Main(string[] args) { try { //Загружаем список баз данных DbManager dbAdmin = new DbManager(); dbAdmin.Load(); //Найходим базу Dbase db = dbAdmin.FindDatabase("demo"); //Заходим в выбранную базу данных var gl = UserContext.DesktopLogin(db.ConnectionString, "root", "root", delegate(string description, double percent) { Console.WriteLine("{0} {1}%", description, (int)(percent * 100)); }); }catch(Exception e) { Console.WriteLine(e.ToString()); Console.ReadKey(); } } } }
Здесь demo — это имя базы данных, а root — логин и пароль пользователя.
Как провести проводку. Этот пример включает все три блока: подключение модулей, список запросов и подключение к базе данных.
// Подключаем необходимые методы using System; using System.Diagnostics; using System.Linq; using Fingrad; using Fingrad.DbManagement; namespace FingradAPI { class Program { //Формируем список запросов static void CommitTran(UserContext gl) { var t = new Transaction(gl.Id); //Выбираем счета t.DebitAccount = Account.CreateByName(gl.Id,"Касса").Id; t.CreditAccount = Account.CreateByName(gl.Id,"Безналичные").Id; //Указываем аналитики var analytic = Fingrad.Analytic.FromName("Компания (ЦФО)", gl.Id); t.SetValue(EditableAnalyticValue.EditOrNew(gl.Id, analytic.Id, "Облако")); //Указываем сумму t.SetAmount((int)GB_CURRENCY_ID.RUR_ID, 10000.0, AmountDirection.Debit); //Сохраняем проводку var storer = new TransactionStorer(gl.Id); storer.Commit(t); if (storer.ExecuteBatch()) return; //Проверяем ошибки foreach (var err in storer.Errors) Console.WriteLine(err.Description); } //Подключаемся к базе данных static void Main(string[] args) { try { //Загружаем список баз данных DbManager dbAdmin = new DbManager(); dbAdmin.Load(); //Найходим базу Dbase db = dbAdmin.FindDatabase("demo"); //Заходим в выбранную базу данных var gl = UserContext.DesktopLogin(db.ConnectionString, "root", "root", delegate(string description, double percent) { Console.WriteLine("{0} {1}%", description, (int)(percent * 100)); }); CommitTran(gl); }catch(Exception e) { Console.WriteLine(e.ToString()); Console.ReadKey(); } } } }
С помощью этого приложения мы подключаемся к базе данных demo с использованием логина и пароля root. Далее мы со счёта Касса переводим на счёт Безналичные сумму 10000 рублей. В проводке мы также указываем аналитику Компания (ЦФО) со значением Облако:
Замечание. Если в значении аналитики есть двойные кавычки, например, ООО "Рассвет", используйте экранирование символов: ООО \"Рассвет\".
Как отредактировать справочник аналитики. Этот пример включает все три блока: подключение модулей, список запросов и подключение к базе данных.
// Подключаем необходимые методы using System; using System.Diagnostics; using System.Linq; using Fingrad; using Fingrad.DbManagement; namespace FingradAPI { class Program { //Формируем список запросов static void UpdateValue(UserContext gl) { //Находим аналитику по имени и колонку "Город" var analytic = Fingrad.Analytic.FromName("бик", 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, "Москва"); //Сохраняем AnalyticValueStorer avs = new AnalyticValueStorer(gl.Id); avs.Push(editableValue); avs.Violation += delegate(object o, AnalyticValueStorerEventArgs e) { //Выводим ошибки на консоль foreach(var d in e.Descriptions) Console.WriteLine(d); }; avs.Store(); } //Подключаемся к базе данных static void Main(string[] args) { try { //Загружаем список баз данных DbManager dbAdmin = new DbManager(); dbAdmin.Load(); //Найходим базу Dbase db = dbAdmin.FindDatabase("demo"); //Заходим в выбранную базу данных var gl = UserContext.DesktopLogin(db.ConnectionString, "root", "root", delegate(string description, double percent) { Console.WriteLine("{0} {1}%", description, (int)(percent * 100)); }); UpdateValue(gl); }catch(Exception e) { Console.WriteLine(e.ToString()); Console.ReadKey(); } } } }
С помощью этого приложения мы подключаемся к базе данных demo с использованием логина и пароля root. Далее мы находим аналитику БИК и присваиваем ей значение 044525225, а её колонке Город присваиваем значение Москва:
Как получить значения справочника аналитики. Этот пример включает все три блока: подключение модулей, список запросов и подключение к базе данных.
// Подключаем необходимые методы using System; using System.Diagnostics; using System.Linq; using Fingrad; using Fingrad.DbManagement; namespace FingradAPI { class Program { //Формируем список запросов static void ListValues(UserContext gl) { //Находим аналитику по имени var analytic = Fingrad.Analytic.FromName("бик", gl.Id); //Получаем все её значения var avf = new Fingrad.Completion.AnalyticValueFilter(gl.Id, 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); //Выводим 1-е 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.Load(); //Найходим базу Dbase db = dbAdmin.FindDatabase("demo"); //Заходим в выбранную базу данных var gl = UserContext.DesktopLogin(db.ConnectionString, "root", "root", delegate(string description, double percent) { Console.WriteLine("{0} {1}%", description, (int)(percent * 100)); }); ListValues(gl); }catch(Exception e) { Console.WriteLine(e.ToString()); Console.ReadKey(); } } } }
С помощью этого приложения мы подключаемся к базе данных demo с использованием логина и пароля root. Далее мы находим аналитику БИК и выводим все её значения на консоль. Также мы находим колонку Город этой аналитики и выводим на консоль первые 10 значений этой колонки.
Как получить список проводок. Этот пример включает все три блока: подключение модулей, список запросов и подключение к базе данных.
// Подключаем необходимые методы using System; using System.Diagnostics; 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.CreateByName(gl.Id, "Касса")); //Ограничиваем по аналитике "Компания (ЦФО)" var company = ep.Constraints.OnAnalytics.AddOrGetConstraint(Fingrad.Analytic.FromName("Компания (ЦФО)", gl.Id).Id); company.SelectAllValues = true; company.SelectDbNull = true; //Получаем выписку var transactions = new ReportGenerator(gl.Id).GetEnumerableExtract(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.Load(); //Найходим базу Dbase db = dbAdmin.FindDatabase("demo"); //Заходим в выбранную базу данных var gl = UserContext.DesktopLogin(db.ConnectionString, "root", "root", delegate(string description, double percent) { Console.WriteLine("{0} {1}%", description, (int)(percent * 100)); }); GetExtract(gl); }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;
Спасибо!
В ближайшее время мы с вами свяжемся.