สร้างกำหนดการเรียกเก็บเงินแบบกลุ่ม

POSThttps://api.omise.co/schedules/upload

อัปโหลดไฟล์ CSV เพื่อสร้างกำหนดการเรียกเก็บเงินหลายรายการในการดำเนินการครั้งเดียว Endpoint นี้เริ่มต้นงานสร้างแบบกลุ่มแบบอะซิงโครนัสและส่งคืน recurring_id ที่คุณสามารถใช้ตรวจสอบความคืบหน้าและดาวน์โหลดรายงานสถานะ

---

🔑ข้อมูลยืนยันตัวตน API

▼

---

พารามิเตอร์คำขอ

จำเป็น - 1 ฟิลด์พารามิเตอร์ที่จำเป็น

▼

`file`FILE(required)

ไฟล์ CSV ที่มีข้อมูลกำหนดการเรียกเก็บเงิน แต่ละแถวแทนหนึ่งกำหนดการที่จะสร้าง

Example:"schedules.csv"

Constraints:ขนาดไฟล์สูงสุด: 10MB, รูปแบบ: CSV, แถวสูงสุด: 10,000

โครงสร้าง CSVคอลัมน์ CSV

▼

`customer_key`STRING(required)

ตัวระบุเฉพาะสำหรับติดตามแถวนี้ในรายงานสถานะ สามารถเป็นสตริงใดก็ได้ที่มีความหมายต่อระบบของคุณ

Example:"sub_001"

`customer`STRING(required)

Customer ID (cust_*) ที่จะถูกเรียกเก็บเงิน ลูกค้าต้องมีบัตรแนบอยู่อย่างน้อยหนึ่งใบ

Example:"cust_test_5xuy4w91xqz7d1w9u0t"

`card`STRING(optional)

Card ID เฉพาะที่จะเรียกเก็บเงิน หากไม่ระบุ จะใช้บัตรเริ่มต้นของลูกค้า

Example:"card_test_5xuy4w91xqz7d1w9u0t"

`amount`INTEGER(required)

จำนวนเงินที่เรียกเก็บในหน่วยสกุลเงินที่เล็กที่สุด (เช่น สตางค์สำหรับ THB, cents สำหรับ USD)

Example:100000

`description`STRING(optional)

คำอธิบายที่จะปรากฏในแต่ละการเรียกเก็บเงินที่สร้างโดยกำหนดการนี้

Example:"Monthly subscription fee"

`every`INTEGER(required)

ตัวคูณความถี่ ตัวอย่างเช่น every=2 กับ period=month หมายถึงทุก 2 เดือน

Example:1

`period`STRING(required)

หน่วยเวลาสำหรับความถี่ของกำหนดการ

Example:"month"

Values:day, week, month

`days_of_month`STRING(optional)

สำหรับกำหนดการรายเดือน: วันที่เฉพาะที่จะเรียกเก็บเงิน (1-28) ใช้เซมิโคลอนเพื่อระบุหลายวัน

Example:"1;15"

`start_date`STRING(optional)

วันที่เริ่มต้นกำหนดการในรูปแบบ YYYY-MM-DD ค่าเริ่มต้นเป็นวันนี้หากไม่ระบุ

Example:"2025-02-01"

`end_date`STRING(optional)

วันที่สิ้นสุดกำหนดการในรูปแบบ YYYY-MM-DD กำหนดการจะหมดอายุหลังจากวันที่นี้

Example:"2025-12-31"

---

การตอบกลับ

200

ยอมรับการอัปโหลด

ไฟล์ CSV ได้รับการยอมรับและงานสร้างแบบกลุ่มได้เข้าคิวแล้ว ใช้ recurring_id ที่ส่งคืนเพื่อตรวจสอบความคืบหน้า

การตอบกลับประกอบด้วย:

• object - เป็น "recurring_export" เสมอ
• id - Recurring export ID (recr_*) สำหรับติดตามงาน
• livemode - ว่าเป็นการดำเนินการในโหมด live หรือไม่
• location - พาธ API เพื่อตรวจสอบงาน
• state - สถานะเริ่มต้น (โดยทั่วไปเป็น "pending")
• total_rows - จำนวนแถวที่ตรวจพบใน CSV
• processed_rows - จำนวนแถวที่ประมวลผลแล้ว (0 ในตอนแรก)
• successful_rows - จำนวนการสร้างที่สำเร็จ (0 ในตอนแรก)
• failed_rows - จำนวนการสร้างที่ล้มเหลว (0 ในตอนแรก)
• created_at - เวลาที่สร้างงาน

400

คำขอไม่ถูกต้อง

การตรวจสอบคำขอล้มเหลว ตรวจสอบข้อความข้อผิดพลาดสำหรับรายละเอียด

สาเหตุทั่วไป:

• ไฟล์หายไปหรือว่างเปล่า
• รูปแบบหรือโครงสร้าง CSV ไม่ถูกต้อง
• คอลัมน์ที่จำเป็นหายไปในหัว CSV
• ไฟล์เกินขีดจำกัดขนาด 10MB
• CSV มีมากกว่า 10,000 แถว

401

ไม่ได้รับอนุญาต

การยืนยันตัวตนล้มเหลว API key ไม่ถูกต้องหรือหายไป

สาเหตุทั่วไป:

• ไม่มี Authorization header
• Secret key ไม่ถูกต้อง
• ใช้ public key แทน secret key
• รูปแบบ HTTP Basic Auth ไม่ถูกต้อง

404

ไม่พบ

ไม่พบ endpoint หรือฟีเจอร์ไม่ได้เปิดใช้งาน

สาเหตุทั่วไป:

• ฟีเจอร์การดำเนินการแบบกลุ่มไม่ได้เปิดใช้งานสำหรับบัญชี
• URL ของ API endpoint ไม่ถูกต้อง

5xx

ข้อผิดพลาดเซิร์ฟเวอร์

เกิดข้อผิดพลาดฝั่งเซิร์ฟเวอร์ เหตุการณ์เหล่านี้หายากแต่ควรจัดการอย่างเหมาะสม

วิธีจัดการ:

• ลองคำขอใหม่ด้วย exponential backoff
• ตรวจสอบ status.omise.co สำหรับเหตุการณ์บริการ
• ดู การจัดการข้อผิดพลาด สำหรับคำแนะนำโดยละเอียด

---

ตัวอย่างโค้ด

cURL

# อัปโหลดไฟล์ CSV เพื่อสร้างกำหนดการเรียกเก็บเงินหลายรายการ
curl https://api.omise.co/schedules/upload \
  -X POST \
  -u skey_test_5xuy4w91xqz7d1w9u0t: \
  -F "file=@/path/to/schedules.csv"

Ruby

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

Omise.api_key = 'skey_test_5xuy4w91xqz7d1w9u0t'

uri = URI('https://api.omise.co/schedules/upload')
request = Net::HTTP::Post.new(uri)
request.basic_auth(Omise.api_key, '')

form_data = [['file', File.open('/path/to/schedules.csv')]]
request.set_form(form_data, 'multipart/form-data')

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

result = JSON.parse(response.body)
puts "Job ID: #{result['id']}"

Python

import omise
import requests

omise.api_secret = 'skey_test_5xuy4w91xqz7d1w9u0t'

with open('/path/to/schedules.csv', 'rb') as csv_file:
    response = requests.post(
        'https://api.omise.co/schedules/upload',
        auth=(omise.api_secret, ''),
        files={'file': csv_file}
    )

result = response.json()
print(f"Job ID: {result['id']}")
print(f"Total rows: {result['total_rows']}")

Node.js

const omise = require('omise')({
  secretKey: 'skey_test_5xuy4w91xqz7d1w9u0t'
});
const fs = require('fs');
const FormData = require('form-data');
const axios = require('axios');

const form = new FormData();
form.append('file', fs.createReadStream('/path/to/schedules.csv'));

const response = await axios.post('https://api.omise.co/schedules/upload', form, {
  auth: {
    username: 'skey_test_5xuy4w91xqz7d1w9u0t',
    password: ''
  },
  headers: form.getHeaders()
});

console.log('Job ID:', response.data.id);
console.log('Total rows:', response.data.total_rows);

PHP

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

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://api.omise.co/schedules/upload',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_USERPWD => OMISE_SECRET_KEY . ':',
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('/path/to/schedules.csv', 'text/csv', 'schedules.csv')
    ]
]);

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

$result = json_decode($response, true);
echo "Job ID: " . $result['id'] . "\n";
echo "Total rows: " . $result['total_rows'] . "\n";

Java

import java.io.File;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.util.Base64;

HttpClient client = HttpClient.newHttpClient();

String boundary = "----WebKitFormBoundary" + System.currentTimeMillis();
File csvFile = new File("/path/to/schedules.csv");
byte[] fileBytes = Files.readAllBytes(csvFile.toPath());

String body = "--" + boundary + "\r\n" +
    "Content-Disposition: form-data; name=\"file\"; filename=\"schedules.csv\"\r\n" +
    "Content-Type: text/csv\r\n\r\n" +
    new String(fileBytes) + "\r\n" +
    "--" + boundary + "--";

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

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.omise.co/schedules/upload"))
    .header("Authorization", "Basic " + auth)
    .header("Content-Type", "multipart/form-data; boundary=" + boundary)
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .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);

using var content = new MultipartFormDataContent();
using var fileStream = File.OpenRead("/path/to/schedules.csv");
var fileContent = new StreamContent(fileStream);
fileContent.Headers.ContentType = new MediaTypeHeaderValue("text/csv");
content.Add(fileContent, "file", "schedules.csv");

var response = await client.PostAsync("https://api.omise.co/schedules/upload", content);
var result = await response.Content.ReadAsStringAsync();

Console.WriteLine(result);

Go

package main

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

func main() {
    file, _ := os.Open("/path/to/schedules.csv")
    defer file.Close()

    body := &bytes.Buffer{}
    writer := multipart.NewWriter(body)
    part, _ := writer.CreateFormFile("file", "schedules.csv")
    io.Copy(part, file)
    writer.Close()

    req, _ := http.NewRequest("POST", "https://api.omise.co/schedules/upload", body)
    req.SetBasicAuth("skey_test_5xuy4w91xqz7d1w9u0t", "")
    req.Header.Set("Content-Type", writer.FormDataContentType())

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

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("Job ID: %s\n", result["id"])
}

---

ตัวอย่างไฟล์ CSV

customer_key,customer,card,amount,description,every,period,days_of_month,start_date,end_date
sub_001,cust_test_5xuy4w91xqz7d1w9u0t,,100000,Monthly premium plan,1,month,1,2025-02-01,2026-01-31
sub_002,cust_test_5xuy4w91xqz7d1w9u0t,card_test_5xuy4w91xqz7d1w9u0t,50000,Basic subscription,1,month,15,2025-02-01,
sub_003,cust_test_5xuy4w91xqz7d1w9u0t,,200000,Enterprise plan,1,month,1;15,2025-02-01,2025-12-31

---

รหัสข้อผิดพลาดและผลลัพธ์

รหัสข้อผิดพลาดทั่วไป

รหัส	คำอธิบาย	การแก้ไข
authentication_failure	API key ไม่ถูกต้อง	ตรวจสอบว่า secret key ของคุณถูกต้อง
invalid_file	ไฟล์หายไปหรือไม่ถูกต้อง	ตรวจสอบว่าไฟล์เป็น CSV ที่ถูกต้อง
file_too_large	ไฟล์เกินขีดจำกัด 10MB	แบ่งเป็นไฟล์ขนาดเล็กลง
invalid_csv_structure	คอลัมน์ที่จำเป็นหายไป	ตรวจสอบแถวหัว CSV
too_many_rows	CSV เกิน 10,000 แถว	แบ่งเป็นหลายไฟล์

รหัสข้อผิดพลาดแถว CSV

รหัส	คำอธิบาย	การแก้ไข
invalid_customer	ไม่พบ Customer ID	ตรวจสอบว่าลูกค้ามีอยู่
no_card_attached	ลูกค้าไม่มีบัตร	แนบบัตรให้ลูกค้าก่อน
invalid_card	ไม่พบ Card ID หรือหมดอายุ	ใช้ Card ID ที่ถูกต้อง
invalid_amount	จำนวนเงินไม่ถูกต้อง	ใช้จำนวนเต็มบวก
invalid_period	ค่า period ไม่ถูกต้อง	ใช้ day, week, หรือ month
invalid_date_format	รูปแบบวันที่ไม่ถูกต้อง	ใช้รูปแบบ YYYY-MM-DD

---

ลองใช้งาน

จำเป็น - 1 ฟิลด์

▼

file(จำเป็น)

Choose Fileเลือกไฟล์ CSV...

IP ของคุณ: ...กำลังโหลด...