# POST /b2c/v1/media/upload/s3

<div class="api-docs" id="bkmrk-">  <div class="endpoint-section">  
</div></div>## Upload Media to S3

این اندپوینت جهت آپلود فایل‌ها (تصاویر، اسناد و ...) بر روی فضای ذخیره‌سازی ابری (S3 Compatible / Liara) استفاده می‌شود.   
<span style="color: #0275d8; font-weight: bold;">انعطاف‌پذیری:</span> کلاینت می‌تواند محدودیت‌های حجم، فرمت فایل و مسیر ذخیره‌سازی را در درخواست تعیین کند. در غیر این صورت، مقادیر پیش‌فرض سیستم اعمال می‌شوند.

<div class="api-docs" id="bkmrk--1"><div class="endpoint-section">  
</div>  
---

  </div># Upload File

<div class="api-docs" id="bkmrk-url%3A-%2Fb2c%2Fv1%2Fmedia%2Fu"><div class="endpoint-info"><div>**URL:** `/b2c/v1/media/upload/s3`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** V1S3Controller@uploadFile</div><div>**Content-Type:** multipart/form-data</div></div></div>### Body Parameters (Multipart/Form-Data)

<div class="api-docs" id="bkmrk-parameter-type-requi"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Required</th><th>Description</th><th>Default / Note</th></tr></thead><tbody><tr><td dir="ltr">file</td><td>File</td><td><span style="color: red;">Yes</span></td><td>فایل مورد نظر برای آپلود.</td><td>-</td></tr><tr><td dir="ltr">branch</td><td>String</td><td>No\*</td><td>شناسه برنچ (برای ساختار پوشه‌بندی پیش‌فرض).</td><td>در مسیر پیش‌فرض استفاده می‌شود.</td></tr><tr><td dir="ltr">type</td><td>String</td><td>No\*</td><td>نوع فایل (مثلاً avatar, ticket) برای پوشه‌بندی.</td><td>در مسیر پیش‌فرض استفاده می‌شود.</td></tr><tr><td dir="ltr">name</td><td>String</td><td>No</td><td>نام دلخواه برای ذخیره فایل (بدون پسوند).</td><td>Timestamp + Random ID</td></tr><tr><td dir="ltr">size</td><td>Integer</td><td>No</td><td>حداکثر حجم مجاز به کیلوبایت.</td><td>`5120` (5MB)</td></tr><tr><td dir="ltr">mimes</td><td>String</td><td>No</td><td>فرمت‌های مجاز (با کاما جدا شوند).</td><td>`jpeg,png,jpg,gif,pdf,webp`</td></tr><tr><td dir="ltr">path</td><td>String</td><td>No</td><td>مسیر کامل ذخیره‌سازی (Folder Path).</td><td>`b2c/uploads/{branch}/{type}/{Y}/{m}/`</td></tr></tbody></table>

  </div>### Response Structure

<div class="api-docs" id="bkmrk-key-type-description"><table class="schema-table" dir="rtl"><thead><tr><th>Key</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td dir="ltr">status</td><td>Boolean</td><td>وضعیت عملیات (true موفق، false ناموفق).</td></tr><tr><td dir="ltr">file</td><td>String</td><td>مسیر کامل (Key) فایل آپلود شده در باکت S3.</td></tr></tbody></table>

</div>### Example Responses

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

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

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

```json
{
    "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):**

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

<div class="api-docs" id="bkmrk--2">---

  </div>### Technical Logic

<div class="api-docs" id="bkmrk-request-%28multipart%29-"><div class="flowchart"><div class="flow-item">Request (Multipart)</div><div class="flow-arrow">↓</div><div class="flow-item-process">**Config Initialization**  
Set Size: input OR 5120KB  
Set Mimes: input OR defaults  
Set Path: input OR `b2c/uploads/...`</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Validation Passed?</div><div style="display: flex; justify-content: space-between; width: 400px; margin: 0 auto;"><div style="text-align: center;"><div class="flow-arrow">↓ Yes</div><div class="flow-item-process">**Generate Filename**  
If `name` exists → Use it  
Else → `Y-m-d-His-microtime`</div></div><div style="text-align: center;"><div class="flow-arrow">↓ No</div><div class="flow-item-process" style="background-color: #f8d7da;">Error 422  
Validation Exception</div></div></div><div class="flow-arrow">↓</div><div class="flow-item-process">**Storage Put**  
Disk: 'liara'  
`put(path + filename, contents)`</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Upload Success?</div><div style="display: flex; justify-content: space-between; width: 500px; margin: 0 auto;"><div style="text-align: center;"><div class="flow-arrow">↓ Yes</div><div class="flow-item-success">Return 201  
{"status": true, "file": "path..."}</div></div><div style="text-align: center;"><div class="flow-arrow">↓ No</div><div class="flow-item-process" style="background-color: #f8d7da;">Return 400  
{"status": false}</div></div></div></div></div>