ربط زاتكا بـ Ruby on Rails
طلب HTTP واحد من Ruby on Rails (Net::HTTP + ActiveRecord): ماثل يبني الفاتورة ويوقّعها ويرسلها للهيئة، ويرجّع رد الهيئة والـ XML القانوني والـ PDF مع رمز QR.
١. جرّبه الحين (بدون مفتاح)
require "net/http"; require "json"
r = Net::HTTP.post(URI("https://matheel.app/api/v1/invoices"),
{ environment: "sandbox", pdf: true, invoice: {
type: "simplified", line_items: [{ name: "قهوة", quantity: 2, price: "50.00" }] } }.to_json,
"Content-Type" => "application/json")
puts JSON.parse(r.body)["status"] # reported
٢. الدالة الجاهزة بعد الدفع
تقفل صف الجهاز (عشان دفعتين بنفس اللحظة ما يكسرون السلسلة)، ترسل الفاتورة مع "pdf": true، وتحفظ device_token الجديد. أي رد غير 200 يرجّع الـ transaction والمفتاح القديم يظل صالح.
# ActiveRecord: `lock` is SELECT … FOR UPDATE; any exception rolls the transaction back.
def matheel_invoice(items)
MatheelDevice.transaction do
device = MatheelDevice.lock.find(1)
r = Net::HTTP.post(URI("https://matheel.app/api/v1/invoices"),
{ device_token: device.token, pdf: true, invoice: { type: "simplified", line_items: items } }.to_json,
"Content-Type" => "application/json", "Authorization" => "Bearer #{ENV.fetch("MATHEEL_KEY")}")
res = JSON.parse(r.body)
raise "matheel #{r.code}: #{res}" unless r.code == "200"
device.update!(token: res["device_token"])
res # Base64.decode64(res["pdf"]) is the PDF
end
end
٣. للإنتاج
- سجّل جهازك مرة (مفتاح الجهاز أو لينك التفعيل) وحط
device_tokenفي جدولmatheel_device. - لو المبلغ اللي معك شامل الضريبة، أرسل
"prices_include_vat": true. - احفظ
invoice_xml(القانوني) وpdfمع الطلب، والتطبيق يعرض الـ PDF من سيرفرك.
أسئلة شائعة
أحتاج مكتبة Ruby on Rails خاصة بزاتكا؟
لا. ماثل API عادي بـ JSON: طلب HTTP واحد. التوقيع والـ XML والشهادة والإرسال للهيئة كلها عند ماثل.
وين أحفظ مفتاح الجهاز؟
صف واحد في قاعدة بياناتك (جدول matheel_device). بعد كل رد 200 احفظ device_token الجديد في نفس الـ transaction.
أجرّب قبل الاشتراك؟
إيه، على بيئة المطورين بدون مفتاح: الطلب تحت يرجّع رد الهيئة الحقيقي والـ PDF.