راهنمای اتصال یوتاپست

۱. کلید API

در پنل: منو ← اتصال‌ها و API ← کلیدها. کلید با up_live_ شروع می‌شود، فقط یک بار نمایش داده می‌شود و فقط مالک یا مدیر برند می‌تواند بسازد. هر کلید فقط یک برند را می‌بیند. کلید تازه فقط «خواندن» دارد؛ برای ساخت پیش‌نویس «ساخت پیش‌نویس» و برای تأیید و زمان‌بندی «انتشار» را هم روشن کنید.

آدرس پایهٔ API

https://uttapost.ir/api/v1

آدرس MCP

https://uttapost.ir/api/mcp

مستندات کامل API

کلید مثل رمز عبور است: در مخزن کد یا پیام نگذارید. هر کلید سقف خرج روزانه دارد و هر لحظه باطل می‌شود.

۲. n8n

دو الگوی آماده دارید. فایل نمونهٔ هر دو را یک‌جا دارد؛ دانلود کنید و در n8n با Import from File وارد کنید.

دریافت نمونهٔ n8n

بعد کلید را در یک Credential از نوع Header Auth (نام Authorization، مقدار Bearer up_live_…) بگذارید.

الگوی الف: وقتی پستی منتشر شد (وب‌هوک)

1. در پنل: «اتصال‌ها و API ← وب‌هوک‌ها»، آدرس https گرهٔ Webhook در n8n را بدهید و رویداد post.published را انتخاب کنید. secret را همان لحظه کپی کنید.
2. در n8n گرهٔ Webhook را روی روش POST و گزینهٔ Raw Body بگذارید (امضا روی بایت‌های خام بدنه است).
3. پشت آن یک گرهٔ Code بگذارید که هدر X-UttaPost-Signature را بررسی کند (بلوک پایین؛ n8n نام هدر را با حروف کوچک می‌دهد). برای require('crypto') متغیر NODE_FUNCTION_ALLOW_BUILTIN=crypto در n8n لازم است.
4. بعدش هرچه می‌خواهید: پیام تلگرام، ردیف شیت، اعلان…

const crypto = require('crypto');

// rawBody: the exact bytes received (a Buffer or the raw string), never JSON.stringify(req.body).
function verifyUttaPost(secret, header, rawBody, toleranceSec = 300) {
    const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
    if (!m) return false;
    if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false;
    const h = crypto.createHmac('sha256', secret);
    h.update(m[1] + '.');
    h.update(rawBody);
    const expected = Buffer.from(h.digest('hex'));
    const given = Buffer.from(m[2]);
    return expected.length === given.length && crypto.timingSafeEqual(expected, given);
}

// In the Code node: read the secret from a credential or an n8n variable, not from the node text.
const header = $input.first().json.headers['x-uttapost-signature'];
const raw = await this.helpers.getBinaryDataBuffer(0, 'data');
if (!verifyUttaPost(YOUR_WEBHOOK_SECRET, header, raw)) {
    throw new Error('invalid UttaPost signature');
}
return $input.all();

رویدادهای قابل انتخاب: draft.created، approval.requested، post.published، post.failed، handoff.opened، credit.low، rule.paused

الگوی ب: زمان‌بندی ← ساخت ← تأیید

گرهٔ Schedule Trigger ← یک HTTP Request به POST https://uttapost.ir/api/v1/drafts/generate ← یک HTTP Request به POST https://uttapost.ir/api/v1/confirm. مرحلهٔ اول فقط قیمت و confirm_token برمی‌گرداند و پولی کم نمی‌شود؛ مرحلهٔ دوم هزینه را کم می‌کند.

# step 1: preview (JSON body), nothing is charged
POST https://uttapost.ir/api/v1/drafts/generate
{"item_ids": [12], "format": "post"}

# step 2: confirm (the token comes from step 1)
POST https://uttapost.ir/api/v1/confirm
{"confirm_token": "{{ $json.data.confirm_token }}"}

می‌توانید بین دو مرحله یک گرهٔ IF بگذارید: اگر data.cost از سقف شما بیشتر بود تأیید نکنید.

۳. Claude و MCP

یوتاپست یک سرور MCP دارد؛ با آن از Claude می‌گویید «آیتم‌های من را نشان بده»، «یک پیش‌نویس بساز» یا «ترکیب هفتگی محتوا بچین». احراز هویت همان کلید API است.

Claude Code

claude mcp add --transport http uttapost https://uttapost.ir/api/mcp --header "Authorization: Bearer up_live_..."

Claude Desktop

فایل claude_desktop_config.json را (از Settings ← Developer ← Edit Config) باز کنید، این بخش را اضافه کنید و برنامه را دوباره باز کنید. به Node.js نیاز دارد.

{
    "mcpServers": {
        "uttapost": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://uttapost.ir/api/mcp",
                "--transport",
                "http-only",
                "--header",
                "Authorization:${UTTAPOST_AUTH}"
            ],
            "env": {
                "UTTAPOST_AUTH": "Bearer up_live_..."
            }
        }
    }
}

ابزارها

ابزارهایی که کلید شما اجازه‌شان را ندارد در فهرست نمی‌آیند. generate_ai_video فقط وقتی محصول ویدیو روشن است دیده می‌شود.

اعتبار فقط با ابزار confirm خرج می‌شود: ابزارهای ساخت اول قیمت و confirm_token می‌دهند (یک‌بار مصرف، ۳۰ دقیقه). سقف خرج روزانهٔ کلید و کیف پول هنگام تأیید دوباره بررسی می‌شود.

۴. محصول خودتان (مثال UttaLine)

اگر محصول دیگری دارید، مثلاً UttaLine که بعد از هر تماس خلاصه‌ای دارد، همان API را از سرور خودتان صدا بزنید: آیتم بسازید، پیش‌نمایش بگیرید، و فقط وقتی هزینه قابل‌قبول بود تأیید کنید. نمونه (Laravel):

use Illuminate\Support\Facades\Http;

$api = Http::baseUrl('https://uttapost.ir/api/v1')
    ->withToken(config('services.uttapost.key'))   // up_live_..., kept in .env, never in the repo
    ->acceptJson()->timeout(15);

// 1. the finished call becomes a library item (scope: draft). A post is built on a photo, so send it as multipart images[]:
//    an item without a photo is refused at the preview (nothing is charged)
$item = $api->attach('images[]', file_get_contents($photoPath), 'work.jpg')
    ->post('items', ['title' => $summary->title, 'description' => $summary->text])->throw()->json('data');

// 2. preview a draft: nothing is charged yet
$preview = $api->post('drafts/generate', ['item_ids' => [$item['id']], 'format' => 'post'])->throw()->json('data');
// $preview['cost'] is in toman; show it, or compare it with your own limit

// 3. confirm only when it is fine (single use, 30 minutes, capped per key per day)
$api->post('confirm', ['confirm_token' => $preview['confirm_token']])->throw();

برای خبر گرفتن از نتیجه (پیش‌نویس ساخته شد، پست منتشر شد) یک وب‌هوک بسازید و امضا را مثل بخش n8n بررسی کنید.

۵. محدودیت‌ها و صداقت

• اتصال‌دهنده‌های وب claude.ai (Custom Connectors) به OAuth نیاز دارند و در این نسخه پشتیبانی نمی‌شوند. Claude Code و Claude Desktop (با mcp-remote) با کلید کار می‌کنند.
• دسترسی از خارج ایران: سرور یوتاپست در ایران است؛ بعضی کلاینت‌های خارجی ممکن است نتوانند به آن برسند. اگر وصل نشد، کلاینت را روی دستگاه یا سرور داخل ایران اجرا کنید.
• هر درخواست MCP یک پیام است (بدون دسته‌ای و بدون پخش زنده)، و سرور وضعیتی نگه نمی‌دارد.
• نرخ و خطاها مثل API هستند: خطاها و سقف‌ها.