ربط Telr مع زاتكا
Telr (بوابة دفع) يبلغك لما الطلب يندفع، وماثل يحوّل هالدفعة لفاتورة زاتكا مرسلة ومقبولة، مع PDF عربي وإنجليزي فيه رمز QR.
بدون كود: قالب n8n جاهز يتحقق من توقيع Telr ويطلّع الفاتورة لكل دفعة ناجحة (الخطوات في التوثيق).
الحدث اللي تستمع له
Transaction advice (HTTP POST, form fields tran_*) to a pre-configured URL; paid when tran_status = 'A' (H = authorised but on hold)
التسجيل
Telr Merchant Administration System > 'Payment Page' or 'Security' menu > 'Transaction advice': URL, transaction types, optionally 'Only include authorised transactions (status A or H)'
التحقق إن الطلب جاي من Telr
Field tran_check = SHA1 of secret:tran_store:tran_type:tran_class:tran_test:tran_ref:tran_prevref:tran_firstref[:tran_order]:tran_currency:tran_amount:tran_cartid:tran_desc:tran_status:tran_authcode:tran_authmessage (trimmed values, case-insensitive compare). tran_order only when Telr support has enabled it
المبلغ والبنود
- المبلغ:
tran_amount + tran_currency - البنود:
none; use your own order via tran_cartid - إيميل العميل:
bill_email (covered by its own bill_check hash)
بوابات الدفع ما ترسل بنود الطلب: الكود يجيبها من طلبك أنت برقم الطلب (الدالة load_order_items من نظامك، مو من ماثل).
لو المبلغ شامل الضريبة (وهو الغالب)، أرسله زي ما هو مع "prices_include_vat": true.
الكود
يستقبل الحدث، يتحقق منه، ويستدعي matheel_invoice(items): الدالة الجاهزة اللي تقفل صف الجهاز وترسل الفاتورة وتحفظ المفتاح الجديد.
<?php
// Telr transaction advice: form POST, verified by the SHA1 tran_check field.
$fields = ['tran_store','tran_type','tran_class','tran_test','tran_ref','tran_prevref','tran_firstref'];
if (isset($_POST['tran_order'])) $fields[] = 'tran_order'; // only if Telr enabled it
$fields = array_merge($fields, ['tran_currency','tran_amount','tran_cartid','tran_desc',
'tran_status','tran_authcode','tran_authmessage']);
$str = getenv('TELR_ADVICE_SECRET');
foreach ($fields as $f) $str .= ':' . trim($_POST[$f] ?? '');
if (strcasecmp(sha1($str), $_POST['tran_check'] ?? '') !== 0) { http_response_code(401); exit('Check mismatch'); }
http_response_code(200);
if ($_POST['tran_status'] !== 'A') exit; // A = authorised, H = on hold
$items = load_order_items($_POST['tran_cartid']); // your lines, price before VAT
matheel_invoice($items);
ملاحظات
Confirmed earlier and re-read for this entry. The docs disagree on tran_order: the prose formula leaves it out and says to include it only when enabled, while the PHP sample always adds a ':' slot for it; the sketch follows the prose. Telr's own PHP sample compares against an undefined $hash_check instead of $check. Separate card_check and bill_check hashes cover the card_* and bill_* fields.
أسئلة شائعة
هل Telr يرسل الفواتير لزاتكا بنفسه؟
Telr بوابة دفع، وربطه مع الهيئة يكون عن طريق خدمة مثل ماثل: كل دفعة ناجحة تتحول لفاتورة مرسلة للهيئة.
لازم أعدّل الأسعار عشان الضريبة؟
لا. أرسل المبلغ اللي دفعه العميل مع "prices_include_vat": true، وماثل يطلّع الضريبة ويخلّي المبلغ المستحق في الفاتورة نفس المدفوع.
وش يصير لو جت دفعتين بنفس الثانية؟
فواتير الجهاز تمشي ورا بعض. اقفل صف الجهاز وقت الإرسال (موجود في الدالة الجاهزة)، وماثل يرفض أي نسخة قديمة من مفتاح الجهاز بـ 409 عشان السلسلة ما تنكسر.