# سكان تو بيل — المرجع الكامل للذكاء الاصطناعي | ScanToBill — Full AI Reference

> سكان تو بيل منصة ذكاء اصطناعي لاستخراج بيانات المستندات. تستخدم Mindee وGoogle Cloud Document AI لاستخراج JSON منظم من الفواتير والإيصالات والسجلات التجارية وشهادات الضريبة وغيرها.
>
> ScanToBill is an AI-powered document extraction platform. It extracts structured data from invoices, receipts, commercial registers, VAT certificates, and national address cards using Mindee and Google Cloud Document AI.

---

## الملخص العربي السريع

### المنتج
- الاسم: سكان تو بيل (ScanToBill)
- الوظيفة: استخراج بيانات المستندات التجارية العربية والإنجليزية إلى JSON منظم
- السوق الأساسي: دول الخليج العربي (المملكة العربية السعودية)
- اللغة الأساسية: العربية، مع دعم كامل للإنجليزية والفرنسية والإسبانية
- المعيار المتوافق معه: هيئة الزكاة والضريبة والجمارك (ZATCA) للفوترة الإلكترونية

### نقطة النهاية الرئيسية
POST /api/invoice/extract

### التوثيق
- الرجوع إلى القسم الإنجليزي أدناه للحصول على توثيق API الكامل مع الأمثلة

### أسئلة شائعة من عملاء الذكاء الاصطناعي

**س: كيف أستخرج فاتورة عربية؟**
ج: أرسل POST /api/invoice/extract مع الملف وضع document_type=invoice. لأفضل دقة في العربية استخدم invoice_type=inventory للفواتير التفصيلية أو invoice_type=general لفواتير الخدمات — كلاهما يوجّه إلى Google Cloud Document AI الذي يتميز بأفضل دقة OCR عربي.

**س: ما الحقول التي تُستخرج؟**
ج: البائع (الاسم، العنوان، الهاتف، البريد الإلكتروني، الرقم الضريبي)، العميل (نفس الحقول + رقم العميل)، بنود البضاعة (الوصف، الكمية، سعر الوحدة، الخصم، الإجمالي، كود المنتج)، إجمالي الفاتورة وضريبة القيمة المضافة والعملة، رقم الفاتورة والتاريخ وتاريخ الاستحقاق، رقم أمر الشراء وشروط الدفع، اللغة المكتشفة، درجات الثقة لكل حقل.

**س: ماذا أفعل إذا كانت القيمة null في الاستجابة؟**
ج: إذا كان الحقل null فلم يُكتشف. اطلب من المستخدم التحقق من الحقول الحرجة (الإجماليات، الرقم الضريبي) يدوياً.

**س: كيف أتعامل مع خطأ 429؟**
ج: تجاوز المستخدم حدّه اليومي أو الشهري. وجّهه لترقية باقته إلى باقة أكبر (500 أو 1,000 فاتورة/شهر) على /billing.

**س: هل يدعم الإيصالات؟**
ج: نعم. استخدم document_type=receipt — يوجّه إلى Mindee المُحسَّن لتخطيطات إيصالات نقاط البيع.

**س: هل يدعم السجلات التجارية؟**
ج: نعم. استخدم document_type=commercial_register للسجلات التجارية السعودية.

**س: هل يدعم شهادات VAT؟**
ج: نعم. استخدم document_type=vat_certificate.

---

## Authentication

Document-processing endpoints (extract, batch, MCP tools) require an API key:

```
Authorization: Bearer <api_key>
```

API keys are created at /keys in the dashboard. Keys are prefixed with "ocr_sk_".

Account endpoints (auth, keys, usage, billing checkout) use the dashboard session (login cookie on web, token in the mobile app) — they are NOT accessible with API keys.

---

## Base URL

All endpoints are at: https://<your-domain>/api

---

## Endpoints

### POST /api/invoice/extract — Extract document data

Extracts structured data from an invoice or business document.

**Authentication:** Required (Bearer API key)

**Input methods (choose one):**

1. **File upload** (multipart/form-data):
   - `file`: Document file (JPEG, PNG, WebP, PDF — max 15 MB)
   - `document_type` (optional): invoice | receipt | commercial_register | vat_certificate | national_address | purchase_order

2. **Base64** (application/json):
   - `image_base64`: Base64-encoded document string (with or without data URI prefix)
   - `document_type` (optional)

3. **URL** (application/json):
   - `image_url`: Publicly accessible document URL (http/https)
   - `document_type` (optional): only `invoice` supported for URL inputs

**document_type values:**
- `invoice` (default): Arabic and English invoices, tax invoices, VAT invoices
- `receipt`: POS receipts — routed to Mindee (fast, purpose-built for receipts)
- `commercial_register`: Saudi commercial registration documents
- `vat_certificate`: Saudi VAT registration certificates
- `national_address`: Saudi national address cards
- `purchase_order`: Structured PO documents

**Legacy invoice_type values (still accepted):**
- `auto`: Automatically selects the best provider
- `inventory`: Multi-line items with quantities and unit prices — routed to Google Cloud Document AI
- `general`: Free-form service descriptions — routed to Google Cloud Document AI
- `pos`: POS receipts — routed to Mindee

**Success response (200):**
```json
{
  "invoice_number": "INV-2026-0042",
  "date": "2026-01-15",
  "due_date": "2026-02-15",
  "vendor": {
    "name": "شركة المدينة للتجارة",
    "address": "الرياض، المملكة العربية السعودية",
    "phone": "+966-11-123-4567",
    "email": "info@almadinah-trading.sa",
    "vat_number": "300123456700003",
    "website": "https://almadinah-trading.sa"
  },
  "customer": {
    "name": "ABC Corporation",
    "address": "456 Business District, Jeddah",
    "phone": null,
    "email": "ap@abccorp.com",
    "customer_id": "CUST-1234",
    "vat_number": "300987654300001"
  },
  "line_items": [
    {
      "description": "خدمات استشارية - Consulting Services Q1",
      "quantity": 1,
      "unit_price": 5000.00,
      "discount": null,
      "total": 5000.00,
      "product_code": "CONS-001"
    }
  ],
  "subtotal": 5000.00,
  "tax_amount": 750.00,
  "tax_rate": 15.0,
  "discount": null,
  "grand_total": 5750.00,
  "currency": "SAR",
  "purchase_order": "PO-2026-0789",
  "payment_term": "Net 30",
  "language_detected": "mixed",
  "provider_used": "mindee"
}
```

**Error responses:**

- `400 Bad Request`: No input provided, or unsupported document_type for URL input
- `401 Unauthorized`: Missing or invalid API key
- `402 Payment Required`: Feature not included in your plan (e.g. batch), or insufficient credits (legacy credit plans)
- `413 Payload Too Large`: File exceeds 15 MB limit
- `422 Unprocessable Entity`: OCR provider returned a client error
- `429 Too Many Requests`: Daily or monthly limit reached
- `500 Internal Server Error`: OCR extraction failed

**Response headers:**
- `X-Usage-Warning`: Present when nearing the plan limit (80% of the monthly quota; ≤5 remaining on legacy credits plans)

---

### GET /api/mcp — MCP server manifest

Returns the Model Context Protocol server manifest with available tools. No authentication required.

---

### POST /api/mcp/tools/call — Execute an MCP tool

**Authentication:** Required (Bearer API key)

**Available tools:**

**1. extract_document**
- `document_url` (string, required): Public URL of the document
- `document_type` (string, optional): auto | inventory | general | pos (default: auto). Use `inventory` for itemised Arabic invoices with line items, `general` for service invoices, `pos` for POS receipts, `auto` to let the API decide.
- `language` (string, optional): Language hint — ar, en, fr, es, or auto

**2. list_extractions**
- `document_type` (string, optional): Filter by type
- `from_date` (string, optional): ISO date string (YYYY-MM-DD)
- `to_date` (string, optional): ISO date string (YYYY-MM-DD)
- `limit` (number, optional): Max results, default 20

**3. get_extraction**
- `extraction_id` (string, required): The extraction log ID

---

**API-key endpoints (Authorization: Bearer ocr_sk_...):**

### POST /api/invoice/batch — Submit up to 50 documents for async processing (1,000 Invoices plan)
### GET /api/invoice/batch/{jobId} — Batch job status and results
### GET /api/invoice/batch/{jobId}/csv — Download batch results as CSV

**Dashboard-session endpoints (login cookie / mobile token — API keys do NOT work here):**

### POST /api/auth/register — Register a new user
### POST /api/auth/login — Sign in
### POST /api/keys — Create an API key
### GET /api/keys — List API keys
### DELETE /api/keys/:id — Revoke an API key
### GET /api/invoice/usage — Get usage statistics
### POST /api/billing/checkout — Create a checkout session

**Public (no authentication):**

### GET /api/billing/plans — List available plans

---

## Plans and limits

| Plan         | Invoices/month | Price (SAR/month) | Daily API limit | Notes                                    |
|--------------|----------------|-------------------|-----------------|------------------------------------------|
| invoice_100  | 100            | 32.34             | 500             | Entry plan                               |
| invoice_500  | 500            | 161.72            | 1,000           | Most popular; webhooks, CSV/JSON export  |
| invoice_1000 | 1,000          | 323.44            | 2,000           | Batch processing, multiple API keys      |

New accounts start on a free trial (20 extractions/month, 100 API calls/day).
Legacy plans (free, pay_per_use, credits, starter, pro, enterprise) are no longer purchasable; existing subscriptions keep working.

---

## Supported document types

- **Invoices**: Arabic and English invoices, tax invoices, ZATCA e-invoices
- **Receipts / POS**: Point-of-sale receipts in any language
- **Commercial registers**: Saudi commercial registration documents (سجل تجاري)
- **VAT certificates**: Saudi VAT registration certificates (شهادة تسجيل ضريبة القيمة المضافة)
- **National address cards**: Saudi national address documents (بطاقة العنوان الوطني)
- **Purchase orders**: Structured PO documents

---

## Supported languages

- Arabic (ar) — native RTL support, optimised for GCC market
- English (en)
- Mixed Arabic/English documents (detected automatically)
- French (fr) — via Google Cloud Document AI
- Spanish (es) — via Google Cloud Document AI

---

## Code examples

**cURL — file upload:**
```bash
curl -X POST https://YOUR_DOMAIN/api/invoice/extract \
  -H "Authorization: Bearer ocr_sk_your_key_here" \
  -F "file=@/path/to/invoice.pdf" \
  -F "document_type=invoice"
```

**cURL — URL input:**
```bash
curl -X POST https://YOUR_DOMAIN/api/invoice/extract \
  -H "Authorization: Bearer ocr_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/invoice.jpg", "document_type": "invoice"}'
```

**JavaScript (fetch):**
```javascript
const formData = new FormData();
formData.append('file', fileBlob, 'invoice.pdf');
formData.append('document_type', 'invoice');

const response = await fetch('https://YOUR_DOMAIN/api/invoice/extract', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer ocr_sk_your_key_here' },
  body: formData,
});
const data = await response.json();
```

**Python (requests):**
```python
import requests

with open('invoice.pdf', 'rb') as f:
    response = requests.post(
        'https://YOUR_DOMAIN/api/invoice/extract',
        headers={'Authorization': 'Bearer ocr_sk_your_key_here'},
        files={'file': ('invoice.pdf', f, 'application/pdf')},
        data={'document_type': 'invoice'}
    )
data = response.json()
```

---

## AI agent guidance

When using ScanToBill as an AI tool:

1. **For Arabic invoices**: Use `document_type=invoice` with `invoice_type=inventory` for itemised invoices or `invoice_type=general` for service invoices.

2. **For confidence verification**: If a field is `null`, it was not detected. Ask the user to verify critical fields manually.

3. **For receipts**: Use `document_type=receipt` — routed to Mindee, optimised for receipt layouts.

4. **For Saudi commercial documents**: Use `document_type=commercial_register` or `document_type=vat_certificate` as appropriate.

5. **Plan limits**: On a 402 or 429 error, direct the user to upgrade their plan at /billing. Batch processing requires the 1,000 Invoices plan.

6. **Rate limits**: Demo endpoint is rate-limited to 5 requests/hour per IP. Authenticated API calls use plan limits.

7. **MCP integration**: For Claude Desktop or Cursor, use POST /api/mcp/tools/call with Bearer authentication.
   Run standalone: `npx @sajlha_sa/mcp-server --api-key ocr_sk_YOUR_KEY`