Data Export

Overview

API Data Export memungkinkan merchant untuk mengekspor dataset dalam jumlah besar seperti payments, dan disbursement untuk keperluan pelaporan operasional, rekonsiliasi, atau analisis data.

Proses ekspor dilakukan secara asynchronous (tidak langsung) untuk menghindari timeout dan memastikan performa sistem tetap optimal. Merchant dapat membuat job ekspor yang berjalan di background, kemudian mengambil file hasil ekspor setelah proses selesai.

Format yang Didukung: Saat ini hanya format CSV yang didukung.

Fitur Utama

Fitur	Deskripsi
Asynchronous Processing	Ekspor diproses di background tanpa blocking API call
Job Tracking	Monitoring status ekspor melalui report id
Flexible Filtering	Filter berdasarkan tanggal dan status
Secure Access	Hanya user yang ter-autentikasi dapat mengakses file ekspor mereka

Authentication

API Data Export menggunakan mekanisme autentikasi yang sama dengan SNAP API lainnya. Pastikan Anda sudah memiliki Bearer Token sebelum melakukan request. Lihat Authentication untuk detailnya.

Endpoints

1. Create Export Job

Endpoint ini digunakan untuk membuat job ekspor data secara asynchronous.

Method: POST
Development: https://sandbox.kirimo.co/v1.0/data/export
Production: https://api.kirimo.co/v1.0/data/export
Content-Type: application/json

Headers

Parameter	Tipe	Mandatori	Keterangan	Contoh
Content-Type	string	✓	Tipe media yang digunakan	application/json
Authorization	string	✓	Bearer token dari endpoint Get Token	Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
X-TIMESTAMP	string	✓	Timestamp format ISO-8601	2025-10-27T13:00:00+07:00
X-SIGNATURE	string	✓	Signature HMAC_SHA512	Lihat Signature Formula
X-CLIENT-KEY	string	✓	Client Key	DXXXX

Request Body

Parameter	Tipe	Mandatori	Keterangan	Contoh
resourceType	string	✓	Tipe data	transactions
format	string	✓	Format file	csv
filters	object	✓	Filter data
filters.startDate	string	✓	Tanggal mulai	2025-10-01
filters.endDate	string	✓	Tanggal akhir	2025-10-27
filters.status	string		Status transaksi	SUCCESS
filters.businessId	int	x	Child business	1
callbackUrl	string	x	Callback HTTPS	https://callback-url.com/receive

Validation Rules


Field	Aturan Validasi	Contoh Valid	Contoh Invalid
resourceType	Harus salah satu dari: qris, va, ewallet, cc, disbursement, transaction, unified_cash_in, unified_cash_out	✅ transaction	❌ invalid_type
format	Hanya csv yang didukung	✅ csv	❌ pdf, xlsx
startDate	Harus dalam format ISO 8601 (YYYY-MM-DD)	✅ 2025-10-01	❌ 01-10-2025
endDate	Harus dalam format ISO 8601 (YYYY-MM-DD)	✅ 2025-10-27	❌ 27/10/2025
Date Range	startDate harus lebih kecil atau sama dengan endDate	✅ start: 2025-10-01, end: 2025-10-27	❌ start: 2025-10-27, end: 2025-10-01
Date Range Length	Maksimal 1 bulan (31 hari)	✅ start: 2025-10-01, end: 2025-10-31	❌ start: 2025-10-01, end: 2025-11-25
Past Data Only	endDate harus kurang dari tanggal hari ini (UTC)	✅ 2025-10-26 (jika hari ini 27 Okt)	❌ 2025-10-27 (jika hari ini 27 Okt)
Date Range To Long	Tidak boleh melebihi dari 1 bulan
Minimum Data Age	Data yang diekspor minimal berumur 1 hari	✅ Data hingga kemarin	❌ Data hari ini
callbackUrl	Jika terisi wajib menggunakan https	✅ https	❌ http only, url only

Example Request

{
  "resourceType": "transactions",
  "format": "csv",
  "filters": {
    "startDate": "2025-10-01",
    "endDate": "2025-10-27",
    "status": "SUCCESS",
    "businessId": 994
  }
}

Response

Success Response (200)

{
  "responseCode": "2000000",
  "responseMessage": "Publish job successfully",
  "reportId": "exp_01J9Y4V34ZKFG5Q7E9YNM9W22R"
}

Validation Error (422)

{
  "responseCode": "422000",
  "responseMessage": "Date Range Required"
}

2. Get Export Job Status

Endpoint ini digunakan untuk mengambil status job ekspor dan file hasil ekspor jika sudah selesai.

Method: GET
Development: https://sandbox.kirimo.co/v1.0/data/export/{reportId}
Production: https://api.kirimo.co/v1.0/data/export/{reportId}

Headers


Parameter	Tipe	Mandatori	Keterangan	Contoh
Authorization	string	✓	Bearer token dari endpoint Get Token	Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
X-TIMESTAMP	string	✓	Timestamp dalam format ISO-8601	2025-10-27T13:00:00+07:00
X-SIGNATURE	string	✓	Signature menggunakan HMAC_SHA512 (symmetric)	Lihat Signature Formula
X-CLIENT-KEY	string	✓	Client Key dari Menu Setting	DXXXX

Path Parameters

Parameter	Tipe	Mandatori	Keterangan	Contoh
reportId	string	✓	ID job ekspor	01J9Y4V34ZKFG5Q7E9YNM9W22R

Response Examples

QUEUE Status (200)

Job telah dibuat dan dalam antrian menunggu untuk diproses oleh worker.

{
  "responseCode": "2000000",
  "reportId": "exp_01J9Y4V34ZKFG5Q7E9YNM9W22R",
  "status": "QUEUE",
  "resourceType": "transactions",
  "startDate": null,
  "endDate": null,
  "message": "Export job has been queued and will start processing shortly."
}

EXPORTING Status (200)

Job sedang dalam proses ekspor data dari database.

{
  "responseCode": "2000000",
  "reportId": "exp_01J9Y4V34ZKFG5Q7E9YNM9W22R",
  "status": "EXPORTING",
  "resourceType": "transactions",
  "startDate": "2025-10-01T00:00:00Z",
  "endDate": "2025-10-27T23:59:59Z",
  "message": "Export job is currently exporting data."
}

EXPORTED Status (200)

Data sudah berhasil diekspor dan file sudah diupload ke S3.

{
  "responseCode": "2000000",
  "reportId": "exp_01J9Y4V34ZKFG5Q7E9YNM9W22R",
  "status": "EXPORTED",
  "resourceType": "transactions",
  "startDate": "2025-10-01T00:00:00Z",
  "endDate": "2025-10-27T23:59:59Z",
  "message": "Export job data is already exported"
}

UPLOADING Status (200)

File sedang dalam proses upload ke SFTP server.

{
  "responseCode": "2000000",
  "reportId": "exp_01J9Y4V34ZKFG5Q7E9YNM9W22R",
  "status": "UPLOADING",
  "resourceType": "transactions",
  "startDate": "2025-10-01T00:00:00Z",
  "endDate": "2025-10-27T23:59:59Z",
  "message": "Export job is currently uploading file"
}

COMPLETED Status (200)

Seluruh proses berhasil diselesaikan dan file siap diakses.

{
  "responseCode": "2000000",
  "responseMessage": "Export job has been completed and uploaded to SFTP.",
  "reportId": "01KFJ4PWM81CFV1FJ9JGTM6J9V",
  "filters": {
    "startDate": "2026-01-01",
    "endDate": "2026-01-31",
    "status": ["all"],
    "businessId": 993
  },
  "status": "COMPLETED",
  "resourceType": "transaction",
  "startAt": "2026-01-22T06:01:48",
  "completedAt": "2026-01-22T06:01:49",
  "fileUrl": "https://storage.kirimo.co/export/merchant-name-transactions-2025-10-01-2025-10-27-SUCCESS.csv"
}

FAILED Status (200)

Proses ekspor gagal karena terjadi error.

{
  "responseCode": "2000000",
  "reportId": "01KFJ4PWM81CFV1FJ9JGTM6J9V",
  "filters": {
    "startDate": "2025-12-01",
    "endDate": "2025-12-31",
    "status": ["all"],
    "businessId": 993
  },
  "status": "FAILED",
  "resourceType": "transaction",
  "startAt": "2026-01-22T06:01:48",
  "completedAt": "2026-01-22T06:01:49",
  "errorMessage": "Database timeout while fetching data."
}

Job Status Flow

Setiap job ekspor melalui status berikut secara berurutan:

Status	Deskripsi
QUEUE	Job telah dibuat dan dalam antrian menunggu worker untuk memproses
EXPORTING	Worker sedang mengekspor data dari database
EXPORTED	Data sudah berhasil diekspor dan file sudah diupload ke S3
UPLOADING	File sedang dalam proses upload ke SFTP server
COMPLETED	Seluruh proses berhasil diselesaikan (success flow)
FAILED	Proses ekspor gagal karena terjadi error

Status Transition Diagram

QUEUE → EXPORTING → EXPORTED → UPLOADING (IF SFTP SETTING ACTIVE) → COMPLETED
            ↓                        ↓
          FAILED                   FAILED`

Catatan: Status FAILED bisa terjadi di tahap EXPORTING, atau UPLOADING. Jika proses gagal di salah satu tahap, status akan langsung berubah menjadi FAILED dengan error_message yang menjelaskan penyebab kegagalan.

Signature Formula

API Data Export menggunakan Symmetric Signature (HMAC_SHA512) untuk keamanan request. Formula signature sama dengan endpoint SNAP API lainnya.

Formula

stringToSign = HttpMethod + ":" + Endpoint + ":" + AccessToken + ":" + LowerCase(HexEncode(SHA-256(Minify(RequestBody)))) + ":" + Timestamp  hash = HMAC_SHA512(stringToSign, secretKey) signature = Base64(hash)

Penjelasan

HttpMethod: Metode HTTP yang digunakan (POST atau GET)
Endpoint: Relative URL tanpa domain (contoh: /v1.0/data/export)
AccessToken: Bearer token yang didapat dari endpoint Get Token
RequestBody: Payload yang dikirim (untuk method POST only)
Timestamp: Timestamp dalam format ISO-8601
secretKey: Client Key dari menu API Key

Hash stringToSign menggunakan algoritma HMAC_SHA512 dengan secret key, kemudian encode dengan Base64. Masukkan hasilnya ke header X-SIGNATURE.

Security & Limitations

Access Control

Aturan	Deskripsi
Authentication	Wajib menggunakan Bearer Token (OAuth 2.0) atau API Key
Ownership Validation	Merchant hanya dapat mengakses export job mereka sendiri
Authorization	Setiap request divalidasi dengan X-SIGNATURE

Rate Limiting

Limit	Nilai
Concurrent Jobs	Maksimal 5 job per menit aktif per business
Rate Limit Response	HTTP 429 - Too Many Requests

File Policies

Policy	Nilai
File Format	Hanya CSV yang didukung
Filename Convention	`{business_name}-{resource_type}-{start_date}-{end_date}-{status}.csv`

Penting:fileUrl link hanya valid selama 1 jam sejak status job berubah menjadi COMPLETED.

Resource Types & Data Structure

Supported Resource Types

Resource Type	Deskripsi	Filter Fields
transaction	Semua transaksi (multi-payment)	startDate, endDate, status
qris	Transaksi QRIS	startDate, endDate, status
va	Transaksi Virtual Account	startDate, endDate, status
ewallet	Transaksi E-Wallet	startDate, endDate, status
cc	Transaksi Credit Card	startDate, endDate, status
disbursement	Transaksi Disbursement	startDate, endDate, status
unified_cash_in	Cash In transactions	startDate, endDate, status
unified_cash_out	Cash Out transactions	startDate, endDate, status

CSV Data Structure

Setiap resource type memiliki struktur kolom yang berbeda. Berikut contoh struktur untuk transactions:

transaction_id,merchant_id,merchant_name,amount,fee,net_amount,currency,status,payment_method,created_at,updated_at,settled_at TRX123456,MER001,Merchant Name,100000,1500,98500,IDR,SUCCESS,qris,2025-10-27T08:00:00Z,2025-10-27T08:01:00Z,2025-10-28T00:00:00Z TRX123457,MER001,Merchant Name,250000,3750,246250,IDR,SUCCESS,va,2025-10-27T09:00:00Z,2025-10-27T09:02:00Z,2025-10-28T00:00:00Z

Error Codes

HTTP Code	Message	Keterangan	Solusi
200	Success	Request berhasil diproses	-
400	Bad Request	Format request tidak valid	Periksa format request body
401	Unauthorized	Token tidak valid atau expired	Generate token baru
422	Validation Error	Validasi parameter gagal	Periksa parameter sesuai validation rules
429	Too Many Requests	Melebihi rate limit (5 concurrent jobs)	Tunggu hingga waktu limit per menit sebelumnya selesai
500	Internal Server Error	Error pada sistem server	Coba lagi atau hubungi support

Overview​

Fitur Utama​

Authentication​

Endpoints​

1. Create Export Job​

Headers​

Request Body​

Validation Rules​

Example Request​

Response​

2. Get Export Job Status​

Headers​

Path Parameters​

Response Examples​

Job Status Flow​

Status Transition Diagram​

Signature Formula​

Formula​

Penjelasan​

Security & Limitations​

Access Control​

Rate Limiting​

File Policies​

Resource Types & Data Structure​

Supported Resource Types​

CSV Data Structure​

Error Codes

Overview

Fitur Utama

Authentication

Endpoints

1. Create Export Job

Headers

Request Body

Validation Rules

Example Request

Response

2. Get Export Job Status

Headers

Path Parameters

Response Examples

Job Status Flow

Status Transition Diagram

Signature Formula

Formula

Penjelasan

Security & Limitations

Access Control

Rate Limiting

File Policies

Resource Types & Data Structure

Supported Resource Types

CSV Data Structure