diff --git a/DOKUMENTASI.md b/DOKUMENTASI.md new file mode 100644 index 0000000..077a2b3 --- /dev/null +++ b/DOKUMENTASI.md @@ -0,0 +1,246 @@ +Berikut adalah rancangan dokumentasi API yang lengkap, profesional, dan siap Anda serahkan (copy-paste) ke developer rekanan Anda. + +Dokumentasi ini mencakup cara autentikasi, struktur request/response, dan contoh integrasi. + +--- + +# Dokumentasi Integrasi Email API (Google Apps Script) + +**Versi:** 1.0.0 +**Status:** Active +**Base URL:** `[URL_WEB_APP_ANDA]` +*(Catatan: URL didapatkan setelah Anda melakukan "Deploy > New Deployment > Web App" di Google Apps Script Editor)* + +## 1. Ikhtisar & Autentikasi + +API ini dibangun menggunakan Google Apps Script untuk menangani pengiriman email transaksional dan bulk email. Semua request harus menggunakan format JSON. + +### Autentikasi + +Setiap request **wajib** menyertakan API Key. + +* **API Key:** `rapiin2025` +* **Metode:** Disertakan dalam body JSON (POST) atau parameter URL (GET). + +### Batasan (Rate Limits) + +* **Maksimal Request:** 500 request per hari (Reset setiap 24 jam). +* **Maksimal Penerima:** 50 penerima (To/CC/BCC) per request. +* **Bulk Email Limit:** Maksimal 10 email object per satu request bulk. + +--- + +## 2. API Endpoints (POST) + +Gunakan method `POST` untuk melakukan pengiriman email. Header `Content-Type: application/json` wajib digunakan. + +### A. Endpoint: Single Email (`send-email`) + +Digunakan untuk mengirim satu email (bisa ke banyak penerima). + +**Body Parameter:** + +| Field | Tipe | Wajib | Keterangan | +| --- | --- | --- | --- | +| `api_key` | String | **Ya** | Kunci autentikasi. | +| `endpoint` | String | **Ya** | Value: `"send-email"` | +| `to` | String/Array | **Ya** | Alamat email penerima. | +| `subject` | String | **Ya** | Subjek email. | +| `body` | String | **Ya** | Body email (Text version). | +| `html_body` | String | Opsional | Body email (HTML version). Jika ada, ini diprioritaskan. | +| `from_name` | String | Opsional | Nama pengirim (Default: API Mailer). | +| `cc` | String/Array | Opsional | Carbon Copy. | +| `bcc` | String/Array | Opsional | Blind Carbon Copy. | +| `reply_to` | String | Opsional | Alamat Reply-To. | +| `attachments` | Array | Opsional | Array object lampiran (Lihat bagian Attachment Object). | + +**Contoh Request (JSON):** + +```json +{ + "api_key": "rapiin2025", + "endpoint": "send-email", + "to": ["user@example.com", "admin@example.com"], + "subject": "Laporan Harian", + "body": "Berikut laporan harian Anda.", + "html_body": "

Laporan Harian

Berikut laporan...

", + "from_name": "Sistem Notifikasi", + "attachments": [ + { + "filename": "invoice.pdf", + "mime_type": "application/pdf", + "base64_data": "JVBERi0xLjQKJ..." + } + ] +} + +``` + +### B. Endpoint: Bulk Email (`bulk-email`) + +Digunakan untuk mengirim email yang berbeda ke penerima yang berbeda dalam satu request HTTP. + +**Body Parameter:** + +| Field | Tipe | Wajib | Keterangan | +| --- | --- | --- | --- | +| `api_key` | String | **Ya** | Kunci autentikasi. | +| `endpoint` | String | **Ya** | Value: `"bulk-email"` | +| `emails` | Array | **Ya** | Array berisi object email (Max 10 item). | + +**Struktur Object dalam Array `emails`:** +Sama seperti parameter Single Email (`to`, `subject`, `body`, dll). + +**Contoh Request (JSON):** + +```json +{ + "api_key": "rapiin2025", + "endpoint": "bulk-email", + "emails": [ + { + "to": "client1@example.com", + "subject": "Tagihan #001", + "body": "Halo Client 1..." + }, + { + "to": "client2@example.com", + "subject": "Tagihan #002", + "body": "Halo Client 2..." + } + ] +} + +``` + +--- + +## 3. Struktur Object Attachment + +Sistem mendukung dua metode lampiran: Mengambil dari Google Drive atau mengirim Base64 string. + +**Opsi 1: Base64 (Upload file langsung)** + +```json +{ + "filename": "laporan.pdf", + "mime_type": "application/pdf", + "base64_data": "BASE64_STRING_HERE" +} + +``` + +**Opsi 2: Google Drive File** +Pastikan akun Google script memiliki akses ke file tersebut. + +```json +{ + "drive_file_id": "1A2B3C4D5E6F..." +} + +``` + +--- + +## 4. API Endpoints (GET) - Monitoring + +Gunakan method `GET` untuk pengecekan sistem. + +| Path | Parameter | Deskripsi | +| --- | --- | --- | +| `/` | `?path=health` | Cek status kesehatan server (Uptime). | +| `/` | `?path=usage` | Cek statistik penggunaan kuota hari ini. | +| `/` | `?path=logs&api_key=...` | Melihat log aktivitas terakhir (Perlu API Key). | + +**Contoh URL:** +`https://script.google.com/.../exec?path=usage` + +--- + +## 5. Response Standar + +API akan selalu mengembalikan response dengan format JSON berikut: + +**Sukses (HTTP 200):** + +```json +{ + "success": true, + "data": { + "messageId": "msg_170425...", + "processing_time_ms": 150 + }, + "meta": { + "version": "1.0.0", + "timestamp": "2025-01-03T04:00:00.000Z" + } +} + +``` + +**Gagal (HTTP 4xx / 5xx):** + +```json +{ + "success": false, + "error": { + "code": 401, + "message": "Invalid API key", + "details": "Please provide a valid API key" + } +} + +``` + +--- + +## 6. Contoh Kode Integrasi (Node.js / Axios) + +Berikut adalah contoh cara memanggil API ini menggunakan Node.js: + +```javascript +const axios = require('axios'); + +const API_URL = 'https://script.google.com/macros/s/[DEPLOYMENT_ID]/exec'; +const API_KEY = 'rapiin2025'; + +async function sendEmail() { + try { + const payload = { + api_key: API_KEY, + endpoint: 'send-email', // Wajib diset manual karena redirect GAS bisa menghilangkan parameter + to: 'customer@gmail.com', + subject: 'Test Integrasi', + body: 'Email ini dikirim dari Node.js', + html_body: 'Email ini dikirim dari Node.js', + from_name: 'Admin Toko' + }; + + // Google Apps Script sering melakukan redirect (302), pastikan client mengikuti redirect + const response = await axios.post(API_URL, payload, { + headers: { 'Content-Type': 'application/json' }, + maxRedirects: 5 + }); + + console.log('Sukses:', response.data); + } catch (error) { + console.error('Gagal:', error.response ? error.response.data : error.message); + } +} + +sendEmail(); + +``` + +--- + +### Catatan Penting untuk Developer + +1. **CORS:** Google Apps Script tidak mendukung CORS preflight standar untuk browser-side AJAX call secara langsung. Disarankan memanggil API ini dari **Backend Server** (Node.js, PHP, Python, dll). +2. **Redirects:** Saat melakukan request POST ke Web App URL (`/exec`), Google akan meredirect ke URL sementara (`googleusercontent.com`). Pastikan HTTP Client Anda dikonfigurasi untuk **Follow Redirects**. +3. **Logs:** Semua aktivitas tercatat di Google Sheet dengan ID: `1994KuhHCUUJotc_YCLy2ALPCNC-PPLrA8xYIT0SSHsQ`. + +--- + +**Next Step yang bisa saya lakukan untuk Anda:** +Apakah Anda ingin saya buatkan juga contoh file `.json` (Postman Collection) agar developer Anda bisa langsung *import* dan *test* API ini tanpa coding manual? \ No newline at end of file