Dokumentasi API

Kirim faktur pajak keluaran dari ERP apa pun (SAP, Oracle, Accurate, Odoo, ERP buatan sendiri) atau dari CoreTax Studio ke Coretax DJP lewat jalur resmi PJAP. Satu API REST JSON, sinkron status otomatis, NSFP kembali ke sistem Anda.

Base URL: https://coretaxgateway.eosteknologi.com/api/v1 · OpenAPI: /api/v1/openapi.json

Alur singkat

ERP/Studio kirim dokumen (POST /documents).
Gateway memvalidasi dengan aturan DJP (kode transaksi, satuan, NITKU, rumus PPN).
Dokumen jadi Draf (atau langsung antre bila autoSubmit).
Disetujui → dikirim ke DJP → status pending_djp.
DJP menyetujui (NSFP) atau menolak (alasan) → webhook ke ERP / Studio menarik status.

Autentikasi & lingkungan

Kirim header Authorization: Bearer <kunci>. Kunci dibuat di portal (menu Kunci API) dan hanya tampil sekali.

test ctg_test_… — simulator DJP. Gratis, tanpa kuota, tidak pernah menyentuh DJP. Cocok untuk pengembangan.
live ctg_live_… — dikirim ke DJP sungguhan. Aktif setelah akun diverifikasi EOS dan penandatangan entitas lengkap.

Contoh cepat

curl https://coretaxgateway.eosteknologi.com/api/v1/ping -H "Authorization: Bearer ctg_test_xxxxxxxx_…"

curl -X POST https://coretaxgateway.eosteknologi.com/api/v1/documents \
  -H "Authorization: Bearer ctg_test_xxxxxxxx_…" \
  -H "Content-Type: application/json" \
  -d @invoice.json

curl -X POST https://coretaxgateway.eosteknologi.com/api/v1/documents/doc_xxx/submit -H "Authorization: Bearer ctg_test_…"
curl "https://coretaxgateway.eosteknologi.com/api/v1/documents?updatedSince=2026-10-01T00:00:00Z" -H "Authorization: Bearer ctg_test_…"

Skema dokumen

Nama field mengikuti tag XML resmi DJP (TaxInvoice / GoodService) dalam camelCase, jadi pemetaan dari spesifikasi DJP langsung.

{
  "externalRef": "INV-2026-10-0001",
  "seller": { "tin": "0012345678901234", "idtku": "0012345678901234000000" },
  "invoiceDate": "2026-10-09",
  "trxCode": "04",
  "buyer": {
    "idType": "TIN",
    "tin": "1091031210911629",
    "idtku": "1091031210911629000000",
    "country": "IDN",
    "name": "PT Pembeli Contoh",
    "address": "Jl. Sudirman No. 1, Jakarta"
  },
  "items": [{
    "type": "A", "code": "000000", "name": "Spare part A-100", "unit": "UM.0018",
    "unitPrice": 1000000, "qty": 2, "discount": 0,
    "taxBase": 2000000, "otherTaxBase": 1833333.33,
    "vatRate": 12, "vat": 220000, "stlgRate": 0, "stlg": 0
  }]
}

Endpoint

GET	/ping	Tes koneksi & daftar entitas
POST	/documents	Buat 1–100 dokumen
GET	/documents	Daftar / sinkron (status, period, q, updatedSince, cursor)
GET	/documents/{id}	Detail + riwayat status
PUT	/documents/{id}	Koreksi draf/ditolak/gagal
POST	/documents/{id}/submit	Setujui & kirim ke DJP
POST	/documents/{id}/cancel	Batalkan sebelum terkirim
GET	/usage	Ringkasan masa & kuota

Status dokumen

draft	Validated, awaiting approval
queued	Queued (quota reserved)
submitting	Sending
pending_djp	Accepted by PJAP channel, awaiting DJP
approved	Approved by DJP, NSFP set
rejected	Rejected by DJP, see djpMessage; correct and resubmit
failed	Technical failure after retries
cancelled	Cancelled before sending

Galat

Setiap galat memakai kode stabil; message = Inggris, message_id = Indonesia. Sertakan requestId saat menghubungi support.

{ "error": { "code": "E_VALIDATION", "message": "Validation failed. See details.", "message_id": "Validasi gagal. Lihat rincian.",
    "details": [{ "field": "items[0].vat", "message": "PPN (1) tidak sesuai rumus …" }] }, "requestId": "9f2c…" }

E_AUTH_MISSING 401 · E_AUTH_INVALID 401 · E_LIVE_DISABLED 403 · E_SCOPE 403 · E_VALIDATION 422 · E_ENTITY_UNKNOWN 422 · E_SIGNER_MISSING 422 · E_IDEMPOTENCY 409 · E_STATE 409 · E_QUOTA 402 · E_BATCH_TOO_LARGE 413 · E_RATE_LIMIT 429 · E_INTERNAL 500

Webhook

POST <your-url>
X-CTG-Event: document.approved
X-CTG-Signature: t=1791500000,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>

{ "event": "document.approved", "deliveryId": 42, "createdAt": "…", "data": { "id": "doc_…", "externalRef": "INV-…", "status": "approved", "nsfp": "04002600000012345", … } }

Idempotensi & batas

Kunci idempotensi = externalRef (atau idempotencyKey / header Idempotency-Key). Mengirim ulang isi yang sama aman: hasilnya "duplicate" dengan status terakhir.
Isi berbeda dengan kunci yang sama → 409 E_IDEMPOTENCY.
Maks 100 dokumen per request, 500 baris per faktur, 300 request/menit per kunci.
Sinkron massal: GET /documents?updatedSince=<ISO>&cursor=… (urut waktu ubah, aman untuk jutaan baris).

CoreTax Studio

CoreTax Studio Enterprise: buka menu "Coretax Gateway", tempel kunci jenis Studio, klik Tes Koneksi. Aktifkan "Kirim otomatis (realtime)" agar setiap faktur yang masuk ke Studio langsung dikirim, dan status/NSFP ditarik kembali otomatis.