はじめに
青果を扱う流通、小売、飲食などさまざまな事業者さまの多くは発注を円滑に実行するためにそれぞれ販売管理のシステムを導入していることと思います。それらは、会計や販売管理、商品管理など他のサービスと連携しているところもありますが、なかには Excel などで工夫していたり、手動で連携させているところもあります。少量多品目多品度の取引になりがちな青果について円滑に受発注しデータを蓄積する機能を持ったファーモは、これらのシステムと連携していくことで利用する生産者や各事業者の負担を減らし、データの利活用できる環境をつくっていきたいと考えています。
今回、ファーモでは外部のシステムと連携していき、利用者の業務負荷を下げてデータを蓄積していくために API（Application Programming Interface）を用意いたしました。
これは、買い手さまの利用している各システムとファーモをつなぐための仕組みです。大きく分けて以下の 2 つの機能があります。
（１）ファーモをつかっている仕入れ先生産者の出荷可能商品の情報を出力する
（２）出力された出荷可能商品の情報をもとに発注データをファーモに送信する
現在、ファーモを使っている企業と連携して開発し、現在、バージョン0.9として提供していますが、ご利用者さまの声を受けてより改善していきます。コメントや改善のご提案などお気軽にお知らせください。
ご利用方法
１．ファーモお問い合わせフォームからご利用申し込みをしてください。
２．承認されると、APIキーとサンドボックス環境の利用方法をお知らせします。
ここでファーモ発注APIに適合するよう開発していただきましたのちに本番環境でご利用ください。
※ サンドボックス環境は予告なく停止・仕様変更する場合がありますことご了承ください。
１．出荷可能商品取得API
目的
ファーモで取引先生産者が設定した商品の情報と、その出荷可能量を取得する
仕組み
ファーモのエンドポイント（URL）にAPIキーを含めてリクエストをするとCSVファイルを取得できます。エンドポイントは申し込み後に連絡いたします。また、このCSVはファーモのグループページからも手動で出力可能なものと同じ形式です。
仕様
取得できるCSVの仕様は次の通りです。
| 番号 | カラム名 | 制約 | 説明 |
|---|
| 1 | 商品ID | 数字 0~9999999 | 商品のIDが数字で入力されます |
| 2 | 商品名 | 文字列 1~50 | |
| 3 | カテゴリー名 | 文字列 1~50 | ファーモで管理しているカテゴリー名です |
| 4 | 量 | 数字 0~99999 | 商品の内容量 |
| 5 | 規格 | 文字列 g,kg,ml,l | 商品の内容量の単位です |
| 6 | 価格 | 数字 0~999999 | 商品の価格です |
| 7 | 荷姿 | 文字列 1~10 | |
| 8 | 規格 | 文字列 1~50 | 商品の規格を説明する文字列が入ります |
| 9 | 入数 | 数字 1~99999 | ロット商品の場合、2以上の入り数が設定されます |
| 10 | 品種補足 | 文字列 1~200 | |
| 11 | 説明 | 文字列 1~200 | |
| 12 | 生産者ID | 数字 1~99999 | |
| 13 | 生産者名 | 文字列 1~50 | |
| 14 | 超過注文可否 | 文字列 空欄or不可 | 不可の場合、設定した上限を超えて発注できません |
| 15 |
取引先指定状況 |
not limited
limited
only me
|
not limited → 購入者の指定がない商品です
limited → 一部の買い手のみが購入できるよう設定された商品です
only me → あなただけが購入できるよう設定された商品です
|
| 16 | 軽減税率対象 | 8%,10% | 消費税率です |
| 17 | 在庫数量 | | |
| 18 | メモ | | |
| 19 | 基準日（第1週始まり日） | YYYY/MM/DD | 3週間分の出荷可能量が出力されますが、その第1週1日目の日付です |
| 20 | 第1週(日)出荷可能量 | 数字 1~99999 | 対象日の出荷可能数量です |
| 21 | 第1週(月)出荷可能量 | 数字 1~99999 | |
| 22 | 第1週(火)出荷可能量 | 数字 1~99999 | |
| 23 | 第1週(水)出荷可能量 | 数字 1~99999 | |
| 24 | 第1週(木)出荷可能量 | 数字 1~99999 | |
| 25 | 第1週(金)出荷可能量 | 数字 1~99999 | |
| 26 | 第1週(土)出荷可能量 | 数字 1~99999 | |
| 27 | 第2週(日)出荷可能量 | 数字 1~99999 | |
| 28 | 第2週(月)出荷可能量 | 数字 1~99999 | |
| 29 | 第2週(火)出荷可能量 | 数字 1~99999 | |
| 30 | 第2週(水)出荷可能量 | 数字 1~99999 | |
| 31 | 第2週(木)出荷可能量 | 数字 1~99999 | |
| 32 | 第2週(金)出荷可能量 | 数字 1~99999 | |
| 33 | 第2週(土)出荷可能量 | 数字 1~99999 | |
| 34 | 第3週(日)出荷可能量 | 数字 1~99999 | |
| 35 | 第3週(月)出荷可能量 | 数字 1~99999 | |
| 36 | 第3週(火)出荷可能量 | 数字 1~99999 | |
| 37 | 第3週(水)出荷可能量 | 数字 1~99999 | |
| 38 | 第3週(木)出荷可能量 | 数字 1~99999 | |
| 39 | 第3週(金)出荷可能量 | 数字 1~99999 | |
| 40 | 第3週(土)出荷可能量 | 数字 1~99999 | |
| 41 | 第1週(日)既注量 | 数字 1~99999 | すでに発注していた場合、その数量が入っています |
| 42 | 第1週(月)既注量 | 数字 1~99999 | |
| 43 | 第1週(火)既注量 | 数字 1~99999 | |
| 44 | 第1週(水)既注量 | 数字 1~99999 | |
| 45 | 第1週(木)既注量 | 数字 1~99999 | |
| 46 | 第1週(金)既注量 | 数字 1~99999 | |
| 47 | 第1週(土)既注量 | 数字 1~99999 | |
| 48 | 第2週(日)既注量 | 数字 1~99999 | |
| 49 | 第2週(月)既注量 | 数字 1~99999 | |
| 50 | 第2週(火)既注量 | 数字 1~99999 | |
| 51 | 第2週(水)既注量 | 数字 1~99999 | |
| 52 | 第2週(木)既注量 | 数字 1~99999 | |
| 53 | 第2週(金)既注量 | 数字 1~99999 | |
| 54 | 第2週(土)既注量 | 数字 1~99999 | |
| 55 | 第3週(日)既注量 | 数字 1~99999 | |
| 56 | 第3週(月)既注量 | 数字 1~99999 | |
| 57 | 第3週(火)既注量 | 数字 1~99999 | |
| 58 | 第3週(水)既注量 | 数字 1~99999 | |
| 59 | 第3週(木)既注量 | 数字 1~99999 | |
| 60 | 第3週(金)既注量 | 数字 1~99999 | |
| 61 | 第3週(土)既注量 | 数字 1~99999 | |
発注API
目的
発注内容をjson形式でファーモに登録することで発注できます。
仕組み
ファーモのエンドポイント（URL）にAPIキーを含めて定められた形式で発注データを送るとファーモ上で発注データが作成され、生産者にも発注メールが送信されます。
発注データのリクエスト形式はjson schemaで提供しているのでご参照ください。
json schema（yml）
レスポンスは下記内容が返却されます。
| 項番 |
ステータス |
メッセージ |
説明 |
| 1 |
success |
発注内容が出力されます |
正常に発注できる場合。 |
| 2 |
success |
すでに発注済みのものと更新はありません。 |
同じ生産者、同じ出荷日にすでに同じ内容の発注がある場合は更新されません。 |
| 3 |
fail |
発注できない商品があり発注していません。連携されていない商品を発注しようとしています。発注内容を見直すかファーモから直接発注してください。 |
発注データの商品IDがファーモに存在しない場合です。発注されません。 |
| 4 |
fail |
APIキーが不正です |
APIキーが正しくない場合。 |
| 5 |
fail |
商品注文情報がありません |
連携情報が空の場合。 |
| 6 |
fail |
商品がファーモ連携ではない可能性があります。もしくは発注先不明です |
発注データの商品IDがファーモに存在しない場合、もしくは発注先生産者が特定できない場合。 |
| 7 |
fail |
ひとつも発注できませんでした。上限越え発注不可のため発注できない商品と連携されていない商品があります。ファーモから直接発注してください。 |
以下の2つの理由によって発注が失敗しているとき。
① 上限越え発注不可商品への発注
② 規格変更によってアーカイブされた商品に発注しようとしている
レスポンスデータの明細行内に、「[商品名]は上限以上注文不可商品で上限を超えているため発注していません」とコメントが付与されます。
|
| 8 |
fail |
ひとつも発注できませんでした。上限越え発注不可のため発注できない商品があります。数量を調整し再度発注してください。 |
発注が失敗し、その原因が上限越え発注不可商品への発注のとき。
レスポンスデータの明細行内に、「[商品名]は上限以上注文不可商品で上限を超えているため発注していません」とコメントが付与されます。 |
| 9 |
fail |
ひとつも発注できませんでした。商品が規格変更されているため発注できません。 |
発注が失敗し、その原因が発注しようとした商品が規格変更によって廃止された商品のとき。
|
| 10 |
fail_send_mail |
上限越え発注不可の商品・発注連携できていない商品があり発注できていない商品があります。ファーモから直接発注してください。
|
以下の2つの理由によって発注が失敗した商品があるとき。
① 上限越え発注不可商品への発注
② 規格変更によってアーカイブされた商品に発注しようとしている
レスポンスデータの明細行内に、「[商品名]は上限以上注文不可商品で上限を超えているため発注していません」とコメントが付与されます。
ほかに発注できている商品はあるため発注メールは発送されます。
|
| 11 |
fail_send_mail |
上限越え発注不可のため発注できていない商品があります。発注数を見直して再発注ください。
|
生産者が出荷可能数量を指定し、上限越え発注を不可としていることで発注失敗した商品がある場合。ほかに発注できている商品はあるため発注メールは発送されます。
|
| 12 |
fail_send_mail |
商品が規格変更されているため発注できていない商品があります。連携しなおしてご確認ください。 |
商品データが更新されて廃止になった商品に発注しようとした場合。ほかに発注できている商品はあるため発注メールは発送されます。 |
| 13 |
fail_send_mail |
発注できていない商品があります。連携されていない商品を発注していない可能性があります。
|
想定していない原因で発注失敗した商品がある場合。発注メールは発送されます。
|
APIのご利用にはファーモのアカウント登録（登録料・利用料無料！）が必要です。こちらからお申し込みください。
※ご登録までは1-2日お時間がかかります。
