MCP untuk AI Agent

URL server

Satu endpoint melayani seluruh kemampuan Billing API. Endpoint ini memakai transport Streamable HTTP dan hanya bisa dijangkau dengan kredensial yang sah.

https://tagihandigital.com/api/mcp

Menghubungkan aplikasi AI

Tambahkan server di atas pada konfigurasi MCP aplikasi Anda. Saat pertama dipakai, aplikasi akan membuka halaman TagihanDigital untuk masuk, memilih organisasi, dan menyetujui izin. Koneksinya terikat pada satu organisasi dan bisa dicabut kapan saja dari halaman Integrasi API.

Claude Desktop dan Claude Code

{
  "mcpServers": {
    "tagihandigital": {
      "type": "http",
      "url": "https://tagihandigital.com/api/mcp"
    }
  }
}

Codex CLI

[mcp_servers.tagihandigital]
url = "https://tagihandigital.com/api/mcp"

Alur OAuth, transport, dan pemanggilan tool di halaman ini diverifikasi dengan pustaka klien MCP resmi (Streamable HTTP) — termasuk discovery metadata, registrasi klien dinamis, PKCE, dan penyegaran token otomatis. Aplikasi lain yang memakai spesifikasi yang sama semestinya ikut bekerja, tetapi belum kami uji satu per satu; kalau aplikasi Anda tidak terhubung, hubungi kami dengan nama dan versinya.

Autentikasi

Ada dua cara, dan keduanya memberi akses ke organisasi yang sama:

• OAuth (disarankan untuk aplikasi AI). Aplikasi mendaftar sendiri, lalu pemilik akun menyetujui akses di halaman consent. Access token berlaku satu jam dan disegarkan otomatis lewat refresh token yang berotasi. Hanya OWNER dan ADMIN yang dapat memberi izin.
• API key. Kirim key produksi seperti pada REST API. Cocok untuk server yang Anda kelola sendiri, tanpa halaman consent.

curl "https://tagihandigital.com/api/mcp" \
  -H "Authorization: Bearer td_live_API_KEY_ANDA" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Organisasi ditentukan oleh kredensial, bukan oleh argumen tool. Access token MCP tidak berlaku sebagai sesi dashboard dan bukan pula API key REST.

Tool yang tersedia

Aplikasi yang hanya meminta izin baca tidak dapat memanggil tool bertanda tulis; permintaannya dijawab sebagai kegagalan tool, bukan kesalahan server.

Satu tagihan dari percakapan

Agent yang memegang datanya sendiri cukup memanggil satu tool. Contoh percakapan:

Anda: Buatkan tagihan untuk Toko Sumber Rejeki, jasa pemasangan
      2 x 150.000 plus PPN 11%, jatuh tempo 24 September.

Agent: (create_invoice_with_payment_link)
       {
         "externalId": "ORD-2026-0917-001",
         "customer": { "name": "Toko Sumber Rejeki",
                       "email": "keuangan@sumberrejeki.co.id" },
         "issueDate": "2026-09-17",
         "dueDate": "2026-09-24",
         "items": [{ "name": "Jasa pemasangan",
                     "quantity": 2, "unitPrice": 150000,
                     "taxPercent": 11 }]
       }

       -> INV/2026/0042, total Rp333.000
          https://tagihandigital.com/pay/8f14e45f-...

Angka di atas hanya contoh bentuk hasilnya; nomor dan tautannya berbeda di tiap organisasi.

Banyak tagihan sekaligus

Untuk lebih dari satu tagihan, pakai batch_create_invoices_with_payment_links. Tool ini menerima 1–50 item dan memprosesnya berurutan. Satu item yang gagal tidak menghentikan item lain, dan hasilnya selalu berisi satu baris per item dengan urutan yang sama seperti masukannya.

Datanya bisa datang dari mana saja — percakapan, data terstruktur, atau spreadsheet. Yang penting, agent lebih dulu menyusunnya menjadi item yang lengkap:

Anda: Ini rekap penjualan September (tempel/unggah spreadsheet).
      Buatkan tagihannya sekaligus.

Agent: (batch_create_invoices_with_payment_links)
       {
         "invoices": [
           { "externalId": "SEP-001",
             "customer": { "name": "Toko Melati",
                           "phone": "081200000011" },
             "issueDate": "2026-09-17",
             "dueDate": "2026-09-30",
             "items": [{ "name": "Kopi 1 kg",
                         "quantity": 12, "unitPrice": 95000 }] },
           { "externalId": "SEP-002",
             "customerId": "cm3k1p2x40000abcd",
             "issueDate": "2026-09-17",
             "dueDate": "2026-09-30",
             "items": [{ "name": "Gula 1 kg",
                         "quantity": 20, "unitPrice": 14000 }] }
         ]
       }

       -> 2 item: 2 selesai, 0 gagal
          SEP-001 INV/2026/0043  https://tagihandigital.com/pay/...
          SEP-002 INV/2026/0044  https://tagihandigital.com/pay/...

Membaca dan menulis berkas adalah kemampuan aplikasi AI yang Anda pakai, bukan tool di server ini. Server hanya menerima data yang sudah terstruktur, sehingga isi spreadsheet tidak perlu dikirim mentah dan format berkas apa pun bisa dipakai.

externalId: kunci anti tagihan ganda

Setiap tagihan wajib membawa externalId — ID milik Anda sendiri, misalnya nomor pesanan atau nomor baris spreadsheet. Nilai inilah yang membuat percobaan ulang aman:

• Permintaan yang sama persis diulang akan memakai hasil yang sudah ada. Tidak ada tagihan, pelanggan, atau link pembayaran kedua yang dibuat, dan hasilnya ditandai resumed: true.
• Permintaan dengan externalId yang sama tetapi isinya berbeda dijawab sebagai konflik EXTERNAL_ID_CONFLICT. Periksa tagihan yang sudah ada dengan get_invoice_by_external_id, lalu pakai ID baru atau perbaiki datanya.

Karena itu, saat mencoba ulang setelah koneksi terputus, kirim kembali externalId yang sama persis — jangan mengarang yang baru.

Bagaimana pelanggan dicocokkan

1. Kalau customerId diberikan, pelanggan itu yang dipakai — dan bila tidak ditemukan, permintaannya gagal tanpa membuat apa pun.
2. Kalau tidak, email dan telepon dicocokkan persis di dalam organisasi. Bila keduanya menunjuk pelanggan yang berbeda, hasilnya AMBIGUOUS_CUSTOMER supaya tidak ada yang ditebak.
3. Kalau tidak ada yang cocok, pelanggan baru dibuat — karena itu namanya wajib diisi.

Nama saja tidak pernah dipakai untuk menggabungkan pelanggan: dua toko bernama sama di kota berbeda adalah dua pelanggan.

Bentuk hasil dan kegagalan

Setiap item pada alur gabungan menghasilkan satu baris berisi externalId, status (COMPLETED, PARTIAL, FAILED), customerId, invoiceId, nomor invoice, tautan pembayaran, dan kode error bila ada. Kegagalan bisnis dikembalikan sebagai hasil tool bertanda error, sehingga agent bisa memperbaiki satu item tanpa menghentikan sisanya. Bila tagihannya berhasil tetapi link pembayarannya gagal, statusnya PARTIAL dan identitas invoice tetap dikembalikan.

Kode error mengikuti tabel di halaman Kode error, ditambah kode khusus alur MCP: AMBIGUOUS_CUSTOMER, PAYMENT_LINK_FAILED, dan OPERATION_IN_PROGRESS.

Batasan versi pertama

Versi ini mencakup seluruh Public Billing API yang tersedia sekarang. Belum ada operasi dashboard lain (misalnya pencatatan pembayaran manual atau pencairan saldo), tidak ada parser berkas di sisi server, dan tidak ada pengiriman tagihan otomatis. Pembuatan link pembayaran mengikuti perilaku halaman pembayaran yang sudah ada: satu link aktif per tagihan, dan pembayar memilih banknya sendiri.