Invoice

Invoice adalah tagihan yang dikirim ke pelanggan. externalId yang Anda kirim saat membuatnya menjadi kunci integrasi yang aman untuk diulang.

GET/v1/invoices

Mengambil daftar invoice organisasi Anda

Hasil dipaging pakai cursor, bukan nomor halaman. Ambil halaman berikutnya dengan mengirim cursor berisi meta.nextCursor dari respons sebelumnya, dan berhenti begitu meta.hasMore bernilai false.

Parameter query

Parameter	Tipe	Wajib	Keterangan
externalId	string	Tidak	Menyaring satu invoice berdasarkan externalId Anda.
paymentStatus	string	Tidak	UNPAID, PARTIAL, atau PAID.
documentStatus	string	Tidak	DRAFT atau SENT.
issuedFrom	tanggal	Tidak	Batas bawah issueDate (inklusif).
issuedTo	tanggal	Tidak	Batas atas issueDate (inklusif).
cursor	string	Tidak	Nilai meta.nextCursor dari respons halaman sebelumnya.
limit	number	Tidak	Jumlah baris per halaman. Default 25, maksimum 100.

curl -X GET "https://tagihandigital.com/api/v1/invoices" \
  -H "Authorization: Bearer td_live_API_KEY_ANDA"

Contoh respons

200 — Daftar invoice

{
  "data": [
    {
      "id": "clx9a",
      "externalId": "ORD-2026-0912",
      "number": "INV-2026-0012",
      "customerName": "PT Maju",
      "documentStatus": "SENT",
      "paymentStatus": "UNPAID",
      "total": "300000",
      "amountPaid": "0"
    }
  ],
  "meta": { "hasMore": true, "nextCursor": "clxB7" }
}

Kemungkinan error

UNAUTHORIZED (401) — Header Authorization hilang, API key salah, atau key sudah dicabut.

POST/v1/invoices

Membuat invoice baru

externalId wajib diisi dan harus unik per organisasi — tidak bisa diubah lagi setelah invoice dibuat. Kalau request pertama Anda timeout lalu diulang, server akan menjawab 409 EXTERNAL_ID_CONFLICT; jangan membuat invoice baru dengan ID lain, ambil invoice yang sudah tercatat lewat GET /v1/invoices/external/{externalId}.

Parameter body

Parameter	Tipe	Wajib	Keterangan
externalId	string	Ya	ID milik sistem Anda sendiri. 1–50 karakter, huruf/angka/./_/:/-, tidak boleh diubah setelah dibuat.
customerId	string	Ya	id pelanggan yang sudah dibuat lewat POST /v1/customers.
issueDate	tanggal	Ya	Tanggal terbit.
dueDate	tanggal	Ya	Tanggal jatuh tempo.
notes	string	Tidak	Catatan pada invoice.
terms	string	Tidak	Syarat pembayaran.
extraDiscount	number	Tidak	Diskon tambahan di luar diskon per item. Default 0.
shippingCost	number	Tidak	Biaya pengiriman. Default 0.
items	array	Ya	Minimal satu item. productId opsional; name wajib; description opsional; quantity default 1; unitPrice wajib; discount default 0; discountType PERCENT atau AMOUNT (default PERCENT); taxPercent default 0.

curl -X POST "https://tagihandigital.com/api/v1/invoices" \
  -H "Authorization: Bearer td_live_API_KEY_ANDA" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "ORD-2026-0912",
  "customerId": "cus_123",
  "issueDate": "2026-09-09",
  "dueDate": "2026-09-16",
  "items": [
    {
      "name": "Konsultasi",
      "quantity": 2,
      "unitPrice": 150000
    }
  ]
}'

Contoh respons

201 — Invoice dibuat

{
  "id": "clx9a",
  "number": "INV-2026-0012",
  "externalId": "ORD-2026-0912",
  "customer": { "id": "cus_123", "name": "PT Maju" },
  "documentStatus": "DRAFT",
  "paymentStatus": "UNPAID",
  "issueDate": "2026-09-09T00:00:00.000Z",
  "dueDate": "2026-09-16T00:00:00.000Z",
  "currency": "IDR",
  "total": "300000",
  "amountPaid": "0",
  "balanceDue": "300000",
  "items": [
    {
      "id": "itm_1",
      "productId": null,
      "name": "Konsultasi",
      "description": null,
      "quantity": "2",
      "unitPrice": "150000",
      "discount": "0",
      "discountType": "PERCENT",
      "taxPercent": "0",
      "amount": "300000"
    }
  ],
  "createdAt": "2026-09-09T02:11:00.000Z",
  "updatedAt": "2026-09-09T02:11:00.000Z"
}

409 — externalId sudah dipakai

{
  "error": {
    "code": "EXTERNAL_ID_CONFLICT",
    "message": "externalId ORD-2026-0912 sudah dipakai",
    "invoiceId": "clx9a",
    "number": "INV-2026-0012"
  }
}

Kemungkinan error

VALIDATION_ERROR (400) — Payload tidak lolos validasi. Field yang bermasalah dirinci pada `issues`.
CUSTOMER_NOT_FOUND (404) — Pelanggan tidak ada di organisasi pemilik key.
PRODUCT_NOT_FOUND (404) — Produk tidak ada di organisasi pemilik key.
EXTERNAL_ID_CONFLICT (409) — externalId sudah dipakai invoice lain di organisasi Anda.
UNAUTHORIZED (401) — Header Authorization hilang, API key salah, atau key sudah dicabut.

GET/v1/invoices/{id}

Mengambil satu invoice lewat id kami

curl -X GET "https://tagihandigital.com/api/v1/invoices/{id}" \
  -H "Authorization: Bearer td_live_API_KEY_ANDA"

Contoh respons

200 — Invoice ditemukan

{
  "id": "clx9a",
  "number": "INV-2026-0012",
  "externalId": "ORD-2026-0912",
  "customer": { "id": "cus_123", "name": "PT Maju" },
  "documentStatus": "SENT",
  "paymentStatus": "UNPAID",
  "issueDate": "2026-09-09T00:00:00.000Z",
  "dueDate": "2026-09-16T00:00:00.000Z",
  "currency": "IDR",
  "total": "300000",
  "amountPaid": "0",
  "balanceDue": "300000",
  "items": [
    {
      "id": "itm_1",
      "productId": null,
      "name": "Konsultasi",
      "description": null,
      "quantity": "2",
      "unitPrice": "150000",
      "discount": "0",
      "discountType": "PERCENT",
      "taxPercent": "0",
      "amount": "300000"
    }
  ],
  "createdAt": "2026-09-09T02:11:00.000Z",
  "updatedAt": "2026-09-09T02:11:00.000Z"
}

Kemungkinan error

INVOICE_NOT_FOUND (404) — Invoice tidak ada di organisasi pemilik key.
UNAUTHORIZED (401) — Header Authorization hilang, API key salah, atau key sudah dicabut.

GET/v1/invoices/external/{externalId}

Mengambil satu invoice lewat externalId milik Anda

Jalan pintas mencari invoice memakai ID milik sistem Anda sendiri, tanpa perlu menyimpan id yang kami berikan saat invoice dibuat.

curl -X GET "https://tagihandigital.com/api/v1/invoices/external/{externalId}" \
  -H "Authorization: Bearer td_live_API_KEY_ANDA"

Contoh respons

200 — Invoice ditemukan

{
  "id": "clx9a",
  "number": "INV-2026-0012",
  "externalId": "ORD-2026-0912",
  "customer": { "id": "cus_123", "name": "PT Maju" },
  "documentStatus": "SENT",
  "paymentStatus": "UNPAID",
  "issueDate": "2026-09-09T00:00:00.000Z",
  "dueDate": "2026-09-16T00:00:00.000Z",
  "currency": "IDR",
  "total": "300000",
  "amountPaid": "0",
  "balanceDue": "300000",
  "items": [
    {
      "id": "itm_1",
      "productId": null,
      "name": "Konsultasi",
      "description": null,
      "quantity": "2",
      "unitPrice": "150000",
      "discount": "0",
      "discountType": "PERCENT",
      "taxPercent": "0",
      "amount": "300000"
    }
  ],
  "createdAt": "2026-09-09T02:11:00.000Z",
  "updatedAt": "2026-09-09T02:11:00.000Z"
}

Kemungkinan error

INVOICE_NOT_FOUND (404) — Invoice tidak ada di organisasi pemilik key.
UNAUTHORIZED (401) — Header Authorization hilang, API key salah, atau key sudah dicabut.