Add DOKUMENTASI.md
This commit is contained in:
parent
634ae73b39
commit
a4bf29e733
|
|
@ -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": "<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?
|
||||
Loading…
Reference in New Issue