مرجع API الإفصاحات

العمليات

يتطلب كل طلب مفتاح Bearer؛ وتستخدم طلبات REST الترويسة Authorization: Bearer $NARWHAL_API_KEY. المصادقة

معرّفات الشركات والإفصاحات

استخدم قيمة id الخاصة بالشركة التي يُعيدها البحث؛ وتبدأ معرّفات تايوان بالبادئة twn: متبوعة بالرمز الذي يُعيده البحث.

يجمع معرّف الإفصاح بين معرّف الشركة ورقم قيد الإفصاح في السجل، وتفصل بينهما نقطتان رأسيتان، مثل usa:0000320193:0000320193-25-000079.

يُقبل اسم بديل لرمز التداول مثل usa:AAPL في مسار الشركة، ويُحوَّل إلى معرّف الشركة.

البحث عن الشركات

ابحث عن الشركات بالاسم أو رمز التداول أو الرمز، مع مرشّحات اختيارية للبلد والسجل. استخدم as_of لاختيار رمز التداول الساري في تاريخ محدد.

• q: اسم الشركة أو رمز التداول أو الرمز، بحد أقصى 200 حرف.
• country: رمز البلد المكوّن من 3 أحرف لاتينية كبيرة.
• registry: رمز السجل بأحرف صغيرة، مثل usa أو jpn أو kor.
• as_of: التاريخ المستخدم لاختيار رمز التداول الساري.
• lang: القيمة الافتراضية en، أو original.
• limit: من 1 إلى 100 نتيجة، والقيمة الافتراضية 20.

تحتوي قائمة companies على هوية الشركة وتفاصيل إدراجها. يوضّح matched المطابقة باستخدام id أو code أو name أو former_code أو former_name؛ ويظهر الاسم السابق وعَلَم delisted بقيمة صحيحة عند انطباق ذلك. عند عدم تحديد q، تتضمن الاستجابة أيضًا coverage، وهو عدد الشركات المحمّلة لكل سجل.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies?q=AAPL&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "companies": [
    {
      "id": "usa:0000320193",
      "name": "Apple Inc.",
      "country": "USA",
      "mic": "XNAS",
      "code": "AAPL",
      "matched": "code"
    }
  ]
}

جلب شركة

اقرأ هوية الشركة ومعيار إعداد تقاريرها وسجل أسمائها وأوراقها المالية والشركات المرتبطة بها.

• as_of: التاريخ المستخدم لاختيار رمز التداول الساري.
• lang: القيمة الافتراضية en، أو original.

تشمل الهوية المعرّفات القانونية المتاحة والتصنيف القطاعي وتفاصيل الحالة. يستخدم fiscal_year_end التنسيق MMDD، مثل 0926 لتاريخ 26 سبتمبر، ويحدّد standard أحد المعايير us_gaap أو ifrs أو j_gaap أو jmis أو k_gaap. يسجّل names الأسماء السابقة مع تواريخها؛ ويصف securities فئات الأسهم وأنواعها ومعرّفاتها وإدراجاتها المؤرخة؛ ويحدّد related الشركات المدرجة في أكثر من سوق أو الشركات الخلف أو السلف. تكون هذه الحقول الثلاثة قوائم دائمًا.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "name": "Apple Inc.",
  "country": "USA",
  "fiscal_year_end": "0926",
  "standard": "us_gaap",
  "industry": {
    "isic": "2620",
    "sector": "Manufacturing",
    "industry": "Manufacture of computer, electronic and optical products",
    "source_scheme": "us_sic",
    "source_code": "3571"
  },
  "names": [
    {
      "name": "APPLE INC",
      "from": "2007-01-10",
      "to": "2019-08-05"
    },
    {
      "name": "APPLE COMPUTER INC",
      "from": "1994-01-26",
      "to": "2007-01-04"
    },
    {
      "name": "APPLE COMPUTER INC/ FA",
      "from": "1997-07-28",
      "to": "1997-07-28"
    }
  ],
  "securities": [
    {
      "class": "common",
      "type": "common",
      "primary": true,
      "listings": [
        {
          "mic": "XNAS",
          "code": "AAPL",
          "from": "2026-10-20"
        }
      ]
    }
  ],
  "related": []
}

جلب البيانات المالية

اقرأ البنود المالية الموحّدة للفترات المالية للشركة، الأحدث أولًا. تستخدم الاستجابة annual أو semiannual أو quarterly مفتاحًا للصفوف، وفقًا لقيمة period.

• fields: أسماء البنود الموحّدة مفصولة بفواصل، أو all؛ والقيمة الافتراضية 15 بندًا شائعًا.
• statement: جميع البنود من income أو balance أو cash_flow أو per_share أو shares أو other.
• period: القيمة الافتراضية annual، أو semiannual أو quarterly، وفق حدود السجل والخطة.
• fiscal_year: سنة مالية واحدة، ضمن النطاق التاريخي المتاح في الخطة.
• basis: إما consolidated أو standalone.
• version: القيمة الافتراضية latest؛ وتتطلب first_reported خطة Pro.
• as_of: الأرقام كما كانت معروفة في التاريخ المحدد؛ ويتطلب ذلك خطة Pro.

يتوفر 77 بندًا موحّدًا: 29 لقائمة الدخل، و28 للميزانية العمومية، و14 للتدفقات النقدية، و3 لكل سهم، و3 للأسهم. اختر الأسماء باستخدام fields، أو استخدم fields=all لجلب جميع البنود، أو اختر قائمة باستخدام statement. البنود الافتراضية البالغ عددها 15 هي revenue وgross_profit وoperating_income وnet_income وcash وtotal_assets وtotal_debt وtotal_liabilities وtotal_equity وoperating_cash_flow وcapex وfree_cash_flow وeps_diluted وdividend_per_share وshares_outstanding. يؤدي اسم حقل غير معروف إلى إرجاع 400 unknown_field.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/financials?fields=revenue,net_income,total_assets,eps_diluted" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "currency": "USD",
  "from_fy": 2023,
  "annual": [
    {
      "fy": 2025,
      "end": "2025-09-27",
      "derived": [],
      "revenue": "416161000000",
      "net_income": "112010000000",
      "total_assets": "359241000000",
      "eps_diluted": "7.46"
    },
    {
      "fy": 2024,
      "end": "2024-09-28",
      "derived": [],
      "revenue": "391035000000",
      "net_income": "93736000000",
      "total_assets": "364980000000",
      "eps_diluted": "6.08"
    },
    {
      "fy": 2023,
      "end": "2023-09-30",
      "derived": [],
      "revenue": "383285000000",
      "net_income": "96995000000",
      "total_assets": "352583000000",
      "eps_diluted": "6.13"
    }
  ]
}

تُعرض المبالغ كسلاسل نصية عشرية بعملة الإفصاح نفسه، دون تحويل للعملة أو تغيير مقياس القيم. تُحذف البنود المفقودة، ويبقى الصفر المُفصح عنه "0". يحدّد كل صف سنته المالية ونهاية فترته، مع الربع أو النصف المالي عند الاقتضاء؛ ويسرد derived البنود التي حسبها Narwhal، مثل free_cash_flow. يظل الإفصاح الرسمي دائمًا المرجع المعتمد.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/financials?statement=per_share" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "from_fy": 2023,
  "annual": [
    {
      "fy": 2025,
      "end": "2025-09-27",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "7.46",
      "dividend_per_share": "1.02"
    },
    {
      "fy": 2024,
      "end": "2024-09-28",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "6.08",
      "dividend_per_share": "0.98"
    },
    {
      "fy": 2023,
      "end": "2023-09-30",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "6.13",
      "dividend_per_share": "0.94"
    }
  ]
}

تنشر اليابان تقارير سنوية ونصف سنوية، دون تقارير ربع سنوية. وتنشر الشركات الأمريكية تقارير سنوية وربع سنوية، دون تقارير نصف سنوية؛ ولا تتوفر تقارير نصف سنوية في تايوان أيضًا. تقارير الاتحاد الأوروبي والمنطقة الاقتصادية الأوروبية سنوية. يؤدي طلب فترة لا ينشرها السجل إلى إرجاع 404 period_not_published، مع تفصيل يحدّد الفترة الواجب استخدامها.

سرد إفصاحات الشركة

اقرأ إفصاحات الشركة مع مرشّحات للفئة والنموذج وتواريخ الإيداع.

• type: إحدى القيم annual أو semiannual أو quarterly أو event أو ownership أو insider أو other.
• form: اسم النموذج كما هو تمامًا، مثل 10-K، بحد أقصى 20 حرفًا.
• filed_from: تاريخ بداية نطاق الإيداع.
• filed_to: تاريخ نهاية نطاق الإيداع.
• include_amendments: ما إذا كانت التعديلات تُضمَّن، والقيمة الافتراضية false.
• cursor: مؤشر الصفحة التالية، مع المرشّحات نفسها.
• limit: من 1 إلى 200 نتيجة، والقيمة الافتراضية 50.
• lang: القيمة الافتراضية en، أو original.

تحدّد الصفوف الإفصاح وتاريخ إيداعه ونموذجه وفئته ونهاية فترته، مع عنوان عندما يوفّره السجل. تُرتَّب النتائج من الأحدث إلى الأقدم؛ استخدم next_cursor للصفحة التالية، وتكون قيمته null في الصفحة الأخيرة. تُعاد قيمة filed_from في الاستجابة عندما تؤخّر حدود الخطة تاريخ البداية.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/filings?type=annual&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "filed_from": "2023-10-27",
  "filings": [
    {
      "id": "usa:0000320193:0000320193-25-000079",
      "filed": "2025-10-31",
      "form": "10-K",
      "type": "annual",
      "period_end": "2025-09-27"
    },
    {
      "id": "usa:0000320193:0000320193-24-000123",
      "filed": "2024-11-01",
      "form": "10-K",
      "type": "annual",
      "period_end": "2024-09-28"
    }
  ],
  "next_cursor": "eyJpIjo0MTUwNjcsImtpbmQiOiJmaWxpbmdzIiwicSI6IjExYzkyYjY4YWJjZTMyM2YiLCJ0IjoiMjAyNC0xMS0wMVQxMDowMTozNiswMDowMCIsInYiOjF9.j2L56WYc-pkZ4UoI0z1vAN4htuG4nzEDOJUTtT_CZOY"
}

جلب إفصاح

اقرأ البيانات الوصفية لإفصاح واحد ورابطه الرسمي في السجل؛ ويقبل lang القيمة الافتراضية en أو القيمة original.

تحدّد الاستجابة الإفصاح والشركة، مع filer_id عندما تختلف الجهة المودِعة. وتشمل النموذج والفئة والعنوان والسنة المالية ونهاية الفترة والطابع الزمني filed_at بتوقيت UTC حيثما توفرت. يحدّد fp القيمة FY أو H1 أو H2 أو من Q1 إلى Q4؛ ويربط url بصفحة الإفصاح الرسمي في السجل. يحدّد amends الإفصاح الذي يجري تعديله، ولا يظهر withdrawn إلا عندما تكون قيمته صحيحة.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/filings/usa:0000320193:0000320193-25-000079" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193:0000320193-25-000079",
  "company_id": "usa:0000320193",
  "form": "10-K",
  "type": "annual",
  "fy": 2025,
  "fp": "FY",
  "period_end": "2025-09-27",
  "filed_at": "2025-10-31T10:01:26Z",
  "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm"
}

أحدث الإفصاحات

اقرأ أحدث الإفصاحات عبر الشركات، مع company_id في كل صف.

• country: رمز البلد المكوّن من 3 أحرف لاتينية كبيرة.
• type: إحدى القيم annual أو semiannual أو quarterly أو event أو ownership أو insider أو other.
• limit: من 1 إلى 200 نتيجة، والقيمة الافتراضية 50.
• lang: القيمة الافتراضية en، أو original.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/filings/latest?country=USA&type=annual&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "filings": [
    {
      "id": "usa:0001888525:0001213900-26-112533",
      "filed": "2026-10-26",
      "form": "20-F",
      "type": "annual",
      "title": "ANNUAL REPORT",
      "company_id": "usa:0001888525"
    },
    {
      "id": "usa:0001901203:0001213900-26-112531",
      "filed": "2026-10-26",
      "form": "10-K/A",
      "type": "annual",
      "title": "AMENDMENT NO. 2 TO FORM 10-K",
      "company_id": "usa:0001901203"
    }
  ]
}

المساهمون بنسبة 5% أو أكثر

اقرأ بيانات المساهمين الواردة في إفصاحات الملكية من الولايات المتحدة واليابان وكوريا. تستخدم القائمة أحدث تقرير لكل مساهم وتستبعد المساهمين الذين أنهوا ملكيتهم.

• security: فئة الأسهم، بحد أقصى 40 حرفًا.
• lang: القيمة الافتراضية en، أو original.
• limit: من 1 إلى 500 نتيجة، والقيمة الافتراضية 100.

يحدد كل صف المساهم ونسبة الملكية وعدد الأسهم وتاريخ الحدث وتاريخ الإفصاح ومعرّف الإفصاح والورقة المالية، حيثما توفرت. لا تُقسّم القائمة إلى صفحات. تُعاد قيمة filed_from في الاستجابة عندما تفرض الخطة تاريخ بداية أحدث.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/holders?limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "filed_from": "2023-10-27",
  "holders": [
    {
      "holder": "Vanguard Capital Management",
      "percent": "7.48",
      "shares": "1099168953",
      "event_date": "2026-03-31",
      "filed": "2026-04-30",
      "filing_id": "usa:0000320193:0002100119-26-000139",
      "security": {
        "class": "common"
      }
    }
  ]
}

البيانات المالية كما وردت في الإفصاح

اقرأ الحقائق المالية لإفصاح واحد وفق وسومها الأصلية تمامًا، مجمّعة حسب المفهوم. تتاح هذه العملية في جميع الخطط ضمن البحث عن الإفصاحات.

يحتوي كل عنصر في concepts على taxonomy وconcept وlabel وunit وقائمة values. وتحتوي كل قيمة على start وend وvalue حيثما توفرت.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/filings/usa:0000320193:0000320193-25-000079/financials/as-reported" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "concepts": [
    {
      "taxonomy": "us-gaap",
      "concept": "Revenues",
      "label": "Revenues",
      "unit": "USD",
      "values": [
        {
          "start": "2023-10-01",
          "end": "2024-09-28",
          "value": "391035000000"
        },
        {
          "start": "2022-09-25",
          "end": "2023-09-30",
          "value": "383285000000"
        }
      ]
    }
  ]
}

تقتصر هذه العملية على إفصاحات الولايات المتحدة؛ وتُرجع إفصاحات اليابان وكوريا 404 as_reported_unavailable. قد يحتوي الإفصاح على آلاف الحقائق، لذا قد يبلغ حجم الاستجابة عدة مئات من الكيلوبايت. لا تُقسّم النتائج إلى صفحات.

حدود الخطط

تتاح جميع العمليات والبنود القياسية في كل الخطط؛ وتحدد الخطة نطاق البيانات التاريخية وتوقيت إتاحتها.

إذا كانت المشكلة الوحيدة في الطلب أن تاريخ بدايته أقدم من المسموح، يُحصر نطاقه ضمن نافذة الخطة باستخدام from_fy للبيانات المالية أو filed_from للإفصاحات والمساهمين. تُحسب نوافذ الإفصاحات والمساهمين بالسنوات التقويمية؛ ولا تتيح خطة Free إلا الإفصاحات المقدمة قبل 00:00 UTC اليوم.

تُرجع طلبات البيانات المالية ربع السنوية أو نصف السنوية على خطة Free، أو طلبات fiscal_year الأقدم من النافذة التاريخية، أو filed_to الأقدم من النافذة، أو البيانات المالية مع version=first_reported أو as_of على خطة أدنى من Pro، الخطأ 403 plan_upgrade_required قبل احتساب أي استهلاك من الحصة.

قواعد الاستجابة

• تُمثّل الأرقام بسلاسل نصية عشرية.
• تُحذف الحقول ذات القيم المفردة غير المتوفرة، ولا تُعاد أبدًا بقيمة null.
• تظهر القوائم دائمًا، وتكون [] عندما تكون فارغة.
• لا تظهر الأعلام مثل delisted وwithdrawn إلا عندما تكون قيمتها صحيحة.
• تكون قيمة next_cursor هي null في الصفحة الأخيرة.
• يُرجع lang=original الأسماء والعناوين بلغة السجل الأصلية حيثما توفرت؛ والقيمة الافتراضية هي en.

الأخطاء

• 400 invalid_query الاستعلام غير صالح.
• 400 unknown_field أحد الأسماء في fields ليس بندًا ماليًا قياسيًا.
• 400 invalid_cursor صيغة المؤشر غير صالحة، أو أنه أُصدر لعوامل تصفية مختلفة.
• 401 invalid_api_key مفتاح API غير صالح.
• 403 plan_upgrade_required النطاق التاريخي أو الفترة أو إصدار البيانات المالية المطلوب غير مشمول في الخطة.
• 404 company_not_found لم يُعثر على الشركة.
• 404 filing_not_found لم يُعثر على الإفصاح.
• 404 period_not_published لا ينشر السجل بيانات الفترة المطلوبة؛ وتحدد تفاصيل الخطأ الفترة التي ينبغي استخدامها.
• 404 as_reported_unavailable الحقائق المالية كما وردت في الإفصاح غير متاحة لهذا الإفصاح.
• 429 rate_limit_exceeded تم تجاوز الحد الأقصى لمعدل الطلبات.
• 429 quota_exhausted استُنفدت حصة الطلبات.
• 503 database_unavailable مخزن البيانات غير متاح؛ أعد إرسال الطلب.

تستخدم الأخطاء البنية القياسية لتفاصيل المشكلة. الأخطاء والحصة

يوضح توثيق المصادقة مفاتيح Bearer، ويوضح توثيق الأخطاء البنية القياسية لتفاصيل المشكلة، ويوضح توثيق MCP الوصول إلى الأدوات. المصادقة · الأخطاء والحصة · MCP