Skip to main content
#P1786

POST /b2c/v1/media/upload/s3


Upload Media to S3

این اندپوینت جهت آپلود فایل‌ها (تصاویر، اسناد و ...) بر روی فضای ذخیره‌سازی ابری (S3 Compatible / Liara) استفاده می‌شود.
انعطاف‌پذیری: کلاینت می‌تواند محدودیت‌های حجم، فرمت فایل و مسیر ذخیره‌سازی را در درخواست تعیین کند. در غیر این صورت، مقادیر پیش‌فرض سیستم اعمال می‌شوند.



Upload File

URL: /b2c/v1/media/upload/s3
Method: POST
Controller: V1S3Controller@uploadFile
Content-Type: multipart/form-data

Body Parameters (Multipart/Form-Data)

Parameter Type Required Description Default / Note
file File Yes فایل مورد نظر برای آپلود. -
branch String No* شناسه برنچ (برای ساختار پوشه‌بندی پیش‌فرض). در مسیر پیش‌فرض استفاده می‌شود.
type String No* نوع فایل (مثلاً avatar, ticket) برای پوشه‌بندی. در مسیر پیش‌فرض استفاده می‌شود.
name String No نام دلخواه برای ذخیره فایل (بدون پسوند). Timestamp + Random ID
size Integer No حداکثر حجم مجاز به کیلوبایت. 5120 (5MB)
mimes String No فرمت‌های مجاز (با کاما جدا شوند). jpeg,png,jpg,gif,pdf,webp
path String No مسیر کامل ذخیره‌سازی (Folder Path). b2c/uploads/{branch}/{type}/{Y}/{m}/

Response Structure

Key Type Description
status Boolean وضعیت عملیات (true موفق، false ناموفق).
file String مسیر کامل (Key) فایل آپلود شده در باکت S3.

Example Responses

۱. آپلود موفق (Success - 201):

{
    "status": true,
    "file": "b2c/uploads/1001/avatar/2023/12/custom-name.jpg"
}

۲. خطای اعتبارسنجی (Validation Error - 422):

{
    "message": "The file must be a file of type: jpeg, png, jpg, gif, pdf, webp.",
    "errors": {
        "file": [
            "The file must be a file of type: jpeg, png, jpg, gif, pdf, webp."
        ]
    }
}

۳. خطای سرور/آپلود (Error - 400):

{
    "status": false,
    "time": 1702165000
}

Technical Logic

Request (Multipart)
↓
Config Initialization
Set Size: input OR 5120KB
Set Mimes: input OR defaults
Set Path: input OR b2c/uploads/...
↓
Validation Passed?
↓ Yes
Generate Filename
If `name` exists → Use it
Else → Y-m-d-His-microtime
↓ No
Error 422
Validation Exception
↓
Storage Put
Disk: 'liara'
put(path + filename, contents)
↓
Upload Success?
↓ Yes
Return 201
{"status": true, "file": "path..."}
↓ No
Return 400
{"status": false}
Back to top