ارسال سفارش به سرور پاتریس
در روش «دریافت از طریق سرور پاتریس»، سایت هر سفارش جدید یا تغییرکرده را با POST /api/site/v1/orders به سرور پاتریس میفرستد. سرور سفارش را نگه میدارد و پاتریس یار را فوراً خبر میکند، پس سایت دیگر درخواست دورهای GET /patris-yar/orders دریافت نمیکند.
این روش کی مناسب است؟
- وقتی هاست سایت ضعیف است و درخواستهای دورهای پاتریس یار بار ایجاد میکنند.
- وقتی میخواهید سفارش بلافاصله پس از ثبت به پاتریس برسد.
این روش فقط وقتی کار میکند که پاتریس یار روی ویندوز ۱۰ یا ۱۱ اجرا شود و به حساب پاتریس وصل باشد.
پیشنیازها
- همهی endpointهای سایت، از جمله
GET /patris-yar/orders،POST /patris-yar/orders/delivered،POST /patris-yar/orders/:id/ackوPOST /patris-yar/products، پیادهسازی شده باشند. - امکان «ارسال سفارشها از طریق سرور پاتریس» برای حساب پاتریس فعال باشد. این امکان بدون «فروشگاه اینترنتی» فعال نمیشود.
GET /patris-yar/pingمقدارorder_modeراcloudبرگرداند.- در پاتریس یار برای این اتصال «دریافت از طریق سرور پاتریس» انتخاب شده باشد.
Endpoint
POST https://patrisyar.payava.com/api/site/v1/orders
هدرها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
X-Payava-Key | string | بله | کلید API حساب پاتریس؛ همان کلید سایت. |
Content-Type | string | بله | application/json; charset=utf-8 |
پارامترها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
siteUrl | string | بله | آدرس اصلی سایت. دامنهی (host) آن باید همان دامنهی «آدرس API» در پاتریس یار باشد. |
pluginVersion | string | خیر | نسخهی پیادهسازی شما، مثل custom-1.0.0. |
orders | array | بله | حداکثر ۵۰ سفارش با قالب سفارش. |
کدام سفارشها و کی ارسال شوند؟
- هنگام ثبت سفارش و هنگام تغییر وضعیت آن، اگر وضعیت از وضعیتهای مجاز باشد و سفارش هنوز به پاتریس تحویل نشده باشد.
- ارسال را در پسزمینه (صف یا job) انجام دهید. ثبت سفارش مشتری نباید منتظر سرور پاتریس بماند.
- هر سفارش را تا وقتی سرور نپذیرفته، در حالت «در انتظار ارسال» نگه دارید.
نمونه درخواست
- curl
- C#
- Python
- PHP
- Node.js
- Go
curl -X POST https://PATRIS_CLOUD_URL/api/site/v1/orders \
-H "X-Payava-Key: YOUR_API_KEY" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"siteUrl":"https://shop.example.com","pluginVersion":"custom-1.0.0","orders":[{"id":1532,"number":"1532","status":"processing","created":"2026-11-07T10:42:13+03:30","customer_name":"علی رضایی","phone":"09120000000","subtotal":2400000,"discount":200000,"shipping":300000,"total":2500000,"lines":[{"pip":"101009001","sku":"","name":"لنت ترمز جلو","quantity":2,"unit_price":1200000,"discount":200000}]}]}'
using System.Net;
using System.Net.Http.Json;
public sealed class PatrisCloudClient(HttpClient http, IConfiguration config)
{
// http.BaseAddress = https://PATRIS_CLOUD_URL/
public async Task<CloudSendResult> SendOrdersAsync(IReadOnlyList<object> orders, CancellationToken ct)
{
using var request = new HttpRequestMessage(HttpMethod.Post, "api/site/v1/orders")
{
Content = JsonContent.Create(new
{
siteUrl = config["Patris:SiteUrl"],
pluginVersion = "custom-1.0.0",
orders // max 50, same objects as GET /orders
})
};
request.Headers.Add("X-Payava-Key", config["Patris:ApiKey"]);
using var response = await http.SendAsync(request, ct);
if (response.StatusCode == HttpStatusCode.TooManyRequests)
return CloudSendResult.RetryAfter(response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(60));
if (!response.IsSuccessStatusCode)
return CloudSendResult.Failed((int)response.StatusCode, await response.Content.ReadAsStringAsync(ct)); // ProblemDetails
var body = await response.Content.ReadFromJsonAsync<CloudOrdersResponse>(ct);
return CloudSendResult.Ok(body!.Results); // mark stored / updated / already_delivered as sent
}
}
public sealed record CloudOrdersResponse(bool Ok, int Stored, int Updated, int AlreadyDelivered, int Invalid, List<CloudOrderResult> Results);
public sealed record CloudOrderResult(string Id, string Status, string? Message);
import os
import requests
CLOUD_URL = os.environ["PATRIS_CLOUD_URL"].rstrip("/")
def send_orders(orders: list[dict]) -> dict:
"""orders: max 50, same objects as GET /orders."""
response = requests.post(
f"{CLOUD_URL}/api/site/v1/orders",
json={"siteUrl": os.environ["SITE_URL"], "pluginVersion": "custom-1.0.0", "orders": orders},
headers={"X-Payava-Key": os.environ["PATRIS_API_KEY"]},
timeout=20,
)
if response.status_code == 429:
return {"retry_after": int(response.headers.get("Retry-After", "60"))}
if not response.ok:
problem = response.json() if response.headers.get("Content-Type", "").startswith("application/") else {}
return {"error": problem.get("detail") or f"HTTP {response.status_code}", "status": response.status_code}
return response.json() # results: mark stored / updated / already_delivered as sent
<?php
/** @param array $orders max 50, same objects as GET /orders */
function patris_send_orders(array $orders): array
{
$ch = curl_init(rtrim(getenv('PATRIS_CLOUD_URL'), '/') . '/api/site/v1/orders');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => true,
CURLOPT_TIMEOUT => 20,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json; charset=utf-8',
'X-Payava-Key: ' . getenv('PATRIS_API_KEY'),
],
CURLOPT_POSTFIELDS => json_encode([
'siteUrl' => getenv('SITE_URL'),
'pluginVersion' => 'custom-1.0.0',
'orders' => $orders,
], JSON_UNESCAPED_UNICODE),
]);
$raw = curl_exec($ch);
if ($raw === false) {
return ['error' => curl_error($ch)]; // network error: retry later
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers = substr($raw, 0, $headerSize);
$body = json_decode(substr($raw, $headerSize), true) ?: [];
if ($status === 429) {
preg_match('/^Retry-After:\s*(\d+)/mi', $headers, $m);
return ['retry_after' => (int) ($m[1] ?? 60)];
}
if ($status < 200 || $status >= 300) {
return ['error' => $body['detail'] ?? "HTTP $status", 'status' => $status]; // ProblemDetails
}
return $body; // results: mark stored / updated / already_delivered as sent
}
const CLOUD_URL = process.env.PATRIS_CLOUD_URL.replace(/\/$/, '');
/** orders: max 50, same objects as GET /orders */
async function sendOrders(orders) {
const response = await fetch(`${CLOUD_URL}/api/site/v1/orders`, {
method: 'POST',
headers: {
'Content-Type': 'application/json; charset=utf-8',
'X-Payava-Key': process.env.PATRIS_API_KEY,
},
body: JSON.stringify({ siteUrl: process.env.SITE_URL, pluginVersion: 'custom-1.0.0', orders }),
signal: AbortSignal.timeout(20000),
});
if (response.status === 429) {
return { retryAfter: Number(response.headers.get('retry-after') || 60) };
}
const body = await response.json().catch(() => ({}));
if (!response.ok) {
return { error: body.detail || `HTTP ${response.status}`, status: response.status }; // ProblemDetails
}
return body; // results: mark stored / updated / already_delivered as sent
}
module.exports = { sendOrders };
package patriscloud
import (
"bytes"
"context"
"encoding/json"
"fmt"
"net/http"
"os"
"strconv"
"strings"
"time"
)
type OrderResult struct {
ID string `json:"id"`
Status string `json:"status"` // stored | updated | already_delivered | invalid
Message string `json:"message"`
}
type Response struct {
Ok bool `json:"ok"`
Results []OrderResult `json:"results"`
}
// SendOrders sends at most 50 orders (same objects as GET /orders).
// retryAfter > 0 means the key is rate limited.
func SendOrders(ctx context.Context, orders []any) (resp *Response, retryAfter time.Duration, err error) {
payload, _ := json.Marshal(map[string]any{
"siteUrl": os.Getenv("SITE_URL"), "pluginVersion": "custom-1.0.0", "orders": orders,
})
url := strings.TrimRight(os.Getenv("PATRIS_CLOUD_URL"), "/") + "/api/site/v1/orders"
req, _ := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
req.Header.Set("Content-Type", "application/json; charset=utf-8")
req.Header.Set("X-Payava-Key", os.Getenv("PATRIS_API_KEY"))
client := &http.Client{Timeout: 20 * time.Second}
res, err := client.Do(req)
if err != nil {
return nil, 0, err // network error: retry later
}
defer res.Body.Close()
if res.StatusCode == http.StatusTooManyRequests {
secs, _ := strconv.Atoi(res.Header.Get("Retry-After"))
return nil, time.Duration(max(secs, 60)) * time.Second, nil
}
if res.StatusCode < 200 || res.StatusCode >= 300 {
var problem struct {
Title string `json:"title"`
Detail string `json:"detail"`
}
json.NewDecoder(res.Body).Decode(&problem)
return nil, 0, fmt.Errorf("patris server %d %s: %s", res.StatusCode, problem.Title, problem.Detail)
}
resp = &Response{}
err = json.NewDecoder(res.Body).Decode(resp)
return resp, 0, err // mark stored / updated / already_delivered as sent
}
نمونه پاسخ موفق
{
"ok": true,
"stored": 1,
"updated": 0,
"alreadyDelivered": 0,
"invalid": 0,
"results": [
{ "id": "1532", "status": "stored", "message": null }
]
}
مقدارهای status در results
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
stored | string | — | سفارش جدید ذخیره شد. سفارش را «ارسالشده» علامت بزنید. |
updated | string | — | سفارش قبلاً ارسال شده بود و نسخهی جدید جایگزین شد. «ارسالشده» علامت بزنید. |
already_delivered | string | — | سفارش قبلاً به پاتریس تحویل شده و تغییر نادیده گرفته شد. «ارسالشده» علامت بزنید. |
invalid | string | — | سفارش نامعتبر است (مثلاً id ندارد یا خیلی بزرگ است). علت در message است. دوباره ارسال نکنید. |
کدهای خطا
پاسخ خطا با قالب ProblemDetails است: title کد وضعیت و detail پیام فارسی قابلنمایش به مدیر سایت.
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
400 | invalid_site_url | — | siteUrl خالی یا نامعتبر است. |
400 | too_many_orders | — | بیش از ۵۰ سفارش در یک درخواست. |
401 | unknown_key | — | کلید ارسال نشده یا در سامانهی پاتریس پیدا نشد. |
403 | revoked | — | کلید باطل شده است. |
403 | tenant_inactive | — | حساب پاتریس غیرفعال است. |
403 | no_subscription | — | اشتراک حساب پاتریس فعال نیست یا تمام شده است. |
403 | ip_not_allowed | — | IP سرور سایت برای این کلید مجاز نیست. |
403 | scope_missing | — | امکان «ارسال سفارشها از طریق سرور پاتریس» برای این حساب فعال نیست. |
409 | conflict | — | دو ارسال همزمانِ یک سفارش جدید. کمی بعد دوباره بفرستید. |
429 | rate_limited | — | تعداد درخواستهای این کلید در دقیقه از حد مجاز گذشته است. پس از ثانیههای هدر Retry-After دوباره بفرستید. |
اگر ارسال شکست خورد چه کنم؟
سفارشها را در حالت «در انتظار ارسال» نگه دارید و دوباره تلاش کنید. این زمانبندی پیشنهاد میشود:
- تلاش دوم پس از ۱ دقیقه.
- تلاش سوم پس از ۵ دقیقه.
- تلاش چهارم پس از ۱۵ دقیقه.
- پس از آن هر ۶۰ دقیقه، تا وقتی سرور بپذیرد.
برای 401 و 403 هم همین کار را بکنید و متن detail را به مدیر سایت نشان دهید. وقتی پشتیبانی پایاوا مشکل را رفع کند، تلاش بعدی موفق میشود.
نکتهها
پس از ارسال به سرور، سفارش را «تحویلشده به پاتریس» علامت نزنید. پاتریس یار پس از دریافت سفارش از سرور، خودش POST /patris-yar/orders/delivered را صدا میزند. تا آن زمان سفارش باید در GET /patris-yar/orders بیاید تا اگر سرور در دسترس نبود، با گذاشتن اتصال روی «دریافت مستقیم از همین اتصال» سفارشها مستقیم از سایت گرفته شوند.
- تغییر وضعیت سفارشی که قبلاً ارسال شده را دوباره بفرستید. سرور تا پیش از تحویل، نسخهی جدید را جایگزین میکند.
- در هر درخواست حداکثر ۵۰ سفارش بفرستید. حجم کل بدنه حداکثر ۱۶ مگابایت است.
- اگر API روی دامنهی دیگری است (مثلاً
api.example.comو سایتshop.example.com)، درsiteUrlهمان دامنهی API را بفرستید. پاتریس یار سفارشهای سرور را با دامنه به همین اتصال نسبت میدهد و فقط در این صورتPOST /patris-yar/orders/deliveredرا برای آنها صدا میزند. - اگر سفارشها را با کلید دیگری بفرستید، پاتریس یاری که کلید قبلی را دارد آنها را نمیبیند. کلید سایت و پاتریس یار همیشه یکی باشد.