サンプルフーズ専用API

直営5店舗のPOS・自社ECカート・在庫管理システムに散らばっていた数字を、 御社の集計ルールで整えたうえで取り出せる窓口です。 呼び出せばその場で、いつも同じ形で返ります。

このAPIについて

これまで担当の方が毎月おこなっていた「店舗別の売上をシートに集めて、ECの数字と突き合わせて、返品と値引きを差し引く」という手順を、そのまま実装しています。 取り出した時点で計算は終わっています。受け取った側で足し引きする必要はありません。

つないでいる情報源

情報源	つなぎ方	取り込む内容	取り込む間隔
自社ECカート	API連携	注文・返品・送料	15分ごと
在庫管理システム	API連携	商品マスタ・在庫数	15分ごと
店舗POS	スプレッドシート	日次の売上・客数・値引き	毎日 5:00（前日ぶん）

応答は即時です。呼び出すとその場で返ります。待ち時間はありません。いっぽうで中身の鮮度は、情報源の更新に追随します—— API連携の2つは15分以内、店舗POSはシートに書かれた前日ぶんまでです。 いつ時点の数字かは、応答の sources で確認できます。

用語について。このドキュメントの「チャネル」は、店舗（store）と EC（ec）の2つを指します。御社の社内用語にそろえてあります。

認証

すべてのリクエストに、お渡ししたAPIキーを X-OpsEngine-Key ヘッダーで付けてください。

リクエスト例

curl https://sample-foods.api.opsengine.cloud/v1/sales/monthly?month=2026-07 \
  -H "X-OpsEngine-Key: oe_live_9f2c...（お渡ししたキー）"

キーの取り扱い。キーは社外に出さないでください。ブラウザで動くページに直接書くと第三者に読まれます。サーバー側か、Google Apps Script のスクリプトプロパティに保存してお使いください。 漏れた可能性があるときは、連絡をいただければその場で無効化して発行し直します。

共通仕様

項目	内容
ベースURL	`https://sample-foods.api.opsengine.cloud`
形式	JSON（UTF-8）
日付・時刻	日本時間（JST）。日付は `YYYY-MM-DD`、時刻は ISO 8601
金額	税込・円。小数点なしの整数
件数の多い応答	`limit` と `offset` で分割。既定 `limit=100`・最大 `1000`

応答には必ず generated_at（応答をつくった時刻）と sources（情報源ごとに、いつ取り込んだ数字か）が入ります。 画面や資料に出すときは、この日時もあわせて表示すると行き違いが起きません。

名前	型	説明
`generated_at`	string	この応答をつくった時刻（JST）
`sources[].name`	string	情報源の名前
`sources[].synced_at`	string	その情報源から最後に取り込んだ時刻

★JSONを見た直後の「で、どう使うのか」に答える節。画面はHTMLで組んだ再現（スクリーンショットではない） -->

オプスエンジンコネクト（以下OC）から使う

OCとは

curl やプログラムを書かなくても、OCから直接このAPIを呼び出せます。 取り出した結果は、いつものスプレッドシートにそのまま届きます。

取り出すと、この表が届きます

JSONのままではなく、そのまま読める表の形で届きます。 列名は御社がふだん使っている言葉に置き換えられるので、そのまま会議資料に貼れます。

SF2026年7月_店舗別売上 GET /v1/sales/monthly

	store_id店舗コード	name店舗名	net_sales売上高	orders注文数	ch_store店舗の売上	ch_ecECの売上
1	sf-yokohama	横浜店	14,820,300	3,842	12,104,500	2,715,800
2	sf-kamakura	鎌倉店	9,376,200	2,417	8,940,100	436,100
3	sf-fujisawa	藤沢店	8,204,900	2,106	7,655,300	549,600
4	sf-ofuna	大船店	7,912,600	2,033	7,488,200	424,400
5	sf-zushi	逗子店	7,899,600	2,082	7,441,900	457,700

列名の上段（灰色）はAPIが返す名前、下段が置き換えた名前。1行が1店舗で、取り出した時点で計算は終わっています（返品・値引きは差し引き済み）

どの表も、一覧から選ぶだけ

このAPIが返せる表は、OCの一覧にすべて並びます。使いたい表を選んで押すだけで取り出せます。

OCオプスエンジンコネクト ── 取り出せる表 4件

月次の売上まとめ店舗別・チャネル別／返品と値引きは差し引き済み取り出す
日次の売上日ごとの売上と注文数／最大62日取り出す
在庫のスナップショット15分ごとに同期／直近7日の出荷数つき取り出す
調整（返品・値引き）の登録シートに書いた調整を、まとめて送る送る

このAPIのエンドポイントは、すべてこの一覧に並びます

一度決めたら、あとは繰り返すだけ

定期実行・列名の言い換え・取り出す条件は、名前をつけて保存できます。翌月からは呼び出すだけ。担当が代わっても同じ表が出ます。

OC設定 ── 月次の売上まとめ保存済み

定期実行毎月 1日 6:00前月ぶんを取得
列名の言い換え net_sales売上高 orders注文数 ch_ecECの売上
保存した条件先月・店舗別今年度・チャネル別横浜店のみ
出す先売上管理シート／「月次」タブ

保存した条件は、次からは名前を選ぶだけで呼び出せます

届いたあとの手直しも、指示だけ

並べ替え・絞り込み・文字列の入れ替えは、OC側で指示できます。 関数を書く必要はありません。

OC加工 ── 月次の売上まとめ 3件の指示

並べ替え売上高が多い順に
絞り込みECの売上が 500,000 以上の店舗だけ
文字列の入れ替え店舗コードの sf- を消して、店名だけに

加工まえ

sf-kamakura	436,100
sf-yokohama	2,715,800
sf-fujisawa	549,600

加工あと

yokohama	2,715,800
fujisawa	549,600

3つの指示を順に当てた結果。指示は保存され、次の月も同じ形で出ます

OCをお使いでない場合も、このAPIはそのままご利用いただけます。上の01の表は、curl や Google Apps Script からでも同じ内容で取得できます。 それぞれの指定と応答は、次の「エンドポイント」に載せています。

OC この画面のプロダクトについてオプスエンジンコネクトを見る

AIから使う

このリファレンスは、AIに渡す説明書としてもそのまま使えます。 項目の意味・単位・取れる範囲が書いてあるので、 ふだんの言葉で聞くだけで、AIが正しい窓口と項目を選べます。

書いてあるから、できること

このリファレンスに書いてあるもの	それでAIができるようになること
項目の意味net_sales は「返品・値引きを差し引いた売上」	「実質の売上を教えて」と聞かれて、正しい列を選べます。書いていなければ、似た名前の列から当てずっぽうに選びます
単位と型金額は税込・円・整数／日時はJST	「万円でまとめて」と言われても、換算や日付の読み違いが起きません
取れる項目の一覧4つの窓口と、それぞれの指定	一覧にないことを聞かれたら「このAPIでは取れません」と答えられます。もっともらしい作り話をしません
いつの数字かgenerated_at と sources	「これは○時点の数字です」と添えられます。古い数字を最新のように言い切ることがなくなります
エラーの意味状態コードと、どうすればよいか	失敗したとき、理由と次の手順を説明できます。黙って空の結果を返しません
鍵のしくみ用途ごとに発行・失効できる	AIに渡す鍵を読み取りだけ・必要な窓口だけに絞れます。見せたくない情報は、はじめから届きません

たとえば、こう動きます

SF社内のAIアシスタントこのリファレンスを渡した状態

担当の方先月、ECの売上がいちばん伸びた店舗は？

AI GET/v1/sales/monthly?month=2026-07&group=store
藤沢店です。ECの売上は 549,600円で、店舗の売上（7,655,300円）に対して前月より伸びていました。 ※ この数字は 2026-08-09 14:30 に取り込んだものです（ec_cart）

担当の方店舗ごとの客単価も出せる？

AI 売上高と注文数から計算できます。ただし客数はこのAPIにはありませんので、「1注文あたり」の金額になります。それでよければ出します。

2つ目の答えが要点です。無いものを無いと言えるのは、取れる項目がリファレンスに書いてあるからです

使い方はかんたんです。このページをそのままAIに読み込ませるか、リンクを渡してください。APIキーは渡さず、実際の呼び出しはOCや社内の仕組みから行うのが安全です。

エンドポイント

ここから、取り出せる窓口をひとつずつ説明します。

以下は見本です。窓口の名前・項目・数値はすべて架空のもので、この4つが決まった仕様というわけではありません。 実際には、御社がいま毎月つくっている表をもとに、必要な窓口と項目を決めてから作ります。

月次の売上まとめ

GET/v1/sales/monthly

指定した月の売上を、店舗別・チャネル別にまとめて返します。返品と値引きは差し引き済みです。

指定できるもの

名前	型	必須	説明
`month`	string	必須	対象の月。`2026-07` の形式
`group`	string	任意	まとめ方。`store`（店舗別・既定）／ `channel`（チャネル別）／ `total`（合計のみ）
`store_id`	string	任意	特定の店舗にしぼる。例：`sf-yokohama`

リクエスト例

curl "https://sample-foods.api.opsengine.cloud/v1/sales/monthly?month=2026-07&group=store" \
  -H "X-OpsEngine-Key: $KEY"

レスポンス例

{
  "month": "2026-07",
  "group": "store",
  "generated_at": "2026-08-09T14:37:02+09:00",
  "sources": [                       // いつ時点の数字か
    { "name": "ec_cart",  "synced_at": "2026-08-09T14:30:00+09:00" },
    { "name": "store_pos", "synced_at": "2026-08-09T05:00:00+09:00" }
  ],
  "total": {
    "net_sales": 48213600,      // 返品・値引きを差し引いた売上
    "orders": 12480,
    "returns": 316400
  },
  "stores": [
    {
      "store_id": "sf-yokohama",
      "name": "横浜店",
      "net_sales": 14820300,
      "orders": 3842,
      "channels": {
        "store": 12104500,
        "ec": 2715800
      }
    },
    {
      "store_id": "sf-kamakura",
      "name": "鎌倉店",
      "net_sales": 9376200,
      "orders": 2417,
      "channels": {
        "store": 8940100,
        "ec": 436100
      }
    }
  ]
}

返ってくるもの

名前	型	説明
`generated_at`	string	この応答をつくった時刻（JST）
`sources[]`	array	情報源ごとの取り込み時刻。数字の鮮度はここで判断できます
`total.net_sales`	integer	全店・全チャネルの合計売上（返品・値引き差し引き後）
`total.returns`	integer	差し引いた返品額の合計
`stores[].store_id`	string	店舗の識別子。社内の店舗コードと同じ
`stores[].channels`	object	チャネル別の内訳。`store` と `ec`

日次の売上

GET/v1/sales/daily

指定した期間の売上を、日ごとに返します。日報や週次の振り返りに使えます。

名前	型	必須	説明
`from`	string	必須	開始日。`2026-07-01`
`to`	string	必須	終了日（その日を含む）。開始日から最大62日
`store_id`	string	任意	特定の店舗にしぼる

レスポンス例

{
  "from": "2026-07-01",
  "to": "2026-07-03",
  "generated_at": "2026-08-09T14:37:02+09:00",
  "days": [
    { "date": "2026-07-01", "net_sales": 1584200, "orders": 412 },
    { "date": "2026-07-02", "net_sales": 1493700, "orders": 388 },
    { "date": "2026-07-03", "net_sales": 1802400, "orders": 465 }
  ]
}

在庫のスナップショット

GET/v1/inventory

商品ごとの在庫数を返します。在庫管理システムとは15分ごとに同期しているので、ほぼ現在の数字です。発注の判断に使えるよう、直近7日の出荷数も添えています。

名前	型	必須	説明
`store_id`	string	任意	店舗にしぼる。省略時は全店の合計
`low_stock`	boolean	任意	`true` で、設定した下限を割っている商品だけ返す
`limit`	integer	任意	返す件数。既定 `100`・最大 `1000`

レスポンス例

{
  "generated_at": "2026-08-09T14:00:07+09:00",
  "count": 2,
  "items": [
    {
      "sku": "SF-0142",
      "name": "三崎まぐろ漬け丼の素 2食",
      "stock": 38,
      "low_stock_threshold": 50,   // 下限を割っている
      "shipped_7d": 126
    },
    {
      "sku": "SF-0207",
      "name": "湘南しらす沖漬け 130g",
      "stock": 214,
      "low_stock_threshold": 80,
      "shipped_7d": 92
    }
  ]
}

調整（返品・値引き）の登録

POST/v1/adjustments

POSやECに乗らない調整——電話での返品対応や、催事での特別値引きなど——を登録します。登録すると、その月の売上まとめに自動で反映されます。

送るもの

名前	型	必須	説明
`date`	string	必須	調整を計上する日。`2026-07-18`
`store_id`	string	必須	対象の店舗
`type`	string	必須	`return`（返品）／ `discount`（値引き）／ `other`
`amount`	integer	必須	金額（円）。売上から差し引く額を正の数で
`memo`	string	任意	経緯のメモ。あとから見返すときの手がかりに（200文字まで）

リクエスト例

curl -X POST https://sample-foods.api.opsengine.cloud/v1/adjustments \
  -H "X-OpsEngine-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-07-18",
    "store_id": "sf-yokohama",
    "type": "return",
    "amount": 4800,
    "memo": "電話での返品対応（配送中の破損）"
  }'

レスポンス例（201 Created）

{
  "adjustment_id": "adj_7Kd2mQ",
  "date": "2026-07-18",
  "store_id": "sf-yokohama",
  "type": "return",
  "amount": 4800,
  "applied_to": "2026-07",        // この月のまとめに反映
  "created_at": "2026-08-09T14:22:31+09:00"
}

締めた月には登録できません。月次の締め（翌月5日）を過ぎた月を date に指定すると 409 を返します。締め後の訂正が必要なときは、ご連絡ください。

エラー

うまくいかなかったときは、次の形で理由が返ります。画面に出すときは message をそのまま表示して差し支えありません。

エラーの形

{
  "error": {
    "code": "invalid_month",
    "message": "month は 2026-07 の形式で指定してください。"
  }
}

状態	コード	意味と、どうすればよいか
200	`—`	成功
201	`—`	登録に成功（POSTのみ）
400	`invalid_month` ほか	指定の形式が違います。`message` に正しい形式が書いてあります
401	`unauthorized`	APIキーが違うか、付いていません。ヘッダー名の綴りをご確認ください
404	`store_not_found`	その `store_id` は登録されていません。店舗が増えたときはご連絡ください
409	`period_closed`	締めた月への登録です。訂正が必要なときはご連絡ください
429	`rate_limited`	呼び出しが多すぎます。`Retry-After` 秒だけ待って、もう一度お試しください
503	`upstream_unavailable`	情報源の側が一時的に応答していません。こちらで検知して対応します。数分おいて再実行してください

利用の上限

項目	上限	備考
呼び出し回数	60回 / 分	超えると `429`。定期実行なら十分な余裕があります
1回に返す件数	1,000件	`limit` と `offset` で分けて取得してください
取得できる期間	過去36か月	それ以前は、必要になった時点でご相談ください

止まっていないかは、こちらで見ています。 応答しない・遅いといった異常はオプスエンジン側で検知して対応します。気づいたことがあれば、ご連絡いただければ確認します。

更新履歴

2026-08-01v1.2 月次まとめにチャネル別の内訳（channels）を追加しました。
2026-06-15v1.1 在庫のスナップショットと、直近7日の出荷数を追加しました。
2026-05-22v1.0.1 催事の値引きが二重に差し引かれていた不具合を直しました。5月分から反映済みです。
2026-05-10v1.0 提供を開始しました。月次・日次の売上と、調整の登録に対応しています。

問い合わせ先

項目を増やしたい、まとめ方を変えたい、情報源を足したい—— いずれも月額の中でご相談いただけます。 「こういう表がほしい」という形でお伝えいただければ、こちらで実装します。

担当：オプスエンジン株式会社
連絡先：info@opsengine.co.jp
受付：平日 10:00〜18:00（障害の検知は時間外も自動で行っています）

ここまでが、お渡しするリファレンスの形です。

実際には、御社の項目名・社内用語・締めの運用にあわせて作成します。いま毎月つくっている表を見せていただければ、それがそのまま設計図になります。

専用APIの開発と提供を見る相談する

サンプルフーズ 専用API

このAPIについて

つないでいる情報源

認証

共通仕様

オプスエンジンコネクト（以下OC）から使う

取り出すと、この表が届きます

どの表も、一覧から選ぶだけ

一度決めたら、あとは繰り返すだけ

届いたあとの手直しも、指示だけ

AIから使う

書いてあるから、できること

たとえば、こう動きます

エンドポイント

月次の売上まとめ

指定できるもの

返ってくるもの

日次の売上

在庫のスナップショット

調整（返品・値引き）の登録

送るもの

エラー

利用の上限

更新履歴

問い合わせ先

ここまでが、お渡しするリファレンスの形です。

サンプルフーズ専用API