一括作成の進捗監視

GEThttps://api.omise.co/recurring_exports/:recurring_id

一括課金スケジュール作成ジョブの現在のステータスを取得します。このエンドポイントを使用して、進捗の追跡、完了ステータスの確認、ステータスレポートのダウンロード準備ができたタイミングの判断を行います。

---

🔑API認証情報

▼

---

リクエストパラメータ

必須 - 1フィールドパスパラメータ

▼

`recurring_id`STRING(required)

一括作成エンドポイントから返されたRecurring export ID。IDはrecr_で始まります。

Example:"recr_test_5xuy4w91xqz7d1w9u0t"

---

レスポンス

200

ジョブステータス取得

進捗の詳細を含む一括作成ジョブの現在のステータスを返します。

レスポンスに含まれる内容：

• object - 常に "recurring_export"
• id - Recurring export ID (recr_*)
• livemode - 本番モードの操作かどうか
• location - このリソースへのAPIパス
• state - 現在のジョブ状態（pending、processing、completed、failed）
• total_rows - CSV内の総行数
• processed_rows - これまでに処理された行数
• successful_rows - 正常に作成されたスケジュール数
• failed_rows - 作成に失敗した行数
• progress_percentage - 完了率（0-100）
• download_uri - ステータスレポートダウンロード用URI（完了時に利用可能）
• created_at - ジョブ作成タイムスタンプ
• completed_at - ジョブ完了タイムスタンプ（未完了の場合はnull）

400

不正なリクエスト

リクエストの検証に失敗しました。詳細はエラーメッセージを確認してください。

一般的な原因：

• 無効なrecurring_id形式
• recurring_idパラメータが欠落

401

認証エラー

認証に失敗しました。APIキーが無効または欠落しています。

一般的な原因：

• Authorizationヘッダーが欠落
• 無効なシークレットキー
• シークレットキーの代わりにパブリックキーを使用
• HTTP Basic Auth形式が不正

404

見つかりません

一括作成ジョブが見つかりません。

一般的な原因：

• 無効なrecurring_id
• ジョブが別のアカウントに属している
• テストモードと本番モードのキーを混同
• ジョブの有効期限が切れている（30日以上経過）

5xx

サーバーエラー

サーバー側でエラーが発生しました。これらは稀ですが、適切に処理する必要があります。

対処方法：

• 指数バックオフでリクエストをリトライ
• status.omise.coでサービスインシデントを確認
• 詳細なガイダンスはエラー処理を参照

---

コードサンプル

cURL

# 一括作成ジョブのステータスを確認
curl https://api.omise.co/recurring_exports/recr_test_5xuy4w91xqz7d1w9u0t \
  -u skey_test_5xuy4w91xqz7d1w9u0t:

Ruby

require 'omise'
require 'net/http'
require 'uri'
require 'json'

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

recurring_id = 'recr_test_5xuy4w91xqz7d1w9u0t'

uri = URI("https://api.omise.co/recurring_exports/#{recurring_id}")
request = Net::HTTP::Get.new(uri)
request.basic_auth(Omise.api_key, '')

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

result = JSON.parse(response.body)
puts "State: #{result['state']}"
puts "Progress: #{result['progress_percentage']}%"
puts "Successful: #{result['successful_rows']} / #{result['total_rows']}"

Python

import omise
import requests

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

recurring_id = 'recr_test_5xuy4w91xqz7d1w9u0t'

response = requests.get(
    f'https://api.omise.co/recurring_exports/{recurring_id}',
    auth=(omise.api_secret, '')
)

result = response.json()
print(f"State: {result['state']}")
print(f"Progress: {result['progress_percentage']}%")
print(f"Successful: {result['successful_rows']} / {result['total_rows']}")

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});
const axios = require('axios');

const recurringId = 'recr_test_5xuy4w91xqz7d1w9u0t';

const response = await axios.get(
  `https://api.omise.co/recurring_exports/${recurringId}`,
  {
    auth: {
      username: 'skey_test_5xuy4w91xqz7d1w9u0t',
      password: ''
    }
  }
);

console.log('State:', response.data.state);
console.log('Progress:', response.data.progress_percentage + '%');
console.log('Successful:', response.data.successful_rows, '/', response.data.total_rows);

PHP

<?php
define('OMISE_SECRET_KEY', 'skey_test_5xuy4w91xqz7d1w9u0t');

$recurring_id = 'recr_test_5xuy4w91xqz7d1w9u0t';

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.omise.co/recurring_exports/{$recurring_id}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => OMISE_SECRET_KEY . ':'
]);

$response = curl_exec($curl);
curl_close($curl);

$result = json_decode($response, true);
echo "State: " . $result['state'] . "\n";
echo "Progress: " . $result['progress_percentage'] . "%\n";
echo "Successful: " . $result['successful_rows'] . " / " . $result['total_rows'] . "\n";

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

HttpClient client = HttpClient.newHttpClient();

String recurringId = "recr_test_5xuy4w91xqz7d1w9u0t";
String auth = Base64.getEncoder().encodeToString("skey_test_5xuy4w91xqz7d1w9u0t:".getBytes());

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.omise.co/recurring_exports/" + recurringId))
    .header("Authorization", "Basic " + auth)
    .GET()
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

C#

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();

var credentials = Convert.ToBase64String(
    System.Text.Encoding.ASCII.GetBytes("skey_test_5xuy4w91xqz7d1w9u0t:")
);
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Basic", credentials);

var recurringId = "recr_test_5xuy4w91xqz7d1w9u0t";
var response = await client.GetAsync($"https://api.omise.co/recurring_exports/{recurringId}");
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine(result);

Go

package main

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

func main() {
    recurringId := "recr_test_5xuy4w91xqz7d1w9u0t"

    req, _ := http.NewRequest("GET",
        "https://api.omise.co/recurring_exports/"+recurringId, nil)
    req.SetBasicAuth("skey_test_5xuy4w91xqz7d1w9u0t", "")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

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

    fmt.Printf("State: %s\n", result["state"])
    fmt.Printf("Progress: %.0f%%\n", result["progress_percentage"])
}

---

完了までのポーリング

ジョブが完了するまでエンドポイントをポーリングする例：

Node.js

const axios = require('axios');

async function waitForCompletion(recurringId, maxAttempts = 60, intervalMs = 5000) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await axios.get(
      `https://api.omise.co/recurring_exports/${recurringId}`,
      {
        auth: { username: 'skey_test_5xuy4w91xqz7d1w9u0t', password: '' }
      }
    );

    const { state, progress_percentage, successful_rows, failed_rows, total_rows } = response.data;

    console.log(`Progress: ${progress_percentage}% (${successful_rows + failed_rows}/${total_rows})`);

    if (state === 'completed') {
      console.log(`Completed! Success: ${successful_rows}, Failed: ${failed_rows}`);
      return response.data;
    }

    if (state === 'failed') {
      throw new Error('Bulk creation job failed');
    }

    await new Promise(resolve => setTimeout(resolve, intervalMs));
  }

  throw new Error('Timeout waiting for job completion');
}

// 使用例
const result = await waitForCompletion('recr_test_5xuy4w91xqz7d1w9u0t');

Python

import time
import requests

def wait_for_completion(recurring_id, max_attempts=60, interval_sec=5):
    api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

    for _ in range(max_attempts):
        response = requests.get(
            f'https://api.omise.co/recurring_exports/{recurring_id}',
            auth=(api_secret, '')
        )
        result = response.json()

        state = result['state']
        progress = result['progress_percentage']
        successful = result['successful_rows']
        failed = result['failed_rows']
        total = result['total_rows']

        print(f"Progress: {progress}% ({successful + failed}/{total})")

        if state == 'completed':
            print(f"Completed! Success: {successful}, Failed: {failed}")
            return result

        if state == 'failed':
            raise Exception('Bulk creation job failed')

        time.sleep(interval_sec)

    raise Exception('Timeout waiting for job completion')

# 使用例
result = wait_for_completion('recr_test_5xuy4w91xqz7d1w9u0t')

---

エラーと結果コード

ジョブ状態

状態	説明	次のステップ
pending	ジョブはキューに入っています	待機して再度ポーリング
processing	ジョブはアクティブに実行中	待機して再度ポーリング
completed	ジョブ完了	ステータスレポートをダウンロード
failed	ジョブで致命的なエラー発生	エラーメッセージを確認し、アップロードをリトライ

一般的なエラーコード

コード	説明	解決方法
authentication_failure	無効なAPIキー	シークレットキーが正しいことを確認
not_found	ジョブが見つかりません	recurring_idが正しいことを確認
job_expired	ジョブデータの有効期限切れ	ジョブは30日間保持されます

---

試してみる

必須 - 1項目

▼

recurring_id(必須)

あなたのIP: ...読み込み中...