API eFaktur: Validasi NPWP dan Konversi Angka ke Terbilang untuk Invoice

Kalau Anda pernah integrasi eFaktur atau bikin generator invoice untuk client Indonesia, dua masalah kecil ini muncul terus:

1. NPWP salah format. User input NPWP tanpa tanda baca, kelebihan digit, atau typo. eFaktur menolak di tahap akhir, padahal bisa ditolak di form sejak awal.
2. Angka terbilang. Setiap faktur dan kwitansi butuh baris terbilang, misalnya 250000 menjadi "dua ratus lima puluh ribu rupiah". Konversi manual rawan typo, dan kalau amount-nya dinamis, Anda butuh fungsi atau API yang konsisten.

Keduanya bisa diselesaikan dengan dua endpoint sederhana dari API Indonesia.

Endpoint yang Dipakai

Base URL: https://use.apiindonesia.id/api/v1

Method	Endpoint	Keterangan
POST	/validasi/npwp	Cek format NPWP 15 digit, sekaligus normalkan tanda bacanya
POST	/util/rupiah/format	Konversi angka ke string Rupiah

Validasi NPWP

curl -X POST "https://use.apiindonesia.id/api/v1/validasi/npwp" \
  -H "x-api-key: $API_INDONESIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"npwp":"01.234.567.8-901.000"}'

Response:

{
  "data": {
    "valid": true,
    "formatted": "01.234.567.8-901.000"
  }
}

Kalau user input "012345678901000" tanpa pemisah, endpoint tetap bisa menormalkan formatnya. Kalau digitnya kurang atau kelebihan, valid berisi false dan Anda bisa langsung menolak di form.

Konversi Angka ke Terbilang

Nilai seperti 250.000 yang sering muncul di invoice cukup dikirim sebagai angka:

curl -X POST "https://use.apiindonesia.id/api/v1/util/rupiah/format" \
  -H "x-api-key: $API_INDONESIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":250000}'

Response:

{
  "data": {
    "formatted": "Rp250.000",
    "amount": 250000
  }
}

Field formatted menghasilkan string Rupiah yang siap ditampilkan di invoice. Catatan penting: endpoint ini menghasilkan string terformat ("Rp250.000"), bukan terbilang kata per kata ("dua ratus lima puluh ribu rupiah"). Untuk baris terbilang di kwitansi, pola yang umum dipakai adalah simpan amount mentah di database, format tampilannya via API, dan render terbilang kata dari amount yang sama, jadi keduanya tidak pernah beda.

Contoh Integrasi JavaScript

Alur di aplikasi invoice: validasi NPWP klien saat submit form, lalu format nilai invoice jadi string Rupiah sebelum render PDF.

const BASE = "https://use.apiindonesia.id/api/v1";
const headers = {
  "x-api-key": process.env.API_INDONESIA_KEY,
  "Content-Type": "application/json",
};

async function validateNpwp(npwp) {
  const res = await fetch(`${BASE}/validasi/npwp`, {
    method: "POST",
    headers,
    body: JSON.stringify({ npwp }),
  });
  const { data } = await res.json();
  return data; // { valid, formatted }
}

async function formatRupiah(amount) {
  const res = await fetch(`${BASE}/util/rupiah/format`, {
    method: "POST",
    headers,
    body: JSON.stringify({ amount }),
  });
  const { data } = await res.json();
  return data.formatted;
}

// Dipakai di handler form invoice
app.post("/api/invoices", async (req, res) => {
  const npwp = await validateNpwp(req.body.npwp);
  if (!npwp.valid) {
    return res.status(400).json({ error: "Format NPWP tidak valid" });
  }
  const total = await formatRupiah(req.body.total);
  res.json({ npwp: npwp.formatted, total_terbilang: total });
});

Di Mana Letaknya di Pipeline eFaktur?

1. Form input: validasi NPWP penjual dan pembeli sebelum data masuk database.
2. Kalkulasi: format total, DPP, dan PPN jadi string Rupiah yang konsisten.
3. Render dokumen: invoice PDF atau CSV yang dikirim ke eFaktur pakai format yang sudah dinormalkan.

Endpoint validasi ini memeriksa struktur NPWP 15 digit, bukan verifikasi keberadaan NPWP ke DJP. Untuk kebutuhan verifikasi pajak formal, tetap gunakan layanan resmi DJP. Tapi untuk menyaring input salah format sejak dini, endpoint ini jauh lebih murah daripada error di tahap akhir.

Pelajari API lain yang relevan di halaman Developer Utilities dan API Validasi.

Mulai Sekarang

Dapatkan API key gratis di dashboard.apiindonesia.id/register dan coba kedua endpoint ini langsung dari terminal. Detail parameter lengkap ada di docs.apiindonesia.id.