API
お使いの基幹システムと、直接つなげます
販売管理、生産管理、独自の社内システム。すでにお使いのシステムから Grid Hub の データを読み書きするための入り口（API）を用意しています。夜間の一括処理のように、 人が画面を見ていない時間帯の連携にお使いいただけます。
AI との接続とは別の入り口です。お使いの AI から会話で操作する場合は、AI から操作するをご覧ください。どちらか一方だけのご利用もできます。
ご利用には別途お申し込みが必要です（月額 4,800 円（税抜））。基本料金には含みません。お申し込みのない会社では、キーを発行しても API は動きません。
取引先や社員へのメール送付は、API からは行えません。API で作れるのは伝票の下書きまでです。発行と送付は画面で人が確認してから押します。
API でできること・できないこと
下の一覧が、現在の版（v1）でご利用いただける範囲です。
できること
- 伝票の一覧と1件の取得（見積・受注・売上・請求・入金・発注・仕入・支払ほか）
- 伝票の下書きの作成と更新
- マスタの一覧と1件の取得（顧客・仕入先・税率・勘定科目・部門ほか。 商品・案件は、それぞれのオプションをご契約の場合）
- 項目（欄）の一覧の取得。絞り込みに使えるキーと演算子を返します
- 前回の続きから読む差分取得
- 項目を指定した絞り込み
API では行えないこと
- 交付（取引先や社員へのメールでの送付）
- 権限グループ・キーの変更
- 「AI への決まりごと」の書き換え
この3つを行う手段は、お申し込みの内容にかかわらずご用意していません。 この定めを変更する場合は、30日前までにお知らせします。
伝票の発行、締め請求、取り消し、書き出し、マスタの登録・更新、および当社から貴社への 通知の送信（Webhook）は、現在の版（v1）の API ではご用意していません。 発行や締め請求などは、画面と AI 接続からご利用いただけます。
「できること」は、キーごとに渡した範囲だけ行えます。キーを発行する画面では、はじめは「読み取り」だけが選ばれています。 API から読めるのは、ご契約の範囲で、そのキーの利用者が画面で開けるマスタです。
毎晩の差分取り込み
前回読んだ続きから取得できます。
続きの位置
応答に次の位置が入ります。次回そのまま渡すと、続きから返します。 続きが無いときは空で返るので、そこで止められます。
並びは更新順
取得している間に他の方が行を追加しても、行が飛ぶことはありません。 更新された行は、更新の順に並び直してもう一度返ります。
取り込みは id で上書きする形にしてください。件数での位置指定は用意していません。
1回あたりの行数
1回の応答は最大 200 行、指定がないときは 50 行です。 総件数は返しません。
取り消した行
取り消した行は一覧から外れます。貴社側に取り込み済みの行は残りますので、 突き合わせの方法をご相談ください。
絞り込み
項目キー、演算子、値の3つを : で繋いで指定します。 1回につき8本までです。
使えるキーと演算子の調べ方
項目の一覧を取得すると、項目キーと、その項目に使える演算子が返ります。 演算子が空の項目は、絞り込みに使えません。
GET /api/v1/fields/documents/<伝票の種類>
効かない条件があったとき
指定した条件のうち1本でも使えないものがあると、行を返さずにお断りします。 絞り込みが効いた結果だけをお返しします。
権限グループで閲覧できない項目では、絞り込めません。存在しない項目を指定したときと 同じ内容でお断りします。
エラーの形
機械が読む符号（code）と、人が読む文 （message）を分けてお返しします。 現在の版（v1）では、一度お配りした符号を変えません。 文は読みやすさのために変えることがあります。
unauthorized（401） | キーが無い、または使えません。理由はお返ししません。 |
|---|---|
not_entitled（403） | API のお申し込みがありません。 |
scope_required（403） | そのキーに渡していない操作です。管理者が画面で範囲を変更できます。 |
forbidden（403） | キーを発行した方の権限で行えない操作です。 |
tenant_readonly（403） | 現在、新しい登録・更新をお受けできない状態です。読み取りはご利用いただけます。 |
not_found（404） | その伝票の種類、またはその行がありません。 |
invalid_request（400） | 指定の形が正しくありません。 |
invalid_filter（400） | 絞り込みの指定が使えません。絞り込みだけを外して取り直すと、 その回の取り込みは続けられます。 |
invalid_cursor（400） | 続きの位置が読めません。位置が読めないときは、その旨をお返しします。 位置を外して1ページ目から取り直せます。 |
conflict（409） | 読み込んでから書き込むまでの間に、他の方が更新しています。 読み直してから送り直せます。 |
idempotency_mismatch（409） | 同じ依頼番号で、前回と違う内容が届きました。 |
in_progress（409） | 同じ依頼番号の1本目を処理しています。しばらく待ってから送り直せます。 |
internal（500 / 503） | 当社側の事情でお応えできませんでした。時間をおいて送り直せます。 |
用意のない方式（POST を受けない場所への POST など）でお呼びいただいた場合は、 405 が返ります。この応答には上の符号が付きません。
二重登録を防ぐしくみ
| 依頼番号が必須 | 書き込みには、1回の依頼ごとの番号を付けていただきます。 同じ依頼番号で送り直された場合は、下書きは1枚のままです。 |
|---|---|
| 同じ番号の2回目 | 1回目の結果をそのままお返しします。 |
| 版の指定が必須 | 更新には、読み込んだ時点の版をお付けいただきます。 人が画面で直した内容を、あとから届いた依頼が上書きすることはありません。 |
| 発行済みの伝票 | API からも書き換えられません。訂正は、訂正版または赤伝で行います。 |
API の操作でも安全に
| キーごとの範囲と期限 | キーは画面で発行します。キーごとに操作の範囲と有効期限を設定でき、 いつでも失効させられます。 |
|---|---|
| 会社ごとのキー | 1つのキーから複数の会社のデータを読むことはできません。 |
| 利用者の権限の範囲内 | 扱えるのは、キーに設定した利用者が画面で閲覧できる範囲です。 どの利用者として動かすかは、キーを発行するときに管理者が選びます。 項目ごとの権限も適用されます。 |
| 監査ログに記録 | API からの操作も監査ログに記録されます。監査ログは追加されるだけで、 書き換えはできません。更新・削除の権限は、当社を含め誰にも与えていません。 |
| 版の指定はパスに | /api/v1/ のように、版を URL に含めます。 貴社の設定に残る形で固定できます。 |
ご利用の流れ
キーの発行
管理者が画面でキーを発行し、操作の範囲と有効期限を設定します。 キーは発行時に一度だけ表示します。
接続の確認
仕様の詳細と、貴社の連携内容に合わせた進め方をご案内します。 ご要望は、今後の開発の検討材料として承ります。
当社は、Grid Hub の提供に必要な範囲で、お客様からの委託を受けてお客様の個人データを取り扱います。 当社の立場と取り扱いの範囲は、プライバシーポリシーに定めるとおりです。 API を通じて貴社のシステムに取り込まれた後のお取り扱いは、貴社にて行っていただきます。 個人情報を含むデータを取り込まれる場合は、貴社の社内規程をご確認ください。