The AiAkaun API

curl https://aiakaun.com/api/v1/me \
  -H "Authorization: Bearer $AIAKAUN_TOKEN" \
  -H "Accept: application/json"

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 37
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Terlalu banyak permintaan. Cuba lagi sebentar."
  }
}

{
  "data": {
    "id": 1234,
    "date": "2026-08-01",
    "description": "Bayaran pelanggan — invois INV-0091",
    "amount": 1250.00,
    "type": "income",
    "status": "confirmed",
    "created_at": "2026-08-01T09:14:22+08:00"
  }
}

{
  "data": [
    { "id": 1234, "date": "2026-08-01", "amount": 1250.00, "type": "income" },
    { "id": 1235, "date": "2026-08-02", "amount": 1800.00, "type": "expense" }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 50,
    "total": 312,
    "last_page": 7
  },
  "links": {
    "next": "https://aiakaun.com/api/v1/transactions?page=2",
    "prev": null
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "Data yang dihantar tidak lengkap.",
    "fields": {
      "amount": ["Medan amount diperlukan."],
      "date": ["Medan date bukan tarikh yang sah."]
    }
  }
}

{
  "data": {
    "user": { "id": 7, "name": "Ali bin Ahmad", "email": "ali@contoh.com" },
    "company": { "id": 42, "name": "Perniagaan Ali Sdn Bhd", "currency": "MYR" },
    "token": {
      "name": "Integrasi kedai",
      "last_four": "f3a9",
      "read_only": false,
      "scopes": ["read:transactions", "write:transactions", "read:reports"],
      "expires_at": null
    }
  }
}

{
  "id": "evt_01k2m9c7q4xz8b3vd6ntr5phaj",
  "event": "invoice.paid",
  "created_at": "2026-08-07T14:22:05+08:00",
  "company": {
    "id": 42,
    "name": "Perniagaan Ali Sdn Bhd"
  },
  "data": {
    "id": 91,
    "number": "INV-0091",
    "contact": { "id": 12, "name": "Kedai Runcit Maju" },
    "total": 1250.00,
    "paid_at": "2026-08-07T14:22:04+08:00",
    "status": "paid"
  }
}

<?php
// Verify an AiAkaun webhook — the SAME algorithm our server uses.
// The signature covers "{timestamp}.{raw body}", not the body alone.

$secret    = getenv('AIAKAUN_WEBHOOK_SECRET');
$payload   = file_get_contents('php://input');   // RAW body — do not parse it first
$signature = $_SERVER['HTTP_X_AIAKAUN_SIGNATURE'] ?? '';
$timestamp = (int) ($_SERVER['HTTP_X_AIAKAUN_TIMESTAMP'] ?? 0);
$tolerance = 300;                                // seconds; rejects replays

if (abs(time() - $timestamp) > $tolerance) {
    http_response_code(400);
    exit('timestamp outside tolerance');
}

$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

// hash_equals, not ===. Constant-time comparison.
if (! hash_equals($expected, $signature)) {
    http_response_code(400);
    exit('invalid signature');
}

$event = json_decode($payload, true);

// De-duplicate on $event['id'] — retries carry the same id.
// Reply 2xx FAST; do the heavy work on your own queue.
http_response_code(204);

const crypto = require('crypto');
const express = require('express');

const app = express();

// express.raw, NOT express.json — we sign the raw bytes, and a JSON
// parser destroys them before you get a chance to check.
app.post('/webhook/aiakaun', express.raw({ type: 'application/json' }), (req, res) => {
  const secret    = process.env.AIAKAUN_WEBHOOK_SECRET;
  const payload   = req.body.toString('utf8');
  const signature = req.get('X-AiAkaun-Signature') || '';
  const timestamp = parseInt(req.get('X-AiAkaun-Timestamp') || '0', 10);
  const tolerance = 300;

  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > tolerance) {
    return res.status(400).send('timestamp outside tolerance');
  }

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(signature, 'utf8');

  // timingSafeEqual throws on a length mismatch — check that first.
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(400).send('invalid signature');
  }

  const event = JSON.parse(payload);

  // De-duplicate on event.id, then reply fast.
  res.status(204).end();
});

app.listen(3000);

import hashlib
import hmac
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)


@app.post("/webhook/aiakaun")
def aiakaun_webhook():
    secret    = os.environ["AIAKAUN_WEBHOOK_SECRET"].encode()
    payload   = request.get_data()                 # RAW bytes, not request.json
    signature = request.headers.get("X-AiAkaun-Signature", "")
    timestamp = int(request.headers.get("X-AiAkaun-Timestamp", "0"))
    tolerance = 300

    if abs(int(time.time()) - timestamp) > tolerance:
        abort(400, "timestamp outside tolerance")

    signed   = f"{timestamp}.".encode() + payload
    expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()

    # compare_digest, not ==. Constant-time comparison.
    if not hmac.compare_digest(expected, signature):
        abort(400, "invalid signature")

    event = request.get_json(force=True)

    # De-duplicate on event["id"], then reply fast.
    return "", 204

# Senarai transaksi Januari 2026, 100 setiap halaman.
curl -G https://aiakaun.com/api/v1/transactions \
  -H "Authorization: Bearer $AIAKAUN_TOKEN" \
  -H "Accept: application/json" \
  -d "from=2026-01-01" \
  -d "to=2026-01-31" \
  -d "per_page=100"

# Cipta satu perbelanjaan. Amaun ialah nombor perpuluhan (RM), bukan sen.
curl -X POST https://aiakaun.com/api/v1/transactions \
  -H "Authorization: Bearer $AIAKAUN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "date": "2026-08-07",
        "description": "Sewa pejabat Ogos 2026",
        "amount": 1800.00,
        "type": "expense",
        "account_code": "6200"
      }'

# Muat naik resit untuk dibaca AI. multipart/form-data — JANGAN tetapkan
# Content-Type sendiri; biar cURL menjananya berserta sempadan (boundary).
curl -X POST https://aiakaun.com/api/v1/documents \
  -H "Authorization: Bearer $AIAKAUN_TOKEN" \
  -H "Accept: application/json" \
  -F "file=@resit-ogos.pdf" \
  -F "type=receipt"