Beranda>Terkait pemrograman>Kode sumber lainnya
Unduh

Buku Panduan Plugin Radar Faktur

1. Pendahuluan

Selamat datang di Buku Panduan Plugin Invoice Radar untuk pengembang!

Panduan ini akan membantu Anda membuat plugin khusus untuk mengambil faktur dan tanda terima dari berbagai platform.

Invoice Radar adalah alat otomatisasi dokumen yang membantu Anda mengambil, mengunduh, dan mengatur faktur dan tanda terima dari berbagai platform.

Pelajari lebih lanjut tentang Radar Faktur

Daftar isi

  1. Perkenalan

  2. Memulai

  3. Struktur Plugin

  4. Menulis Plugin Pertama Anda

  5. Pola Berguna

  6. Referensi Langkah

2. Memulai

Prasyarat

  • Pengetahuan dasar tentang JSON, HTML, CSS dan JavaScript.

  • Editor teks atau IDE (misalnya VSCode, Sublime Text).

  • Radar Faktur diinstal di macOS atau Windows.

Instalasi

  1. Unduh dan Instal Radar Faktur :

    • Minta Akses ke Radar Faktur

  2. Unduh Plugin Kosong :

    • Unduh Plugin Kosong ke mesin lokal Anda.

    • Ganti nama file menjadi your-plugin-name.json .

    • Masukkan ke dalam folder pilihan Anda.

  3. Tambahkan Plugin ke Radar Faktur :

    • Buka Radar Faktur.

    • Arahkan ke pengaturan dan pilih tab Available Plugins .

    • Pilih Choose Plugin Directory dan pilih folder tempat Anda menyimpan plugin.

    • Plugin Anda sekarang akan muncul di daftar plugin yang tersedia.

3. Struktur Plugin

Plugin untuk Invoice Radar ditulis dalam JSON dan mengikuti struktur tertentu. Setiap plugin terdiri dari bagian berikut:

Deskripsi Plugin :

  • Metadata : Informasi dasar tentang plugin, seperti nama, deskripsi, dan URL beranda.

  • configSchema : Properti konfigurasi yang mungkin diperlukan plugin.

Langkah Pengikisan :

  • checkAuth : Langkah-langkah untuk memverifikasi apakah pengguna sudah diautentikasi.

  • startAuth : Langkah-langkah untuk memulai proses otentikasi.

  • getDocuments : Langkah-langkah untuk mengambil dan mengunduh dokumen.

Contoh Plugin Minimal

 { "$schema": "https://raw.githubusercontent.com/invoiceradar/plugins/main/schema.json", "id": "example", "name": "Contoh Platform", "description": " Deskripsi singkat tentang layanan.", "homepage": "https://example.com", "checkAuth": [
    { "tindakan": "navigasi", "url": "https://example.com/dashboard"
    },
    { "action": "checkElementExists", "selector": "#logout-button"
    }
  ], "mulaiAuth": [
    { "tindakan": "navigasi", "url": "https://example.com/login"
    },
    { "action": "waitForElement", "selector": "#account-summary", "timeout": 120000
    }
  ], "dapatkan Dokumen": [
    { "action": "navigasi", "url": "https://example.com/billing"
    },
    { "action": "extractAll", "selector": ".invoice-row", "variable": "invoice", "fields": { "id": { "selector": ".invoice-id"
        }, "tanggal": { "pemilih": ".tanggal faktur"
        }, "total": { "pemilih": ".total-faktur"
        }, "url": { "selector": ".invoice-download", "atribut": "href"
        }
      }, "untuk Setiap": [
        { "action": "downloadPdf", "url": "{{invoice.url}}", "document": "{{invoice}}"
        }
      ]
    }
  ]
}

Skema selengkapnya dapat ditemukan di sini.

4. Menulis Plugin Pertama Anda

Panduan Langkah demi Langkah

Mari buat plugin sederhana untuk mengambil faktur dari layanan hipotetis.

  1. Tentukan Metadata :

    Informasi ini digunakan untuk mengidentifikasi dan menampilkan plugin di Invoice Radar. URL beranda digunakan untuk mendapatkan favicon layanan.

    Perhatikan bahwa id harus unik dan menggunakan huruf kecil.

     { "id": "example-service", "name": "Example Service", "description": "Deskripsi singkat tentang layanan.", "homepage": "https://example.com"}

    Pelajari lebih lanjut tentang kolom metadata.

  2. Tentukan Skema Konfigurasi (Opsional):

    Skema konfigurasi menentukan bidang mana yang diperlukan agar plugin dapat berfungsi. Dalam contoh ini, kita memerlukan teamID dan password untuk mengautentikasi.

    Bidang ini akan ditampilkan kepada pengguna saat menambahkan plugin di Invoice Radar.

     "configSchema": { "teamID": { "type": "string", "title": "ID Tim", "description": "ID tim atau akun Anda untuk mengambil faktur.", "wajib": true
  }
}

    Pelajari lebih lanjut tentang bidang skema konfigurasi.

  3. Periksa Otentikasi :

    checkAuth berisi langkah-langkah untuk memverifikasi apakah pengguna diautentikasi. Hal ini dapat dilakukan dengan memeriksa URL atau keberadaan elemen. Langkah terakhir di dalam checkAuth adalah langkah verifikasi.

    Langkah-langkah ini dijalankan ketika proses dimulai. Jika pengguna sudah diautentikasi, plugin akan melewati proses otentikasi dan langsung mengambil dokumen.

     "checkAuth": [
  { "tindakan": "navigasi", "url": "https://example.com/dashboard"
  },
  { "action": "checkElementExists", "selector": "#logout-button"
  }
]

  4. Mulai Otentikasi :

    startAuth berisi langkah-langkah untuk memulai proses otentikasi. Ini mungkin melibatkan navigasi ke halaman login dan menunggu indikator login berhasil.

    Browser akan terlihat selama proses otentikasi, memungkinkan pengguna untuk berinteraksi dengan formulir login.

     "mulaiAuth": [
  { "tindakan": "navigasi", "url": "https://example.com/login"
  },
  { "action": "waitForElement", "selector": "#account-summary", "timeout": 120000
  }
]

  5. Mengikis Dokumen :

    getDocuments berisi langkah-langkah untuk mengambil dan mengunduh dokumen. Hal ini dapat melibatkan navigasi ke halaman penagihan, mengekstrak detail faktur, dan mengunduh PDF.

     "dapatkan Dokumen": [
  { "action": "navigasi", "url": "https://example.com/billing"
  },
  { "action": "extractAll", "selector": ".invoice-row", "variable": "invoice", "fields": { "id": { "selector": ".invoice-id"
      }, "tanggal": { "pemilih": ".tanggal faktur"
      }, "total": { "pemilih": ".total-faktur"
      }, "url": { "selector": ".invoice-download", "atribut": "href"
      }
    }, "untuk Setiap": [
      { "action": "downloadPdf", "url": "{{invoice.url}}", "document": { "type": "invoice", "id": "{{invoice.id}}", "tanggal": "{{faktur.tanggal}}", "total": "{{faktur.total}}"
        }
      }
    ]
  }
]

  6. Anda sudah selesai! :

    Simpan file dan tambahkan ke Invoice Radar. Anda sekarang dapat menjalankan plugin untuk mengambil faktur dari layanan.

5. Pola Berguna

Pola umum untuk pemeriksaan autentikasi ( checkAuth )

Pola 1: Buka Dasbor dan periksa URL

Banyak layanan yang secara otomatis mengalihkan ke halaman login jika pengguna tidak diautentikasi. Kita dapat menggunakan perilaku ini untuk memeriksa apakah pengguna diautentikasi.

 { "action": "navigasi", "url": "https://example.com/login"},
{ "aksi": "checkURL", "url": "https://example.com/account",
}

Tergantung pada layanannya, mereka mungkin mengarahkan Anda dari dasbor ke halaman login jika Anda tidak diautentikasi. Dalam hal ini, Anda dapat menggunakan langkah checkURL untuk memeriksa apakah URL masih cocok setelah mengunjungi dasbor.

 { "action": "navigasi", "url": "https://example.com/dashboard"},
{ "aksi": "checkURL", "url": "https://example.com/dashboard",
}

Perhatikan bahwa Anda dapat menggunakan pola glob untuk mencocokkan URL dinamis: https://example.com/dashboard/** .

Pola 2: Periksa Tombol Logout

Anda dapat menggunakan pemilih yang unik pada status terautentikasi untuk memeriksa apakah pengguna telah diautentikasi, misalnya tombol logout atau tautan profil.

 { "action": "navigasi", "url": "https://example.com/home"},
{ "action": "waitForElement", "selector": "#logout-button"}

Tip: Pastikan situs web terisi penuh

Dalam beberapa kasus, situs web belum dimuat sepenuhnya ketika langkah checkElementExists dijalankan. Untuk menghindari hal ini, Anda dapat menggunakan atribut waitForNetworkIdle untuk menunggu halaman dimuat sepenuhnya.

 { "action": "navigate", "url": "https://example.com/home", "waitForNetworkIdle": true},
{ "action": "checkElementExists", "selector": "#logout-button"}

Pola umum untuk memulai otentikasi ( startAuth )

Pola 1: Buka Halaman Login dan tunggu status login

Sebagian besar proses otentikasi dimulai dengan menavigasi ke halaman login dan menunggu elemen tertentu muncul setelah login berhasil.

Ingatlah bahwa browser akan terlihat selama proses otentikasi, memungkinkan pengguna untuk berinteraksi dengan formulir login. Alur autentikasinya sendiri dapat diotomatisasi, tetapi tidak diperlukan.

 { "action": "navigasi", "url": "https://example.com/login"},
{ "action": "waitForElement", "selector": "#logout-button", "timeout": 120000}

Untuk memberikan waktu yang cukup bagi pengguna untuk login, disarankan untuk memberikan waktu tunggu yang lama, dengan default 120 detik.

Referensi Langkah

Bagian ini memberikan ikhtisar langkah-langkah yang tersedia yang dapat digunakan untuk membuat plugin untuk Invoice Radar. Setiap langkah mewakili tindakan spesifik yang dapat dilakukan selama proses otomatisasi.

Daftar isi

  • Langkah Navigasi

    • Navigasi ( navigate )

    • Tunggu URL ( waitForURL )

    • Tunggu Elemen ( waitForElement )

    • Tunggu Navigasi ( waitForNavigation )

    • Tunggu Jaringan Idle ( waitForNetworkIdle )

  • Langkah Interaksi

    • Klik Elemen ( click )

    • Ketik Teks ( type )

    • Pilih Dropdown ( dropdownSelect )

    • Jalankan JavaScript ( runJs )

  • Langkah Verifikasi

    • Periksa Elemen yang Ada ( checkElementExists )

    • Periksa URL ( checkURL )

    • Jalankan JavaScript ( runJs )

  • Langkah Ekstraksi Data

    • Ekstrak ( extract )

    • Ekstrak Semua ( extractAll )

  • Langkah-Langkah Pengambilan Dokumen

    • Unduh PDF ( downloadPdf )

    • Tunggu Unduhan PDF ( waitForPdfDownload )

    • Cetak Halaman sebagai PDF ( printPdf )

    • Unduh Base64 PDF ( downloadBase64Pdf )

  • Langkah Logika Bersyarat

    • Jika if )

  • Langkah-Langkah Lain-Lain

    • Tidur ( sleep )

  • Cuplikan

    • Dapatkan Faktur dari URL Stripe ( getInvoiceFromStripeUrl )

    • Dapatkan Faktur dari Portal Pelanggan Stripe ( getInvoicesFromStripeBillingPortal )

Langkah Navigasi

Navigasi ( navigate )

Navigasikan ke URL yang diberikan dan tunggu halaman dimuat. Secara default, ini hanya menunggu pemuatan halaman awal, bukan permintaan AJAX berikutnya.

 { "action": "navigasi", "url": "https://example.com"}

Anda dapat mengatur waitForNetworkIdle ke true untuk memastikan halaman dimuat sepenuhnya sebelum melanjutkan.

 { "action": "navigate", "url": "https://example.com/dashboard", "waitForNetworkIdle": true}

Senang mengetahui :

  • URL relatif didukung dan akan diselesaikan berdasarkan halaman saat ini.

  • Tindakan navigasi hanya akan menunggu pemuatan halaman awal, bukan permintaan AJAX berikutnya.

Tunggu URL ( waitForURL )

Menunggu URL saat ini cocok dengan URL yang diberikan, opsional dengan batas waktu. Mendukung wildcard.

 { "action": "waitForURL", "url": "https://example.com/profile/**", "timeout": 3000}

Tunggu Elemen ( waitForElement )

Menunggu pemilih tertentu muncul di halaman, opsional dengan batas waktu.

 { "action": "waitForElement", "selector": "#example", "timeout": 3000}

Tunggu Navigasi ( waitForNavigation )

Menunggu navigasi halaman terjadi. Langkah ini tidak akan menunggu halaman dimuat sepenuhnya. Gunakan langkah waitForNetworkIdle untuk tujuan itu. Batas waktu bersifat opsional dan defaultnya adalah 10 detik

 { "action": "waitForNavigation", "timeout": 10000}

Tunggu Jaringan Idle ( waitForNetworkIdle )

Menunggu jaringan dalam keadaan idle. Ini berguna jika Anda ingin memastikan halaman telah selesai memuat semua sumber daya. Langkah-langkahnya selesai ketika tidak ada lagi permintaan jaringan selama 500 md. Batas waktu bersifat opsional dan defaultnya adalah 15 detik.

Langkah navigate memiliki opsi waitForNetworkIdle yang dapat disetel ke true untuk mendapatkan perilaku yang sama.

 { "aksi": "waitForNetworkIdle", "batas waktu": 10000}

⚡️ Langkah Interaksi

Klik Elemen ( click )

Mengklik elemen yang ditentukan oleh pemilih tertentu pada halaman.

 { "aksi": "klik", "pemilih": "#button"}

Ketik Teks ( type )

Ketikkan teks tertentu ke dalam elemen yang ditentukan oleh pemilih tertentu di halaman.

 { "action": "type", "selector": "#input", "value": "Halo Dunia"}

Pilih Dropdown ( dropdownSelect )

Memilih nilai tertentu dari dropdown yang ditentukan oleh pemilih tertentu di halaman. Pemilihan terjadi berdasarkan atribut value dari opsi.

 { "action": "dropdownSelect", "selector": "#dropdown", "value": "Opsi 1"}

Jalankan JavaScript ( runJs )

Menjalankan JavaScript yang diberikan dalam konteks halaman. Kalau janji dibalas, pasti ditunggu.

Jika Anda ingin menggunakan hasil skrip pada langkah berikutnya, gunakan langkah ekstrak saja.

 { "action": "runJs", "script": "document.querySelector('#example').click();"}

Langkah Verifikasi

Langkah-langkah ini digunakan di dalam checkAuth untuk memverifikasi apakah pengguna diautentikasi.

Periksa Elemen yang Ada ( checkElementExists )

Memeriksa apakah pemilih tertentu ada di halaman. Biasanya digunakan untuk pemeriksaan otentikasi.

 { "action": "checkElementExists", "selector": "#example"}

Periksa URL ( checkURL )

Memeriksa apakah URL saat ini cocok dengan URL yang diberikan. Mendukung pola wildcard seperti https://example.com/dashboard/** .

 { "aksi": "checkURL", "url": "https://example.com"}

Jalankan JavaScript ( runJs )

Langkah runJs juga dapat digunakan sebagai langkah verifikasi. Dengan menjalankan skrip yang mengembalikan nilai benar atau salah, Anda dapat memverifikasi apakah pengguna diautentikasi.

 { "action": "runJs", "script": "document.cookie.includes('authToken');"}

Langkah Ekstraksi Data

Langkah-langkah ini digunakan untuk memuat data dari halaman, seperti daftar item atau nilai tunggal, dan menggunakannya dalam langkah berikutnya.

Ekstrak ( extract )

Mengekstrak satu bagian data dari halaman dan menyimpannya dalam sebuah variabel.

Menggunakan bidang CSS:

 { "tindakan": "ekstrak", "variabel": "akun", "bidang": { "id": "#team-id", "name": "#team-name", "url": { " selector": "#team-link", "atribut": "href"
    }
  }
}

Dalam contoh ini account digunakan sebagai nama variabel, dan bidang id , name , dan url diekstraksi menggunakan pemilih CSS. Mereka dapat digunakan pada langkah selanjutnya menggunakan placeholder {{account.id}} , {{account.name}} , dan {{account.url}} .

Menggunakan JavaScript:

 { "action": "extract", "variable": "token", "script": "localStorage.getItem('authToken')"}

Contoh ini membuat variabel token yang diekstraksi menggunakan JavaScript. Nilainya dapat diakses menggunakan placeholder {{token}} . Dimungkinkan juga untuk mengembalikan suatu objek.

Ekstrak Semua ( extractAll )

Mengekstrak daftar data dari halaman, dan menjalankan langkah-langkah yang diberikan untuk setiap item. Ini biasanya digunakan untuk mengulangi daftar faktur dan mengunduhnya.

Untuk setiap elemen yang cocok dengan selector , bidang diekstraksi dan disimpan dalam variable yang tersedia di langkah forEach .

Senang mengetahui :

  • Setiap pemilih di dalam objek fields secara otomatis dicakup ke elemen yang cocok.

  • Bidang variable bersifat opsional. Jika tidak disediakan, data yang diekstrak akan disimpan dalam variabel default item .

  • Indeks saat ini dapat diakses menggunakan placeholder {{index}} . Ini dimulai dari 0 dan bertambah untuk setiap item.

Dengan bidang CSS:

 { "action": "extractAll", "selector": ".invoice-list .invoice-item", "variable": "invoice", "fields": { "id": "td.invoice-id", " date": "td.invoice-date", "total": "td.invoice-total", "url": { "selector": "a.invoice-link", "attribute": "href"
    }
  }, "untuk Setiap": [
    { "action": "navigasi", "url": "{{invoice.url}}"
    },
    { "action": "downloadPdf", "faktur": "{{faktur}}"
    }
  ]
}

Dengan JavaScript:

Saat menggunakan JavaScript, hasilnya harus berupa array objek atau nilai. Kalau hasilnya menjanjikan, ditunggu.

 { "action": "extractAll", "script": "Array.from(document.querySelectorAll('#year-selector option')).map(option => option.value);", "variable": "tahun ", "untukSetiap": [
    { "action": "dropdownSelect", "selector": "#year-selector", "value": "{{tahun}}"
    }
  ]
}

Paginasi

Dukungan eksperimental, belum didokumentasikan.

Langkah-Langkah Pengambilan Dokumen

Langkah-langkah ini digunakan untuk mengunduh dokumen dan memprosesnya di Invoice Radar. Semua langkah memerlukan objek document untuk diteruskan sebagai argumen, yang berisi metadata dokumen.

Argumen document memiliki bidang berikut:

Diperlukan

  • id : ID dokumen unik

    • Misalnya INV-123 atau 123456

  • date : Tanggal faktur sebagai string

    • Misal 2022-01-01 atau 01/01/2022 atau January 1, 2022

Direkomendasikan

  • total : Jumlah total faktur termasuk mata uang.

    • Misalnya $100.00 atau €100.00 atau 100 EUR atau 100,00€

    • Parser bawaan akan mencoba mengekstrak jumlah dan mata uang dari string.

Opsional

  • type : Jenis dokumen (Opsional. Defaultnya adalah auto )

    • Dapat diatur ke auto , invoice , receipt , refund atau other .

  • metadata : Metadata tambahan untuk dokumen (Opsional)

    • Misalnya { "orderNumber": "12345" }

Anda dapat meneruskan setiap bidang secara terpisah atau seluruh objek jika berisi semua bidang yang wajib diisi.

Misalnya menggunakan bidang terpisah:

 "dokumen": { "id": "{{item.invoiceId}}", "date": "{{item.date}}", "total": "{{item.amount}} {{item.currency }}", "ketik": "faktur"}

Misalnya jika objek berisi semua bidang yang wajib diisi, Anda dapat meneruskannya secara langsung:

 "dokumen": "{{item}}"

Unduh PDF ( downloadPdf )

Mengunduh PDF dari URL yang diberikan.

 { "action": "downloadPdf", "url": "https://example.com/invoice.pdf", "document": { "id": "{{item.invoiceId}}", "date": "{{item.tanggal}}", "total": "{{item.total}}"
  }
}

Tunggu Unduhan PDF ( waitForPdfDownload )

Menunggu unduhan PDF. Batas waktu default adalah 15 detik.

 { "action": "waitForPdfDownload", "timeout": 10000, "document": { "id": "{{item.invoiceId}}", "date": "{{item.date}}", "total ": "{{item.total}}"
  }
}

Cetak Halaman sebagai PDF ( printPdf )

Mencetak halaman saat ini ke file PDF.

 { "action": "printPdf", "document": { "id": "{{item.invoiceId}}", "date": "{{item.date}}", "total": "{{item .total}}"
  }
}

Unduh Base64 PDF ( downloadBase64Pdf )

Mengunduh PDF dari string yang dikodekan base64.

 { "action": "downloadBase64Pdf", "base64": "{{item.base64String}}", "document": { "id": "{{item.invoiceId}}", "date": "{{item .date}}", "total": "{{item.total}}"
  }
}

Langkah Logika Bersyarat

Jika if )

Jalankan langkah-langkah yang diberikan jika kondisinya benar. Jika kondisinya salah, langkah else akan dijalankan.

 { "action": "if", "script": "'{{invoice.url}}'.includes('pdf')", "then": [
    { "aksi": "klik", "pemilih": "#contoh"
    }
  ],  "kalau tidak": [
    { "action": "navigasi", "url": "https://example.com/fallback"
    }
  ]
}

Langkah-Langkah Lain-Lain

Tidur ( sleep )

Menunggu selama jangka waktu tertentu dalam milidetik. Hal ini umumnya tidak disarankan. Dalam kebanyakan kasus, lebih baik menggunakan langkah waitForElement, waitForURL, atau waitForNetworkIdle.

 { "aksi": "tidur", "durasi": 1000}

Cuplikan

Cuplikan adalah serangkaian langkah yang dibuat sebelumnya untuk menyederhanakan tugas-tugas umum. Langkah-langkah untuk cuplikan tertentu terlihat di dalam alat pengembang

Saat ini, pembuatan cuplikan khusus tidak dapat dilakukan. Jika Anda memiliki tugas umum yang menurut Anda berguna sebagai cuplikan, silakan buat masalah di GitHub.

Dapatkan Faktur dari URL Stripe ( getInvoiceFromStripeUrl )

Mengekstrak faktur dari URL faktur Stripe.

 { "action": "runSnippet", "snippet": "getInvoiceFromStripeUrl", "args": { "url": "https://invoice.stripe.com/i/inv_123"
  }
}

Dapatkan Faktur dari Portal Pelanggan Stripe ( getInvoicesFromStripeBillingPortal )

Mengekstrak faktur yang tersedia dari portal penagihan Stripe.

 { "action": "runSnippet", "snippet": "getInvoicesFromStripeBillingPortal", "args": { "url": "https://stripe-portal.example.com/billing"
  }
}

Pola Tingkat Lanjut

Menjalankan permintaan pengambilan

Terkadang, Anda mungkin perlu menjalankan permintaan pengambilan di dalam sebuah langkah untuk mengambil data dari API. Untuk melakukan ini, Anda dapat menggunakan tindakan extractAll .

 { "action": "extractAll", "variable": "faktur", "script": "fetch('https://example.com/api/invoices').then(res => res.json()) " "untukSetiap": [
    { "action": "downloadPdf", "url": "{{invoice.url}}", "document": { "id": "{{invoice.id}}", "date": "{{faktur .date}}", "total": "{{faktur.total}}"
      }
    }
  ]
}

Ini akan menjalankan permintaan pengambilan dan mengembalikan hasilnya sebagai objek JavaScript.

Jalankan langkah-langkah di dalam