بدء سريع
سجّل الدخول وأنشئ مشروع اختبار ثم مفتاحًا بالنطاقات المطلوبة فقط، واستدعِ GET /v1/tools، واضبط خدمة واحدة، ثم أنشئ مفتاح live منفصلًا بعد اختبار القبول.
export GALON_API_BASE="https://api.galon.ai"
export GALON_API_KEY="gln_test_..."
curl "$GALON_API_BASE/v1/tools" -H "Authorization: Bearer $GALON_API_KEY"
المصادقة والعزل
أرسل مفتاح API في ترويسة Authorization: Bearer. يرتبط كل مفتاح بمستأجر ومشروع وبيئة واحدة. احتفظ به في مخزن أسرار الخادم فقط، ولا تضعه في متصفح أو تطبيق جوال أو مستودع مصدر.
مفاتيح محدودة حسب الخدمة
امنح نطاقات دقيقة مثل mail:send أو domain:lookup أو build:create. استخدم مفتاحًا لكل تطبيق. تجنب نطاقات الخدمة الشاملة إلا عند الحاجة الفعلية لكل العمليات، وألغِ المفاتيح غير المستخدمة فورًا.
mail:send
domain:lookup
domain:read
build:create
build:read
artifact:read
job:read
المهام غير المتزامنة والتكرار الآمن
تعيد عمليات التغيير مهمة. أرسل Idempotency-Key ثابتًا: يعيد المفتاح والطلب نفسيهما المهمة نفسها، بينما يعيد المفتاح نفسه مع طلب مختلف HTTP 409. تابع نقطة المهمة ولا تكرر إلا الطلبات الآمنة أو المتكررة بأمان.
POST /v1/jobs
GET /v1/jobs/{job_id}
POST /v1/jobs/{job_id}/cancel
GET /v1/builds/{job_id}/artifacts
إرسال البريد الإلكتروني
يستقبل POST /v1/emails الحقول from_email وsubject وtext أو html، وto: عنوان واحد أو قائمة. الحقلان cc وbcc قائمتان اختياريتان؛ ولا يتجاوز مجموع to وcc وbcc 50 مستلمًا مختلفًا، ويُحتسب كل مستلم في حصتك وفي الاستخدام المفوتر. يتلقى كل مستلم نسخته الخاصة مع رابط إلغاء الاشتراك بنقرة واحدة، لذلك لا يُكشف مستلمو bcc أبدًا؛ ويُتجاوز المستلمون المحظورون (الارتدادات والشكاوى وإلغاء الاشتراك). الحقل attachments قائمة تضم 10 كائنات على الأكثر تحتوي filename وcontent (base64) وcontent_type اختياريًا؛ ويجب أن تبقى الرسالة المرمّزة دون 25 ميغابايت، وتُرفض الملفات التنفيذية. يؤجل scheduled_at (بصيغة ISO 8601 مع المنطقة الزمنية، وبحد أقصى 72 ساعة مسبقًا) الإرسال؛ ويلغيه POST /v1/emails/{job_id}/cancel ما دام في قائمة الانتظار. يستقبل POST /v1/emails/batch الكائن {"emails": [...]} مع 1 إلى 100 رسالة بلا مرفقات؛ وتصبح كل رسالة job مستقلًا، آمنًا عند التكرار (idempotent) بمفتاح Idempotency-Key للدفعة وبموقعها. ولا يزال to_email مقبولًا لمستلم واحد. تسجيل الدفعة وحده ذري (atomic=true)، أما التنفيذ والتسليم فمستقلان. تتطلب إعادة المحاولة القائمة المرتبة نفسها تمامًا؛ وأي تغيير في المحتوى أو الحجم أو الترتيب يعيد HTTP 409.
POST /v1/emails
POST /v1/emails/batch
POST /v1/emails/{job_id}/cancel
الأخطاء
تعني HTTP 401 بيانات اعتماد غير صالحة أو منتهية، و403 نطاقًا غير كافٍ، و409 تعارض التكرار أو الإصدار، و422 طلبًا غير صالح، و503 عدم توفر مؤقتًا.
مرجع قابل للقراءة آليًا
استخدم عقد OpenAPI للمخططات ودليل دمج LLM لتعليمات الوكلاء. الإنجليزية هي المرجع؛ وتبقى المسارات وأسماء الحقول والنطاقات والأمثلة متطابقة في كل ترجمة.