Dokumentasi API Warga+

Mulai Cepat

• Daftar di app.wargaplus.id untuk mendapatkan akses API.
• Ambil API key dari dashboard (mode sandbox/production).
• Gunakan environment variable untuk menyimpan kredensial.

Autentikasi

Gunakan header Authorization: Bearer <API_KEY> untuk setiap permintaan.

• Semua endpoint wajib HTTPS.
• Token berbeda untuk sandbox dan production.
• Jika gagal auth, server mengembalikan 401 Unauthorized dengan error code auth_invalid_token.

Base URL & Versi

• Sandbox: https://sandbox-api.wargaplus.id/v1
• Production: https://api.wargaplus.id/v1

Endpoint Utama

GET /environments

Daftar lingkungan yang Anda kelola.

• Query: page, page_size
• Response 200: { "data": [ { "id": "env_123", "name": "RW 09" } ], "page": 1, "total": 1 }
• Error: 401 (auth_invalid_token), 429 (rate_limited)

POST /announcements

Kirim pengumuman ke warga.

• Payload: { "title": "Pemadaman", "body": "Info pemadaman...", "environment_id": "env_123", "channels": ["app","email"] }
• Response 201: { "id": "ann_123", "status": "scheduled" }
• Error: 400 (invalid_body), 401, 403 (forbidden), 429

POST /bills

Buat tagihan/iuran baru.

• Payload: { "title": "Iuran Kebersihan", "amount": 50000, "due_date": "2025-02-15", "environment_id": "env_123", "resident_ids": ["usr_1","usr_2"] }
• Response 201: { "id": "bill_123", "status": "pending" }
• Error: 400 (invalid_body), 401, 403, 404 (environment_not_found), 429

GET /bills/{id}

Detail tagihan.

• Response 200: { "id": "bill_123", "status": "pending", "amount": 50000, "due_date": "2025-02-15" }
• Error: 401, 403, 404 (bill_not_found), 429

POST /payments/confirm

Konfirmasi pembayaran manual.

• Payload: { "bill_id": "bill_123", "reference": "TRX-001", "paid_at": "2025-01-20T08:00:00Z" }
• Response 200: { "bill_id": "bill_123", "status": "paid" }
• Error: 400 (invalid_body), 401, 403, 404 (bill_not_found), 409 (already_paid), 429

GET /reports

Ringkasan laporan aktivitas.

• Query: from, to, environment_id
• Response 200: { "payments": { "count": 10, "amount": 2500000 }, "announcements": 4, "tickets": 2 }
• Error: 401, 403, 429

Webhook

• Daftarkan URL webhook di dashboard.
• Kami mengirim event: payment.paid, bill.overdue, announcement.sent.
• Verifikasi tanda tangan header X-WP-Signature menggunakan HMAC-SHA256.
• Balas 2xx; percobaan ulang dilakukan hingga 3 kali dengan backoff.

Rate Limit

• Default: 100 request/menit per API key (sandbox dan production dihitung terpisah).
• Header: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error & Response

• Gunakan kode HTTP standar (400, 401, 403, 404, 409, 429, 500).
• Format error JSON: { "error": { "code": "string", "message": "string", "details": {} } }.

Contoh Permintaan

curl -X POST "https://api.wargaplus.id/v1/bills" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Iuran Kebersihan",
    "amount": 50000,
    "due_date": "2025-02-15",
    "resident_ids": ["usr_123", "usr_456"]
  }'

Dukungan Teknis

Untuk bantuan integrasi, hubungi [email protected] atau lihat panduan di How-To Dashboard.