🔌 الحساب الحر

ألف - استعراض عام

يقوم برنامج التطبيقات بتشغيل نفس الحسابات التي يستخدمها الموقع. يمكنك إرسال قيم حقل الحاسبة كبارامترات استفسار أو JSON والحصول على النتائج المحسوبة مرة أخرى كJSON - بما في ذلك أي جدول إهلاك أو بيانات الرسم البياني التي تنتجها الحاسبة.

• 198+ أجهزة حسابية، كل منها له نقطة نهائية خاصة به
• لا يوجد مفتاح API — الوصول المجهول الهوية، محدود المعدل بموجب بروتوكول الإنترنت
• CORS — Access-Control-Allow-Origin: * (قابلة للاستخدام في جانب الزبون)
• الحد الأقصى للمعدل: 60 طلبات/ساعة لكل بروتوكول شبكة (HTTP 429 عند تجاوزها)
• الأخطاء مجانية — فقط رد ناجح (2xx) يستخدم مكالمة واحدة من حصتك الشهرية. كل 400، 401، 404، 429 و 500 تكلفك شيئا.

العنوان الأساسي

https://calculator.free/api/v1/

الفهرس - قائمة بكل آلة حسابية

GET https://calculator.free/api/v1/

يعيد قائمة مقروءة آليا من جميع الحسابات مع كل حقل (الكلمة، العلامة، النوع، الافتراض، الوحدة) ومفاتيح النتيجة - بما يكفي لبناء عميل ديناميكي. كل حقل يحمل أيضاً راية مطلوبة - صحيحة بالنسبة للمجالات القليلة التي لا تحتوي على بيانات افتراضية (التواريخ، في الغالب). أرسل تلك: يمكن لبعض الحاسبات الاستدلال على واحدة، والباقي يجيب 400 بدونها.

حساب - تشغيل آلة حساب واحدة

GET  https://calculator.free/api/v1/<slug>/?field=value&field=value
POST https://calculator.free/api/v1/<slug>/     (JSON or form body)

شكل الاستجابة:

{
  "ok": true,
  "slug": "mortgage",
  "country": "us",
  "inputs":   { ... the values actually computed with ... },
  "results":  { ... computed result keys ... },
  "schedule": { "columns": [...], "rows": [...] } | null,
  "chart":    { "type": "pie", "slices": [...] } | null,
  "defaults_applied": ["tax", "insurance"]
}

حسابات قائمة على البلدان (الرهن العقاري، القروض، ضريبة الدخل، ضريبة المبيعات...) ?country=us|uk|ca|au|in|ie|nz|za. يرجع سلوك غير معروف 404؛ البلد غير المدعوم أو المدخلات السيئة يرجع 400 مع رسالة مفيدة ومواصفات الحقل.

البارامترات والافتراضات والأخطاء

إرسال الحقول التي تهتم بها فقط. أي شيء تتركه خارج الملء مع نشر الحقل الافتراضي - نفس القيمة صفحة الحاسبة تملأ مسبقاً، لذلك API والموقع دائماً يعود نفس الأرقام لنفس المدخلات. كل رد يورد ما تم ملء تحت defaults_applied.

أي شيء لا يستطيع برنامج الوصلة البينية حله بصدق هو خطأ، وليس صفرا أبدا: مقياس مخطئ في الهجاء، أو قيمة من النوع الخاطئ، أو خيار غير معروف في القائمة المنسدلة، أو حقل مفقود لا يحتوي على قيمة افتراضية (حقول التاريخ - تاريخ الميلاد لا يمكن تخمينه). كل 400 اسم للمقياس المخالف ويصدق مواصفات الحقل الكاملة حتى يستطيع العميل تصحيح نفسه.

$ curl "https://calculator.free/api/v1/mortgage/?price=350000&rate=6.5&term=30"
{
  "ok": false,
  "error": "unknown_parameter",
  "message": "Unknown parameter 'term' for calculator 'mortgage'. Did you mean 'years'? ...",
  "unknown_parameters": ["term"],
  "did_you_mean": { "term": "years" },
  "valid_parameters": ["down", "extra", "extra_onetime", "extra_yearly", "hoa",
                       "insurance", "other", "pmi", "price", "rate", "tax", "years"],
  "fields": [ ... ]
}

اللجنة /api/v1/ index ينشر كل حقل مفتاح، نوع، وحدة، افتراضي وما إذا كان مطلوبا - بما فيه الكفاية لبناء عميل لا تخمين أبدا.

التوثيق والخطط

يمكنك استدعاء واجهة البرمجة التطبيقية بدون مفتاح على الإطلاق - الطلبات المجهولة هي محدودة بالمعدل حسب عنوان IP. لحصة شهرية أعلى ويمكن التنبؤ بها (والاستخدام التجاري)، إنشاء مفتاح على صفحة حسابك وإرسالها واحدة من ثلاث طرق:

GET  https://calculator.free/api/v1/mortgage/?price=350000&key=YOUR_KEY
curl -H "Authorization: Bearer YOUR_KEY" "https://calculator.free/api/v1/bmi/?units=metric&height=180&weight=80"
curl -H "X-Api-Key: YOUR_KEY"           "https://calculator.free/api/v1/bmi/?units=metric&height=180&weight=80"

• مجاني — غير معروفة الهوية (محدودة بمعدلات بروتوكول الإنترنت) أو مفتاح مجاني بحصة شهرية صغيرة.
• مطور 9 دولارات شهريا — 10,000 calls/month, commercial use.
• الأعمال التجارية 49 دولارا/شهريا — 100,000 calls/month, priority throughput.

ماذا يحسب في حصتك

Only a successful response does. One 2xx = one call. Every error is free: a 400 for a misspelled parameter, a bad value or a missing required field, a 404 for an unknown slug, a 401 for a bad key, a 429, and anything that goes wrong on our side. Explore the contract and fix your request as many times as you need — you are billed for answers, not for corrections.

لأن الأخطاء خالية فهي محدودة بالمعدل بدلاً من ذلك: إذا كان مفتاح واحد يسبب أكثر من 200 إذا رفضت الاستجابات في ساعة، فهي تحصل على HTTP 429 "too_many_invalid_requests" حتى تنتهي الساعة. المكالمات الناجحة لا تحسب أبدا في ذلك، لذا فإن التكامل العامل لن يرى أبدا - إنه فقط يأخذ العميل عالقًا في حلقة إعادة المحاولة.

عندما تستخدم حصة المفتاح الشهرية، يعيد API HTTP 429 مع خطأ "quota_exceeded"؛ مفتاح غير معروف أو غير نشط يعيد HTTP 401. انظر الخطط الكاملة وادخل على التسعير الصفحة.

أمثلة

curl

curl "https://calculator.free/api/v1/mortgage/?price=350000&down=70000&rate=6.9&years=30"

JavaScript fetch()

const r = await fetch(
  "https://calculator.free/api/v1/bmi/?" + new URLSearchParams({
    units: "metric", height: "180", weight: "80"
  }));
const { results } = await r.json();
console.log(results.bmi, results.category);

Python

import requests

r = requests.get("https://calculator.free/api/v1/mortgage/",
                 params={"price": 350000, "down": 70000,
                         "rate": 6.9, "years": 30},
                 headers={"Authorization": "Bearer YOUR_KEY"})
print(r.json()["results"])

POST JSON

curl -X POST "https://calculator.free/api/v1/income-tax/?country=uk" \
  -H "Content-Type: application/json" \
  -d '{"income": 60000}'

جميع النقاط النهائية

وترد مفاتيح الحقل ومفاتيح النتائج لكل منها في القائمة التالية: /api/v1/ الفهرس.