メインコンテンツまでスキップ

API仕様

概要​

  • タノミマスターを利用する際にWebからの操作だけでなく、REST APIによっても情報を取得や更新を行えます。
  • REST APIの種別は大きく3種類、小売向け、メーカー向け、共通に分かれています。
    • 小売向けのAPIは発注、納品通知などを行えます。
    • メーカー向けのAPIは受注処理、納期回答などを行えます。
    • 共通APIは、タノミマスターで利用しているカテゴリなどのマスタの取得を行えます。

APIドキュメント​

稼働中のAPI仕様は以下のURLで閲覧できます。各環境ごとにAPIの実装が異なる場合があるのでAPIのバージョンをご確認ください。

上記のページはOpenAPI Specificationで書かれたドキュメントの一部が抜粋されて見やすく簡易的に表示されています。 開発者や、開発時に参照する目的の場合は、OpenAPI Speificationのymlファイルを上記からダウンロードし、Swagger Editorなどを利用して可視化することをおすすめします。 参考: Swagger Editor

APIのリクエストやレスポンスをCLIから簡易的に確認するためのサンプルコードを以下に掲載しています。 https://github.com/tanomimaster/tanomimaster-openapi/wiki

API実装の方向性​

  • Web上で行える操作はREST APIでも同様に操作できるようになっています。
  • API仕様は幅広く意見や参加者を募集したいのでOSSとして公開しております。

動作環境​

開発環境、ステージング環境、本番環境の3つの環境があります。エンドポイントはAPI仕様に記載してあります。

APIキー​

REST APIを呼び出すためにはキーが必要になります。小売単位、メーカー単位で1つ発行できます。

API呼び出しの仕様​

受注確定処理​

メーカー向けに受注確定を行う際の推奨事項を記載します。

メーカーが受注確定をしていない注文は、小売側からキャンセルが可能になっています。そのため、下の図で示す2と3の間に小売からキャンセルが行われます。できるだけそのパターンを減らすために2と3の呼び出しの間隔は短くすることを推奨します。

また、受注確定をする前にメーカー内での受注処理を行ってしまうと小売からキャンセルになる可能性があるためタノミマスター上で受注確定を行ってからメーカー内で受注に関する処理を行うことを推奨します。

alt-text

注文状態に応じた注文の取得​

メーカー​

注文の状態に対して、その注文を取得する際のパラメータの一覧を記載します。

ステータスAPI Query string parameter
納期未回答発注済みstatus=0&is_confirmed=false
黒伝連携済みstatus=0&is_confirmed=true
出荷待ちstatus=2
出荷済みstatus=3
納品済みstatus=4
キャンセル黒伝連携前キャンセルstatus=99&is_confirmed=false&is_cancel_confirmed=false
連携前キャンセル連携済みstatus=99&is_confirmed=false&is_cancel_confirmed=true
赤伝キャンセルstatus=99&is_confirmed=true&is_cancel_confirmed=false
赤伝キャンセル連携済みstatus=99&is_confirmed=true&is_cancel_confirmed=true

受注CSVとREST APIのエンティティの対応表​

受注CSVにあるCSVカラムがREST APIのどのエンティティのアトリビュートに対応するかを表にします。

カラム名称エンティティアトリビュート
1発注依頼区分N/AN/A
2小売コードRetailcode
3小売名Retailname
4小売支店コードRetailBranchcode
5小売支店名RetailBranchname
6小売営業所コードRetailSalesOfficecode
7小売営業所名RetailSalesOfficename
8発注日時Orderordered_at
9仕入先名Makername
10注文番号Ordercode
11注文明細NoOrderProductbranch_number
12型式（品番）OrderProductcode
13メーカー内部コードOrderProductinternal_code
14ガス種OrderProductgas_type
15カタログURLOrderProductcatalog_url
16承認図URLOrderProductapproved_drawing_url
17発注数OrderProductnumber_of_items
18発注単価OrderProductmaker_price_for_retail
19希望納期OrdersMakerdesired_delivery_date
20メーカー営業所名MakerSalesOfficename
21メーカー営業所電話番号MakerSalesOfficetel
22メーカー営業所FAXMakerSalesOfficefax
23小売担当者名RetailUserlast_name first_name
24納品先名OrderProductshipping_office_name
25納品先住所OrderProductshipping_address
26納品先TELOrderProductshipping_tel
27明細単位の備考OrderProductmemo
28注文単位の備考Ordermemo

API呼び出し例​

以下にAPI呼び出しのサンプルコードを記載します。curl コマンドによる実行例を示します。 サンプルを実行するにあたり、APIの認証トークンと接続先のホスト名は変数にしてあるので適宜環境変数に設定してください。

bash, zsh

maker_token "<maker token>"
retail_token "<retail token>"
token "<maker or retail token>"
host="https://development.tanomimaster.com"
#host="https://staging.tanomimaster.com"
#host="https://tanomimaster.com"

fish

set maker_token "<maker token>"
set retail_token "<retail token>"
set token "<maker or retail token>"
set host "https://development.tanomimaster.com"
#set host "https://staging.tanomimaster.com"
#set host "https://tanomimaster.com"

また、サーバからの出力はjqコマンドによって整形するようにしています。

共通​

メーカー一覧を取得

curl -s -H "Authorization: Token $token" "$host/api/v1/master/makers" | jq

メーカーコード anedd1bup5 の詳細を取得

curl -s -H "Authorization: Token $token" "$host/api/v1/master/makers/anedd1bup5" | jq

メーカーコード anedd1bup5 の支店一覧を取得

curl -s -H "Authorization: Token $token" "$host/api/v1/master/makers/anedd1bup5/maker_branches" | jq

メーカーコード anedd1bup5 の支店コードc6ef06fc9a7efd6045cf9e05c4の詳細取得

curl -s -H "Authorization: Token $token" "$host/api/v1/master/makers/anedd1bup5/maker_branches/c6ef06fc9a7efd6045cf9e05c4" | jq

メーカーコード anedd1bup5 の支店コードc6ef06fc9a7efd6045cf9e05c4に属する営業所一覧を取得

curl -s -H "Authorization: Token $token" "$host/api/v1/master/makers/anedd1bup5/maker_branches/c6ef06fc9a7efd6045cf9e05c4/maker_sales_offices" | jq

メーカーコード anedd1bup5 の支店コードc6ef06fc9a7efd6045cf9e05c4に属する営業所コードb69980937ff8da735504c690bcを取得

curl -s -H "Authorization: Token $token" "$host/api/v1/master/makers/anedd1bup5/maker_branches/c6ef06fc9a7efd6045cf9e05c4/maker_sales_offices/b69980937ff8da735504c690bc" | jq

メーカー​

すべての注文の一覧を取得

curl -s -H "Authorization: Token $maker_token" "$host/api/v1/maker/orders_makers" | jq

納期未回答の発注済み注文の一覧を取得

curl -s -H "Authorization: Token $maker_token" "$host/api/v1/maker/orders_makers?status=0&is_confirmed=false" | jq

納期未回答の発注済み注文の一覧を取得(100件ずつ1ページ目を取得)

curl -s -H "Authorization: Token $maker_token" "$host/api/v1/maker/orders_makers?status=0&is_confirmed=false&limit=100&page=1" | jq

注文IDZ2lkOi8vdGFub21pbWFzdGVyLXd3dy9PcmRlcnNNYWtlci8zNQの明細番号1に対して受注確定を行う

curl -s -X POST -H "Authorization: Token $maker_token" "$host/api/v1/maker/orders_makers/Z2lkOi8vdGFub21pbWFzdGVyLXd3dy9PcmRlcnNNYWtlci8zNQ/order_products/1/confirm" | jq

注文IDZ2lkOi8vdGFub21pbWFzdGVyLXd3dy9PcmRlcnNNYWtlci8zNQの明細番号1に対してキャンセル受注確定を行う

curl -s -X POST -H "Authorization: Token $maker_token" "$host/api/v1/maker/orders_makers/Z2lkOi8vdGFub21pbWFzdGVyLXd3dy9PcmRlcnNNYWtlci8zNQ/order_products/1/confirm_cancel" | jq

注文IDZ2lkOi8vdGFub21pbWFzdGVyLXd3dy9PcmRlcnNNYWtlci8zNQの明細番号1に対して配送済みステータスへ変更する

curl -s -X POST \
-H "Authorization: Token $maker_token" \
-H "Content-Type: application/json" \
-d '{"delivery_company_id": 1, "shipping_slip_number", "xxxx-xxxx-xxxx-xxxx"}' \
"$host/api/v1/maker/orders_makers/Z2lkOi8vdGFub21pbWFzdGVyLXd3dy9PcmRlcnNNYWtlci8zNQ/order_products/1/confirm" | jq

小売り​

発注を行う

(bashの場合)

# Generate a random number between 1000000000 and 9999999999
code=$(( 1000000000 + RANDOM % (9999999999 - 1000000000) ))

# Prepare the JSON body for the POST request
order_body="
{
  \"code\": \"$code\",
  \"makers\": [
    {
      \"maker_code\": \"maker_code\",
      \"retail_sales_office_code\": \"a32a0c942926de863083e3598c\",
      \"retail_user_code\": \"ftlkqvkkvs\",
      \"desired_delivery_date\": \"2023-08-10\",
      \"shipping_postcode\": \"1060031\",
      \"shipping_city\": \"city\",
      \"shipping_street_address\": \"street\",
      \"shipping_building\": \"building\",
      \"shipping_office_name\": \"office name\",
      \"shipping_tel\": \"03-0000-1111\",
      \"shipping_prefecture_code\": 1,
      \"products\": [
        {
          \"code\": \"qghdvhjabusntjmanslz\",
          \"branch_number\": 1,
          \"number_of_items\": 2,
          \"memo\": \"memo\"
        }
      ]
    }
  ]
}"

curl -s -X POST \
  -H "Authorization: Token $retail_token" \
  -H "Content-Type: application/json" \
  -d "$order_body" \
  "$host/api/v1/retail/orders" | jq

(fishの場合)

set order_body "
{
  \"code\": \"$(random 1000000000 9999999999)\",
  \"makers\": [
    {
      \"maker_code\": \"maker_code\",
      \"retail_sales_office_code\": \"a32a0c942926de863083e3598c\",
      \"retail_user_code\": \"ftlkqvkkvs\",
      \"desired_delivery_date\": \"2023-08-10\",
      \"shipping_postcode\": \"1060031\",
      \"shipping_city\": \"city\",
      \"shipping_street_address\": \"street\",
      \"shipping_building\": \"building\",
      \"shipping_office_name\": \"office name\",
      \"shipping_tel\": \"03-0000-1111\",
      \"shipping_prefecture_code\": 1,
      \"products\": [
        {
          \"code\": \"qghdvhjabusntjmanslz\",
          \"branch_number\": 1,
          \"number_of_items\": 2,
          \"memo\": \"memo\"
        }
      ]
    }
  ]
}
"


curl -s -X POST \
  -H "Authorization: Token $retail_token" \
  -H "Content-Type: application/json" \
  -d $order_body \
  "$host/api/v1/retail/orders" | jq

FAQ​

納期を表現するのカラムの種類と意味は？​

  • orders_makers.desired_delivery_date
    • 希望納期
    • 小売が注文時に選択した納品を希望する日
  • orders_products.estimated_delivery_date
    • 納期目安
    • 注文時にタノミマスターのシステムが商品ごとに設定された納期目安を参考にし、自動で算出した日付。
  • orders_products.official_estimated_delivery_date
    • 納期回答
    • メーカーが納期日を登録した内容