Developer Referencev1

開発者向けドキュメント

Maskeel Operationsの業務を利用する Operations APIと、会計につなぐ GL API(仕訳)・AR API(債権)・AP API(債務)を、自社のシステム・業務パッケージ・AI エージェントから呼び出すためのリファレンスです。このページだけで、認証から最初の確定までを進められるようにしています。

01基本

ベース URLhttps://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 が付きます
OpenAPIhttps://app.maskeel.biz/openapi.json(全エンドポイントのスキーマ)

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

02認証と API キー

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

方式ヘッダー用途
API キーX-API-Key: mk_…システム連携・バッチ・AI エージェント
ユーザーの JWTAuthorization: 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}
GLgl:events:{read,write} gl:journals:read gl:rules:write gl:exports:write gl:periods:write gl:imports:{read,write} gl:import-definitions:write
AR・APar:documents:{read,write} ar:exports:write ap:documents:{read,write} ap:exports:write

03確認 → 確定

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

  1. POST /v1/{resource}/preview本文は {"action": "…", …}。応答に preview_id・expires_at、操作によって expected(記録される内容)や effects(在庫・売上の戻しなどの影響)が入ります。何も記録しません。
  2. POST /v1/{resource}/confirm確認と同じ本文に preview_id を加え、ヘッダー Idempotency-Key を付けます。成功すると 201 と operation_id・status: "confirmed"。
  3. GET /v1/operations/{operation_id}確定結果をあとから取得します(operations:read)。
確定で返るエラー状態意味
*_PREVIEW_NOT_FOUND404確認が見つからない(別の利用者の確認も含む)
*_PREVIEW_EXPIRED409確認から 30 分を過ぎた
*_PREVIEW_USED409その確認はすでに確定に使われた
*_PREVIEW_MISMATCH409確認と確定の本文が違う
*_STATE_CHANGED409確認のあとに在庫・残高・伝票が変わった。もう一度確認する

* は領域ごとの接頭辞です(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_ERROR422形式・必須項目・未定義の項目
AUTHENTICATION_REQUIRED401認証がない、キーが失効・期限切れ
FORBIDDEN403スコープ・権限(承認者以上が必要など)が足りない
TRIAL_EXPIRED402試用期間が終わっている
*_NOT_FOUND404受注・取引先・確認などが見つからない
PERIOD_CLOSED409締めた月の日付では記録できない
INSUFFICIENT_STOCK APPROVAL_REQUIRED INVALID_ORDER_STATE409業務ルールで拒否
IDEMPOTENCY_CONFLICT409同じキーで別の本文
TRANSACTION_RETRY_REQUIRED503一時的な競合。再送してよい
INTERNAL_ERROR500サーバーの障害

06Operations API リソース

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

領域リソースaction
販売POST /orders(確認なし・201)受注の作成
sales-ordersupdate・approve・reject・cancel・archive・archive_cancelled
shipmentsship
sales-invoicesinvoice
customer-receiptsreceive・cancel
POST /orders/{id}/ship-and-post出荷と売上計上を 1 回で
締め請求・返金closing-invoicesset_method・issue・cancel・receipt・net
customer-settlementsclaim・allocate・apply・plan・approve・pay・reverse ほか
返品return-intakes return-receipts return-replacements return-credit-memos受付・入庫・代替品・クレジットメモ
購買purchase-orderscreate・update・approve・reject・cancel・archive・archive_cancelled
goods-receiptsreceive・close_short
supplier-invoicesmatch・cancel
supplier-paymentspay・reverse
purchase-returnsreturn・debit_memo・reverse
purchase-chargesset・post・allocate
在庫inventory-transferstransfer
inventory-adjustmentsadjust・reverse
stocktakesconfirm(棚卸の開始・実数入力は POST /stocktakes・PUT /stocktakes/{id}/counts)
inventory-openingsconfirm・receive(開始在庫)
inventory-valuations inventory-settings評価方法・承認金額・ロット管理
前受金・前渡金customer-advances supplier-advancesreceive / pay・apply・refund・reverse・reverse_application
製造・原価work-orderscreate・update・cancel・start・issue・return・report・complete・abandon・disassemble
cost-actuals cost-runs process-costs cost-variancesregister・run・reverse
締めperiod-closes period-reopensclose / reopen
マスタitems parties warehouses locationsPOST 作成・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

Maskeel GL APIは、既存ERPの取引を会計へつなぐ中継基盤です。Maskeel Operationsとは独立して利用できます。

会計イベントを受け取り、会社ごとの仕訳ルールで仕訳にして、会計ソフトの取込形式で渡します。GL API は会計ソフトではありません。帳簿の保存・決算書・申告書は会計ソフトで行います。Operations API の業務イベントは、GL連携を有効にし、対象の仕訳ルールを設定すると連携されます。ほかのシステムの取引は、次の 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/preview と POST /v1/gl/event-imports/confirm(列の対応は事前に設定)

イベントの種類

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保存した出力の履歴(取込完了は別途申告。照合は /exports/{export_id}/reconciliation)
PUT /v1/gl/rules仕訳ルール(イベントの種類 × 取引先・品目群・倉庫・部門 → 科目・補助科目・税区分)
POST /v1/gl/period-closes/preview|confirm月の仕訳を確定する(Operation の締めの後。以後その月の仕訳は変わらない)
GET /v1/gl/journals/export?period=…&format=…会計ソフトの取込形式で出力
format出力先
moneyforwardマネーフォワード クラウド会計(仕訳帳インポート)
kanjo_bugyo勘定奉行クラウド・奉行V ERPクラウド(仕訳伝票データ。Shift_JIS、科目・部門はコード)
yayoi弥生会計(弥生インポート形式)
csv json汎用形式(所定の項目)
freee未対応(専用形式)

未対応の形式を指定すると422になります。出力は会計ソフトへの直接API登録ではありません。取込先での動作は導入時に検証します。

09AR API(債権)

Maskeel AR APIは、債権の発生(請求書・返品・値引・赤伝票・残高移行)を「書類」の単位で受け取り、債権管理の機能がある会計ソフトの債権伝票の受入形式で渡します。仕訳はGL APIが作らず、会計ソフトが債権伝票から作ります。入金・消込・残高の管理は会計ソフトが行い、AR APIは入金伝票を渡さず、結果を戻すこともしません。GL APIと同じ基盤(APIキー・Idempotency-Key・エラー・会計ソフトの一覧の写し)の上の、独立したAPIです。

会計ソフトへの渡し方(設定)

PUT /tenants/12/v1/ar/settings
X-API-Key: mk_…
Idempotency-Key: settings-2026-11
{ "version": 0,
  "mode": "gl_with_ap_ar",
  "effective_from": "2026-11",
  "covered_ledgers": ["ar", "ap"],
  "covered_event_types": ["sales.invoiced", "sales.credited"],
  "receivable_account": "売掛金",
  "payable_account": "買掛金" }
  • mode は gl_only(既定。GL APIだけで渡す)か gl_with_ap_ar。設定はAR・AP共通で、/v1/ap/settings は同じものです。変更は承認者以上
  • effective_from の月から、AR・APが受け持つ取引はGL APIが仕訳にしません(GET /v1/gl/events?status=handed_to_ar で確認)。GLで確定済みの月以前や月の途中からの切り替えはできません
  • Maskeel Operationsの取引は受け持つ範囲が決まっています(売上計上・売上取消・売上返品・入金消込・前受金など)。他のシステムからGL APIに直接届くイベントは covered_event_types に種類を書きます(*.reversed も同じ扱い)
  • receivable_account payable_account は債権・債務科目の名前。会計ソフトの勘定科目の写しで照合します

書類を送る

POST /tenants/12/v1/ar/documents
X-API-Key: mk_…
Idempotency-Key: billing:INV000184
{ "type": "invoice",
  "document_date": "2026-11-05", "due_date": "2026-12-31",
  "invoice_no": "INV000184",
  "source": { "system": "billing", "ref": "INV000184" },
  "party": { "code": "C1024", "name": "サンプル商事" },
  "memo": "11月分 保管料",
  "lines": [
    { "kind": "sales", "account": "売上高", "department": "東日本物流",
      "tax_category": "課税売上 10%", "tax_rate": "0.10",
      "amount": "128000", "tax_amount": "12800", "description": "保管料" }
  ] }

201 { "document_id": "…", "type": "invoice", "period": "2026-11", "totals": { "net": "128000", "tax": "12800", "gross": "140800" } }
type内容明細の kind金額の向き
invoice請求書(都度請求は受注ごと、締め請求は締め請求書 1 枚)sales(return discount の行も可)正
credit返品・値引(マイナスの請求書)return discount負(絶対値で送っても負にします)
<type>.reversed赤伝票。元の書類を全額打ち消す(source か reverses_document_id で元を指定)―元の反対
opening_balance残高移行。切り替えの月に、未回収の請求書を 1 件ずつ(税込残高、税額 0)balance正
  • amount は税抜、tax_amount は送信元が確定した税額で必須(税率 0 の行だけ省略可)。AR APIは税額を計算せず、会計ソフトにも再計算させない形(税込金額+税額の直接指定)で出します
  • tax_category は送信元の税区分名。種類(課税売上・非課税売上・輸出・対象外など)と税率を読み取り、会計ソフトの区分コードにします
  • account department は名前で送ります。会計ソフトから書き出した一覧(GL APIの「会計ソフトとの接続」で取り込む写し)と名前で照合し、一致しないものだけ画面で一度選びます。party.code はそのまま会計ソフトの取引先コードになります
  • 同じ (source.system, source.ref, type) は 1 回だけ。同じ内容の再送は 200、内容が違えば 409。訂正は赤伝票と新しい番号の書類で行います。締めた月の日付は 409 PERIOD_CLOSED
  • Maskeel Operationsの売上計上・クレジットメモ・締め請求書と、それぞれの取消は、業務と同じトランザクションで自動的に書類になります(送る必要はありません)

出力と突き合わせ

メソッド・パス内容
GET /v1/ar/documents・/{document_id}書類の一覧・照会(period type status で絞り込み)
GET /v1/ar/check?period=2026-11出力前のチェック。一致しない名前・未登録の取引先・出力できない理由(保存しない)
GET /v1/ar/export?period=2026-11&format=…その月の債権伝票の受入ファイル(保存しない)。format は会計ソフトの受入形式の名前
POST /v1/ar/exports・GET /v1/ar/exports/{export_id}/file保存版の出力とそのファイル(Idempotency-Key)
POST /v1/ar/ledger/{software}/postings会計ソフトから書き出した債権伝票(multipart:file・period)を戻して突き合わせる。書類IDを入れた摘要で照合し、会計ソフトの伝票No.と、記帳確認済み・漏れ・二重・金額違い・未出力を記録
GET /v1/ar/ledger/{software}/postings?period=…その月の最新の突き合わせと、書類ごとの結果
  • 伝票No.は会計ソフトが採番します。受入ファイルの摘要の先頭に Maskeel AR <書類ID> を入れ、突き合わせの手がかりにします
  • 返品・値引は会計ソフトの明細種別で区別し、金額は絶対値で渡します。赤伝票は元の種別のまま金額をマイナスにします
  • AR APIが出した受入ファイルそのもの(伝票No.なし)を戻すと 422 NOT_FROM_LEDGER です
  • 受入形式は会計ソフトごとに定義します。債権管理の機能がない会計ソフト(仕訳だけを受け取るもの)にはGL APIで仕訳を渡します。取込先での動作は導入時に実機で検証します

10AP API(債務)

Maskeel AP APIは、債務の発生(照合済みの仕入先請求書・返品・値引・赤伝票・残高移行)を書類の単位で受け取り、債務管理の機能がある会計ソフトの債務伝票の受入形式で渡します。作りとエンドポイントはAR APIと同じで、パスが /v1/ap/…、スコープが ap:… になります。設定(/v1/ap/settings)はAR APIと共通です。

支払・支払予定・支払方法は渡しません。会計ソフトが精算先(仕入先)に登録した支払条件から支払予定を作り、支払処理と銀行連携を行います。支払の結果を業務システムに戻すこともしません。債務の残高は会計ソフトが正です。

書類を送る

POST /tenants/12/v1/ap/documents
X-API-Key: mk_…
Idempotency-Key: purchasing:V-20261105
{ "type": "supplier_invoice",
  "document_date": "2026-11-05", "due_date": "2026-12-31",
  "invoice_no": "V-20261105",
  "source": { "system": "purchasing", "ref": "SI-0001" },
  "party": { "code": "S0001", "name": "サンプル部品" },
  "lines": [
    { "kind": "purchase", "account": "仕入高", "department": "東日本物流",
      "tax_category": "課税仕入 10%", "tax_rate": "0.10", "amount": "200000", "tax_amount": "20000" },
    { "kind": "purchase", "account": "外注費",
      "tax_category": "課税仕入 10% 非適格", "tax_rate": "0.10", "amount": "50000", "tax_amount": "5000" }
  ] }

201 { "document_id": "…", "type": "supplier_invoice", "period": "2026-11", "totals": { "net": "250000", "tax": "25000", "gross": "275000" } }
type内容明細の kind金額の向き
supplier_invoice仕入先請求書(入荷と照合済みのもの。採用した価格差異も同じ書類に)purchase(return discount の行も可)正
debit_note返品・値引(マイナスの請求書)return discount負
<type>.reversed赤伝票。元の書類を全額打ち消す―元の反対
opening_balance残高移行。切り替えの月に、未払の仕入先請求書を 1 件ずつbalance正
  • invoice_no は仕入先の請求書番号。受入ファイルの摘要に入れます。due_date は書類に残しますが、支払予定として会計ソフトには渡しません
  • 適格請求書のない仕入は tax_category にその旨(「非適格」「80%控除」など)を含めて送ると、会計ソフトのインボイス区分を付けて出します。控除割合の計算は会計ソフトが行い、tax_amount は請求された消費税相当額の全額です
  • Maskeel Operationsの仕入先請求の照合・仕入返品・仕入値引と、それぞれの取消は自動的に書類になります。入荷・諸掛・在庫・原価差異はGL APIが仕訳にします。入荷のたびに債務にはなりません
  • 二重の防止、税額、名前の照合、締めた月、エラーはAR APIと同じです

出力と突き合わせ

メソッド・パス内容
GET /v1/ap/documents・/{document_id}書類の一覧・照会
GET /v1/ap/check?period=…出力前のチェック(保存しない)
GET /v1/ap/export?period=…&format=…・POST /v1/ap/exports債務伝票の受入ファイル(保存しない/保存版)。摘要の先頭は Maskeel AP <書類ID>
POST /v1/ap/ledger/{software}/postings・GET …?period=…会計ソフトから書き出した債務伝票を戻して突き合わせる/その結果

11Slack 連携

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

エンドポイントSlack の設定
POST /integrations/slack/commandsSlash Commands(/maskeel)
POST /integrations/slack/interactionsInteractivity(確定・取消ボタン)
POST /integrations/slack/eventsEvent 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

12ページング・制限

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

13最初の確定まで

  1. 試用環境を作るデモ環境で会社を作り、会社 ID を控えます。
  2. API キーを発行するログインした本人の JWT で POST /v1/api-keys。必要なスコープだけを付けます。
  3. 照会で疎通を確かめるGET /v1/catalog/items?limit=5 が返れば認証は通っています。
  4. 確認してから確定する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 の仕訳ルール、データ移行は初期導入として個別にお見積もりします。→ 導入の進め方と費用・お問い合わせ