IAMs API v1 Public Spec

Panduan Integrasi IAMs API v1

Panduan ini membahas cara Anda mengirim data transaksi ke sistem kami lewat IAMs API v1. Fokusnya: skema payload, validasi teknis, dan mekanisme keamanan agar request tetap aman dan konsisten.

Base: /v1 HMAC + Timestamp + Nonce Mode: Batch Array
Quick Start
1
Generate Session Key
POST /v1/generate-key
2
Sync Data
POST /v1/sync
Mulai cepat →
⚡

Ringkas

Anda perlu meminta session key sebelum mengirim data transaksi. Setiap request wajib memuat signature HMAC dan proteksi replay via timestamp + nonce.

Nonce dibuat oleh Anda untuk setiap request (unik dan tidak boleh dipakai ulang). Rekomendasi format: UUID v4.

🪪

Kredensial Wajib

Untuk bisa mengakses IAMs API v1, Anda wajib memiliki:

  • vendor_id (kode integrasi Anda) → diberikan oleh tim kami.
  • master_key → diberikan oleh tim kami untuk generate session key.

Jika belum memiliki keduanya, silakan minta dulu ke tim kami. Tanpa kredensial ini, request akan ditolak.

🌐

Base URL (Publik)

Gunakan base berikut untuk akses publik:

BASE URL
https://api.toyotaintercom.com/v1

Catatan:

  • Akses /v1 langsung. Jangan gunakan root domain tanpa path karena akan di-redirect.
  • Endpoint: /v1/generate-key dan /v1/sync.
  • Jika Anda mendapat error redirect/HTML, pastikan URL sudah memakai /v1.

Header (Tanpa X-)

Generate Session Key

Master-Key Timestamp Nonce

Sync Data

Session-Key Timestamp Nonce Signature

Nonce adalah nilai acak unik yang Anda buat untuk setiap request. Jangan pernah menggunakan nonce yang sama dua kali. Format yang disarankan: UUID v4.

🔑

1) Generate Session Key

POST
Endpoint
/v1/generate-key

Request Body:

{
  "vendor_id": "iams"
}

Response Sukses:

{
  "status": true,
  "message": "Session key dibuat.",
  "data": {
    "session_key": "<string>",
    "expires_at": "2026-02-25T10:00:00Z"
  }
}
🔄

2) Sync Data Transaksi

POST
Endpoint
/v1/sync

Formula Signature:

HMAC_SHA256( raw_body + "." + Timestamp + "." + Nonce , session_key )

Request Body:

{
  "items": [
    {
      "no_spk": "25PDG01124",
      "tgl_spk": "2026-01-08T11:17:41Z",
      "tgl_transaksi": "2026-01-08T13:05:00Z",
      "kacab": "TJEN IMANUEL",
      "spv": "DENI USMAN EFENDI",
      "nik_spv": "1271211604790006",
      "jabatan_spv": "SPV II",
      "sales": "MEGA FITRIA",
      "nik_sales": "1371025306850011",
      "jabatan_sales": "SM",
      "type": "A351RA-GMEFJ 1.2 G M/T",
      "nama_debitur": "MIZEL PUTRA KAMTA QQ SRI LENA HARTATI",
      "nama_pembeli": "SRI LENA HARTATI",
      "nama_di_stnk": "SRI LENA HARTATI",
      "no_rangka": "MHKAB1BC6TJ077634",
      "no_mesin": "WA-A228957",
      "jenis_pembelian": "CASH/KREDIT/CAD",
      "leasing": "PT MAYBANK INDONESIA FINANCE",
      "wilayah": "PADANG",
      "nilai_asuransi": 8102220,
      "tr_asuransi": 2025555,
      "tr_n_asuransi": 5647506,
      "disc_unit": 10000000,
      "referensi": 1000000,
      "titipan": false,
      "model": "AGYA",
      "discount_stock_unit": 10000000,
      "proporsional": 1250000,
      "status_batal": "TIDAK BATAL",
      "tgl_pelunasan_leasing": "2026-02-13",
      "status_closing": false
    }
  ]
}

Field proporsional wajib dikirim sebagai angka / numeric (nominal).

ℹ️ Info Nilai Kosong
Field opsional boleh dikirim sebagai null atau string "null" (case-insensitive). Keduanya dianggap kosong oleh sistem.
tgl_transaksi wajib diisi (tidak boleh null atau kosong).
Contoh:
{
  "items": [
    {
      "no_spk": "25PDG01124",
      "tgl_pelunasan_leasing": null,
      "referensi": "null",
      "status_closing": "null"
    }
  ]
}

Response Sukses:

{
  "status": true,
  "message": "Sync berhasil.",
  "data": {
    "processed": 1
  }
}
📅

Format Tanggal

ISO 8601

2026-01-08T11:17:41Z

Legacy

2026-01-08 11:17:41

🧩

Aturan Upsert

no_spk bersifat unik. Jika no_spk yang sama dikirim kembali, data akan di-update sesuai payload terbaru.

🧪

Contoh cURL

Generate Key:

curl -X POST "https://api.toyotaintercom.com/v1/generate-key" \
  -H "Content-Type: application/json" \
  -H "Master-Key: <master_key>" \
  -H "Timestamp: 1708762800" \
  -H "Nonce: 6b31b4d3-5c2d-4f7a-9a2b-9d1b3b0a1f58" \
  -d '{"vendor_id":"iams"}'

Sync:

curl -X POST "https://api.toyotaintercom.com/v1/sync" \
  -H "Content-Type: application/json" \
  -H "Session-Key: <session_key>" \
  -H "Timestamp: 1708762800" \
  -H "Nonce: 9ad0f0c2-2d74-4f3f-9b9a-bc5c74c3f96f" \
  -H "Signature: <signature>" \
  -d '<raw_json_body>'
⚡ Template Postman (Rekomendasi)

Buka koleksi siap pakai di Postman untuk uji cepat.

Buka di Postman →
⚠️

Error Teknis

Pola error mengikuti praktik umum API di Indonesia: HTTP status resmi + code internal + message ringkas.

Format respons error

HTTP status tetap resmi (4xx/5xx). Di body ada code internal + message yang jelas. Opsional tambah details untuk info teknis.

{
  "status": false,
  "code": "TIMESTAMP_OUT_OF_WINDOW",
  "message": "Timestamp di luar rentang waktu yang diizinkan.",
  "details": {
    "max_skew_seconds": 300
  }
}
401 Auth / Signature
Master key tidak sesuai.
Session key belum diisi.
Session key sudah tidak valid.
Signature belum diisi.
Signature tidak cocok.
Timestamp tidak berada dalam rentang waktu yang diizinkan.
Timestamp belum diisi.
Format timestamp gak valid.
Nonce belum diisi.
409 Replay
Nonce sudah pernah dipakai.
403 Akses
Akses belum diizinkan (allowlist).
404 Referensi
Data pihak pengirim tidak ketemu.
422 Validasi
Format tgl_spk / tgl_transaksi belum bener.
Format tgl_pelunasan_leasing belum bener.