استدعاؤك الأول

بمجرد أن يصبح مفتاحك نشطًا، اقرأ ملفك التعريفي. فهو أبسط استدعاء، ويخبرك بما يُسمح لتطبيقك بفعله.

باستخدام حزمة SDK لـ ‎.NET

builder.Services
    .AddAnisPartners(options => options.Authority = new Uri("https://<the address Anis gave you>"))
    .WithSigner(EcdsaP256Signer.FromPemFile("/secure/partner-key.pem", keyId));

// later, from the container:
var profile = await anis.Profile.GetAsync(ct);
Console.WriteLine(string.Join(", ", profile.Application!.Scopes));

راجع صفحة حزمة SDK لـ ‎.NET لملفات الإعدادات، وحفظ المفتاح، وبقية العميل البرمجي.

استخدم أحدث إصدار من الحزمة، 2.2.0

لا توقّع أنيس ردّ قراءة ملفك التعريفي — ولا ردود استدعاءات المعلومات الأخرى (المحافظ والكتالوج والبطاقات المملوكة) — وتقرأ الحزمة هذه الردود كما هي. إصدارات 1.x مهجورة: فهي لا تستطيع التحقق من الردود التي توقّعها أنيس اليوم. ثبّت الإصدار 2.2.0 في كل اللغات؛ والإصدار 2.0.1 هو أقدم إصدار ما زال يتحقق منها.

ما الذي يعود

قراءة ملفك التعريفي تُعيد معرّف الشريك ومعرّف التطبيق، والحساب التجاري لدى أنيس الذي تعمل نيابةً عنه، والصلاحيات التي يملكها تطبيقك في هذه اللحظة. تأتي الصلاحيات من السياسة الحية لتطبيقك وتُفحص في كل استدعاء — فأي تغيير يجريه موظفو أنيس يسري على استدعائك التالي، لا على إعادة التشغيل التالية — لذا اقرأها بدلًا من تخزينها مؤقتًا.

عندما يُرفض استدعاء

يحمل كل رفض قيمة code ورابطًا إلى صفحته في رموز الأخطاء. أول ما قد تصادفه منها:

الرمز	يعني عادةً
`invalid_credentials`	معرّف المفتاح أو ملف المفتاح أو الساعة أو العنوان الذي تستدعيه غير صحيح — أو أن المفتاح ليس نشطًا (لم يصبح نشطًا بعد، أو لم يعد نشطًا)
`malformed_signed_request`	أداة التوقيع لديك تبني الاستدعاء بشكل خاطئ: ترويسة توقيع، أو الأجزاء الموقّعة أو ترتيبها، أو بصمة المحتوى (`Content-Digest`). ولا يقول شيئًا عن مفتاحك
`insufficient_scope`	صلاحية ناقصة، أو استدعاء من خارج الشبكات المسموح بها لك. اقرأ ملفك التعريفي من الخادم نفسه: إن أجاب فشبكتك سليمة — قارن الصلاحيات التي يسردها بالصلاحية التي يحتاجها الاستدعاء؛ وإن رُفض بالطريقة نفسها فالسبب الشبكة (أو أن التطبيق يفتقد صلاحية `profile:read`)

افحص توقيعك

إذا فشل التحقق من توقيع، فاسأل أنيس عمّا رآه: افحص توقيعك يمرّر استدعاءك عبر جميع فحوصات أنيس، ولا يغيّر شيئًا، ويُبلغك بالطريقة (method) والعنوان والمسار والاستعلام (query) التي شملها التوقيع، والمفتاح الذي عثر عليه، والصلاحيات السارية. ويتطلّب صلاحية diagnostics:use.

var seen = await anis.Diagnostics.CheckSignatureAsync(ct);
Console.WriteLine($"{seen.Method} {seen.Authority}{seen.Path} ?{seen.CanonicalQuery} key {seen.KeyId}");

ما يُجيب به الفحص الذاتي يدلّك على موضع المشكلة:

الفحص الذاتي	ما يعنيه
ينجح	مفتاحك وحالته وساعتك والعنوان وشبكتك كلها سليمة. المشكلة في مسار الاستدعاء الفاشل نفسه أو استعلامه أو محتواه: قارن نصّ التوقيع لذلك الاستدعاء بـأمثلة اختبار التوقيع. وإذا رُفض ذلك الاستدعاء بالرمز `insufficient_scope`، فقارن الصلاحيات التي يسردها الفحص الذاتي بالصلاحية التي يحتاجها.
يُرفض بالرمز `malformed_signed_request`	أداة التوقيع لديك تبني الاستدعاءات بشكل خاطئ: ترويسة توقيع، أو الأجزاء الموقّعة أو ترتيبها، أو المعامل `nonce`، أو بصمة المحتوى (`Content-Digest`) — والفحص الذاتي يُرسل `{}` بالضبط. تقرّر أنيس ذلك قبل أن تنظر في أي مفتاح، فهو لا يقول شيئًا عن مفتاحك.
يُرفض بالرمز `invalid_credentials`	معرّف المفتاح أو ملف المفتاح، أو حالة المفتاح، أو ساعتك، أو صيغة التوقيع — أو العنوان: استدعِ العنوان الذي أعطتك إياه أنيس كما هو تمامًا. راجع قائمة فحص الرفض 401 بندًا بندًا.
يُرفض بالرمز `insufficient_scope`	تستدعي من خارج الشبكات المسموح بها لك، أو أن تطبيقك يفتقد صلاحية `diagnostics:use`. اقرأ ملفك التعريفي من الخادم نفسه: إن أجاب فشبكتك سليمة — تحقّق من أنه يسرد `diagnostics:use`؛ وإن رُفض بالطريقة نفسها فالسبب الشبكة (أو أن التطبيق يفتقد صلاحية `profile:read` أيضًا). اطلب من موظفي أنيس تغيير أيٍّ منهما.

إذا لم يتغيّر شيء من جهتك

إذا رُفض الفحص الذاتي بالرمز invalid_credentials، ولم تكشف قائمة فحص الرفض 401 شيئًا، ولم يتغيّر شيء من جهتك، فقد يكون وصولك معلّقًا: اكتب إلى support@anis.ly واذكر قيمة requestId للاستدعاء المرفوض.