البدء السريع

من الصفر إلى أول فاتورة معتمدة في خمس خطوات.

1 — أنشئ حسابًا واحصل على مفتاح اختبار

بعد التسجيل نُنشئ لك تلقائيًا مفتاحًا بصيغة fwt_test_…. تجده في صفحة المفاتيح. مفاتيح الاختبار لا تتصل ببوابة الفوترة الوطنية إطلاقًا.

2 — تأكّد أن المفتاح يعمل

curl https://fawtara.codexal.co/api/v1/ping \
  -H "Authorization: Bearer fwt_test_xxxxxxxxxxxx"

{
  "data": {
    "object": "ping",
    "ok": true,
    "mode": "test",
    "account_id": "acc_3b91f0c2a7d4e856",
    "scopes": ["invoices:write", "invoices:read", "account:read"],
    "api_version": "v1"
  }
}

3 — أرسل أول فاتورة

curl -X POST https://fawtara.codexal.co/api/v1/invoices \
  -H "Authorization: Bearer fwt_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ea1c-4b7f-9c0d-2a3b4c5d6e7f" \
  -d '{
    "invoice_number": "INV-1001",
    "issue_date": "2026-10-23",
    "payment_method": "cash",
    "customer": {
      "name": "شركة المثال للتجارة",
      "identity_type": "tax",
      "identity_number": "12345678",
      "phone": "0790000000",
      "city": "Amman"
    },
    "lines": [
      { "name": "خدمة استشارية", "quantity": 1, "unit_price": 150.000 }
    ]
  }'

الردّ (مختصَر):

{
  "data": {
    "id": "inv_7a2f9c1b4e8d0536",
    "status": "accepted",
    "invoice_number": "INV-1001",
    "uuid": "4f1a7c2e-9b3d-4e85-a0f6-1c2d3e4f5a6b",
    "icv": 1,
    "qr_content": "AQ3YtNix...",
    "qr_image_url": "https://fawtara.codexal.co/api/v1/invoices/inv_7a2f9c1b4e8d0536/qr.png",
    "ubl_url": "https://fawtara.codexal.co/api/v1/invoices/inv_7a2f9c1b4e8d0536/ubl",
    "totals": { "subtotal": 150.000, "discount_total": 0, "tax_total": 0, "total": 150.000 }
  }
}

4 — اطبع رمز QR على الفاتورة

لديك خيارَان:

• استخدم qr_image_url مباشرة في وسم <img> (يتطلّب ترويسة المصادقة، لذا احضره من خادمك).
• أو خُذ النصّ من qr_content وولّد الصورة في نظامك بأي مكتبة QR.

5 — انتقل إلى الإنتاج