البدء السريع

ثلاث خطوات: اضبط مفتاحك، ثم أنشئ ملف PDF، ثم التقط صورة لصفحة. كل مثال في هذه الصفحة يُشغَّل على الواجهة البرمجية الفعلية قبل نشره.

١. اضبط مفتاح الواجهة البرمجية

تقرأ الأمثلة المفتاح من متغير البيئة SAHIFA_API_KEY، فلا ينتهي به المطاف في الشيفرة المصدرية.

# macOS, Linux
export SAHIFA_API_KEY="sk_live_..."

# Windows PowerShell
$env:SAHIFA_API_KEY = "sk_live_..."

ليس لديك مفتاح بعد؟ راجع الحصول على مفتاح الواجهة البرمجية.

٢. أنشئ PDF من HTML

يرسل هذا الطلب فاتورة عربية قصيرة ويضيف تذييلًا للصفحة، ويحفظ الملف باسم invoice.pdf.

# HTML to PDF with an Arabic footer. Requires: SAHIFA_API_KEY in the environment.
curl https://api.sahifa.dev/v3/convert/pdf \
  --user "api:$SAHIFA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "source": "<html dir=\"rtl\" lang=\"ar\"><body><h1>فاتورة ضريبية</h1><p>الإجمالي: 1,150.00 ر.س</p></body></html>",
    "format": "A4",
    "margin": "20mm",
    "footer": { "source": "<div style=\"width:100%;text-align:center\">صفحة {{page}} من {{total}}</div>" }
  }' \
  --fail-with-body --output invoice.pdf

// HTML to PDF with an Arabic footer. Node.js 18+ (built-in fetch).
// Run: SAHIFA_API_KEY=... node pdf.mjs
import { writeFile } from 'node:fs/promises';

const html = `<html dir="rtl" lang="ar"><body>
  <h1>فاتورة ضريبية</h1>
  <p>الإجمالي: 1,150.00 ر.س</p>
</body></html>`;

const res = await fetch('https://api.sahifa.dev/v3/convert/pdf', {
  method: 'POST',
  headers: {
    Authorization: 'Basic ' + Buffer.from(`api:${process.env.SAHIFA_API_KEY}`).toString('base64'),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    source: html,
    format: 'A4',
    margin: '20mm',
    footer: { source: '<div style="width:100%;text-align:center">صفحة {{page}} من {{total}}</div>' },
  }),
});

if (!res.ok) throw new Error(`Sahifa error ${res.status}: ${(await res.json()).error}`);
await writeFile('invoice.pdf', Buffer.from(await res.arrayBuffer()));
console.log(`invoice.pdf created in ${res.headers.get('x-response-duration')} ms`);

# HTML to PDF with an Arabic footer. Python 3.8+, requires: pip install requests
# Run: SAHIFA_API_KEY=... python pdf.py
import os
import requests

html = """<html dir="rtl" lang="ar"><body>
  <h1>فاتورة ضريبية</h1>
  <p>الإجمالي: 1,150.00 ر.س</p>
</body></html>"""

res = requests.post(
    "https://api.sahifa.dev/v3/convert/pdf",
    auth=("api", os.environ["SAHIFA_API_KEY"]),
    json={
        "source": html,
        "format": "A4",
        "margin": "20mm",
        "footer": {"source": '<div style="width:100%;text-align:center">صفحة {{page}} من {{total}}</div>'},
    },
    timeout=60,
)
if not res.ok:
    raise RuntimeError(f"Sahifa error {res.status_code}: {res.json()['error']}")

with open("invoice.pdf", "wb") as f:
    f.write(res.content)
print(f"invoice.pdf created in {res.headers['X-Response-Duration']} ms")

// HTML to PDF with an Arabic footer. .NET 8+.
// .NET 10: SAHIFA_API_KEY=... dotnet run pdf.cs  (or paste into Program.cs of a console app)
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json.Nodes;

var key = Environment.GetEnvironmentVariable("SAHIFA_API_KEY");
using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Basic", Convert.ToBase64String(Encoding.UTF8.GetBytes($"api:{key}")));

var html = """
    <html dir="rtl" lang="ar"><body>
      <h1>فاتورة ضريبية</h1>
      <p>الإجمالي: 1,150.00 ر.س</p>
    </body></html>
    """;

var body = new JsonObject
{
    ["source"] = html,
    ["format"] = "A4",
    ["margin"] = "20mm",
    ["footer"] = new JsonObject { ["source"] = "<div style=\"width:100%;text-align:center\">صفحة {{page}} من {{total}}</div>" },
};
var res = await http.PostAsync("https://api.sahifa.dev/v3/convert/pdf",
    new StringContent(body.ToJsonString(), Encoding.UTF8, "application/json"));
if (!res.IsSuccessStatusCode)
    throw new Exception($"Sahifa error {(int)res.StatusCode}: {await res.Content.ReadAsStringAsync()}");

await File.WriteAllBytesAsync("invoice.pdf", await res.Content.ReadAsByteArrayAsync());
Console.WriteLine("invoice.pdf saved");

// HTML to PDF with an Arabic footer. Java 18+ (UTF-8 source by default).
// Run: SAHIFA_API_KEY=... java Pdf.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Base64;

public class Pdf {
    public static void main(String[] args) throws Exception {
        String key = System.getenv("SAHIFA_API_KEY");
        String auth = Base64.getEncoder().encodeToString(("api:" + key).getBytes(StandardCharsets.UTF_8));

        // JSON written by hand to keep the example dependency-free; use Jackson or Gson in real code.
        String body = """
            {
              "source": "<html dir='rtl' lang='ar'><body><h1>فاتورة ضريبية</h1><p>الإجمالي: 1,150.00 ر.س</p></body></html>",
              "format": "A4",
              "margin": "20mm",
              "footer": { "source": "<div style='width:100%;text-align:center'>صفحة {{page}} من {{total}}</div>" }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.sahifa.dev/v3/convert/pdf"))
            .header("Authorization", "Basic " + auth)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();

        HttpResponse<byte[]> res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofByteArray());
        if (res.statusCode() != 200) {
            throw new RuntimeException("Sahifa error " + res.statusCode() + ": " + new String(res.body(), StandardCharsets.UTF_8));
        }
        Files.write(Path.of("invoice.pdf"), res.body());
        System.out.println("invoice.pdf saved");
    }
}

يستخدم التذييل المتغيرين {{page}} و {{total}}. وتحتاج الترويسة أو التذييل إلى margin يتسع لهما. راجع مرجع PDF لجميع الخيارات.

٣. التقط صورة لصفحة

يلتقط هذا الطلب صفحة ويب كاملة بصيغة PNG ويُخفي نوافذ الموافقة على ملفات تعريف الارتباط، ويحفظ الملف باسم page.png.

# Full-page screenshot of a URL, without cookie banners. Requires: SAHIFA_API_KEY.
curl --get https://api.sahifa.dev/take \
  --data-urlencode "access_key=$SAHIFA_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data "format=png" \
  --data "full_page=true" \
  --data "block_cookie_banners=true" \
  --fail-with-body --output page.png

// Full-page screenshot of a URL, without cookie banners. Node.js 18+.
// Run: SAHIFA_API_KEY=... node screenshot.mjs
import { writeFile } from 'node:fs/promises';

const params = new URLSearchParams({
  access_key: process.env.SAHIFA_API_KEY,
  url: 'https://example.com',
  format: 'png',
  full_page: 'true',
  block_cookie_banners: 'true',
});

const res = await fetch(`https://api.sahifa.dev/take?${params}`);
if (!res.ok) throw new Error(`Sahifa error ${res.status}: ${(await res.json()).error}`);
await writeFile('page.png', Buffer.from(await res.arrayBuffer()));
console.log('page.png saved');

# Full-page screenshot of a URL, without cookie banners. Requires: pip install requests
# Run: SAHIFA_API_KEY=... python screenshot.py
import os
import requests

res = requests.get(
    "https://api.sahifa.dev/take",
    params={
        "access_key": os.environ["SAHIFA_API_KEY"],
        "url": "https://example.com",
        "format": "png",
        "full_page": "true",
        "block_cookie_banners": "true",
    },
    timeout=60,
)
if not res.ok:
    raise RuntimeError(f"Sahifa error {res.status_code}: {res.json()['error']}")

with open("page.png", "wb") as f:
    f.write(res.content)
print("page.png saved")

// Full-page screenshot of a URL, without cookie banners. .NET 8+.
// .NET 10: SAHIFA_API_KEY=... dotnet run screenshot.cs
var key = Environment.GetEnvironmentVariable("SAHIFA_API_KEY");
var query = string.Join("&", new Dictionary<string, string>
{
    ["access_key"] = key!,
    ["url"] = "https://example.com",
    ["format"] = "png",
    ["full_page"] = "true",
    ["block_cookie_banners"] = "true",
}.Select(p => $"{p.Key}={Uri.EscapeDataString(p.Value)}"));

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
var res = await http.GetAsync($"https://api.sahifa.dev/take?{query}");
if (!res.IsSuccessStatusCode)
    throw new Exception($"Sahifa error {(int)res.StatusCode}: {await res.Content.ReadAsStringAsync()}");

await File.WriteAllBytesAsync("page.png", await res.Content.ReadAsByteArrayAsync());
Console.WriteLine("page.png saved");

// Full-page screenshot of a URL, without cookie banners. Java 11+.
// Run: SAHIFA_API_KEY=... java Screenshot.java
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.stream.Collectors;

public class Screenshot {
    public static void main(String[] args) throws Exception {
        Map<String, String> params = new LinkedHashMap<>();
        params.put("access_key", System.getenv("SAHIFA_API_KEY"));
        params.put("url", "https://example.com");
        params.put("format", "png");
        params.put("full_page", "true");
        params.put("block_cookie_banners", "true");
        String query = params.entrySet().stream()
            .map(e -> e.getKey() + "=" + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&"));

        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.sahifa.dev/take?" + query)).GET().build();
        HttpResponse<byte[]> res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofByteArray());
        if (res.statusCode() != 200) {
            throw new RuntimeException("Sahifa error " + res.statusCode() + ": " + new String(res.body(), StandardCharsets.UTF_8));
        }
        Files.write(Path.of("page.png"), res.body());
        System.out.println("page.png saved");
    }
}

راجع مرجع لقطات الشاشة لإطار العرض والتقاط عنصر محدد والوضع الداكن وخيارات الحجب.

٤. تعامل مع أوقات الازدحام

عندما تمتلئ قائمة الانتظار تُعيد الواجهة الرمز 429. إعادة المحاولة بعد انتظار قصير آمنة، لأن الطلب الفاشل لا يترك أي أثر.

# curl retries 408, 429, 500, 502, 503 and 504 responses on its own, honouring Retry-After.
curl https://api.sahifa.dev/v3/convert/pdf \
  --user "api:$SAHIFA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "source": "https://example.com" }' \
  --retry 4 --retry-delay 2 --retry-max-time 60 \
  --fail-with-body --output example.pdf

// Retry on 429 (queue full) and 503 (temporarily unavailable), honouring Retry-After.
// Node.js 18+. Run: SAHIFA_API_KEY=... node retry.mjs
import { writeFile } from 'node:fs/promises';

async function render(body, attempts = 4) {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch('https://api.sahifa.dev/v3/convert/pdf', {
      method: 'POST',
      headers: { 'X-API-Key': process.env.SAHIFA_API_KEY, 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });
    if (res.ok) return Buffer.from(await res.arrayBuffer());
    const retryable = res.status === 429 || res.status === 503;
    if (!retryable || attempt === attempts) throw new Error(`Sahifa error ${res.status}: ${(await res.json()).error}`);
    const wait = Number(res.headers.get('retry-after')) || 2 ** attempt;
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}

await writeFile('example.pdf', await render({ source: 'https://example.com' }));
console.log('example.pdf saved');

# Retry on 429 (queue full) and 503 (temporarily unavailable), honouring Retry-After.
# Requires: pip install requests. Run: SAHIFA_API_KEY=... python retry.py
import os
import time
import requests


def render(body, attempts=4):
    for attempt in range(1, attempts + 1):
        res = requests.post(
            "https://api.sahifa.dev/v3/convert/pdf",
            headers={"X-API-Key": os.environ["SAHIFA_API_KEY"]},
            json=body,
            timeout=60,
        )
        if res.ok:
            return res.content
        if res.status_code not in (429, 503) or attempt == attempts:
            raise RuntimeError(f"Sahifa error {res.status_code}: {res.json()['error']}")
        time.sleep(int(res.headers.get("Retry-After", 2 ** attempt)))


with open("example.pdf", "wb") as f:
    f.write(render({"source": "https://example.com"}))
print("example.pdf saved")

// Retry on 429 (queue full) and 503 (temporarily unavailable), honouring Retry-After. .NET 8+.
// .NET 10: SAHIFA_API_KEY=... dotnet run retry.cs
using System.Net;
using System.Text;
using System.Text.Json.Nodes;

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("SAHIFA_API_KEY"));

async Task<byte[]> Render(JsonObject body, int attempts = 4)
{
    for (var attempt = 1; ; attempt++)
    {
        var res = await http.PostAsync("https://api.sahifa.dev/v3/convert/pdf",
            new StringContent(body.ToJsonString(), Encoding.UTF8, "application/json"));
        if (res.IsSuccessStatusCode) return await res.Content.ReadAsByteArrayAsync();
        var retryable = res.StatusCode is HttpStatusCode.TooManyRequests or HttpStatusCode.ServiceUnavailable;
        if (!retryable || attempt == attempts)
            throw new Exception($"Sahifa error {(int)res.StatusCode}: {await res.Content.ReadAsStringAsync()}");
        var wait = res.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(Math.Pow(2, attempt));
        await Task.Delay(wait);
    }
}

await File.WriteAllBytesAsync("example.pdf", await Render(new JsonObject { ["source"] = "https://example.com" }));
Console.WriteLine("example.pdf saved");

// Retry on 429 (queue full) and 503 (temporarily unavailable), honouring Retry-After. Java 11+.
// Run: SAHIFA_API_KEY=... java Retry.java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;

public class Retry {
    static final HttpClient HTTP = HttpClient.newHttpClient();

    static byte[] render(String json, int attempts) throws Exception {
        for (int attempt = 1; ; attempt++) {
            HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.sahifa.dev/v3/convert/pdf"))
                .header("X-API-Key", System.getenv("SAHIFA_API_KEY"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json, StandardCharsets.UTF_8))
                .build();
            HttpResponse<byte[]> res = HTTP.send(request, HttpResponse.BodyHandlers.ofByteArray());
            if (res.statusCode() == 200) return res.body();
            boolean retryable = res.statusCode() == 429 || res.statusCode() == 503;
            if (!retryable || attempt == attempts) {
                throw new RuntimeException("Sahifa error " + res.statusCode() + ": " + new String(res.body(), StandardCharsets.UTF_8));
            }
            long wait = res.headers().firstValue("Retry-After").map(Long::parseLong).orElse((long) Math.pow(2, attempt));
            Thread.sleep(wait * 1000);
        }
    }

    public static void main(String[] args) throws Exception {
        Files.write(Path.of("example.pdf"), render("{\"source\": \"https://example.com\"}", 4));
        System.out.println("example.pdf saved");
    }
}

ماذا بعد

المستندات العربية واتجاه النص: الخطوط والأرقام والجداول التي تتكرر ترويستها في كل صفحة.
نصائح وأخطاء شائعة: الصفحات المبنية بجافاسكربت، والصور المؤجلة التحميل، وفواصل الصفحات.
الأخطاء: معنى كل رمز حالة وطريقة معالجته.

البداية

مرجع الواجهة البرمجية