API Aggregator Sharing Happiness
API ini dipakai mitra untuk menampilkan program donasi Sharing Happiness di platformnya, lalu mencatat donasi yang sudah mereka terima. Setiap endpoint di halaman ini bisa langsung Anda coba.
- 1Isi kredensial
Nama aggregator dan token dari tim Sharing Happiness.
- 2Pilih environment
Coba dulu di Development, baru pindah ke Production.
- 3Pilih program
Ambil
slugdari Daftar Program, lihat isinya lewat Detail Program. - 4Buat donasi
Kirim donasi ke slug itu, lalu simpan
transaction_number.
| Environment | Base URL |
|---|---|
| Development | https://dev.sharinghappiness.org/api/v1 |
| Production | https://be.sharinghappiness.org/api/v1 |
Kredensial & Environment
Token tidak pernah dikirim ke server. Yang dikirim hanya signature, yaitu hash dari token. Token juga hanya disimpan di tab ini dan hilang begitu halaman ditutup, kecuali Anda mencentang "Ingat di browser ini".
Konvensi API
Format request
Request dengan body wajib memakai JSON (UTF-8):
Content-Type: application/json
Accept: application/jsonFormat tanggal
Semua tanggal berformat YYYY-MM-DD HH:MM:SS dengan zona waktu Asia/Jakarta (WIB).
Envelope response
"status": 20,
"message": "...",
"result": { }Semua endpoint mengembalikan HTTP 200, termasuk saat gagal. Cek hasilnya dari field status di body.
| status | Arti |
|---|---|
| 20 | Sukses. |
| 30 | Gagal: input tidak valid, autentikasi ditolak, atau data tidak ditemukan. Penjelasannya ada di field message. |
| 40 | Disiapkan untuk akses yang ditolak, tapi belum dipakai di endpoint aggregator. |
Autentikasi & Signature
Setiap request harus membawa signature, yaitu hash SHA-256 dari nomor menit saat ini (window 60 detik) yang digabung dengan token. Nilainya berganti tiap menit, jadi buat signature baru tepat sebelum request.
window = floor(unix_timestamp / 60)
signature = SHA256( window . TOKEN ) // hex, huruf kecil- Server menerima signature dari menit saat ini, satu menit sebelumnya, dan satu menit sesudahnya. Artinya jam server Anda boleh meleset paling banyak satu menit. Sinkronkan dengan NTP.
- Dari server, kirim lewat header
X-Signature. Bisa juga lewat fieldsignature: query string untuk GET, body JSON untuk POST. - Jangan kirim token itu sendiri, baik di URL maupun di body.
$signature = hash('sha256', ((int) floor(time() / 60)) . $token);import hashlib, time
signature = hashlib.sha256(f"{int(time.time() // 60)}{token}".encode()).hexdigest()import { createHash } from 'node:crypto';
const signature = createHash('sha256')
.update(`${Math.floor(Date.now() / 60000)}${token}`)
.digest('hex');printf '%s' "$(( $(date +%s) / 60 ))${TOKEN}" | openssl dgst -sha256 | awk '{print $NF}'Status transaksi
Transaksi dari endpoint aggregator langsung berstatus paid. Status lain hanya muncul kalau tim Sharing Happiness mengubahnya, misalnya saat refund.
Status program
Daftar pesan error
Semua message yang bisa muncul dari endpoint aggregator. Konsol di atas mencocokkan setiap response dengan daftar ini dan menampilkan penjelasannya.
Troubleshooting
Selalu mendapat "Invalid signature!"
Pertama, cek token cocok dengan environment-nya, karena token Development dan Production berbeda. Lalu cek jam server: selisih lebih dari satu menit membuat signature ditolak. Window dan token digabung tanpa pemisah, misalnya "29858492" + TOKEN. Hasil hash harus hex huruf kecil.
Konsol menampilkan "Request diblokir"
Matikan opsi "Kirim lewat header X-Signature". CORS server belum mengizinkan header itu dari browser. Dari server Anda (cURL, PHP, Python, Node), header tetap bisa dipakai.
Amount yang tercatat berbeda dengan yang dikirim
Kalau program punya harga satuan (base_amount) dan Anda mengirim quantity, server menghitung ulang amount = harga × quantity. Untuk donasi nominal bebas, jangan kirim quantity.
Request timeout saat membuat donasi
Jangan langsung mengulang request, karena transaksinya mungkin sudah tercatat. Kirim waktu request, slug, nominal, dan email donatur ke tim Sharing Happiness supaya bisa dicek.
Detail program "tidak ditemukan", padahal slug-nya benar
Endpoint Detail hanya membuka program berstatus published. Cek status program itu di Daftar Program (filter status=all).