ドキュメント

SOAPless を組み込むときに必要な情報を、実運用を前提に整理したガイドです。

このページの内容

初期設定からメソッド公開方針、テスト方法、トラブル対応まで順に確認できます。

API リファレンス →

3 ステップで開始

WSDL の登録から最初の JSON リクエスト送信まで、最短の流れで確認できます。

GET / POST の考え方

サービス既定、オペレーション単位の上書き、GET を公開できる条件をまとめています。

正確な API 仕様を見る

パス、ヘッダー、ステータスコード、OpenAPI まわりの仕様をすぐ確認できます。

クイックスタート

まずは 3 ステップで動かしてみるのが最短です。

セットアップ後に得られるもの

Account ID を含む固定 URL、JSON ベースの入出力、APIキー認証、必要に応じた GET 公開をまとめて使えるようになります。

Step 1: WSDL サービスを登録する

ダッシュボードから SOAP サービスを登録します。WSDL の URL と、必要であれば SOAP の認証情報を入力してください。登録が完了すると、SOAPless が WSDL を解析して REST エンドポイントを生成します。

Step 2: APIキーを作成する

API Keys ページで APIキーを発行します。キーの全文は作成時に一度しか表示されないため、その場で控えてください。

Step 3: 最初のリクエストを送信する

生成された REST エンドポイントを呼び出します。標準設定では POST + JSON ですぐに利用できます。

First requestbash
curl -X POST https://soapless.miravy.com/api/v1/ab12cd34ef/my-service/GetUser \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sl_live_your_api_key_here" \
  -d '{"userId": 42}'

参照系のオペレーションでは GET が自動で追加されることがあります。Starter / Pro では、オペレーションごとに GET を手動で有効化することもできます。

GET examplebash
curl "https://soapless.miravy.com/api/v1/ab12cd34ef/my-service/GetSum?a=2&b=3" \
  -H "X-API-Key: sl_live_your_api_key_here"

認証

すべての API リクエストには、 X-API-Key ヘッダーに APIキーを含める必要があります。

Authentication headerhttp
POST /api/v1/{accountId}/{serviceSlug}/{operationName} HTTP/1.1
Host: soapless.miravy.com
Content-Type: application/json
X-API-Key: sl_live_your_api_key_here

GET リクエストでも同じ X-API-Key ヘッダーを使用し、JSON ボディは不要です。

APIキーはアカウント単位で管理されます。ダッシュボードからいつでも作成・ローテーション・無効化できるので、開発・ステージング・本番で分けて使うのがおすすめです。

上流 SOAP サービスの認証

SOAP サービス側で認証が必要な場合は、サービスごとにダッシュボードから設定できます。HTTP Basic Auth は全プラン、WS-Security は Starter 以上、カスタムヘッダーは Pro で利用できます。

  • HTTP Basic Auth: 上流サービスがユーザー名とパスワードによる標準的な HTTP 認証を使っている場合に設定します。
  • WS-Security: SOAP ヘッダーに UsernameToken を付けて認証するサービス向けです。SOAP サービスでよく使われる方式です。
  • カスタムヘッダー: 独自トークンやゲートウェイ用ヘッダーを毎回付与したい場合に使います。

保存された SOAP 認証情報は暗号化して保管されます。編集画面では、認証方式を変えずに入力欄を空のまま保存すると、現在の値をそのまま維持します。

リクエストの送信

SOAPless は各 SOAP オペレーションを REST エンドポイントとして公開します。

POST /api/v1/{accountId}/{serviceSlug}/{operationName}
GET /api/v1/{accountId}/{serviceSlug}/{operationName}

GET は任意です。入力が単純な参照系オペレーションでは自動で公開されます。Starter / Pro では、ダッシュボードからオペレーションごとに GET を手動で有効化することもできます。

  • accountId: Settings に表示される固定の Account ID です(例: ab12cd34ef)。
  • serviceSlug: サービス登録時に設定した slug(例: my-erp
  • operationName: WSDL で定義された SOAP オペレーション名 (例: GetUser

POST の場合は JSON をリクエストボディとして送信します。SOAPless が SOAP XML エンベロープへ変換し、上流サービスのレスポンスを JSON に整形して返します。

  • POST は標準で利用できます。オペレーションごとに `GET only` を明示した場合だけ例外です。
  • GET は、入力が単純な参照系オペレーションで自動追加されるか、Starter / Pro のオペレーション単位設定で追加できます。
  • 自動 GET の対象になりやすいのは GetUserListOrdersGetSum のような参照系の名前を持つオペレーションです。
  • GET を公開できるのは、各入力フィールドがトップレベルの primitive: string, number, integer, boolean だけで構成されている場合です。
  • オペレーションごとの method policy は、同名オペレーションであれば WSDL refresh 後も維持されます。
  • ネストした object や array を含むオペレーションは POST を使ってください。

ダッシュボードの Method Policy

各サービスには既定の公開方針があり、必要ならオペレーション単位で上書きできます。

  • Inherit: サービスの既定設定をそのまま使います。
  • POST: そのオペレーションを POST のみに固定します。
  • GET: query-safe な入力で GET のみを公開します。
  • GET + POST: query-safe な入力で両方を公開します。
  • 両方を公開している場合は、クライアントに合わせて選べます。query parameter で扱いたいなら GET、JSON body で送りたいなら POST が向いています。
  • オペレーション単位の policy は Starter / Pro で利用できます。
  • policy を変更すると API Explorer と OpenAPI にも反映されます。

Operation のテスト

サービス詳細ページのテストパネルでは、APIキーを作る前でも session 認証でオペレーションを試せます。

  • 入力 JSON はオペレーションの schema からサンプル値を自動生成します。
  • GET と POST の両方に対応するオペレーションでは、テスト前に method を切り替えられます。
  • SOAP fault は raw object dump ではなく、読めるメッセージに整形して表示します。
  • 本番クライアントでは APIキー付きの REST エンドポイント を利用してください。

レスポンス形式

成功レスポンスは result meta フィールドを含む JSON オブジェクトで返されます。

Success responsejson
{
  "result": {
    "id": 42,
    "name": "Alice Johnson",
    "email": "alice@acme.com",
    "department": "Engineering"
  },
  "meta": {
    "service": "my-erp",
    "operation": "GetUser",
    "latencyMs": 245
  }
}

エラー形式

エラーレスポンスは統一された JSON 構造で返されます。

Error responsejson
{
  "error": {
    "type": "VALIDATION_ERROR",
    "code": 400,
    "message": "Missing required field: userId"
  }
}

type フィールドはプログラムで処理しやすいエラーカテゴリです。 message フィールドは人間が読める説明文です。エラータイプの一覧は API リファレンス をご確認ください。

レート制限

使用量の上限は APIキー単位ではなくアカウント単位で管理されます。Free プランでは月間上限を超えると HTTP 429 が返り、有料プランでは超過分が従量課金の対象になります。

プラン月間上限リクエスト制限超過時
Free100 回10 req/minブロック
Starter ($29/mo)10,000 回制限なし$0.01/回
Pro ($99/mo)100,000 回制限なし$0.01/回

上限やリセット時刻はレスポンスヘッダーから確認できます。

Rate limit headershttp
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9542
X-RateLimit-Reset: 2026-04-01T00:00:00Z

認証の詳細

SOAPless は APIキーで認証します。ここでは作成方法と運用時の注意点をまとめます。

APIキーの取得方法

  1. ダッシュボードにサインインします。
  2. API Keys ページに移動します。
  3. 「Create API Key」をクリックして、用途が分かる名前を付けます。
  4. キーをその場でコピーしてください。完全なキー(sl_live_...)は一度しか表示されません。

APIキーの使い方

すべてのリクエストで X-API-Key ヘッダーにキーを含めてください。プロキシ呼び出しと OpenAPI spec の取得で、どちらも同じヘッダーを使えます。

Header formathttp
GET /api/services/{id}/openapi HTTP/1.1
Host: soapless.miravy.com
X-API-Key: sl_live_your_api_key_here

APIキー運用のベストプラクティス

  • キーは環境変数に保存し、ソースコードには含めないでください。
  • 環境ごと(開発・ステージング・本番)に別々のキー を使用してください。
  • 定期的にダッシュボードからキー をローテーションしてください。
  • 漏洩したキーはすぐに無効化してください。

curl の使用例

コマンドラインや CI パイプラインから実行できる一般的な操作です。

プロキシ呼び出し

SOAP オペレーションをプロキシ呼び出しbash
curl -X POST https://soapless.miravy.com/api/v1/ab12cd34ef/my-erp/GetUser \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sl_live_abc123" \
  -d '{"userId": 42}'

OpenAPI Spec の取得

自動生成された OpenAPI 3.0 仕様をダウンロードします(有料プランが必要)。

Download OpenAPI specbash
curl -H "X-API-Key: sl_live_abc123" \
  https://soapless.miravy.com/api/services/{service-id}/openapi \
  -o my-service-openapi.json

レート制限ヘッダーの確認

View response headersbash
curl -v -X POST https://soapless.miravy.com/api/v1/ab12cd34ef/my-erp/GetUser \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sl_live_abc123" \
  -d '{"userId": 42}' 2>&1 | grep -i x-ratelimit

エラーハンドリング

SOAPless は統一された JSON 形式でエラーを返します。ここでは、よくあるケースごとの見方を説明します。

401 Unauthorized

APIキーが未設定、無効、または無効化されています。 X-API-Key ヘッダーを確認し、キーがダッシュボードで無効化されていないか確認してください。

401 responsejson
{
  "error": {
    "type": "auth",
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

429 Too Many Requests

Free プランの月間上限、または短時間あたりの制限に達しています。 X-RateLimit-Reset ヘッダーで次のリセット時刻を確認してください。Free は月次上限に達するとブロックされ、有料プランでは超過分が従量課金として処理されます。

429 responsejson
{
  "error": {
    "type": "rate_limit",
    "code": "MONTHLY_LIMIT_EXCEEDED",
    "message": "Monthly API call limit exceeded (100 calls for free plan)."
  }
}

502 Bad Gateway

上流の SOAP サービスに到達できないか、SOAP Fault が返っています。まずは SOAP サービス側の稼働状況を確認し、 error.detail があれば元の Fault メッセージも確認してください。

502 responsejson
{
  "error": {
    "type": "upstream",
    "code": "SOAP_FAULT",
    "message": "Upstream SOAP service returned a fault",
    "detail": "Server was unable to process request: timeout"
  }
}

リトライ戦略

JavaScript retry examplejavascript
async function callWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, options);

    if (res.status === 429) {
      const resetAt = res.headers.get("X-RateLimit-Reset");
      const waitMs = resetAt
        ? new Date(resetAt).getTime() - Date.now()
        : 1000 * Math.pow(2, attempt);
      await new Promise((r) => setTimeout(r, waitMs));
      continue;
    }

    if (res.status === 502 && attempt < maxRetries - 1) {
      await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
      continue;
    }

    return res;
  }
  throw new Error("Max retries exceeded");
}

SDK コード例

各言語での SOAPless Proxy 呼び出しのコードスニペットです。

JavaScript / TypeScript

JavaScript examplejavascript
const response = await fetch(
  "https://soapless.miravy.com/api/v1/ab12cd34ef/my-erp/GetUser",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": process.env.SOAPLESS_API_KEY,
    },
    body: JSON.stringify({ userId: 42 }),
  }
);

if (!response.ok) {
  const err = await response.json();
  throw new Error(err.error.message);
}

const { result, meta } = await response.json();
console.log(result);  // { id: 42, name: "Alice Johnson", ... }
console.log(meta);    // { latencyMs: 245, ... }

Python

Python examplepython
import os
import requests

response = requests.post(
    "https://soapless.miravy.com/api/v1/ab12cd34ef/my-erp/GetUser",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["SOAPLESS_API_KEY"],
    },
    json={"userId": 42},
    timeout=30,
)
response.raise_for_status()

data = response.json()
print(data["result"])   # {'id': 42, 'name': 'Alice Johnson', ...}
print(data["meta"])     # {'latencyMs': 245, ...}

Go

Go examplego
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]int{"userId": 42})
	req, _ := http.NewRequest(
		"POST",
		"https://soapless.miravy.com/api/v1/ab12cd34ef/my-erp/GetUser",
		bytes.NewReader(body),
	)
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-API-Key", os.Getenv("SOAPLESS_API_KEY"))

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]interface{}
	json.NewDecoder(resp.Body).Decode(&result)
	fmt.Println(result["result"])
}

モニタリングと使用量

SOAPless では、ダッシュボードとレスポンスヘッダーの両方から使用量を追跡できます。

使用量ダッシュボード

ダッシュボードでは、Recent API calls や集計情報からコール数、レイテンシ、エラー傾向を確認できます。使用量のリセット時刻はプランと請求期間に応じて変わるため、固定で毎月 1 日とは限りません。

レート制限ヘッダー

すべてのレスポンスにレート制限ヘッダーが含まれており、クライアント側でも残量とリセット時刻を確認できます。

  • X-RateLimit-Limit — 現在のプランで使えるコール上限
  • X-RateLimit-Remaining — 現在の期間で残っているコール数
  • X-RateLimit-Reset — 次回のリセット時刻を示す ISO 8601 タイムスタンプ

自己完結できる操作

プラン変更、請求書確認、カード更新、解約はダッシュボードの Billing と Stripe ポータルから行えます。アカウントの完全削除は Settings から実行できます。

メールでの連絡は、セキュリティ、プライバシー、法務、法人導入、またはダッシュボードから復旧できないアカウント問題に限定しています。

次のステップ