Menerbitkan faktur melalui API

POST /invoices dengan Idempotency-Key, PPN dalam persen, serta daftar, storno, dan penandaan lunas.

Faktur pertama Anda dalam 6 langkah

Kirim POST /v1/invoices dengan objek buyer dan minimal satu entri di lines.
Tambahkan header Idempotency-Key — wajib, satu kunci per operasi logis.
Kirim vat_rate sebagai persen (21) dan unit_price sebagai harga satuan NETO.
Respons 201 membawa id, number, series, total net/vat/gross, dan metadata yang Anda kirim.
Ambil dokumen dengan GET /v1/invoices/{id}/pdf atau XML UBL dengan GET /v1/invoices/{id}/xml.

Semua endpoint

Metode	Endpoint	Scope	Idempotency-Key	Permintaan / menit
POST	/invoices Terbitkan faktur atau proforma	invoices:write	wajib	30
GET	/invoices Daftar faktur (paginasi kursor)	invoices:read	—	120
POST	/invoices/preview-totals Hitung total tanpa membuat apa pun	invoices:read	—	120
GET	/invoices/{invoice_id} Ambil satu faktur	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Unduh PDF faktur	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Terbitkan nota kredit yang membatalkan faktur ini	invoices:write	wajib	30
POST	/invoices/{invoice_id}/payments Tandai faktur sebagai lunas	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Tandai faktur sebagai belum lunas	invoices:write	—	30

Apa itu API 4invoices

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10457-invoice' \
  -d '{
    "buyer": {
      "name": "Exemplu Comert SRL",
      "tax_id": "RO12345678",
      "address": "Str. Fabricii 12",
      "city": "Cluj-Napoca",
      "county": "Cluj",
      "country": "RO",
      "email": "[email protected]"
    },
    "lines": [
      { "description": "Abonament SaaS, iulie", "quantity": 1, "unit_price": 400, "vat_rate": 21, "unit": "buc" },
      { "description": "Implementare", "quantity": 6, "unit_price": 250, "vat_rate": 21, "unit": "ora" }
    ],
    "currency": "RON",
    "document_kind": "factura",
    "due_date": "2026-08-15",
    "metadata": { "order_id": "10457" }
  }'

bash
# Paginasi kursor: ikuti next_cursor hingga has_more bernilai false.
curl -sS "https://api.4invoices.net/v1/invoices?limit=50&status=issued&issued_from=2026-07-01" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"object":"list","data":[...],"has_more":true,"next_cursor":"inv_01J..."}

curl -sS "https://api.4invoices.net/v1/invoices?limit=50&cursor=inv_01J..." \
  -H "Authorization: Bearer $ACCESS_TOKEN"

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/storno \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: storno-inv_01J7ABC-1'

# Nota kredit mendapat nomor fiskal SENDIRI; nomor asli tidak pernah dipakai ulang.

bash
# Tandai lunas
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Batalkan
curl -sS -X DELETE https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Error

Status	Tipe	Kode
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Kesalahan umum

Pendaftaran berbasis kursor: ikuti next_cursor hingga has_more bernilai false. Filter mencakup status, document_kind, buyer_tax_id, issued_from, issued_to, dan q.
Storno adalah POST /v1/invoices/{id}/storno dan mendapat nomor fiskalnya sendiri — nomor asli tidak pernah dipakai ulang.
Proforma (document_kind proforma) tidak menggunakan nomor fiskal dan tidak dapat diajukan ke sistem faktur elektronik nasional.
metadata dikembalikan saat membaca: simpan id pesanan Anda di sana dan Anda tidak memerlukan tabel pemetaan terpisah.
POST /v1/invoices/preview-totals menjalankan aritmatika yang sama tanpa efek samping — berguna untuk menampilkan total di keranjang Anda sendiri.

Tanya jawab untuk pengembang

Berapa banyak baris yang bisa dimiliki satu faktur?

Antara 1 dan 400. description dibatasi 1024 karakter, dan quantity harus benar-benar positif.

Apa yang terjadi jika saya mengirim ulang permintaan yang sama setelah timeout?

Dengan Idempotency-Key yang sama, Anda mendapat faktur asli beserta header Idempotency-Replayed: true. Tidak ada dokumen kedua yang diterbitkan.

Bagaimana cara menandai faktur sebagai lunas?

POST /v1/invoices/{id}/payments menandainya lunas, dan DELETE pada jalur yang sama membatalkannya. Keduanya memerlukan scope invoices:write.

Lihat juga