📘 SarfSDK Integration Guide

This guide explains how to integrate SarfSDK into your Laravel (or any web) project.

1. Introduction

SarfSDK is part of the Sarf application, a digital platform that helps users track budgets, monitor daily expenses, and maintain financial records.

By integrating this SDK, your system can send invoices directly to Sarf users, eliminating manual entry and enabling real-time expense tracking.

2. How to Include

<script src="https://sarf.sa/project/sdk/sarf-sdk.js"></script>
<script>
  SarfSDK({
    key: "YOUR_PUBLIC_KEY",
    container: "sarf-sdk",
    userid: "9665XXXXXXXX",
    invoiceTotal: "total",
    customer_mobile: "customer_mobile",
    description: "description",
    attachments: "attachments",
    language: "en"  // or "ar"
  });
</script>

3. Configuration Options

Option	Type	Required	Description
`key`	String	✅ Yes	Your Sarf public API key.
`container`	String	✅ Yes	Element ID where SDK will render.
`userid`	String	✅ Yes	User’s mobile number (9665XXXXXXXX).
`invoiceTotal`	String	❌ No	Input ID for invoice total.
`customer_mobile`	String	❌ No	Input ID for customer’s mobile number.
`description`	String	❌ No	Input ID for invoice description.
`attachments`	String	❌ No	File input ID for invoice attachments.
`isModal`	Boolean	❌ No	Whether to use modal form (default: true).
`register_div`	String	❌ No	Element ID where register button appears.
`invoice_btn_type`	"button" / "submit"	❌ No	Button type for invoice submission.
`registration_btn_type`	"button" / "submit"	❌ No	Button type for registration.
`language`	"en" or "ar"	❌ No	Interface language (default: "ar").

4. Workflow

SDK initializes and validates your public key.
Calls /api/check-user to verify the userid.
If user exists → shows Send Invoice button.
If not → shows Register with Sarf button.
If customer_mobile + invoiceTotal are present → invoice auto-generated.
Otherwise → modal form appears for manual input.

5. Examples

Example 1: Show Only Buttons

<div id="sarf-sdk"></div>

<script>
  SarfSDK({
    key: "MY_PUBLIC_KEY",
    container: "sarf-sdk",
    userid: "966500123456",
    language: "en"
  });
</script>

Example 2: Auto-send Invoice

<input type="text" id="customer_mobile" value="966500987654" />
<input type="text" id="total" value="150.75" />
<input type="text" id="description" value="Order #1234" />
<input type="file" id="attachments" multiple />

<div id="sarf-sdk"></div>

<script>
  SarfSDK({
    key: "MY_PUBLIC_KEY",
    container: "sarf-sdk",
    userid: "966500123456",
    invoiceTotal: "total",
    customer_mobile: "customer_mobile",
    description: "description",
    attachments: "attachments",
    language: "en"
  });
</script>

6. API Endpoints Used

/api/validate-key → Validate key
/api/check-user → Check user registration
/api/user/list → Search customers
/api/generate_simple_invoice → Generate invoice

7. Error Handling

Empty fields → Invoice not generated.
Invalid files → Attachments rejected.
Invalid/expired key → Auth error.
Network issues → Console + alert message.