ドキュメント
SOAPless を組み込むときに必要な情報を、実運用を前提に整理したガイドです。
このページの内容
初期設定からメソッド公開方針、テスト方法、トラブル対応まで順に確認できます。
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 ですぐに利用できます。
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 を手動で有効化することもできます。
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キーを含める必要があります。
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_hereGET リクエストでも同じ 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 の対象になりやすいのは
GetUser、ListOrders、GetSumのような参照系の名前を持つオペレーションです。 - 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 オブジェクトで返されます。
{
"result": {
"id": 42,
"name": "Alice Johnson",
"email": "alice@acme.com",
"department": "Engineering"
},
"meta": {
"service": "my-erp",
"operation": "GetUser",
"latencyMs": 245
}
}エラー形式
エラーレスポンスは統一された JSON 構造で返されます。
{
"error": {
"type": "VALIDATION_ERROR",
"code": 400,
"message": "Missing required field: userId"
}
}type フィールドはプログラムで処理しやすいエラーカテゴリです。 message フィールドは人間が読める説明文です。エラータイプの一覧は API リファレンス をご確認ください。
レート制限
使用量の上限は APIキー単位ではなくアカウント単位で管理されます。Free プランでは月間上限を超えると HTTP 429 が返り、有料プランでは超過分が従量課金の対象になります。
| プラン | 月間上限 | リクエスト制限 | 超過時 |
|---|---|---|---|
| Free | 100 回 | 10 req/min | ブロック |
| Starter ($29/mo) | 10,000 回 | 制限なし | $0.01/回 |
| Pro ($99/mo) | 100,000 回 | 制限なし | $0.01/回 |
上限やリセット時刻はレスポンスヘッダーから確認できます。
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9542
X-RateLimit-Reset: 2026-04-01T00:00:00Z認証の詳細
SOAPless は APIキーで認証します。ここでは作成方法と運用時の注意点をまとめます。
APIキーの取得方法
APIキーの使い方
すべてのリクエストで X-API-Key ヘッダーにキーを含めてください。プロキシ呼び出しと OpenAPI spec の取得で、どちらも同じヘッダーを使えます。
GET /api/services/{id}/openapi HTTP/1.1
Host: soapless.miravy.com
X-API-Key: sl_live_your_api_key_hereAPIキー運用のベストプラクティス
- キーは環境変数に保存し、ソースコードには含めないでください。
- 環境ごと(開発・ステージング・本番)に別々のキー を使用してください。
- 定期的にダッシュボードからキー をローテーションしてください。
- 漏洩したキーはすぐに無効化してください。
curl の使用例
コマンドラインや CI パイプラインから実行できる一般的な操作です。
プロキシ呼び出し
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 仕様をダウンロードします(有料プランが必要)。
curl -H "X-API-Key: sl_live_abc123" \
https://soapless.miravy.com/api/services/{service-id}/openapi \
-o my-service-openapi.jsonレート制限ヘッダーの確認
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 ヘッダーを確認し、キーがダッシュボードで無効化されていないか確認してください。
{
"error": {
"type": "auth",
"code": "INVALID_API_KEY",
"message": "Invalid API key"
}
}429 Too Many Requests
Free プランの月間上限、または短時間あたりの制限に達しています。 X-RateLimit-Reset ヘッダーで次のリセット時刻を確認してください。Free は月次上限に達するとブロックされ、有料プランでは超過分が従量課金として処理されます。
{
"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 メッセージも確認してください。
{
"error": {
"type": "upstream",
"code": "SOAP_FAULT",
"message": "Upstream SOAP service returned a fault",
"detail": "Server was unable to process request: timeout"
}
}リトライ戦略
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
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
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
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 から実行できます。
メールでの連絡は、セキュリティ、プライバシー、法務、法人導入、またはダッシュボードから復旧できないアカウント問題に限定しています。
次のステップ
- API リファレンス — エンドポイント・レスポンスコード・エラータイプの詳細
- アカウントを作成 — 月 100 回の API コールを無料で利用可能
- 料金プランを見る — チームに合ったプランを選択