このSDKはこれまで定期的にメンテナンスをしていましたが、2023年4月をもって定期的なメンテナンスを終了しました。 詳細は「freee会計 Public APIに関するSDKのメンテナンス終了、およびスキーマのymlファイルでの公開終了について」をご覧ください。
会計freee APIを C# で利用するための SDK です。
会計freee APIの詳細については、会計API 概要 | freee Developers Community をご参照ください。
最新バージョンとなる 2.x は現在 alpha リリース版となっています。一部の API 呼び出しに問題が発生する可能性があります。
このSDKは、リリースバージョンによって、内部で利用するAPIバージョンが異なります。
- 2.0.0 以降 - 会計freee APIの新しいAPIバージョン(v2020-06-15)に対応しています。
- 2.0.0 未満 - 会計freee APIの古いAPIバージョンを利用しています。古いAPIの提供終了に伴い、2020年12月以降に利用不可となります。
会計freee API C# SDK を利用する手順について記載します。
本SDKを利用する前に下記をご確認ください。
- freee 本体のアカウントがあること
- ASP.NET Core および ASP.NET Core MVC の基礎について理解があること
freee 本体のアカウントは、後述する freeeアプリストアへのアプリケーション登録 で必要になります。
freee API に関しては、チュートリアルガイド をご参照ください。
ASP.NET Core の基礎知識については、ASP.NET Core - ASP.NET のドキュメント | Microsoft Docs をご参照ください。
このリポジトリは以下の環境を想定しています。
- .NET Core 3.1 以上
- dotnet コマンド
- Visual Studio Code
このリポジトリは、.NET Core 3.1 を対象としています。SDK をお持ちでない方は、.NET のダウンロードページ から .NET Core SDK をダウンロードしインストールして下さい。dotnet コマンドは、 .NET Core SDK と同時にインストールされます。
Visual Studio Code をお持ちでない方は、Visual Studio Code ダウンロードページ より入手し、前述の C# エクステンションをインストールしてください。
本 SDK で利用する ClientId および ClientSecret を取得するため、freeeアプリストアの開発者ページでアプリケーションを登録します。
こちらの チュートリアル | freee アプリストア を参考に、アプリケーションを登録して下さい。
本 SDK と接続するには、コールバックURLに、https://localhost:5001/signin-freee を設定します。
本リポジトリをクローンしたのち、Visual Studio Code を開き、統合ターミナルで下記を実行します。
# Visual Studio Code でプロジェクトを開く
cd <freee-accounting-sdk-csharpのクローン先ディレクトリ>
code -r samples\BasicWebAppプロジェクトが開いたら、再び統合ターミナルを開きます。上記で取得した ClientId および ClientSecret を、下記のようにシークレット情報として設定します。
# シークレット情報を追加する
dotnet user-secrets set "Freee:ClientId" "<freee ClientId>"
dotnet user-secrets set "Freee:ClientSecret" "<freee ClientSecret>"シークレットを設定できたら、統合ターミナルで下記を実行し、ブラウザで https://localhost:5001 を開いてください。
dotnet runWelcome と書かれたページが表示されれば正常に起動できています。
右上の Login をクリックすると、freeeアプリストアのアプリケーションに対して認証が行われます。初回は「アプリ連携の開始」という画面が表示されますので、内容を確認し「許可する」ボタンをクリックしてください。
正常に認証されれば、 https://localhost:5001 にリダイレクトされます。上部のバーに Hello <ユーザー名>! と表示され、freeeの情報を取得できていることが確認できます。
ASP.NET Core MVC プロジェクトに、本 SDK を導入する方法を説明します。
ASP.NET Core MVC のプロジェクトを新規に作成する場合は、ASP.NET Core MVC の概要 | Microsoft Docs をご参照ください。
大まかな作業は下記のとおりです。
- プロジェクトファイルを編集する
- freeeアプリストアに登録したアプリケーションの
ClientIdおよびClientSecretをシークレット情報として設定する Startup.csに認証処理を追加するAccountControllerを作成し、 login, logout などの処理を実装する- View に Login, Logout を実装する
まず、プロジェクトファイル <プロジェクト名>.csproj を以下のように、[1][2] を追加して更新します。 <UserSecretsId> には任意の GUID を指定してください。
<PropertyGroup>
<TargetFramework>netcoreapp3.1</TargetFramework>
<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
<!-- [1] ここから -->
<!-- [1] ※ 値には新規に生成したGUIDを指定してください -->
<UserSecretsId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</UserSecretsId>
<!-- [1] ここまでを追加 -->
</PropertyGroup>
<ItemGroup>
...
<!-- [2] ここから -->
<PackageReference Include="Freee.Accounting.Sdk" Version="2.0.0-alpha" />
<PackageReference Include="Freee.OAuth.AspNetCore" Version="2.0.0-alpha" />
<!-- [2] ここまでを追加 -->
</ItemGroup>プロジェクトファイルを編集出来たら、前述の サンプルの実行方法 を参考にシークレット情報を追加します。なお、追加したパッケージは、初回に実行する際に自動でリストアされます。
次に、認証処理を追加します。Startup.cs を以下のように、[1][2][3] を追加して更新します。
// -- [1] ここから ----
using Freee.OAuth.AspNetCore;
using Microsoft.AspNetCore.Authentication.Cookies;
// -- [1] ここまでを追加 ----
// ... 略 ...
namespace BasicWebApp
{
public class Startup
{
// ... 略 ...
public void ConfigureServices(IServiceCollection services)
{
services.Configure<CookiePolicyOptions>(options =>
{
// This lambda determines whether user consent for non-essential cookies is needed for a given request.
options.CheckConsentNeeded = context => true;
options.MinimumSameSitePolicy = SameSiteMode.None;
});
// -- [2] ここから ----
services.AddAuthentication(options =>
{
options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = FreeeAuthenticationDefaults.AuthenticationScheme;
})
.AddCookie()
.AddFreee(options =>
{
options.ClientId = Configuration["Freee:ClientId"];
options.ClientSecret = Configuration["Freee:ClientSecret"];
options.SaveTokens = true;
});
// -- [2] ここまでを追加 ----
services.AddControllersWithViews();
}
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
// The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseCookiePolicy();
app.UseRouting();
// -- [3] ここから ----
app.UseAuthentication();
app.UseAuthorization();
// -- [3] ここまでを追加 ----
app.UseEndpoints(endpoints =>
{
endpoints.MapControllerRoute(
name: "default",
pattern: "{controller=Home}/{action=Index}/{id?}");
});
}アカウントの処理を行うコントローラ AccountController を作成します。Controllers\AccountController.cs を新規作成し、下記を記述します。ここでは、 login、 logout、および me （アカウント情報を表示する）処理を作成します。
using System.Threading.Tasks;
using Freee.Accounting.Api;
using Freee.Accounting.Client;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
namespace BasicWebApp.Controllers
{
public class AccountController : Controller
{
[HttpGet]
public IActionResult Login(string returnUrl = "/")
{
return Challenge(new AuthenticationProperties { RedirectUri = returnUrl });
}
public IActionResult Logout(string returnUrl = "/")
{
return SignOut(new AuthenticationProperties { RedirectUri = returnUrl }, CookieAuthenticationDefaults.AuthenticationScheme);
}
[Authorize]
[HttpGet]
public async Task<IActionResult> Me()
{
var accessToken = await HttpContext.GetTokenAsync("access_token");
var config = new Configuration
{
AccessToken = accessToken
};
var usersApi = new UsersApi(config);
var dealsApi = new DealsApi(config);
var user = await usersApi.GetUsersMeAsync(companies: true);
var deals = await dealsApi.GetDealsAsync(user.User.Companies[0].Id, limit: 5);
ViewBag.Deals = deals.Deals;
return View(user.User);
}
}
}つぎに、View を作成・編集します。
まず、レイアウトに login/logout の機能を追加しましょう。
Views\Shared\_LoginPartial.cshtml を新規作成し、下記を記述します。
<ul class="navbar-nav">
@if (User.Identity.IsAuthenticated)
{
<li class="nav-item">
<a class="nav-link text-dark" asp-action="Me" asp-controller="Account">Hello @User.Identity.Name!</a>
</li>
<li class="nav-item">
<form class="form-inline" asp-action="Logout" asp-controller="Account" asp-route-returnUrl="@Url.Action("Index", "Home", new { area = "" })">
<button type="submit" class="nav-link btn btn-link text-dark">Logout</button>
</form>
</li>
}
else
{
<li class="nav-item">
<a class="nav-link text-dark" asp-action="Login" asp-controller="Account">Login</a>
</li>
}
</ul>Views\Shared\_Layout.cshtml を編集し、<header> に作成した _LoginPartial パーシャルを追加します。
<body>
<header>
<nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-shadow mb-3">
<div class="container">
<a class="navbar-brand" asp-area="" asp-controller="Home" asp-action="Index">MvcSample</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target=".navbar-collapse" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="navbar-collapse collapse d-sm-inline-flex flex-sm-row-reverse">
<!-- [1] ここから -->
<partial name="_LoginPartial" />
<!-- [1] ここまで追加 -->
<ul class="navbar-nav flex-grow-1">
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Index">Home</a>
</li>
<li class="nav-item">
<a class="nav-link text-dark" asp-area="" asp-controller="Home" asp-action="Privacy">Privacy</a>
</li>
</ul>つぎに、アカウント情報を表示する Account/Me のビューを作成します。Views\Account\Me.cshtml を新規作成し、下記を記述してください。
@model Freee.Accounting.Models.UsersMeResponseUser
@{
ViewData["Title"] = "User info";
}
<h1>User info</h1>
<dl>
<dt>@nameof(Model.Email)</dt>
<dd>@Model.Email</dd>
<dt>@nameof(Model.LastName)</dt>
<dd>@Model.LastName</dd>
<dt>@nameof(Model.FirstName)</dt>
<dd>@Model.FirstName</dd>
</dl>
<h2>Deals</h2>
<ul>
@foreach (Freee.Accounting.Models.Deals deal in ViewBag.Deals)
{
<li>
<span>@deal.IssueDate - @deal.Type</span>
<br />
<span>Amount: @deal.Amount</span>
</li>
}
</ul>ここまで更新が完了したら、統合ターミナルで下記を実行し、ブラウザで https://localhost:5001 を開いてください。
dotnet runサンプルと同じように動作すれば正常に導入できました。エラーが出る場合は、サンプルを参考に修正してください。
このプロジェクトへのコントリビューションを歓迎いたします。詳細についてはコントリビューションガイドをご覧ください。
ライセンスについては下記をご参照ください。