راهنمای اتصال به API هما (نسخه خروجی استاندارد)
این API امکان خواندن، ایجاد، ویرایش و حذف دادهها را فراهم میکند. پاسخها با ساختار استاندارد بازگردانده میشوند تا پیادهسازی سمت کلاینت ساده و قابل اطمینان باشد.
Base URL:
Methods: GET خواندن | POST ایجاد/ویرایش/حذف
Content-Type (POST):
https://endpoint.homais.com/endpoint/homa/Methods: GET خواندن | POST ایجاد/ویرایش/حذف
Content-Type (POST):
application/json; charset=utf-8پارامترهای الزامی
- PortalCode: کد پرتال شما
- Token: توکن دسترسی معتبر
- apiPin: پین امنیتی API
نام موجودیتها (table)
| table | توضیح |
|---|---|
product |
فهرست محصولات |
warecategory |
دستهبندی کالا |
warehouse |
انبارها |
wareunit |
واحدهای اندازهگیری |
contactlist |
مخاطبان/مشتریان |
contactcategory |
دستههای مخاطبان |
invoiceheader |
سربرگ فاکتور |
invoicebody |
اقلام فاکتور |
cdn |
فایلها و پیوستها |
CustomerAddress |
آدرسهای مشتری |
blogpost |
محتوا/پست |
blogcategory |
دستههای محتوا |
URLs |
لینکهای کوتاه |
URLClicks |
بازدیدهای لینک |
ساختار پاسخ استاندارد
برای عملیات ایجاد/ویرایش/حذف، پاسخها با ساختار زیر برمیگردند:
[
{ "success": true, "code": 201, "message": "Inserted successfully.", "id": 45678, "extra": null }
]
نمونه خطا:
[
{ "success": false, "code": 401, "message": "Token is not valid.", "id": null, "extra": null }
]
در حالت خواندن (GET)، خروجی بهصورت آرایهای از رکوردها است:
[
{ "ID": 123, "Title": "Product A", "PortalCode": 10130017, "Price": 450000 },
{ "ID": 124, "Title": "Product B", "PortalCode": 10130017, "Price": 520000 }
]
خواندن دادهها (GET)
نمونه درخواست
GET https://endpoint.homais.com/endpoint/homa/?PortalCode=10130017&Token={STABLE_TOKEN}&apiPin={PIN}&table=product&pageNo=1&pageSize=20&queryCommand=Price%20%3E%20100000
ایجاد، ویرایش، حذف (POST)
برای انجام عملیات، پارامتر updateCommand=true را در QueryString ارسال کنید و بدنه JSON را در درخواست قرار دهید.
ایجاد (Insert)
POST https://endpoint.homais.com/endpoint/homa/?PortalCode=10130017&Token={STABLE_TOKEN}&apiPin={PIN}&table=blogpost&updateCommand=true
Content-Type: application/json
{
"Title": "New Post",
"Slug": "new-post",
"Body": "\
Content...\
", "IsPublished": true, "PublishedAt": "2025-08-10T10:20:00" }پاسخ ایجاد
\[
{ "success": true, "code": 201, "message": "Inserted successfully.", "id": 45678, "extra": null }
]
ویرایش (Update)
POST https://endpoint.homais.com/endpoint/homa/?PortalCode=10130017&Token={STABLE_TOKEN}&apiPin={PIN}&table=blogpost&updateCommand=true
Content-Type: application/json
{
"id": 45678,
"Title": "Updated Title"
}
پاسخ ویرایش
\[
{ "success": true, "code": 200, "message": "Updated successfully.", "id": 45678, "extra": null }
]
حذف با شناسه (Delete by ID)
POST https://endpoint.homais.com/endpoint/homa/?PortalCode=10130017&Token={STABLE_TOKEN}&apiPin={PIN}&table=blogpost&updateCommand=true
Content-Type: application/json
{
"ID": 45678,
"DeleteOrder": true
}
حذف با شرط (Delete by Condition)
POST [https://endpoint.homais.com/endpoint/homa/?PortalCode=10130017\&Token={STABLE\_TOKEN}\&apiPin={PIN}\&table=blogpost\&updateCommand=true](https://endpoint.homais.com/endpoint/homa/?PortalCode=10130017&Token={STABLE_TOKEN}&apiPin={PIN}&table=blogpost&updateCommand=true)
Content-Type: application/json
{
"DeleteOrder": true,
"deleteCondition": "IsPublished = 0 AND Title LIKE N'Draft %'"
}
کدهای پاسخ
| code | شرح |
|---|---|
| 200 | عملیات موفق (Update/Delete) |
| 201 | عملیات موفق (Insert) |
| 400 | درخواست نامعتبر |
| 401 | دسترسی نامعتبر |
| 404 | رکوردی یافت نشد |
| 500 | خطای داخلی |
نکات امنیتی
- از HTTPS استفاده کنید.
TokenوapiPinرا محرمانه نگه دارید.queryCommandرا فقط از ورودیهای معتبر بسازید.- در سمت کلاینت Rate Limit منطقی اعمال کنید.
نمونههای سریع cURL
GET
curl "https://endpoint.homais.com/endpoint/homa/?PortalCode=10130017&Token=XXXX&apiPin=YYYY&table=product&pageNo=1&pageSize=20&queryCommand=Price%20%3E%20100000"
POST Insert
curl -X POST "https://endpoint.homais.com/endpoint/homa/?PortalCode=10130017&Token=XXXX&apiPin=YYYY&table=blogpost&updateCommand=true" ^
-H "Content-Type: application/json" ^
-d "{{\"Title\":\"New Post\",\"Slug\":\"new-post\",\"Body\":\"<p>...</p>\",\"IsPublished\":true}}"