ربط زاتكا بـ Java / Kotlin
طلب HTTP واحد من Java / Kotlin (java.net.http + JDBC): ماثل يبني الفاتورة ويوقّعها ويرسلها للهيئة، ويرجّع رد الهيئة والـ XML القانوني والـ PDF مع رمز QR.
١. جرّبه الحين (بدون مفتاح)
// Java 15+; import java.net.URI; import java.net.http.*;
var body = """
{"environment":"sandbox","pdf":true,"invoice":{"type":"simplified",
"line_items":[{"name":"قهوة","quantity":2,"price":"50.00"}]}}""";
var res = HttpClient.newHttpClient().send(
HttpRequest.newBuilder(URI.create("https://matheel.app/api/v1/invoices"))
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(body)).build(),
HttpResponse.BodyHandlers.ofString());
System.out.println(res.body()); // {"status":"reported", "pdf":"JVBERi0…", …}
٢. الدالة الجاهزة بعد الدفع
تقفل صف الجهاز (عشان دفعتين بنفس اللحظة ما يكسرون السلسلة)، ترسل الفاتورة مع "pdf": true، وتحفظ device_token الجديد. أي رد غير 200 يرجّع الـ transaction والمفتاح القديم يظل صالح.
// JDBC + java.net.http. Jackson (or any JSON library) for the body.
public Map<String, Object> matheelInvoice(Connection db, List<Map<String, Object>> items) throws Exception {
db.setAutoCommit(false);
try {
ResultSet rs = db.createStatement().executeQuery("SELECT token FROM matheel_device WHERE id = 1 FOR UPDATE");
rs.next();
String body = json.writeValueAsString(Map.of("device_token", rs.getString(1), "pdf", true,
"invoice", Map.of("type", "simplified", "line_items", items)));
HttpResponse<String> r = http.send(HttpRequest.newBuilder(URI.create("https://matheel.app/api/v1/invoices"))
.header("Content-Type", "application/json").header("Authorization", "Bearer " + System.getenv("MATHEEL_KEY"))
.POST(HttpRequest.BodyPublishers.ofString(body)).build(), HttpResponse.BodyHandlers.ofString());
Map<String, Object> res = json.readValue(r.body(), Map.class);
if (r.statusCode() != 200) throw new IllegalStateException(r.body());
PreparedStatement up = db.prepareStatement("UPDATE matheel_device SET token = ? WHERE id = 1");
up.setString(1, (String) res.get("device_token")); up.executeUpdate();
db.commit();
return res;
} catch (Exception e) { db.rollback(); throw e; }
}
٣. للإنتاج
- سجّل جهازك مرة (مفتاح الجهاز أو لينك التفعيل) وحط
device_tokenفي جدولmatheel_device. - لو المبلغ اللي معك شامل الضريبة، أرسل
"prices_include_vat": true. - احفظ
invoice_xml(القانوني) وpdfمع الطلب، والتطبيق يعرض الـ PDF من سيرفرك.
أسئلة شائعة
أحتاج مكتبة Java / Kotlin خاصة بزاتكا؟
لا. ماثل API عادي بـ JSON: طلب HTTP واحد. التوقيع والـ XML والشهادة والإرسال للهيئة كلها عند ماثل.
وين أحفظ مفتاح الجهاز؟
صف واحد في قاعدة بياناتك (جدول matheel_device). بعد كل رد 200 احفظ device_token الجديد في نفس الـ transaction.
أجرّب قبل الاشتراك؟
إيه، على بيئة المطورين بدون مفتاح: الطلب تحت يرجّع رد الهيئة الحقيقي والـ PDF.