انتقل إلى المحتوى
ShopentlyLearn

مقال جديد

إنشاء مسودات المقالات

POST/api/v1/addons/shopently.blog/posts

المصادقة
Bearer
متاح بدءًا من
BASIC
الوحدة المثبتة المطلوبة
shopently.blog · إصدار عقد الوحدة 1
الصلاحيات المطلوبة
addon.shopently.blog:post_create

أمثلة الكود

مثال على الطلب

cURL

: "${SHOPENTLY_SHOP_URL:?}"

curl --disable --globoff --fail-with-body --silent --show-error \
  --proto '=https' --connect-timeout 5 --max-time 30 \
  --request POST \
  --header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \
  --header 'Idempotency-Key: learn-8ee78b431a9e4a4198d15a5dd386bb14' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "author_id": "341494e0-caab-4f47-a8ff-f6795c42a775",
  "comments_mode": "open",
  "content_html": "<h2>Porównaj właściwości</h2><p>Sprawdź opis produktu i wybierz wariant odpowiedni do swoich potrzeb.</p>",
  "cover_alt": "Niebieska ilustracja poradnika",
  "cover_caption": "Ilustracja redakcyjna",
  "cover_media_id": "e8663afe-3c38-461c-a142-a980085630af",
  "excerpt": "Praktyczny poradnik zakupowy.",
  "locale": "pl",
  "meta_description": "Praktyczne wskazówki dotyczące wyboru produktu.",
  "meta_keywords": [
    "poradnik",
    "wybór"
  ],
  "meta_title": "Jak wybrać produkt",
  "slug": "jak-wybrac-produkt",
  "title": "Jak wybrać produkt"
}' \
  --url "${SHOPENTLY_SHOP_URL%/}"/api/v1/addons/shopently.blog/posts

PHP

<?php
declare(strict_types=1);

$baseUrl = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/');
$origin = parse_url($baseUrl);
if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) ||
    isset($origin['user'], $origin['pass']) || isset($origin['user']) || isset($origin['path']) ||
    isset($origin['query']) || isset($origin['fragment'])) {
    throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin');
}
$credential = getenv('SHOPENTLY_ACCESS_TOKEN') ?: '';
if ($credential === '' || strpbrk($credential, "\r\n") !== false) {
    throw new RuntimeException('Invalid credential');
}
$headers = ['Idempotency-Key: learn-8ee78b431a9e4a4198d15a5dd386bb14', 'Content-Type: application/json'];
$headers[] = 'Authorization: Bearer ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/addons/shopently.blog/posts');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HEADERFUNCTION => static function ($handle, string $line) use (&$responseHeaders): int {
        if (str_contains($line, ':')) {
            [$name, $value] = explode(':', $line, 2);
            $responseHeaders[strtolower(trim($name))] = trim($value);
        }
        return strlen($line);
    },
]);
curl_setopt($handle, CURLOPT_POSTFIELDS, '{
  "author_id": "341494e0-caab-4f47-a8ff-f6795c42a775",
  "comments_mode": "open",
  "content_html": "<h2>Porównaj właściwości</h2><p>Sprawdź opis produktu i wybierz wariant odpowiedni do swoich potrzeb.</p>",
  "cover_alt": "Niebieska ilustracja poradnika",
  "cover_caption": "Ilustracja redakcyjna",
  "cover_media_id": "e8663afe-3c38-461c-a142-a980085630af",
  "excerpt": "Praktyczny poradnik zakupowy.",
  "locale": "pl",
  "meta_description": "Praktyczne wskazówki dotyczące wyboru produktu.",
  "meta_keywords": [
    "poradnik",
    "wybór"
  ],
  "meta_title": "Jak wybrać produkt",
  "slug": "jak-wybrac-produkt",
  "title": "Jak wybrać produkt"
}');
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
$error = curl_error($handle);
curl_close($handle);
if ($raw === false) {
    throw new RuntimeException('Transport error: ' . $error);
}
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP ' . $status . '; request_id=' .
        ($responseHeaders['x-request-id'] ?? '') . '; retry_after=' . ($responseHeaders['retry-after'] ?? ''));
}
$result = $raw === '' ? null : json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING);
echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), PHP_EOL;

Python

from contextlib import ExitStack
import json
import os
from urllib.parse import urlsplit

import requests  # python -m pip install requests

base_url = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/")
origin = urlsplit(base_url)
if origin.scheme != "https" or not origin.hostname or origin.username or origin.password or origin.path or origin.query or origin.fragment:
    raise ValueError("SHOPENTLY_SHOP_URL must be an HTTPS origin")
credential = os.environ['SHOPENTLY_ACCESS_TOKEN']
if not credential or "\r" in credential or "\n" in credential:
    raise ValueError("Invalid credential")
headers = {'Idempotency-Key': 'learn-8ee78b431a9e4a4198d15a5dd386bb14'}
headers["Authorization"] = 'Bearer' + " " + credential
body = '{\n  "author_id": "341494e0-caab-4f47-a8ff-f6795c42a775",\n  "comments_mode": "open",\n  "content_html": "<h2>Porównaj właściwości</h2><p>Sprawdź opis produktu i wybierz wariant odpowiedni do swoich potrzeb.</p>",\n  "cover_alt": "Niebieska ilustracja poradnika",\n  "cover_caption": "Ilustracja redakcyjna",\n  "cover_media_id": "e8663afe-3c38-461c-a142-a980085630af",\n  "excerpt": "Praktyczny poradnik zakupowy.",\n  "locale": "pl",\n  "meta_description": "Praktyczne wskazówki dotyczące wyboru produktu.",\n  "meta_keywords": [\n    "poradnik",\n    "wybór"\n  ],\n  "meta_title": "Jak wybrać produkt",\n  "slug": "jak-wybrac-produkt",\n  "title": "Jak wybrać produkt"\n}'
if body is not None:
    headers["Content-Type"] = "application/json"

with ExitStack() as stack:
    session = stack.enter_context(requests.Session())
    files = None
    if False:
        image = stack.enter_context(open(os.environ["SHOPENTLY_IMAGE_FILE"], "rb"))
        if os.fstat(image.fileno()).st_size > 5242880:
            raise ValueError("Image exceeds 5 MiB")
        files = {"file": ("article.png", image, "image/png")}
    response = session.request(
        'POST', base_url + '/api/v1/addons/shopently.blog/posts', headers=headers,
        data=body.encode("utf-8") if body is not None else None, files=files,
        timeout=(5, 30), allow_redirects=False,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP {response.status_code}; request_id={response.headers.get('X-Request-ID', '')}; retry_after={response.headers.get('Retry-After', '')}")
    if False:
        if response.headers.get("Content-Type") != "image/webp" or len(response.content) > 5242880:
            raise ValueError("Unexpected image response")
        with open(os.environ["SHOPENTLY_OUTPUT_FILE"], "xb") as output:
            output.write(response.content)
    else:
        result = response.json() if response.content else None
        print(json.dumps(result, ensure_ascii=False, indent=2))

مثال على الاستجابة 201

JSON
{
  "data": {
    "html_normalized": false,
    "id": "2103ba96-2713-420b-b197-8a008730c851",
    "public_number": 1,
    "revision_id": "8c4af6da-63f4-42aa-8b37-57c703fa0af7",
    "status": "draft",
    "version": 1
  },
  "meta": {
    "request_id": "f6a16d96-69fc-401d-9d04-cdc96f86a4c7"
  }
}

نظرة عامة

أدر مدونة متجرك بمقالات HTML وصور وكتّاب وبيانات وصفية لمحركات البحث. احفظ المسودات وأعد الترجمات وانشر فورًا أو في موعد تحدده ضمن منطقة زمنية معينة. أدر التعليقات ومراجعتها من اللوحة، ويمكن لمولّد خارجي استخدام API بالصلاحيات التي تمنحها.

BASIC · api.enabled · addons.use(shopently.blog) · addon.shopently.blog:post_create

المعاملات

ترويسات الطلب

Idempotency-Keyسلسلة نصيةمطلوب

معرّف فريد لعملية كتابة منطقية واحدة.

minLength: 1maxLength: 128
القيود
pattern
"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
مثال: "learn-8ee78b431a9e4a4198d15a5dd386bb14"

محتوى الطلب

application/json · مطلوب

كائنحقول إضافية: لا
author_idسلسلة نصية nullمطلوب

الكاتب

سلسلة نصية:format: "uuid"
comments_modeسلسلة نصيةمطلوب

التعليقات

القيود
enum
["inherit", "open", "closed"]
content_htmlسلسلة نصيةمطلوب

المحتوى

maxLength: 50000
cover_altسلسلة نصيةمطلوب

النص البديل

maxLength: 250
cover_captionسلسلة نصيةمطلوب

وصف الصورة

maxLength: 500
cover_media_idسلسلة نصية nullمطلوب

صورة الغلاف

سلسلة نصية:format: "uuid"
excerptسلسلة نصيةمطلوب

مقدمة

maxLength: 1000
expected_versionعدد صحيحاختياري

الإصدار المقروء قبل الكتابة؛ يؤدي عدم التطابق إلى رفض التحديث.

const: 1
القيمة الافتراضية: 1
localeسلسلة نصيةمطلوب

اللغة المحددة لهذا الطلب.

minLength: 2maxLength: 35
القيود
pattern
"^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$"
meta_descriptionسلسلة نصيةمطلوب

وصف محركات البحث باللغة المحددة.

maxLength: 160
meta_keywordsمصفوفة <سلسلة نصية> مطلوب

الكلمات المفتاحية لمحركات البحث باللغة المحددة.

maxItems: 20
مصفوفة:minLength: 1maxLength: 50
meta_titleسلسلة نصيةمطلوب

عنوان محركات البحث باللغة المحددة.

maxLength: 70
slugسلسلة نصيةمطلوب

جزء مسار URL باللغة المحددة.

maxLength: 160
titleسلسلة نصيةمطلوب

العنوان باللغة المحددة.

maxLength: 200

الاستجابات

الاستجابة 201

dataكائنحقول إضافية: لامطلوب

محتوى الاستجابة الناجحة.

الحقول · data
html_normalizedقيمة منطقيةمطلوب

HTML · category-v1

idسلسلة نصيةمطلوب

معرّف المورد؛ احتفظ به كما أعيد.

format: "uuid"
public_numberعدد صحيح nullاختياري

الرقم

عدد صحيح:minimum: 1
revision_idسلسلة نصيةمطلوب

النسخة

format: "uuid"
statusسلسلة نصيةمطلوب

الحالة التي تقبلها هذه العملية تحديدًا.

القيود
enum
["draft", "scheduled", "published", "archived"]
versionعدد صحيحمطلوب

إصدار المورد المستخدم للتحكم في التعديلات المتزامنة.

minimum: 1maximum: 9223372036854775807
metaكائنحقول إضافية: لامطلوب

البيانات الوصفية للاستجابة.

الحقول · meta
request_idسلسلة نصيةمطلوب

معرّف الطلب؛ في البيانات الوصفية للاستجابة يحدد طلب HTTP.

minLength: 1maxLength: 100
مثال على الاستجابة

حالة HTTP

201
تم إنشاء المورد المخطط
400
طلب غير صالح
401
المصادقة مطلوبة
403
الإذن مرفوض
404
المورد غير موجود
409
تعارض الإصدارات
422
فشل التحقق من البيانات
429
تم تجاوز حد الطلبات
حالات HTTP الأخرى (7)
405
الطريقة غير مسموحة
413
الطلب كبير جدًا
415
تنسيق غير مدعوم
500
خطأ في الخادم
502
خطأ في بوابة API
503
الخدمة غير متاحة
504
انتهت مهلة الانتظار

دليل الأخطاء: ErrorResponse

الترويسات

401

WWW-Authenticateسلسلة نصيةاختياري

نظام المصادقة الذي يطلبه الخادم.

405

Allowسلسلة نصيةاختياري

طرق HTTP التي يدعمها هذا المورد.

429, 503

Retry-Afterعدد صحيحاختياري

الحد الأدنى للانتظار قبل إعادة المحاولة، بالثواني.

minimum: 0