Saltar al contenido
ShopentlyLearn

Nuevo artículo

Crear borradores de artículos

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

Autenticación
Bearer
Disponible desde
BASIC
Módulo instalado requerido
shopently.blog · Versión del contrato del módulo 1
Permisos necesarios
addon.shopently.blog:post_create

Ejemplos de código

Ejemplo de solicitud

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))

Ejemplo de respuesta 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"
  }
}

Vista general

Administra el blog de tu tienda con artículos HTML, fotos, autores y metadatos para buscadores. Guarda borradores, prepara traducciones y publica de inmediato o a una hora elegida en una zona horaria específica. Administra los comentarios y su moderación en el panel; un generador externo puede usar la API con los permisos que otorgues.

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

Parámetros

Encabezados de solicitud

Idempotency-KeyCadena de textoObligatorio

Identificador único de una operación lógica de escritura.

minLength: 1maxLength: 128
Restricciones
pattern
"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
Ejemplo: "learn-8ee78b431a9e4a4198d15a5dd386bb14"

Cuerpo de la solicitud

application/json · Obligatorio

ObjetoCampos adicionales: No
author_idCadena de texto nullObligatorio

Autor

Cadena de texto:format: "uuid"
comments_modeCadena de textoObligatorio

Comentarios

Restricciones
enum
["inherit", "open", "closed"]
content_htmlCadena de textoObligatorio

Contenido

maxLength: 50000
cover_altCadena de textoObligatorio

Texto alternativo

maxLength: 250
cover_captionCadena de textoObligatorio

Pie de foto

maxLength: 500
cover_media_idCadena de texto nullObligatorio

Foto de portada

Cadena de texto:format: "uuid"
excerptCadena de textoObligatorio

Introducción

maxLength: 1000
expected_versionNúmero enteroOpcional

Versión leída antes de escribir; si no coincide, se rechaza la actualización.

const: 1
Valor predeterminado: 1
localeCadena de textoObligatorio

Idioma seleccionado para esta solicitud.

minLength: 2maxLength: 35
Restricciones
pattern
"^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$"
meta_descriptionCadena de textoObligatorio

Descripción para buscadores en el idioma seleccionado.

maxLength: 160
meta_keywordsLista <Cadena de texto> Obligatorio

Palabras clave para buscadores en el idioma seleccionado.

maxItems: 20
Lista:minLength: 1maxLength: 50
meta_titleCadena de textoObligatorio

Título para buscadores en el idioma seleccionado.

maxLength: 70
slugCadena de textoObligatorio

Segmento de la ruta URL en el idioma seleccionado.

maxLength: 160
titleCadena de textoObligatorio

Título en el idioma seleccionado.

maxLength: 200

Respuestas

Respuesta 201

dataObjetoCampos adicionales: NoObligatorio

Contenido de una respuesta correcta.

Campos · data
html_normalizedBooleanoObligatorio

HTML · category-v1

idCadena de textoObligatorio

Identificador del recurso; consérvalo tal como se devuelve.

format: "uuid"
public_numberNúmero entero nullOpcional

Número

Número entero:minimum: 1
revision_idCadena de textoObligatorio

Revisión

format: "uuid"
statusCadena de textoObligatorio

Estado admitido por esta operación concreta.

Restricciones
enum
["draft", "scheduled", "published", "archived"]
versionNúmero enteroObligatorio

Versión del recurso utilizada para controlar cambios simultáneos.

minimum: 1maximum: 9223372036854775807
metaObjetoCampos adicionales: NoObligatorio

Metadatos de la respuesta.

Campos · meta
request_idCadena de textoObligatorio

Identificador de la solicitud; en los metadatos de respuesta identifica la solicitud HTTP.

minLength: 1maxLength: 100
Ejemplo de respuesta

Estado HTTP

201
Recurso creado Esquema
400
Solicitud no válida
401
Autenticación necesaria
403
Permiso denegado
404
Recurso no encontrado
409
Conflicto de versión
422
Error de validación
429
Límite de solicitudes excedido
Otros estados HTTP (7)
405
Método no permitido
413
Solicitud demasiado grande
415
Formato no compatible
500
Error del servidor
502
Error de la puerta de enlace API
503
Servicio no disponible
504
Tiempo de espera agotado

Catálogo de errores: ErrorResponse

Cabeceras

401

WWW-AuthenticateCadena de textoOpcional

Esquema de autenticación exigido por el servidor.

405

AllowCadena de textoOpcional

Métodos HTTP admitidos por este recurso.

429, 503

Retry-AfterNúmero enteroOpcional

Espera mínima antes de reintentar, en segundos.

minimum: 0