Skip to content

وثائق واجهة برمجة تطبيقات NFL

يمكنك عرض ملصقات غذائية متوافقة مع المعايير، وإدارة الوصفات، واستخراج البيانات الغذائية برمجيًا. هناك أمران يعملان اليوم مع كل حساب مؤهل: تضمين الملصق المباشر و الصادرات المُعالجة بواسطة الخادمتتوفر واجهة برمجة تطبيقات موارد REST في مرحلة الوصول المبكر ضمن خطة الأعمال.

تقبل واجهة برمجة التطبيقات (API) وتعيد فقط بيانات JSON (تعيد نقاط نهاية عرض التسميات الملف الثنائي).

تعريف

https://nutritionfactlabel.com/api/v1

نقطة نهاية واجهة برمجة التطبيقات

جميع موارد REST موجودة ضمن عنوان URL أساسي واحد مُرقّم. التغييرات الجذرية تُنشر فقط ضمن بادئة إصدار جديدة. خلال فترة الوصول المبكر، ستتلقى رسالة ترحيبية تؤكد عنوان URL الأساسي المُفعّل لمفاتيحك.

ملخص أنماط عناوين URL للموارد

/v1/recipes
/v1/recipes/{RECIPE_ID}
/v1/recipes/{RECIPE_ID}/label.{svg|png|pdf}
/v1/ingredients
/v1/ingredients/{INGREDIENT_ID}
/v1/analyze

المصادقة

قم بمصادقة كل طلب باستخدام مفتاحك السري في Authorization يتم تحديد نطاق المفاتيح لحسابك وتحمل استحقاقات خطتك: نفس البوابات الموجودة على جانب الخادم مثل التطبيق.

احتفظ بالمفاتيح سراً. لا تقم أبدًا بتضمينها في كود جانب العميل؛ بل قم بتضمينها عبر خادمك الخلفي. قم بتدوير المفتاح المسرب فورًا عن طريق الدعم.

طلب نموذجي

curl https://nutritionfactlabel.com/api/v1/recipes \
  -H 'Authorization: Bearer nfl_live_9f30c2...'

حدود المعدل

للحفاظ على الأمور عادلة ومستقرة: 60 طلبًا في الدقيقة لكل مفتاح؛ يتم تحديد عرض الملصق بشكل إضافي عند 5 متزامنةاطلب بيانات بحجم 1 ميجابايت. بعد تجاوز هذا الحد، ستحصل على 429 مع Retry-After العنوان.

مثال على الإجابة

HTTP/2 429 Too Many Requests
Retry-After: 22

{ "error": { "code": "rate_limited",
  "message": "Try again in 22 seconds." } }

تضمين علامة البث المباشر متوفر الآن

اعرض تسمية محدّثة باستمرار على أي موقع ويب، بدون مفتاح API. فعّل خاصية التضمين في وصفة ضمن أداة إنشاء الوصفات (صف الوصفة ← تضمين) للحصول على رمزها العام.

يتم ضبط ارتفاع وسم البرنامج النصي تلقائيًا؛ يتم تحديث الوصفة في NFL وكل صفحة تعرض المحتوى المضمن. الخطط الاحترافية والتجارية؛ تعطيل المحتوى المضمن يؤدي إلى إلغاء الرمز المميز فورًا.

التعريف: علامة نصية

<script src="https://nutritionfactlabel.com/embed.js"
        data-label="YOUR_EMBED_TOKEN"
        data-width="290"></script>

بديل: إطار iframe

<iframe
  src="https://nutritionfactlabel.com/embed/TOKEN"
  width="290" height="560" frameborder="0"
  title="Nutrition Facts"></iframe>

تصدير الملصقات متوفر الآن

يتم عرض ملفات SVG / PNG / PDF على الخادم بواسطة نفس محرك التطبيق، مع تطبيق قواعد الخطة (التنسيقات، وأنواع الملفات، والعلامة المائية) عند الوصول. استدعِها مباشرةً باستخدام رمز الجلسة الخاص بك حتى تصبح مفاتيح API متاحة للجميع. تُعيد الملف الثنائي، أو 403 خارج خطتك.

ملاحظتان حول التكافؤ مع التصدير داخل التطبيق. يتم عرض التطبيق في المتصفح، لذا استخدم نقطة النهاية هذه عندما تحتاج إلى إنشاء تسمية بدون علامة. jpg يُعيد النظام الحالي بايتات PNG، بينما eps و ai هي تنسيقات مخصصة للتصدير فقط، ولا يدعمها نقطة النهاية.

تعريف

POST /functions/v1/export-label
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

{
  "fileType": "pdf",
  "data": { ...label state },
  "extra": { }
}

وصفات الوصول المبكر · الأعمال

الهدف الأساسي: المكونات، والحصص، و label_format (152 تنسيقًا عبر 114 دولة) ينتج عنها المحسوبة label: القيم الغذائية مقربة حسب الولاية القضائية، بيان المكونات، مسببات الحساسية.

السمات الرئيسية: id, name, servings, serving_weight_g, label_format, label (محسوب)، embed_enabled، الطوابع الزمنية.

تعريف

GET    /v1/recipes
POST   /v1/recipes
GET    /v1/recipes/{ID}
PUT    /v1/recipes/{ID}
DELETE /v1/recipes/{ID}
GET    /v1/recipes/{ID}/label.pdf

مثال على الإجابة

{
  "id": "rcp_2m4k9q",
  "name": "Chocolate Chip Cookies",
  "servings": 12,
  "serving_weight_g": 28,
  "label_format": "standard",
  "label": {
    "calories": 140,
    "total_fat_g": 7,
    "allergens": ["wheat","milk","soy"],
    ...
  },
  "embed_enabled": false
}

مكونات الوصول المبكر · الأعمال

مكونات مخصصة مع معلومات غذائية لكل 100 غرام، وأنواع مسببات الحساسية، وتكلفة اختيارية، مطابقة لتلك التي تم إنشاؤها في التطبيق، ويمكن البحث عنها في أداة إنشاء المكونات. عناوين مكونات وزارة الزراعة الأمريكية هي: usda:{fdc_id}؛ تعيين "archived": true للأرشفة (مستبعدة من القوائم افتراضياً).

تعريف

GET    /v1/ingredients
POST   /v1/ingredients
GET    /v1/ingredients/{ID}
PUT    /v1/ingredients/{ID}
DELETE /v1/ingredients/{ID}

طلب نموذجي

POST /v1/ingredients

{
  "name": "Organic almond flour",
  "nutrients_per_100g": {
    "calories": 571, "total_fat_g": 50,
    "protein_g": 21, "dietary_fiber_g": 10
  },
  "allergens": ["tree_nuts"],
  "cost_per_unit": 12.5, "unit": "kg"
}

تحليل التغذية الوصول المبكر · الأعمال

تحليل فوري دون حفظ الوصفة. يُعيد نفس النتيجة label كائن إضافي claims: ادعاءات المحتوى الغذائي التي تتوافق معها القيم (مثل "مصدر جيد للألياف") مع مراجعها في قانون اللوائح الفيدرالية. تتم مطابقة الأسماء غير المطابقة مع وزارة الزراعة الأمريكية.

طلب نموذجي

POST /v1/analyze

{
  "label_format": "standard",
  "servings": 12,
  "serving_weight_g": 28,
  "ingredients": [
    { "ingredient_id": "usda:173410", "grams": 120 },
    { "name": "brown sugar", "grams": 80 }
  ]
}

أخطاء

رموز HTTP التقليدية؛ أما نص الخطأ فهو JSON مع رمز آلي ثابت ورسالة بشرية. 400 مدخلات مشوهة · 401 مفتاح تالف · 403 خارج خطتك · 404 غير موجود / ليس لك · 429 معدل محدود · 500 أعد المحاولة مع التراجع.

مثال على الإجابة

{
  "error": {
    "code": "plan_format_not_allowed",
    "message": "The 'eu-1169' label format
      requires the Professional plan."
  }
}

الحصول على الوصول

لا يتطلب التضمين مفتاحًا؛ قم بتفعيله لكل وصفة (الإصدار الاحترافي+). يتضمن الإصدار وصولًا مبكرًا إلى واجهة برمجة تطبيقات REST. عمل الخطة: البريد الإلكتروني support@nutritionfactlabel.com يتم إرسال المفاتيح من بريدك الإلكتروني الخاص بالحساب خلال يوم عمل واحد.

هل ينقصك أحد نقاط النهاية التي تحتاجها؟ أخبرنا. شركاء الوصول المبكر يوجهون خارطة الطريق.

قم بالترقية إلى باقة الأعمال