دریافت اشخاص و ماندهحساب
پاتریس یار اشخاصی را که در پاتریس برای مای پاتریس تعریف شدهاند، با POST /patris-yar/mypatris/persons به سایت میفرستد. هر شخص با username شناخته میشود و سایت آن را ذخیره یا جایگزین میکند.
پیشنیازها
- مای پاتریس روی سایت اختصاصی
- یک جدول اشخاص با کلید اصلی
username.
Endpoint
POST /patris-yar/mypatris/persons
هدرها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
X-Payava-Key | string | بله | کلید API حساب پاتریس. |
Content-Type | string | بله | application/json; charset=utf-8 |
پارامترها
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
persons | array | بله | اشخاص تغییرکرده. ممکن است خالی باشد. |
deleted | string[] | بله | username اشخاصی که در پاتریس حذف شدهاند. ممکن است خالی باشد. |
فیلدهای هر شخص
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
username | string | بله | نام کاربری شخص در مای پاتریس. شخص بدون username را ذخیره نکنید. |
code | integer | بله | کد حساب شخص در پاتریس. صورتحساب با همین کد ارسال میشود. |
name | string | خیر | نام شخص. |
mobile | string | خیر | موبایل شخص. |
tel | string | خیر | تلفن ثابت. |
address | string | خیر | نشانی. |
email | string | خیر | ایمیل. |
role | string | خیر | نقش شخص در مای پاتریس. |
debtor | number | بله | ماندهحساب، به واحد پاتریس. مثبت یعنی بدهکار، منفی یعنی بستانکار، صفر یعنی بیحساب. |
credit_limit | number | بله | سقف اعتبار، به واحد پاتریس. |
is_lock | boolean | بله | true یعنی حساب شخص در پاتریس قفل است. |
national_code | string | خیر | کد ملی. |
نمونه درخواست و پیادهسازی
- curl
- C#
- Python
- PHP
- Node.js
- Go
ارسال اشخاص
curl -X POST https://shop.example.com/patris-yar/mypatris/persons \
-H "X-Payava-Key: YOUR_API_KEY" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"persons":[{"username":"09120000000","code":101001,"name":"علی رضایی","mobile":"09120000000","tel":"","address":"","email":"","role":"","debtor":3500000,"credit_limit":10000000,"is_lock":false,"national_code":""}],"deleted":["old.customer"]}'
POST /mypatris/persons
patris.MapPost("/mypatris/persons", async (PersonsRequest body, IMyPatrisStore store) =>
{
var deleted = 0;
foreach (var username in body.Deleted)
deleted += await store.DeletePersonAsync(username);
var stored = 0;
foreach (var person in body.Persons.Where(p => !string.IsNullOrWhiteSpace(p.Username)))
{
await store.UpsertPersonAsync(person); // key: Username
stored++;
}
return Results.Json(new { stored, deleted });
});
public sealed class PersonsRequest
{
public List<MyPatrisPerson> Persons { get; set; } = new();
public List<string> Deleted { get; set; } = new();
}
public sealed class MyPatrisPerson
{
public string? Username { get; set; }
public long Code { get; set; }
public string? Name { get; set; }
public string? Mobile { get; set; }
public string? Tel { get; set; }
public string? Address { get; set; }
public string? Email { get; set; }
public string? Role { get; set; }
public decimal Debtor { get; set; }
[System.Text.Json.Serialization.JsonPropertyName("credit_limit")] public decimal CreditLimit { get; set; }
[System.Text.Json.Serialization.JsonPropertyName("is_lock")] public bool IsLock { get; set; }
[System.Text.Json.Serialization.JsonPropertyName("national_code")] public string? NationalCode { get; set; }
}
POST /mypatris/persons
class MyPatrisPerson(BaseModel):
username: str = ""
code: int = 0
name: str = ""
mobile: str = ""
tel: str = ""
address: str = ""
email: str = ""
role: str = ""
debtor: Decimal = Decimal(0)
credit_limit: Decimal = Decimal(0)
is_lock: bool = False
national_code: str = ""
class PersonsRequest(BaseModel):
persons: list[MyPatrisPerson] = []
deleted: list[str] = []
@router.post("/mypatris/persons")
def mypatris_persons(body: PersonsRequest):
deleted = sum(mypatris_store.delete_person(u) for u in body.deleted)
stored = 0
for person in body.persons:
if person.username.strip():
mypatris_store.upsert_person(person) # key: username
stored += 1
return {"stored": stored, "deleted": deleted}
POST /mypatris/persons
if ($method === 'POST' && $route === '/mypatris/persons') {
$body = json_body();
$deleted = 0;
foreach ((array) ($body['deleted'] ?? []) as $username) {
$deleted += $myPatris->deletePerson((string) $username);
}
$stored = 0;
foreach ((array) ($body['persons'] ?? []) as $person) {
if (trim((string) ($person['username'] ?? '')) === '') {
continue;
}
$myPatris->upsertPerson($person); // key: username
$stored++;
}
respond(200, ['stored' => $stored, 'deleted' => $deleted]);
}
POST /mypatris/persons
router.post('/mypatris/persons', async (req, res, next) => {
try {
let deleted = 0;
for (const username of req.body.deleted || []) {
deleted += await myPatrisStore.deletePerson(String(username));
}
let stored = 0;
for (const person of req.body.persons || []) {
if (!String(person.username || '').trim()) continue;
await myPatrisStore.upsertPerson(person); // key: username
stored++;
}
res.json({ stored, deleted });
} catch (err) {
next(err);
}
});
POST /mypatris/persons
type MyPatrisPerson struct {
Username string `json:"username"`
Code int64 `json:"code"`
Name string `json:"name"`
Mobile string `json:"mobile"`
Tel string `json:"tel"`
Address string `json:"address"`
Email string `json:"email"`
Role string `json:"role"`
Debtor float64 `json:"debtor"`
CreditLimit float64 `json:"credit_limit"`
IsLock bool `json:"is_lock"`
NationalCode string `json:"national_code"`
}
func myPatrisPersons(w http.ResponseWriter, r *http.Request) {
var body struct {
Persons []MyPatrisPerson `json:"persons"`
Deleted []string `json:"deleted"`
}
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
writeJSON(w, http.StatusBadRequest, map[string]string{"code": "invalid_json", "message": err.Error()})
return
}
deleted, stored := 0, 0
for _, u := range body.Deleted {
deleted += myPatrisStore.DeletePerson(r.Context(), u)
}
for _, p := range body.Persons {
if strings.TrimSpace(p.Username) == "" {
continue
}
myPatrisStore.UpsertPerson(r.Context(), p) // key: username
stored++
}
writeJSON(w, http.StatusOK, map[string]int{"stored": stored, "deleted": deleted})
}
// patris.HandleFunc("POST "+base+"/mypatris/persons", myPatrisPersons)
نمونه پاسخ موفق
200 OK
{ "stored": 1, "deleted": 1 }
پاتریس یار مقدارهای پاسخ را نمیخواند. فقط موفق بودن پاسخ مهم است.
کدهای خطا
| نام | نوع | الزامی | توضیح |
|---|---|---|---|
401 | payava_patris_unauthorized | — | کلید نادرست است. |
400 | invalid_json | — | بدنهی درخواست JSON معتبر نیست. |
نکتهها
- اول
deletedو بعدpersonsرا پردازش کنید. اگر یکusernameدر هر دو آمد، شخص باید باقی بماند. usernameناشناخته درdeletedرا بدون خطا رد کنید.- موبایل را پیش از ذخیره به شکل
09xxxxxxxxxیکسان کنید تا با موبایل حساب مشتری تطبیق پیدا کند. - کد ملی و ماندهحساب اطلاعات حساس هستند. آنها را فقط به خود شخص نشان دهید.