توثيق API وMCP

إجراء أول استدعاء

تستخدم API تنسيق JSON عبر HTTPS. يعيد هذا الاستدعاء آخر خمس قوائم دخل سنوية لشركة Apple. ولا يحتاج إلى مفتاح.

curl "https://api.financial.md/v1/company/financials/income_statement/standardized?company=ticker:AAPL&period_type=annual&limit=5"

القائمة هي إحدى القيم income_statement أو balance_sheet أو cash_flow أو supplemental. ونوع الفترة هو إحدى القيم annual أو quarterly أو ltm أو ytd.

تحديد شركة

يأخذ كل مسار خاص بشركة المعلمة company.

• ticker:AAPL، أو ticker:AAPL.XNAS لتحديد البورصة
• cik:320193، رقم الشركة لدى SEC
• fmd_<id>، المعرّف الذي تمنحه FinancialMD للشركة

تُفسَّر AAPL وحدها بوصفها رمز تداول، والأرقام وحدها بوصفها CIK. يوضح الرد ما تمت مطابقته في meta.company.matched_by.

قراءة قيمة

الرد الناجح هو { data, meta }. لا يأتي أي رقم داخل data منفردًا، بل ضمن كائن قيمة:

{
  "value": 391035000000,
  "unit": "USD",
  "currency": "USD",
  "decimals": -6,
  "period": { "start": "2023-10-01", "end": "2024-09-28", "type": "annual", "fiscal_year": 2024, "fiscal_period": "FY" },
  "known": { "from": "YYYY-MM-DDThh:mm:ssZ", "to": null },
  "restated": false,
  "method": "as_filed",
  "calc_type": "as_filed",
  "proof": { "id": "p_...", "accession": "0000320193-24-000123", "form": "10-K", "filed": "2024-11-01", "taxonomy": "us-gaap", "tag": "...", "source_url": "https://www.sec.gov/..." }
}

known هو النطاق الزمني الذي كان فيه هذا الرقم أحدث رقم مُودَع. تكون restated صحيحة فقط عندما يغيّر إيداع لاحق لدى SEC (المستند المودَع) الرقم؛ وعندئذ يوضح restatement_kind كيفية تغييره. يتيح proof.id الوصول عبر GET /proof/{id} إلى الإيداع لدى SEC (المستند المودَع) والحقائق الخام التي تستند إليها القيمة.

قراءة الماضي كما كان معلومًا آنذاك

• يُرجع as_of=2024-06-30 على أي مسار قراءة ما كان معلومًا في تلك اللحظة.
• يُرجع original=true النسخة المُبلَّغ عنها أول مرة لكل فترة.
• يُرجع history=true جميع نسخ كل فترة، بدءًا بالأقدم.
• يسرد GET /v1/changes?since=<timestamp> الحقائق التي أصبحت معلومة منذ ذلك الوقت.

المسارات

تتضمن وثيقة OpenAPI كل المعلمات ومخططات الاستجابة. وتقدّم llms.txt وllms-full.txt وملف المهارة المعلومات نفسها للوكلاء؛ https://api.financial.md/docs هو المرجع التفاعلي، ويسرد https://api.financial.md/changelog التغييرات.

تحقّق من رقم

curl -X POST "https://api.financial.md/v1/verify" -H "content-type: application/json" \
  -d '{"company":"ticker:AAPL","concept":"income_statement_total_revenues","period":"FY2024","value":391035000000}'

تتضمن الإجابة verdict بقيمة matches أو differs أو unknown، والقيمة المودَعة مع الإثبات الخاص بها، والفرق، وscale_hint عندما يختلف رقمك بعامل من قوى العشرة.

الحدود

تخضع الاستدعاءات دون مفتاح لحدود يومية لكل عنوان IP.

• 25 استدعاءً محسوبًا ضمن الحصة: النسب والفرز والتحقق
• 1,000 عملية قراءة لطبقة الإيداع لدى SEC (المستند المودَع): القوائم المالية والحقائق كما أُبلغ عنها والإيداعات لدى SEC (المستندات المودَعة) والملكية والأسعار
• 1,000 عملية قراءة للبيانات الوصفية: الدليل والملفات التعريفية والمقاييس والإثباتات والتغييرات

يتضمن كل رد RateLimit-Limit وRateLimit-Remaining وRateLimit-Reset. ويتضمن رد 429 الترويسة Retry-After.

لا تُصدر مفاتيح API ذات حدود أعلى بعد. راجع مفاتيح API. الاستدعاءات على api.financial.md مجانية. ويمكن للوكلاء الدفع لكل استدعاء على agent.financial.md. راجع التسعير.

نطاق التغطية

تشمل التغطية الشركات التي تقدم مستنداتها إلى SEC والمدرجة حاليًا في بورصة أمريكية.

• تتوفر قوائم مالية موحّدة للجهات المودِعة التي تُعد تقاريرها وفق US GAAP.
• الجهات المودِعة التي تُعد تقاريرها وفق IFRS، مثل كثير من الشركات الأجنبية التي تقدم Form 20-F أو 40-F، لديها إيداعات لدى SEC (المستندات المودَعة)، لكن ليست لديها قوائم مالية موحّدة بعد.
• الشركات التي شُطبت من البورصة موجودة في الدليل مع قوائمها المالية وإيداعاتها لدى SEC (المستندات المودَعة). ابحث عنها باستخدام CIK: لا يمكن البحث عنها برمز تداول ولا تتوفر لها أسعار، لذا يقتصر سجل الأسعار على الشركات المدرجة حاليًا.
• تأتي بيانات الملكية من الإيداعات لدى SEC (المستندات المودَعة) المقدمة منذ July 1, 2026، وتُحدَّث يوميًا عند 13:00 UTC من فهرس EDGAR اليومي: معاملات المطلعين من Forms 3, 4 and 5 للشركات المشمولة بالتغطية، وكل Form 13F-HR، بحيث تصل تقارير 13F للربع الجديد تباعًا مع إيداع المديرين لها. لا يُربط مركز 13F بشركة إلا عندما يذكر غلاف Schedule 13D أو 13G ورقتها المالية. بالنسبة للربع المنتهي في June 30, 2026، يربط ذلك 80 بالمئة من القيمة المُبلَغ عنها؛ وتظهر المراكز الأخرى في محفظة المدير تحت اسم المُصدِر كما ورد في الإيداع لدى SEC (المستند المودَع).
• لا تُقدَّم تقديرات إجماع المحللين ولا النصوص المفرَّغة لمكالمات الأرباح: فكلاهما بيانات مرخَّصة. تُقدَّم بيانات القطاعات كما أُبلغ عنها، والأخبار هي موجز الإيداعات لدى SEC (المستندات المودَعة) من نوع 8-K.

عندما تكون الشركة معروفة لكن مجموعة بيانات غير متوفرة، يرد API بالرمز not_covered ويسرد مجموعات البيانات المتوفرة لديه.

خادم MCP

يتيح خادم MCP استخدام API نفسه عبر 50 أداة للقراءة فقط. وهو يستخدم MCP Streamable HTTP ولا يتطلب حسابًا.

https://mcp.financial.md/mcp

يسرد دليل MCP الأدوات. وبطاقة الخادم مخصصة للسجلات.

الأخطاء

يأتي الخطأ بالصيغة { "error": { code, message, docs, request_id, remedies } }. توضّح قائمة remedies ما يجب فعله بعد ذلك. ويشرح مرجع الأخطاء كل رمز.