npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

coretax-xml

v0.1.0

Published

Periksa data Faktur Pajak Keluaran dan buat berkas XML untuk impor ke Coretax DJP. Validate Indonesian output tax invoices and generate Coretax import XML.

Readme

coretax-xml

CI npm license

Periksa data Faktur Pajak Keluaran dan buat berkas XML untuk diimpor ke Coretax DJP, dari JSON atau CSV. Pustaka dan alat baris perintah, tanpa dependensi.

English below.

Status: percobaan (0.x). Keluaran pustaka ini sama persis, karakter demi karakter, dengan berkas contoh resmi DJP, dan aturannya diambil dari templat Excel DJP. Namun belum ada laporan bahwa berkas hasil pustaka ini berhasil diimpor ke Coretax. Periksa hasilnya sebelum mengunggah, dan laporkan hasil impor Anda.

Proyek ini tidak berafiliasi dengan Direktorat Jenderal Pajak dan bukan nasihat perpajakan.

Kenapa

Coretax menerima impor faktur lewat XML. Cara resminya adalah mengisi templat Excel lalu menjalankan konverter DJP, sebuah program Windows. Itu sulit diotomatiskan dari sistem penagihan, dan kesalahan isian baru ketahuan setelah berkas ditolak.

Pustaka ini membuat XML yang sama langsung dari data Anda, dan memeriksa aturan templat lebih dulu: kode rujukan, panjang NPWP dan ID TKU, hitungan PPN, dan keterangan yang wajib untuk kode transaksi tertentu. Setiap masalah dilaporkan dengan letaknya.

Pasang

npm install coretax-xml

Butuh Node.js 18 atau lebih baru.

Pakai dari baris perintah

Dari JSON:

npx coretax-xml faktur faktur.json -o faktur.xml

Dari dua berkas CSV yang kolomnya sama dengan lembar Faktur dan DetailFaktur di templat Excel DJP:

npx coretax-xml faktur --faktur faktur.csv --detail detail.csv -o faktur.xml

Lembar Faktur DJP diawali baris NPWP Penjual; NPWP penjual diambil dari situ. Bila baris itu tidak ada, tambahkan --npwp 1090000000002325.

Tanggal di CSV ditulis DD/MM/YYYY dengan dua digit (08/04/2025) atau YYYY-MM-DD. Excel dengan pengaturan wilayah Amerika menulis 4/8/2025 (bulan dulu); tanggal seperti itu ditolak agar hari dan bulan tidak tertukar diam-diam. Simpan CSV dengan pengaturan wilayah Indonesia, atau ubah format sel tanggal ke dd/mm/yyyy sebelum menyimpan.

Periksa saja, tanpa membuat XML:

npx coretax-xml validate faktur.json

Contoh keluaran bila ada masalah:

GALAT      invoices[0].transactionCode: Kode transaksi harus "01" sampai "10".
PERINGATAN invoices[0].buyerName: Nama pembeli kosong. Coretax akan mengisinya dari data pembeli yang terdaftar.
1 galat, 1 peringatan.
XML tidak dibuat.

Kode keluar: 0 berhasil, 1 data memuat galat, 2 perintah atau berkas tidak dapat diproses. Contoh berkas masukan ada di folder examples.

Pakai dari kode

import { buildTaxInvoiceXml, validateTaxInvoices } from 'coretax-xml'
import type { TaxInvoiceBatch } from 'coretax-xml'

const batch: TaxInvoiceBatch = {
  sellerTin: '1090000000002325',
  invoices: [
    {
      date: '2025-04-08',
      transactionCode: '04',
      sellerIdTku: '1090000000002325000000',
      buyerTin: '1090000000002365',
      buyerIdType: 'TIN',
      buyerCountry: 'IDN',
      buyerName: 'PT Contoh Pembeli',
      buyerAddress: 'Jalan Bandung No. 1',
      buyerIdTku: '1090000000002365000000',
      items: [
        {
          kind: 'A',
          name: 'Barang ABC',
          unit: 'UM.0018',
          price: 12000000,
          quantity: 10,
          totalDiscount: 0,
          taxBase: 120000000,
          otherTaxBase: 110000000,
          vatRate: 12,
          vat: 13200000,
          stlgRate: 0,
          stlg: 0,
        },
      ],
    },
  ],
}

const issues = validateTaxInvoices(batch) // [] bila tidak ada masalah
const xml = buildTaxInvoiceXml(batch) // melempar CoretaxValidationError bila ada galat
  • validateTaxInvoices(batch) tidak pernah melempar galat. Hasilnya daftar { path, code, message, severity }.
  • buildTaxInvoiceXml(batch) memeriksa dulu. Bila ada masalah berjenis error, ia melempar CoretaxValidationError yang membawa daftar lengkapnya di .issues. Peringatan tidak menghentikannya.
  • batchFromCsv(fakturCsv, detailCsv, sellerTin?) mengubah dua teks CSV menjadi batch. sellerTin boleh dihilangkan bila CSV faktur diawali baris NPWP Penjual.

Isian

Nama isian di JSON dan padanannya di templat Excel DJP.

Faktur

| JSON | Kolom Excel DJP | Wajib | Keterangan | | --- | --- | --- | --- | | date | Tanggal Faktur | Ya | YYYY-MM-DD. Di CSV boleh DD/MM/YYYY dua digit. | | type | Jenis Faktur | Tidak | Selalu Normal (bawaan). | | transactionCode | Kode Transaksi | Ya | 01 sampai 10. | | additionalInfo | Keterangan Tambahan | 07, 08 | Kode TD.005xx. | | supportingDocument | Dokumen Pendukung | Tidak | | | supportingDocumentPeriod | Period Dok Pendukung | Tidak | MMYYYY, misalnya 012025. | | reference | Referensi | Tidak | | | facilityStamp | Cap Fasilitas | 07, 08 | Kode TD.011xx. | | sellerIdTku | ID TKU Penjual | Ya | 22 digit, diawali NPWP penjual. | | buyerTin | NPWP/NIK Pembeli | Ya | 16 digit. 0000000000000000 bila, dan hanya bila, jenis ID bukan TIN. | | buyerIdType | Jenis ID Pembeli | Ya | TIN, National ID, Passport, atau Other ID. | | buyerCountry | Negara Pembeli | Ya | Kode dari referensi DJP, misalnya IDN. IND adalah India. | | buyerDocumentNumber | Nomor Dokumen Pembeli | Bukan TIN | Untuk TIN, - ditulis sebagai elemen kosong. | | buyerName | Nama Pembeli | Selain TIN dan Passport | Untuk TIN dan Passport, Coretax mengisinya dari data yang terdaftar. | | buyerAddress | Alamat Pembeli | Bukan TIN | Untuk TIN, Coretax mengisinya dari data NPWP. | | buyerEmail | Email Pembeli | Tidak | | | buyerIdTku | ID TKU Pembeli | Ya | 22 digit untuk TIN, selain itu 000000. |

Barang dan jasa

| JSON | Kolom Excel DJP | Keterangan | | --- | --- | --- | | kind | Barang/Jasa | A barang, B jasa. | | code | Kode Barang Jasa | 6 digit. Bawaan 000000. | | name | Nama Barang/Jasa | | | unit | Nama Satuan Ukur | Kode UM.xxxx, misalnya UM.0018 untuk Unit. | | price | Harga Satuan | | | quantity | Jumlah Barang Jasa | | | totalDiscount | Total Diskon | 0 bila tidak ada. | | taxBase | DPP | | | otherTaxBase | DPP Nilai Lain | Sama dengan DPP bila tidak dipakai. | | vatRate | Tarif PPN | Dalam persen. | | vat | PPN | | | stlgRate | Tarif PPnBM | Dalam persen. 0 bila tidak ada. | | stlg | PPnBM | 0 bila tidak ada. |

Angka boleh berupa bilangan (15000.5) atau teks ("15000.50"), paling banyak dua angka di belakang koma. Pakai teks bila nilainya sangat besar.

Yang diperiksa

Galat (XML tidak dibuat):

  • NPWP bukan 16 digit, ID TKU bukan 22 digit, atau ID TKU penjual tidak diawali NPWP penjual.
  • Kode transaksi, satuan ukur, negara, atau jenis ID pembeli tidak ada di referensi DJP.
  • Keterangan tambahan atau cap fasilitas kosong untuk kode transaksi 07 dan 08, tidak ada di daftar kode transaksi itu, atau diisi untuk kode transaksi lain.
  • Tanggal bukan tanggal yang ada, atau periode dokumen pendukung bukan MMYYYY.
  • Pembeli tanpa NPWP: NPWP tidak diisi nol, nomor dokumen, nama (kecuali Passport), atau alamat kosong, atau ID TKU bukan 000000.
  • Pembeli TIN dengan NPWP 0000000000000000.
  • Angka negatif, lebih dari dua desimal, atau bilangan dengan galat pembulatan seperti 0.1 + 0.2.
  • PPN tidak sama dengan tarif × DPP nilai lain, untuk kode transaksi 01, 04, dan 09.
  • Total diskon melebihi harga × jumlah; faktur tanpa barang/jasa; teks berisi karakter yang tidak dapat ditulis ke XML.

Peringatan (XML tetap dibuat):

  • DPP tidak sama dengan harga × jumlah − diskon.
  • PPN tidak sama dengan tarif × DPP nilai lain, untuk kode transaksi selain 01, 04, 09.
  • PPnBM tidak sama dengan tarif × DPP nilai lain.
  • Nama atau alamat pembeli ber-NPWP kosong, atau nama pembeli Passport kosong; email yang tampaknya salah.
  • Pembeli ber-NPWP dengan negara selain IDN. Contoh XML DJP sendiri memakai IND, yang di daftar DJP berarti India.

Selisih di bawah satu rupiah dianggap pembulatan dan tidak dilaporkan.

Data rujukan

Semua daftar kode ikut diekspor sebagai Map:

import { UNITS, TRANSACTION_CODES, COUNTRIES, ADDITIONAL_INFO, FACILITY_STAMPS } from 'coretax-xml'

UNITS.get('UM.0018') // 'Unit'
ADDITIONAL_INFO['07'].get('TD.00501') // '1 - untuk Kawasan Bebas'
ADDITIONAL_INFO['08'].get('TD.00501') // '1 - untuk BKP dan JKP Tertentu'

| Ekspor | Isi | | --- | --- | | UNITS | 39 satuan ukur | | TRANSACTION_CODES | 10 kode transaksi | | BUYER_ID_TYPES | 4 jenis identitas pembeli | | GOODS_SERVICES | A dan B | | COUNTRIES | 254 kode negara | | ADDITIONAL_INFO | Keterangan tambahan: 31 kode untuk 07, 10 kode untuk 08 | | FACILITY_STAMPS | Cap fasilitas: 31 kode untuk 07, 10 kode untuk 08 |

Kode yang sama punya arti berbeda di bawah kode transaksi 07 dan 08, jadi keduanya dipisah.

Sumber

  • Bentuk XML: Sample Faktur PK Template v.1.4.xml. Berkas ini disimpan utuh di test/fixtures dan menjadi pembanding dalam tes.
  • Aturan dan kode rujukan: Sample Faktur PK Template v.1.6.1.xlsx dari ConverterEfakturCoretax__v1.6.zip. Lembar rujukannya disimpan di data/djp-reference-v1.6.1.json.

Keduanya diunduh dari halaman Template XML dan Converter Excel ke XML milik DJP.

Catatan tentang sumbernya:

  • Daftar negara DJP memuat 16 kode dua huruf di antara kode tiga huruf. Daftar itu dipakai apa adanya.
  • Nama elemen BuyerAdress (satu huruf d) mengikuti berkas contoh DJP.
  • Bila DJP menerbitkan templat baru, data rujukan dibangkitkan ulang dengan node scripts/generate-reference.mjs. Lihat CONTRIBUTING.md.

Cakupan

Versi ini hanya menangani Faktur Pajak Keluaran. Belum termasuk: retur, bukti potong, dokumen lain, lampiran SPT, dan membaca Excel secara langsung. Simpan lembar Faktur dan DetailFaktur masing-masing sebagai CSV untuk memakainya.

Ikut mengembangkan

Lihat CONTRIBUTING.md. Laporan hasil impor ke Coretax, berhasil maupun ditolak, adalah bantuan yang paling berharga.

Lisensi

MIT


English

Validate Indonesian output tax invoices (Faktur Pajak Keluaran) and generate the XML file that Coretax, the Indonesian tax authority's system, imports. A library and a CLI with zero dependencies.

Status: experimental (0.x). The output matches DJP's official sample file character for character, and the rules come from DJP's Excel template. No one has yet reported importing a file made by this library into Coretax. Not affiliated with the Directorate General of Taxes; not tax advice.

npm install coretax-xml
npx coretax-xml faktur faktur.json -o faktur.xml
npx coretax-xml faktur --faktur faktur.csv --detail detail.csv --npwp 1090000000002325 -o faktur.xml
npx coretax-xml validate faktur.json
import { buildTaxInvoiceXml, validateTaxInvoices } from 'coretax-xml'

const issues = validateTaxInvoices(batch) // never throws
const xml = buildTaxInvoiceXml(batch) // throws CoretaxValidationError on errors
  • Field names are English; the field tables above map each one to its column in DJP's Excel template.
  • Issues carry a path such as invoices[0].items[2].vat, a stable code, a message in Indonesian, and a severity of error or warning.
  • Amounts are numbers or strings with at most two decimals. Values with float noise are rejected, not rounded.
  • CSV input: DJP's Faktur sheet starts with an NPWP Penjual row, which supplies the seller NPWP (--npwp is then optional). Dates must be DD/MM/YYYY with two digits or YYYY-MM-DD; US-locale dates like 4/8/2025 are refused so day and month cannot swap silently.
  • DJP's own sample XML uses IND (India in DJP's list) as the country of a domestic buyer; this library warns and suggests IDN.
  • Reference tables (UNITS, TRANSACTION_CODES, COUNTRIES, ADDITIONAL_INFO, FACILITY_STAMPS, …) are generated from DJP's template v1.6.1 and exported.
  • Scope: output tax invoices only. Returns, withholding slips and direct Excel input are not covered yet.

License

MIT