Приложение 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;
Спасибо!
В ближайшее время мы с вами свяжемся.