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.
Maintainers
Readme
coretax-xml
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.
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-xmlButuh Node.js 18 atau lebih baru.
Pakai dari baris perintah
Dari JSON:
npx coretax-xml faktur faktur.json -o faktur.xmlDari 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.xmlLembar 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.jsonContoh 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 galatvalidateTaxInvoices(batch)tidak pernah melempar galat. Hasilnya daftar{ path, code, message, severity }.buildTaxInvoiceXml(batch)memeriksa dulu. Bila ada masalah berjeniserror, ia melemparCoretaxValidationErroryang membawa daftar lengkapnya di.issues. Peringatan tidak menghentikannya.batchFromCsv(fakturCsv, detailCsv, sellerTin?)mengubah dua teks CSV menjadibatch.sellerTinboleh dihilangkan bila CSV faktur diawali barisNPWP 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 bukan000000. - Pembeli
TINdengan NPWP0000000000000000. - 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
Passportkosong; email yang tampaknya salah. - Pembeli ber-NPWP dengan negara selain
IDN. Contoh XML DJP sendiri memakaiIND, 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 ditest/fixturesdan menjadi pembanding dalam tes. - Aturan dan kode rujukan:
Sample Faktur PK Template v.1.6.1.xlsxdariConverterEfakturCoretax__v1.6.zip. Lembar rujukannya disimpan didata/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
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-xmlnpx 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.jsonimport { 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
pathsuch asinvoices[0].items[2].vat, a stablecode, a message in Indonesian, and aseverityoferrororwarning. - Amounts are numbers or strings with at most two decimals. Values with float noise are rejected, not rounded.
- CSV input: DJP's
Faktursheet starts with anNPWP Penjualrow, which supplies the seller NPWP (--npwpis then optional). Dates must beDD/MM/YYYYwith two digits orYYYY-MM-DD; US-locale dates like4/8/2025are 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 suggestsIDN. - 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.
