تخطي إلى المحتوى الرئيسي

اعثر على أداتك التالية

الوثائق/حِزم SDK وأدوات المطوّرين/أمثلة الشيفرة: Node.js وPython وPHP وcURL
حِزم SDK وأدوات المطوّرين

أمثلة الشيفرة: Node.js وPython وPHP وcURL

أمثلة كاملة جاهزة للنسخ واللصق، بأربع لغات، ترسل مهمة وتنتظرها مع تراجع تدريجي ثم تنزّل النتيجة.

إجابة مختصرة

تعمل الاستدعاءات الثلاثة نفسها في كل لغة: POST /api/v1/jobs/ مع Idempotency-Key، ثم الاستعلام الدوري عن GET /api/v1/jobs/{jobId}/ مع تراجع تدريجي، ثم تنزيل output.downloadUrl. الأمثلة أدناه برامج كاملة تتضمن مهلات ومعالجة للأخطاء؛ عيّن MAXSCANNER_API_KEY في البيئة قبل تشغيلها.

Node.js (18+)

يستخدم fetch المدمج، لذا لا حاجة إلى أي حزم.

const KEY = process.env.MAXSCANNER_API_KEY;
const BASE = 'https://maxscanner.app/api/v1';
const headers = { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' };

const create = await fetch(`${BASE}/jobs/`, {
  method: 'POST',
  headers: { ...headers, 'Idempotency-Key': 'report-2026-11-pdf' },
  body: JSON.stringify({ url: 'https://example.com/report.docx', filename: 'report.docx', format: 'pdf' }),
});
if (!create.ok) throw new Error(`create failed: ${create.status} ${await create.text()}`);
const { jobId } = await create.json();

let delay = 2000, job;
for (let i = 0; i < 60; i++) {
  job = await (await fetch(`${BASE}/jobs/${jobId}/`, { headers })).json();
  if (job.status === 'completed' || job.status === 'failed') break;
  await new Promise((r) => setTimeout(r, delay));
  delay = Math.min(delay * 1.5, 10000);
}
if (job.status !== 'completed') throw new Error(job.error || 'job did not finish');

const file = await fetch(job.output.downloadUrl);
await (await import('node:fs/promises')).writeFile('report.pdf', Buffer.from(await file.arrayBuffer()));

Python

import os, time, requests

KEY = os.environ["MAXSCANNER_API_KEY"]
BASE = "https://maxscanner.app/api/v1"
S = requests.Session()
S.headers.update({"Authorization": f"Bearer {KEY}"})

r = S.post(f"{BASE}/jobs/", json={"url": "https://example.com/report.docx", "filename": "report.docx", "format": "pdf"},
           headers={"Idempotency-Key": "report-2026-11-pdf"}, timeout=30)
r.raise_for_status()
job_id = r.json()["jobId"]

delay, job = 2.0, {}
for _ in range(60):
    job = S.get(f"{BASE}/jobs/{job_id}/", timeout=30).json()
    if job["status"] in ("completed", "failed"):
        break
    time.sleep(delay)
    delay = min(delay * 1.5, 10)

if job.get("status") != "completed":
    raise RuntimeError(job.get("error") or "job did not finish")
with open("report.pdf", "wb") as fh:
    fh.write(requests.get(job["output"]["downloadUrl"], timeout=60).content)

PHP

<?php
$key = getenv('MAXSCANNER_API_KEY');
$base = 'https://maxscanner.app/api/v1';

function api(string $method, string $url, string $key, ?array $body = null, array $extra = []): array {
  $ch = curl_init($url);
  $headers = array_merge(["Authorization: Bearer $key", 'Content-Type: application/json'], $extra);
  curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $headers, CURLOPT_TIMEOUT => 30]);
  if ($body !== null) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
  $data = json_decode(curl_exec($ch), true);
  curl_close($ch);
  return $data ?? [];
}

$job = api('POST', "$base/jobs/", $key, ['url' => 'https://example.com/report.docx', 'filename' => 'report.docx', 'format' => 'pdf'], ['Idempotency-Key: report-2026-11-pdf']);
$delay = 2;
for ($i = 0; $i < 60; $i++) {
  $status = api('GET', "$base/jobs/{$job['jobId']}/", $key);
  if (in_array($status['status'], ['completed', 'failed'], true)) break;
  sleep($delay);
  $delay = min($delay * 2, 10);
}
if ($status['status'] === 'completed') file_put_contents('report.pdf', file_get_contents($status['output']['downloadUrl']));

cURL وسطر الأوامر

يتطلب jq. مفيد لاختبار مفتاح أو صيغة قبل كتابة شيفرة التطبيق.

JOB=$(curl -s -X POST 'https://maxscanner.app/api/v1/jobs/' \
  -H "Authorization: Bearer $MAXSCANNER_API_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: report-2026-11-pdf' \
  -d '{ "url": "https://example.com/report.docx", "filename": "report.docx", "format": "pdf" }' | jq -r .jobId)

until STATUS=$(curl -s "https://maxscanner.app/api/v1/jobs/$JOB/" -H "Authorization: Bearer $MAXSCANNER_API_KEY"); \
      echo "$STATUS" | jq -e '.status == "completed" or .status == "failed"' > /dev/null; do sleep 5; done

curl -s -o report.pdf "$(echo "$STATUS" | jq -r .output.downloadUrl)"

OpenAPI ومساعدو البرمجة بالذكاء الاصطناعي

يمكن استخدام وصف OpenAPI 3.1 على https://maxscanner.app/openapi/maxscanner-v1.yaml لتوليد عميل محدد الأنواع بالمولّد الذي تستخدمه عادةً. ويمكن لمساعدي البرمجة قراءة https://maxscanner.app/llms.txt و https://maxscanner.app/ai/api.md، اللذين يلخصان نقاط النهاية والقواعد نفسها.

الأسئلة الشائعة

هل توجد SDK رسمية؟

ليس بعد. فـ API صغيرة بما يكفي لتغطيها الأمثلة أعلاه، أو عميل مولَّد من ملف OpenAPI.

أدلة ذات صلة