1rupiahDocs
EN

Bangun di atas API 1ERP

Hubungkan toko online, gudang, alat BI, dan aplikasi Anda sendiri ke 1ERP dengan aturan, persetujuan, dan jejak audit yang sama seperti di aplikasi.

1Mendapatkan akses

Admin membuat klien API di Pengaturan, API lalu memilih cakupannya. Klien tidak pernah bisa memegang lebih dari pembuatnya, dan tidak pernah memegang izin pengaturan pengguna, perusahaan, atau tagihan.

Rahasia hanya tampil sekali. Putar atau cabut kapan saja; token yang terbit dengan rahasia lama langsung berhenti.

2Autentikasi

Kirim kunci langsung sebagai bearer token untuk skrip sederhana, atau pakai OAuth2 client credentials untuk aplikasi. Token akses berlaku satu jam dan bisa dipersempit ke cakupan yang lebih sedikit.

bash
curl https://api.1rupiah.biz.id/v1/api/whoami \
  -H "Authorization: Bearer 1rk_..."
bash
curl -X POST https://api.1rupiah.biz.id/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "1rc_...",
    "client_secret": "1rk_...",
    "scope": "sales.view"
  }'

3Membaca data

GET /v1/api/objects menampilkan objek yang bisa disinkronkan: parties, items, sales-orders, customer-invoices, purchase-orders, supplier-invoices, journals, dan employees. Setiap daftar berhalaman dengan kursor (limit 1 sampai 500, bawaan 100) dan bisa disaring dengan updated_since untuk sinkron bertahap. Kirim next_cursor sebagai cursor sampai nilainya null.

bash
curl "https://api.1rupiah.biz.id/v1/api/objects/sales-orders?limit=100&updated_since=2026-11-01T00:00:00Z" \
  -H "Authorization: Bearer 1rk_..."
json
{
  "object": "sales-orders",
  "items": [ { "id": "...", "doc_no": "SO/2026/11/0001", "status": "confirmed" } ],
  "next_cursor": "WyIyMDI2LTExLTAxVDAzOjAwOjAwWiIsIi4uLiJd"
}

4Menulis data

Penulisan memakai endpoint dan aturan yang sama dengan aplikasi, termasuk persetujuan. Kirim Idempotency-Key (8 sampai 128 karakter) pada POST, PUT, PATCH, dan DELETE: jawaban sukses diputar ulang selama 24 jam, dan kunci yang sama dengan isi berbeda ditolak. Perubahan memakai If-Match dengan versi baris.

bash
curl -X POST https://api.1rupiah.biz.id/v1/sales-orders \
  -H "Authorization: Bearer 1rk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-web-10293" \
  -d @order.json

5Galat

Setiap galat berbentuk sama: kode yang tetap, pesan dalam bahasa permintaan, rincian bila ada, dan request_id untuk disebutkan saat menghubungi dukungan.

json
{
  "error": {
    "code": "rate_limited",
    "message": "Terlalu banyak permintaan. Tunggu sebentar lalu coba lagi.",
    "details": { "retry_after_seconds": 12 },
    "request_id": "8e0e136b-d333-49e4-907d-34f94f3d9e00"
  }
}

6Webhook

Langganan peristiwa bisnis di Pengaturan, Integrasi, misalnya sales_order.confirmed, journal_entry.posted, semua peristiwa satu objek dengan sales_order.*, atau semuanya dengan *. Setiap kiriman ditandatangani di header X-1rupiah-Signature berbentuk t=<detik unix>,v1=<HMAC SHA256 dari "t.body">. Kiriman gagal diulang setelah 1, 5, dan 30 menit, lalu 2, 6, dan 24 jam. Endpoint yang terus gagal dimatikan dan peristiwa webhook_endpoint.disabled diterbitkan; nyalakan lagi di Pengaturan, Integrasi.

javascript
import { createHmac, timingSafeEqual } from 'node:crypto';

// header: X-1rupiah-Signature, rawBody: isi permintaan apa adanya (sebelum JSON.parse)
function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  return parts.v1?.length === expected.length && timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

7Batasan

600 permintaan per menit per klien, terlihat di header X-RateLimit-Limit dan X-RateLimit-Remaining. Melebihi batas dijawab 429 dengan retry_after_seconds. Pengguna yang dibatasi ke cabang atau proyek tertentu tetap terbatas lewat API.

8Referensi

Spesifikasi OpenAPI 3.1 dibangun dari rute yang berjalan: https://api.1rupiah.biz.id/v1/openapi.json.