طابع DHL Internetmarke: الطابع كملصق ZPL

الطابع مجرد ملصق آخر

المتاجر ومكاتب الإصلاح وفرق الخدمات اللوجستية ترسل رسائل فردية كل يوم: دليل مع فاتورة، نموذج إرجاع، رسالة مسجلة. الخطوة المادية الأخيرة هي الدفع البريدي—ما يعني عادة آلة طابع بريدي أو درج طوابع مطبوعة مسبقًا أو مشيًا إلى الآلة.

تكامل INTERNETMARKE يشتري الطابع الحقيقي المدفوع قانونيًا عبر بيانات مطوّر DHL الخاصة بك ضد محفظة Portokasse الخاصة بك، ويعيده بصيغتين:

• PDF - مستند الطابع الرسمي، 43 × 89 مم، بتدوير تلقائي.
• ZPL - نفس الطابع مُحوّلًا إلى نقاط بدقة 203 (711 × 344 بكسل)، جاهزًا لطابعة Zebra.

zplCloud لا يعيد بيع الرسوم البريدية. كل عملية شراء تُخصم من Portokasse بالسعر الحالي PPL؛ بلا هامش ربح ولا تقريب ولا مخزون مشترى مسبقًا.

إعداد لمرة واحدة

التكاملات ← DHL Internetmarke:

1. البيانات - مفتاح API وسر من بوابة مطوّري DHL، إضافة إلى دخول Portokasse (بريد إلكتروني وكلمة مرور، بحد أقصى 22 حرفًا). يجب اعتماد تطبيق REST مرة واحدة في واجهة Portokasse تحت بياناتي ← التطبيقات التجارية. إن تخطيت ذلك، يعيد كل استدعاء 401 genericUserAuthenticationError—البيانات صحيحة، التطبيق ببساطة غير مفعّل.

2. المرسلون - عنوان مرسل واحد أو أكثر؛ علّم واحدًا كافتراضي.

3. المنتج - منتج الرسالة المراد شراؤه.

تحقق يتحقق من البيانات ويعرض رصيد Portokasse الحالي. سر API وكلمة مرور Portokasse مخزنان على الخادم ولا يُعادان أبدًا إلى المتصفح.

واجهتا API، وأيها تريد

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

شراء طابع (API العامة):

curl -X POST https://api.zplcloud.com/v1/integrations/dhl/stamp \
  -H "X-Api-Key: sk_zplcloud_…" -H "Content-Type: application/json" \
  -d '{
        "format": "zpl",
        "receiver": { "name": "Max Mustermann",
                      "addressLine1": "Musterstrasse 12b",
                      "postalCode": "12345", "city": "Musterstadt",
                      "country": "DEU" }
      }'

senderId اختياري—يُستخدم المرسل الافتراضي عند حذفه. يحمل الرد ZPL والهندسة ومعرّفات DHL لسجلاتك والرصيد الجديد:

{
  "ok": true, "format": "zpl",
  "zpl": "^XA^FO…^XZ",
  "widthMm": 89, "heightMm": 43,
  "widthPx": 711, "heightPx": 344,
  "walletBalanceCents": 12220,
  "voucherId": "VH-4f2a9c…",
  "shopOrderId": "1000023456"
}

format: "pdf" يعيد PDF الطابع الأصلي بصيغة base64.

قبل الشراء، تحقق مما يمكنك شراؤه:

GET /v1/integrations/dhl/status    # الرصيد + كتالوج المنتجات
GET /v1/integrations/dhl/stamps    # معاملاتك بما فيها معرفات القسائم

اقرأ status قبل الدفعة. الشراء برصيد Portokasse فارغ يفشل لدى DHL، والمحاولة الفاشلة هي ما ستجده في السجل بعدها.

Print Views: لا عميل API على طاولة التغليف

لعداد الشحن لا تريد تكاملًا على كل مكتب. Print View لـ DHL لا يحتاج أي تصميم ملصق—الطابع هو الملصق. له عنوان URL خاص:

https://print.zplcloud.com/d/dhl/{slug}

أولوية الجوال، قابل للتثبيت كـ PWA، مع حقل بحث وقائمة مرسلين ونموذج مستلم واختيار طابعة.

ربط قاعدة بيانات الطلبات

شغّل وكيل CLI على جهاز في شبكتك. سلسلة اتصال SQL Server تبقى هناك:

zplcloud proxy --agent "Lager" \
  --sql ORDERS="Server=127.0.0.1;Database=erp;User Id=zplcloud;Password=…;Encrypt=True;TrustServerCertificate=True"

أنشئ مصدر البيانات (مصادر البيانات، النوع SQL Server، الخادم ORDERS) باستعلام أساسي:

SELECT orderId, nachname, vorname, strasse, plz, ort
FROM auftraege
WHERE orderId LIKE @p0

ثم اربط الأعمدة في محرر Print View تحت DHL: عمود معرّف الطلب (الافتراضي orderId) هو ما يُطابق القيمة المُدخلة، وحقول المستلم تأخذ الاسم والشارع والرمز البريدي والمدينة. يمكن للاسم دمج أعمدة: vorname+nachname.

ماذا يفعل المشغّل

اكتب 10042 ← بحث ← ينفذ الوكيل الاستعلام وتمتلئ حقول المستلم ← اختر المرسل والطابعة ← اشترِ واطبع:

1. يُشترى الطابع عبر Portokasse الخاص بك،

2. يُحوَّل PDF إلى ZPL بدقة 203،

3. يذهب ZPL إلى الطابعة المحددة (Weblink أو طابعة وكيل CLI).

رسالة النجاح تظهر فقط بعد أن تقبل الطابعة المهمة. إذا كانت الطابعة غير متاحة تُبلغ العملية كخطأ بدلًا من النجاح الصامت—لقد دفعت ثمن ذلك الطابع، لذا عليك أن تعرف هل خرج.