Developer Guide Merukari Python API

API For Beginners

外部連携も管理画面操作も、最初の1本から迷わない API ガイド。

このページは初心者向けの開発者ドキュメントです。どの URL を使うか、どう認証するか、どんな JSON が返るかを、コピペできるサンプルコード付きでまとめています。

最初の3ステップを見る 先に操作ガイドを見る
Before You Start
  • このガイドの例では https://s.by0.uk を使っています。ドメインが違う場合は読み替えてください。
  • 外部連携にはまず /v1/{taskNo} を使うのが最も簡単です。
  • /api/* は管理画面用の内部 API です。Cookie と CSRF を使います。

Quick Start

最初の3ステップ

01

Task No を確認する

ダッシュボードの `Operations Desk` に表示されている番号を確認します。外部 API はこの番号を使って取得します。

02

認証方法を選ぶ

外部システムから読むだけなら API key を使います。管理画面を自動化したい場合はログインして Cookie を使います。

03

まず curl で試す

コードに入れる前に、まず `curl` で 1 回成功させるのが最短です。成功したら同じ内容を JavaScript や PHP に移します。

Authentication

認証方法の選び方

Recommended

X-API-Key

外部システム連携ならこれが最も簡単です。ヘッダーに API key を付けるだけで /v1/{taskNo} を読めます。

Alternative

Authorization: Bearer

API key を Bearer トークンとして渡す方法です。既存の HTTP クライアントに載せやすい時はこちらでも大丈夫です。

Debug Only

?api_key=...

動作確認用には使えますが、URL に残りやすいので本番運用では推奨しません。

Internal API

Cookie session + CSRF

/api/* を使う場合はこちらです。ログインで Cookie を取得し、更新系 API では X-CSRF-Token を付けます。

Endpoints

まず覚える API

Method Path 認証 用途
GET /health 不要 サーバーが応答しているか確認します。
GET /v1/{taskNo} API key または Cookie 外部連携の本命です。対象タスクの取得済み商品を最新順で返します。
GET /s/{shortCode} 不要 短縮URLを開くと、内部でアフィリエイトURLへリダイレクトします。
POST /api/auth/login 不要 内部 API 用のログインです。Cookie を受け取ります。
GET /api/me Cookie 現在ログイン中か、どのテナントかを確認します。
GET /api/status Cookie 件数サマリー、ベースURL、設定の一部を返します。
POST /api/tasks/{taskNo}/run Cookie + CSRF 対象タスクを手動実行します。

Parameters

/v1/{taskNo} の基本ルール

taskNo

ダッシュボードに表示されるタスク番号です。テナントの権限外や存在しない番号だと 404 になります。

limit

返却件数です。例: limit=100。全件欲しい時は limit=all を使えます。

offset

ページ送り開始位置です。例: offset=100。

並び順

既定で最新順です。新しい取得結果から返ります。

重複保存

同一タスクで同じ商品を再取得しても、重複レコードを増やさず更新扱いにします。

テナント分離

同じ Task No を推測しても、認証したテナント外のデータは取得できません。

Code Samples

そのまま試せるサンプルコード

curl

外部 API を読む

curl -s \
  -H "X-API-Key: YOUR_API_KEY" \
  "https://s.by0.uk/v1/1?limit=3"

JavaScript

fetch で読む

const response = await fetch("https://s.by0.uk/v1/1?limit=3", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await response.json();
console.log(data.records);

Python

requests で読む

import requests

url = "https://s.by0.uk/v1/1"
params = {"limit": 3}
headers = {"X-API-Key": "YOUR_API_KEY"}

response = requests.get(url, params=params, headers=headers, timeout=30)
response.raise_for_status()

data = response.json()
for row in data["records"]:
    print(row["title"], row["price"])

PHP

共有サーバーから読む

<?php
$url = "https://s.by0.uk/v1/1?limit=3";
$headers = [
    "X-API-Key: YOUR_API_KEY",
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$body = curl_exec($ch);
if ($body === false) {
    throw new Exception(curl_error($ch));
}

$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new Exception("HTTP error: " . $status);
}

$data = json_decode($body, true);
foreach ($data["records"] as $row) {
    echo $row["title"] . " / " . $row["price"] . PHP_EOL;
}

Session Example

内部 API を使うときの最小ログイン例

Python

ログインしてタスクを手動実行する

import requests

base_url = "https://s.by0.uk"
session = requests.Session()

login_response = session.post(
    f"{base_url}/api/auth/login",
    json={
        "username": "YOUR_USERNAME",
        "password": "YOUR_PASSWORD",
    },
    timeout=30,
)
login_response.raise_for_status()

me = login_response.json()["me"]
csrf_token = me["csrf_token"]

run_response = session.post(
    f"{base_url}/api/tasks/1/run",
    json={},
    headers={"X-CSRF-Token": csrf_token},
    timeout=120,
)
run_response.raise_for_status()

print(run_response.json())

Response Examples

返却される JSON の例

GET /health

ヘルスチェック

{
  "status": "ok",
  "time": "2026-04-01T11:00:00+09:00"
}

GET /v1/1?limit=2

外部公開 API

{
  "task": {
    "task_no": 1,
    "task_name": "ポケカ",
    "keyword": "ポケカ",
    "category": "トレーディングカード",
    "source": "mercari"
  },
  "total": 120,
  "offset": 0,
  "count": 2,
  "records": [
    {
      "task_no": 1,
      "title": "ポケモンカード まとめ売り SR入り",
      "image_url": "https://static.mercdn.net/item/detail/orig/photos/m12345678901_1.jpg",
      "product_url": "https://jp.mercari.com/item/m12345678901",
      "price": 6800,
      "short_url": "https://s.by0.uk/s/Ab12Cd34",
      "fetched_at": "2026-04-01T08:49:18+09:00"
    },
    {
      "task_no": 1,
      "title": "ポケモンカード 引退品 まとめ",
      "image_url": "https://static.mercdn.net/item/detail/orig/photos/m12345678902_1.jpg",
      "product_url": "https://jp.mercari.com/item/m12345678902",
      "price": 12000,
      "short_url": "https://s.by0.uk/s/Xy98Mn45",
      "fetched_at": "2026-04-01T08:49:18+09:00"
    }
  ]
}

POST /api/auth/login

ログイン成功

{
  "message": "ログインしました。",
  "me": {
    "authenticated": true,
    "auth_type": "session",
    "username": "tenant1_owner",
    "tenant_id": 2,
    "tenant_name": "Tenant 1",
    "tenant_slug": "tenant-1",
    "is_superadmin": false,
    "csrf_token": "CSRF_TOKEN_HERE"
  }
}

GET /api/status

状態確認

{
  "server_time": "2026-04-01T11:00:00+09:00",
  "base_url": "https://s.by0.uk",
  "counts": {
    "task_count": 1,
    "enabled_task_count": 1,
    "item_count": 120,
    "issued_url_count": 120,
    "log_count": 42
  },
  "tenant": {
    "tenant_id": 2,
    "tenant_name": "Tenant 1",
    "tenant_slug": "tenant-1"
  },
  "settings_preview": {
    "fetcher_mode": "api",
    "short_base_url": "https://s.by0.uk",
    "short_code_length": "8",
    "api_default_limit": "50"
  },
  "tasks_due_now": [1]
}

POST /api/tasks/1/run

手動実行

{
  "task_no": 1,
  "tenant_id": 2,
  "source": "mercari",
  "status": "success",
  "items_processed": 60,
  "message": "60件のメルカリ商品を取得しました。",
  "finished_at": "2026-04-01T11:05:00+09:00",
  "next_run_at": "2026-04-01T11:35:00+09:00"
}

Errors

よくあるエラー

{
  "error": "認証が必要です。"
}

{
  "error": "Task not found"
}

{
  "error": "CSRF token が一致しません。再ログインしてください。"
}

Tips

初心者向けのおすすめ運用

外部連携はまず X-API-Key で /v1/{taskNo} を読むところから始めるのが最短です。管理画面の自動化は Cookie と CSRF を使うぶん少し複雑なので、必要になった時にだけ取り組むのがおすすめです。

さらに詳しい説明や手元で保存する用の資料は docs/api-developer-guide.md を参照してください。