開発者向けドキュメント — Maskeel Operation API ／ GL API

01基本

ベース URL	`https://app.maskeel.biz`
パス	`/tenants/{tenant_id}/v1/...`（`tenant_id` は会社 ID。正の整数）
形式	JSON（UTF-8）。項目は snake_case。定義にない項目を送ると `422 VALIDATION_ERROR`
金額	10 進数の文字列を推奨（例 `"1250.00"`）。小数は 2 桁まで
日付	`YYYY-MM-DD`。業務日は日本時間。省略すると当日
キャッシュ	v1 の応答には `Cache-Control: no-store` が付きます
OpenAPI	`https://app.maskeel.biz/openapi.json`（全エンドポイントのスキーマ）

Maskeel は業務イベントを記録します。仕訳の起票・勘定科目の判断は GL API の仕訳ルールで行います。送金・振込データの作成は行いません。

02認証と API キー

次のどちらか 1 つを送ります。両方、または同じヘッダーを 2 つ送ると 422 です。

方式	ヘッダー	用途
API キー	`X-API-Key: mk_…`	システム連携・バッチ・AI エージェント
ユーザーの JWT	`Authorization: Bearer <JWT>`	自社アプリから利用者本人として呼ぶ。API キーの発行・失効

API キーの発行

本人の JWT で発行します。キーは 1 つの会社・1 人の利用者に属し、その利用者の権限の範囲でだけ動きます。秘密の値は発行時の応答にだけ含まれ、サーバーにはハッシュだけを保存します。

POST /tenants/12/v1/api-keys
Authorization: Bearer eyJ…
{ "name": "logi-erp nightly",
  "scopes": ["sales:orders:read", "sales:orders:ship"],
  "expires_in_days": 90 }

201 { "key_id": "…", "api_key": "mk_…", "scopes": [ … ], "expires_at": "…" }

name 1〜80 文字、scopes 1〜10 個、expires_in_days 1〜90 日（既定 30）
一覧は GET /v1/api-keys（view=self|tenant）、失効は POST /v1/api-keys/{key_id}/revoke
呼び出しのたびに、キーの利用者がまだ会社に所属し、権限を持っているかを確かめます
キーをソースコード・ログ・チャットに残さないでください。漏れたら直ちに失効させてください

スコープ

キーには必要な操作だけを与えます。足りないと 403 FORBIDDEN です。

領域	スコープ
共通	`operations:read`
販売	`sales:orders:{create,read,update,approve,cancel,ship,invoice,receipt,receipt_cancel}` `sales:ship_and_post` `sales:catalog:read`
締め請求・返金	`sales:closing_invoices:{read,write}` `sales:customer_refunds:{read,write}` `sales:customer_credits:read`
返品	`sales:returns:{create,read}` `sales:return_intakes:{create,read}` `sales:return_receipts:{read,write}` `sales:return_replacements:{create,read}` `sales:return_credit_memos:{create,read}`
購買	`purchasing:{orders,receipts,invoices,payments,returns,charges,advances}:{read,write}`
在庫	`inventory:read` `inventory:{transfers,adjustments,stocktakes,settings,valuation}:write`
前受金	`sales:advances:{read,write}`
製造・原価	`manufacturing:work-orders:{read,write}` `manufacturing:costing:{read,write}`
締め	`periods:read` `periods:close:write` `periods:reopen:write`
マスタ	`masters:{read,write}`
GL	`gl:events:{read,write}` `gl:journals:read` `gl:rules:write` `gl:periods:write`

03確認 → 確定

残高を動かす操作は、すべて 2 段階です。確認（preview）では確定と同じ業務ロジックを実行して取り消すので、在庫不足・与信・締め済みなど確定で拒否される条件は、確認の時点で返ります。

POST /v1/{resource}/preview本文は {"action": "…", …}。応答に preview_id・expires_at、操作によって expected（記録される内容）や effects（在庫・売上の戻しなどの影響）が入ります。何も記録しません。
POST /v1/{resource}/confirm確認と同じ本文に preview_id を加え、ヘッダー Idempotency-Key を付けます。成功すると 201 と operation_id・status: "confirmed"。
GET /v1/operations/{operation_id}確定結果をあとから取得します（operations:read）。

確定で返るエラー	状態	意味
`*_PREVIEW_NOT_FOUND`	404	確認が見つからない（別の利用者の確認も含む）
`*_PREVIEW_EXPIRED`	409	確認から 30 分を過ぎた
`*_PREVIEW_USED`	409	その確認はすでに確定に使われた
`*_PREVIEW_MISMATCH`	409	確認と確定の本文が違う
`*_STATE_CHANGED`	409	確認のあとに在庫・残高・伝票が変わった。もう一度確認する

* は領域ごとの接頭辞です（SALES_・PURCHASING_・INVENTORY_・PERIOD_・ADVANCE_・COST_・MASTER_・GL_ など）。

04Idempotency-Key

記録する要求には Idempotency-Key を付けます。通信が切れたら、同じキー・同じ本文で送り直してください。二重には記録されません。

使える文字は英数字と _ . : -、1〜128 文字。UUID や「連携元のシステム名＋伝票番号」がおすすめです
キーは会社・利用者・操作ごとに保存されます
同じキー・同じ本文の再送には最初の応答を返し、Idempotency-Replayed: true が付きます
同じキーで本文が違うと 409 IDEMPOTENCY_CONFLICT（POST /v1/orders では IDEMPOTENCY_KEY_REUSED）

05エラー

{ "error": { "code": "INSUFFICIENT_STOCK", "message": "在庫が不足しています（商品A：必要 5、在庫 3）", "retryable": false } }

retryable: true のときは Retry-After ヘッダーの秒数だけ待って、同じ Idempotency-Key で再送します。message は利用者にそのまま見せられる日本語です。

コード	状態	意味
`VALIDATION_ERROR`	422	形式・必須項目・未定義の項目
`AUTHENTICATION_REQUIRED`	401	認証がない、キーが失効・期限切れ
`FORBIDDEN`	403	スコープ・権限（承認者以上が必要など）が足りない
`TRIAL_EXPIRED`	402	試用期間が終わっている
`*_NOT_FOUND`	404	受注・取引先・確認などが見つからない
`PERIOD_CLOSED`	409	締めた月の日付では記録できない
`INSUFFICIENT_STOCK` `APPROVAL_REQUIRED` `INVALID_ORDER_STATE`	409	業務ルールで拒否
`IDEMPOTENCY_CONFLICT`	409	同じキーで別の本文
`TRANSACTION_RETRY_REQUIRED`	503	一時的な競合。再送してよい
`INTERNAL_ERROR`	500	サーバーの障害

06Operation API リソース

特記のないものは POST /tenants/{tenant_id}/v1/{リソース}/preview と …/confirm の組です。本文の action で操作を選びます。

領域	リソース	action
販売	`POST /orders`（確認なし・201）	受注の作成
	`sales-orders`	update・approve・reject・cancel・archive・archive_cancelled
	`shipments`	ship
	`sales-invoices`	invoice
	`customer-receipts`	receive・cancel
	`POST /orders/{id}/ship-and-post`	出荷と売上計上を 1 回で
締め請求・返金	`closing-invoices`	set_method・issue・cancel・receipt・net
締め請求・返金	`customer-settlements`	claim・allocate・apply・plan・approve・pay・reverse ほか
返品	`return-intakes` `return-receipts` `return-replacements` `return-credit-memos`	受付・入庫・代替品・クレジットメモ
購買	`purchase-orders`	create・update・approve・reject・cancel・archive・archive_cancelled
	`goods-receipts`	receive・close_short
	`supplier-invoices`	match・cancel
	`supplier-payments`	pay・reverse
	`purchase-returns`	return・debit_memo・reverse
	`purchase-charges`	set・post・allocate
在庫	`inventory-transfers`	transfer
	`inventory-adjustments`	adjust・reverse
	`stocktakes`	confirm（棚卸の開始・実数入力は `POST /stocktakes`・`PUT /stocktakes/{id}/counts`）
	`inventory-openings`	confirm・receive（開始在庫）
	`inventory-valuations` `inventory-settings`	評価方法・承認金額・ロット管理
前受金・前渡金	`customer-advances` `supplier-advances`	receive / pay・apply・refund・reverse・reverse_application
製造・原価	`work-orders`	create・update・cancel・start・issue・return・report・complete・abandon・disassemble
製造・原価	`cost-actuals` `cost-runs` `process-costs` `cost-variances`	register・run・reverse
締め	`period-closes` `period-reopens`	close / reopen
マスタ	`items` `parties` `warehouses` `locations`	`POST` 作成・`PATCH /{id}` 更新（`version` 必須）・`POST /{id}/archive`。重要な項目は `master-changes` で確認→確定。BOM・工程は `PUT items/{id}/bom\|routing`

# 例：入金を記録する（都度請求の得意先）
POST /tenants/12/v1/customer-receipts/preview
{ "action": "receive", "party_id": 5, "amount": "11000.00", "order_id": 19, "business_date": "2026-09-30" }

07照会 API

対象	GET
品目・得意先の検索	`/v1/catalog/items` `/v1/catalog/customers`（`q`・`after_id`・`limit`≤100）
マスタ	`/v1/{items\|parties\|warehouses\|locations}`・`/{id}`・`items/{id}/bom`・`items/{id}/routing`
在庫	`/v1/inventory/items`（`as_of`・`warehouse_id`）・`/v1/inventory/items/{id}/moves`
購買	`/v1/purchase-orders`・`/{id}`・`/{id}/pdf`・`/v1/payables`・`/v1/suppliers/{party_id}/payables`
締め請求・返品	`/v1/closing-invoices`・`/{id}/pdf`・`/v1/return-intakes`・`/v1/customer-credits/{party_id}`
製造・原価	`/v1/work-orders`・`/v1/work-in-process`・`/v1/cost-reports/{manufacturing\|variances\|direct-costing}`
締め	`/v1/periods`・`/v1/periods/{month}`・`/v1/periods/{month}/checks`
確定結果	`/v1/operations/{operation_id}`

08GL API

会計イベントを受け取り、会社ごとの仕訳ルールで仕訳にして、会計ソフトの取込形式で渡します。GL API は会計ソフトではありません。帳簿の保存・決算書・申告書は会計ソフトで行います。Operation API で確定した業務イベントは自動で GL API に届きます。ほかのシステムの取引は、次の events で送ります。

会計イベントを送る

POST /tenants/12/v1/gl/events
X-API-Key: mk_…
Idempotency-Key: logi-erp:INV-000184
{ "type": "sales.invoiced",
  "occurred_on": "2026-09-30",
  "source": { "system": "logi-erp", "ref": "INV-000184" },
  "party": { "code": "C1024" },
  "segments": { "department": "東日本物流", "warehouse": "WH-02" },
  "lines": [
    { "amount": "128000", "tax_rate": "0.10", "tax_amount": "12800", "item_group": "保管料" }
  ] }

201 { "event_id": "…", "status": "journalized", "journal_id": "…" }

Idempotency-Key は必須です。連携元のシステム名と伝票番号をつなげると、同じ伝票の二重送信を確実に防げます
インボイスの税額は tax_amount で送った額をそのまま使い、GL API で再計算しません（省略時は請求書・税率ごとに 1 回端数処理）
仕訳ルールに当てはまらないイベントは status: "unmapped" で保留され、ルールを追加すると仕訳になります
締めた月の日付のイベントは 409 PERIOD_CLOSED。訂正は取消イベント（*.reversed）と新しいイベントで行います
CSV で送る場合は POST /v1/gl/event-imports（列の対応は事前に設定）

イベントの種類

type	内容
`sales.shipped` `sales.invoiced` `sales.receipt`	出荷（売上原価仮勘定）・売上計上・入金
`purchase.received` `purchase.invoice_matched` `purchase.payment`	入荷（入庫請求仮勘定）・仕入先請求の照合・支払
`inventory.adjusted` `inventory.revalued`	在庫調整・評価替え
`manufacturing.completed` `manufacturing.variance`	完成・原価差異
`advance.received` `advance.paid` `advance.applied`	前受金・前渡金
`*.reversed`	上記の取消

仕訳・照合・出力

メソッド・パス	内容
`GET /v1/gl/events`・`/{event_id}`	受け取ったイベントと仕訳の状態（`status=unmapped` で保留分だけ）
`GET /v1/gl/journals?period=2026-09`	月の仕訳
`GET /v1/gl/exports?period=2026-09`	会計ソフトへ渡した履歴と、受け取ったイベントとの件数・金額の照合
`PUT /v1/gl/rules`	仕訳ルール（イベントの種類 × 取引先・品目群・倉庫・部門 → 科目・補助科目・税区分）
`POST /v1/gl/period-closes/preview\|confirm`	月の仕訳を確定する（Operation の締めの後。以後その月の仕訳は変わらない）
`GET /v1/gl/journals/export?period=…&format=…`	会計ソフトの取込形式で出力

format	出力先
`kanjo_bugyo`	勘定奉行（仕訳伝票の取込形式）
`freee`	freee会計
`moneyforward`	マネーフォワードクラウド会計（仕訳インポート）
`yayoi`	弥生会計（仕訳日記帳）
`csv` `json`	列を指定した汎用形式

09Slack 連携

Slack は Operation API と同じ業務ロジックを呼ぶ入口です。設定手順はトップページにあります。

エンドポイント	Slack の設定
`POST /integrations/slack/commands`	Slash Commands（`/maskeel`）
`POST /integrations/slack/interactions`	Interactivity（確定・取消ボタン）
`POST /integrations/slack/events`	Event Subscriptions（`file_shared`。PDF の取込）

Slack の署名（X-Slack-Signature）と時刻（前後 5 分以内）を検証します
利用者の紐付けは本人の JWT で POST /v1/slack/link-code → Slack で /maskeel link コード（10 分・1 回限り）。状態は GET /v1/slack/link、解除は POST /v1/slack/unlink

10ページング・制限

一覧は limit と、マスタ・カタログでは after_id（前ページの最後の ID）で進めます。上限は一覧ごとに 100〜1000 件です
現在、v1 にリクエスト数の上限は設けていません。初回の大量移行や毎分の連続送信は、事前にご相談ください
本文の大きさは要求ごとに制限があります（Slack の受付は 16KB まで）
外部への通知（Webhook）は提供していません。確定結果は確定の応答か GET /v1/operations/{id}、GL の状態は GET /v1/gl/events で取得します

11最初の確定まで

試用環境を作るデモ環境で会社を作り、会社 ID を控えます。
API キーを発行するログインした本人の JWT で POST /v1/api-keys。必要なスコープだけを付けます。
照会で疎通を確かめるGET /v1/catalog/items?limit=5 が返れば認証は通っています。
確認してから確定するPOST /v1/orders で受注を作り、shipments を preview → confirm。応答の operation_id を保存します。

# curl での例
curl -s https://app.maskeel.biz/tenants/12/v1/shipments/preview \
  -H "X-API-Key: $MASKEEL_API_KEY" -H "Content-Type: application/json" \
  -d '{"action":"ship","order_id":19}'

curl -s https://app.maskeel.biz/tenants/12/v1/shipments/confirm \
  -H "X-API-Key: $MASKEEL_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"action":"ship","order_id":19,"preview_id":"…"}'

連携の設計からご相談になる場合　既存システムとの接続、GL API の仕訳ルール、データ移行は初期導入として個別にお見積もりします。→ 導入の進め方と費用・お問い合わせ