6.5 KiB

Raw Permalink Blame History

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):

{
  "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):

{
  "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)

{
  "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.

{
  "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):

{
  "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):

{
  "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:

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

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).
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.
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?

6.5 KiB Raw Permalink Blame History