Developer Portal

# Quick Faraid calc — wife + 2 sons + 1 daughter, Hanafi madhab
curl -X POST https://api.faraid.ai/api/hesapla \
  -H "Authorization: Bearer fk_sand_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "mezhep": "hanefi",
    "olen_cinsiyet": "erkek",
    "es_listesi": [{"ad": "Ayşe"}],
    "ogul_listesi": [{"ad":"Ahmet"},{"ad":"Mehmet"}],
    "kiz_listesi":  [{"ad":"Fatma"}],
    "toplam_mal":   100000,
    "dil": "en"
  }'

import requests

API_KEY = "fk_sand_YOUR_KEY_HERE"
BASE    = "https://api.faraid.ai"

payload = {
    "mezhep": "hanefi",
    "olen_cinsiyet": "erkek",
    "es_listesi": [{"ad": "Ayşe"}],
    "ogul_listesi": [{"ad": "Ahmet"}, {"ad": "Mehmet"}],
    "kiz_listesi":  [{"ad": "Fatma"}],
    "toplam_mal":   100000,
    "dil": "en",
}
r = requests.post(
    f"{BASE}/api/hesapla",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json=payload, timeout=30,
)
r.raise_for_status()
result = r.json()
print(result["pay_dagitimi"])
#  Ayşe: 1/8 (12.50%)
#  Ahmet: 7/20 (35.00%)
#  Mehmet: 7/20 (35.00%)
#  Fatma: 7/40 (17.50%)

const API_KEY = "fk_sand_YOUR_KEY_HERE";
const BASE    = "https://api.faraid.ai";

const payload = {
  mezhep:        "hanefi",
  olen_cinsiyet: "erkek",
  es_listesi:    [{ ad: "Ayşe" }],
  ogul_listesi:  [{ ad: "Ahmet" }, { ad: "Mehmet" }],
  kiz_listesi:   [{ ad: "Fatma" }],
  toplam_mal:    100000,
  dil:           "en",
};

const r = await fetch(`${BASE}/api/hesapla`, {
  method:  "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type":  "application/json",
  },
  body: JSON.stringify(payload),
});
if (!r.ok) throw new Error(`HTTP ${r.status}`);
const result = await r.json();
console.log(result.pay_dagitimi);

curl -X POST https://api.faraid.ai/api/what-if \
  -H "Authorization: Bearer fk_sand_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "baseline": { /* same as /api/hesapla payload */ },
    "scenarios": ["remove_child","spouse_dies","change_madhab"]
  }'

r = requests.post("https://api.faraid.ai/api/what-if",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "baseline": payload,
        "scenarios": ["remove_child", "spouse_dies", "change_madhab"],
    })
for s in r.json()["scenarios"]:
    print(s["key"], s["diffs"])

import hmac, hashlib
from flask import request, jsonify

SECRET = "YOUR_WEBHOOK_SECRET"  # shown ONCE when endpoint created

def verify_signature(payload: bytes, signature: str) -> bool:
    expected = "sha256=" + hmac.new(SECRET.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.route("/faraid-webhook", methods=["POST"])
def handle():
    sig = request.headers.get("X-Faraid-Signature", "")
    if not verify_signature(request.data, sig):
        return jsonify(error="invalid signature"), 401

    event_type = request.headers["X-Faraid-Event"]
    data       = request.json
    # Idempotency: store X-Faraid-Delivery-ID to dedupe retries
    return jsonify(received=True), 200

const crypto  = require("crypto");
const express = require("express");
const SECRET  = process.env.FARAID_WEBHOOK_SECRET;

function verifySignature(rawBody, signature) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", SECRET).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

const app = express();
app.post("/faraid-webhook",
  express.raw({ type: "application/json" }),  // raw body for signature
  (req, res) => {
    const sig = req.headers["x-faraid-signature"];
    if (!verifySignature(req.body, sig)) return res.status(401).json({ error: "bad sig" });

    const eventType = req.headers["x-faraid-event"];
    const data      = JSON.parse(req.body.toString());
    // Idempotency: dedupe by req.headers["x-faraid-delivery-id"]
    res.json({ received: true });
  });
app.listen(3000);

import requests
from typing import Optional

class FaraidClient:
    def __init__(self, api_key: str, base_url: str = "https://api.faraid.ai"):
        self.s = requests.Session()
        self.s.headers.update({"Authorization": f"Bearer {api_key}"})
        self.base = base_url.rstrip("/")

    def calculate(self, **fields) -> dict:
        r = self.s.post(f"{self.base}/api/hesapla", json=fields, timeout=30)
        r.raise_for_status()
        return r.json()

    def what_if(self, baseline: dict, scenarios: list) -> dict:
        r = self.s.post(f"{self.base}/api/what-if",
                        json={"baseline": baseline, "scenarios": scenarios}, timeout=60)
        r.raise_for_status()
        return r.json()

    def save_will(self, country: str, title: str, content_text: str,
                  group_id: Optional[str] = None) -> dict:
        r = self.s.post(f"{self.base}/api/wills/save", json={
            "country": country, "title": title,
            "content_text": content_text, "group_id": group_id,
        }, timeout=20)
        r.raise_for_status()
        return r.json()

# Usage
client = FaraidClient("fk_live_xxxxxxxx")
result = client.calculate(mezhep="hanefi", olen_cinsiyet="erkek",
                          es_listesi=[{"ad":"Ayşe"}], toplam_mal=100000)

// requires Node 18+ (native fetch)
export class FaraidClient {
  constructor(apiKey, baseUrl = "https://api.faraid.ai") {
    this.apiKey = apiKey;
    this.base = baseUrl.replace(/\/$/, "");
  }

  async _post(path, body) {
    const r = await fetch(`${this.base}${path}`, {
      method: "POST",
      headers: { "Authorization": `Bearer ${this.apiKey}`,
                 "Content-Type": "application/json" },
      body: JSON.stringify(body),
    });
    if (!r.ok) throw new Error(`HTTP ${r.status}: ${await r.text()}`);
    return r.json();
  }

  calculate(fields) { return this._post("/api/hesapla", fields); }
  whatIf(baseline, scenarios) {
    return this._post("/api/what-if", { baseline, scenarios });
  }
  saveWill(opts) { return this._post("/api/wills/save", opts); }
}

# Environment
export FARAID_KEY="fk_live_xxxxxxxxxxxxxxxxx"

# 1) Simple calc — fractions only (no money)
curl -X POST https://api.faraid.ai/api/hesapla \
  -H "Authorization: Bearer $FARAID_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mezhep":"hanefi","olen_cinsiyet":"erkek","ogul_adedi":2}'

# 2) Generate Turkish will draft (after calc)
curl -X POST https://api.faraid.ai/api/wills/save \
  -H "Authorization: Bearer $FARAID_KEY" \
  -d '{"country":"TR","title":"Test","content_text":"VASİYETNAME..."}'

# 3) Check usage / quota
curl https://api.faraid.ai/api/billing/subscription \
  -H "Authorization: Bearer $FARAID_KEY"

# 4) List webhook endpoints
curl https://api.faraid.ai/api/webhooks/endpoints \
  -H "Authorization: Bearer $FARAID_KEY"