246 lines
6.5 KiB
Markdown
246 lines
6.5 KiB
Markdown
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": "<h1>Laporan Harian</h1><p>Berikut laporan...</p>",
|
|
"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: '<b>Email ini dikirim dari Node.js</b>',
|
|
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? |