Перейти до вмісту
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