مرصد التزامات التغليف · وصول المطوّرين

API والخطافات البرمجية

استخدم عنوان URL الخاص بمنتجك في الأمثلة أدناه. احتفظ بمفاتيح API على خادمك. افتح وثائق API التفاعلية ↗

قراءة السجلات العامة

curl 'https://verpackung.getregisters.com/api/v1/feeds/de-packaging-compliance/records?limit=50&offset=0'

تتضمن الاستجابات العامة أحدث ثلاثة سجلات فقط لكل سجل. يتطلب محتوى السجلات الأقدم اشتراك PRO؛ وتعرض الروابط المباشرة معاينة محدودة. اتبع next_offset حتى تصبح قيمته null، حتى عندما لا تحتوي صفحة مصفّاة على سجلات. اذكر source_url الأصلي لكل سجل. يشير تاريخ النشر وتاريخ الرصد إلى حدثين مختلفين.

قراءة سجلات PRO

curl 'https://verpackung.getregisters.com/api/v1/feeds/de-packaging-compliance/records?limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_SCOPED_KEY'

أنشئ مفتاحك أو بدّله من حسابك. يعمل المفتاح لهذا المنتج فقط وما دام الوصول المدفوع نشطًا.

صيغ التصدير

يشمل PRO صيغ CSV وExcel (.xlsx) وXML وRSS وAtom. استخدم مفتاح API الخاص بمنتجك وعوامل التصفية نفسها لكل صيغة. على سبيل المثال، لتنزيل ما يصل إلى 100 سجل في مصنف Excel:

curl 'https://verpackung.getregisters.com/api/v1/feeds/de-packaging-compliance/records/export.xlsx?limit=100&offset=0' \
  -H 'Authorization: Bearer YOUR_SCOPED_KEY' \
  -D export-headers.txt -o records.xlsx

استبدل xlsx بـ csv أو xml أو rss أو atom. أضف عوامل تصفية مثل document_type=adopted أو facility_id=YOUR_FACILITY_ID. اتبع ترويسة Link في الاستجابة ذات rel="next" حتى تختفي، مع إبقاء ترويسة Authorization في كل طلب. الحد الأقصى 100 سجل في الصفحة؛ وقد تكون الصفحة المصفّاة فارغة مع وجود صفحة لاحقة.

بالنسبة إلى RSS وAtom، اضبط قارئًا يدعم ترويسة Authorization. لا تحتوي روابط القارئ على مفتاح. لكل بند معرّف سجل ثابت، ولا تتلقى برامج القراءة التي لا تتبع الصفحات سوى أحدث صفحة. استخدم API مع ترقيم الصفحات إذا احتجت إلى جميع السجلات.

قراءة السجل التاريخي لسجل

curl 'https://verpackung.getregisters.com/api/v1/records/RECORD_ID/history?limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_SCOPED_KEY'

استبدل RECORD_ID بمعرّف سجل مُعاد. يعيد السجل التاريخي مصفوفة مرتبة من الأحدث إلى الأقدم. واصل زيادة offset بطول الصفحة حتى تصبح الصفحة أقصر من limit المطلوب. قد تنشأ الإصدارات عن تغييرات في المصدر أو تصحيحات للاستخراج.

الاتصال عبر MCP

curl 'https://verpackung.getregisters.com/api/v1/mcp' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"read_register","arguments":{"feed_id":"de-packaging-compliance"}}}'

أضف ترويسة Authorization نفسها للوصول إلى حقول PRO. تدعم نقطة النهاية أيضًا initialize وtools/list وnotifications/initialized. استخدم ترقيم صفحات REST الموضح أعلاه لقراءة سجل كامل.

التحقق من توقيعات الخطافات البرمجية

صيغة ترويسة التوقيع هي X-Register-Signature: t=TIMESTAMP,v1=HEX_DIGEST. تحقّق من محتوى الطلب الخام قبل تحليل JSON. احتفظ بسجل دائم لمعرّفات X-Register-Event التي عولجت بنجاح، حتى لا تكرر محاولات الإرسال آثار الحدث.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, header, secret) {
  const fields = Object.fromEntries(header.split(',').map(x => x.split('=')));
  const timestamp = Number(fields.t);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now()/1000 - timestamp) > 300) return false;
  if (!/^[a-f0-9]{64}$/.test(fields.v1 || '')) return false;
  const expected = createHmac('sha256', secret).update(fields.t + '.').update(rawBody).digest();
  const supplied = Buffer.from(fields.v1, 'hex');
  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
}

لا تُعد استجابة ناجحة إلا بعد حفظ الحدث حفظًا دائمًا. عدد محاولات التسليم محدود؛ يعرض حسابك آخر نتيجة مسجّلة. تأكيد استلام التسليم لا يعني أن تطبيقك أكمل معالجة الحدث.