[API] 端末データ管理

API
Terminal

端末データ管理

端末は組織の下にあり、必ずしも店舗の下にある必要はありません。また、端末の所属店舗は変更可能です。このセクションでは、端末情報の取得・管理について説明します。


端末データの取得 (`/

リクエスト

curl -X 'POST' \
  'https://api.receiptroller.com/{organizationId}/terminals' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "storeId": "1234-store-5678",
    "keyword": "端末",
    "planId": "standard-plan",
    "currentPage": 1,
    "itemsPerPage": 10,
    "sort": "terminalCode asc"
}'
  • storeId: 店舗ID
  • keyword: 検索キーワード
  • planId: 端末に紐づくプランID
  • currentPage: 現在のページ(ページネーション)
  • itemsPerPage: ページごとのアイテム数。上限は1000件です。
  • sort: 並び順(terminalCode asc または terminalCode desc

レスポンス

{
  "terminals": {
    "items": [
      {
        "id": "abc123-terminal-456",
        "organizationId": "1234-organization-5678",
        "storeId": "1234-store-5678",
        "terminalCode": "TM-001",
        "memo": "端末メモ内容",
        "planId": "standard-plan"
      }
    ],
    "currentPage": 1,
    "itemsPerPage": 10,
    "totalItems": 1,
    "totalPages": 1,
    "keyword": "端末",
    "sort": "terminalCode asc"
  }
}

エラーレスポンス

  • 400 Bad Request: 不正なリクエスト

    {
      "error": "Invalid request format"
    }
    
  • 401 Unauthorized: 認証エラー

    {
      "error": "Invalid or missing token"
    }
    
  • 404 Not Found: 指定された storeId または planId が存在しない場合

    {
      "error": "Store or plan not found"
    }
    

端末詳細の取得 (`/

リクエスト

curl -X 'GET' \
  'https://api.receiptroller.com/{organizationId}/terminal/{id}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR TOKEN}'

レスポンス

{
  "id": "abc123-terminal-456",
  "organizationId": "1234-organization-5678",
  "storeId": "1234-store-5678",
  "terminalCode": "TM-001",
  "memo": "端末メモ内容",
  "planId": "standard-plan"
}

エラーレスポンス

  • 400 Bad Request: 不正なリクエスト

    {
      "error": "Invalid request format"
    }
    
  • 401 Unauthorized: 認証エラー

    {
      "error": "Invalid or missing token"
    }
    
  • 404 Not Found: 指定された terminalId が存在しない場合

    {
      "error": "Terminal not found"
    }
    

端末の作成 (`/

リクエスト

curl -X 'POST' \
  'https://api.receiptroller.com/{organizationId}/terminal/create' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "storeId": "1234-store-5678",
    "terminalCode": "TM-002",
    "memo": "新しい端末メモ"
}'

リクエストボディ

  • storeId: 店舗ID(必須)
  • terminalCode: 端末コード(必須)
  • memo: メモ(任意)

レスポンス

{
  "id": "新しい端末ID",
  "organizationId": "1234-organization-5678",
  "storeId": "1234-store-5678",
  "terminalCode": "TM-002",
  "memo": "新しい端末メモ",
  "planId": "standard-plan"
}

エラーレスポンス

  • 400 Bad Request: 不正なリクエスト

    {
      "error": "Invalid request format"
    }
    
  • 401 Unauthorized: 認証エラー

    {
      "error": "Invalid or missing token"
    }
    
  • 409 Conflict: 端末コードが既に存在する場合

    {
      "error": "Terminal code already exists"
    }
    

端末の更新 (`/

リクエスト

curl -X 'POST' \
  'https://api.receiptroller.com/{organizationId}/terminal/update' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "abc123-terminal-456",
    "storeId": "1234-store-5678",
    "terminalCode": "TM-002",
    "memo": "更新された端末メモ"
}'

リクエストボディ

  • id: 端末ID(必須)
  • storeId: 店舗ID(任意、変更がある場合)
  • terminalCode: 端末コード(必須)
  • memo: メモ(任意)

レスポンス

{
  "id": "abc123-terminal-456",
  "organizationId": "1234-organization-5678",
  "storeId": "1234-store-5678",
  "terminalCode": "TM-002",
  "memo": "更新された端末メモ",
  "planId": "standard-plan"
}

エラーレスポンス

  • 400 Bad Request: 不正なリクエスト

    {
      "error": "Invalid request format"
    }
    
  • 401 Unauthorized: 認証エラー

    {
      "error": "Invalid or missing token"
    }
    
  • 404 Not Found: 端末が存在しない場合

    {
      "error": "Terminal not found"
    }
    
  • 409 Conflict: 端末コードが既に存在する場合

    {
      "error": "Terminal code already exists"
    }
    
更新日: 2024-09-26