tm_panel/docs/client/Filestore Frontend Guide.md

Frontend Guide: File Upload + Profile Image APIs

This is a simple reference for frontend integration with file upload, file retrieval, and setting profile image.

Base URLs

• Admin APIs: /admin/v1
• Customer/Public APIs: /api/v1

All protected endpoints require:

• Authorization: Bearer <access_token>

---

1) Login (Admin)

Use this when you want to update admin user profile image.

Request

• POST /admin/v1/profile/login
• Content-Type: application/json

{
  "username": "admin",
  "password": "Admin1234"
}

Response (success)

{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": "65bc1234567890abcdef1234",
      "profile_image": null
    },
    "access_token": "<jwt>",
    "refresh_token": "<jwt>",
    "expires_at": 1776783486
  }
}

---

2) Upload File (GridFS)

Use multipart form upload.

Admin route

• POST /admin/v1/files/upload

Customer route

• POST /api/v1/files/upload

Form fields

• file (required, File)
• category (optional, string), example: profile_images
• tags (optional, repeatable), example: user, profile
• description (optional, string)

Response (success)

{
  "file_id": "69e7899c2053abd3fa5433e0",
  "filename": "avatar.png",
  "content_type": "image/png",
  "size": 123456,
  "message": "File uploaded successfully"
}

---

3) Get File Info

• GET /admin/v1/files/{file_id}/info
• GET /api/v1/files/{file_id}/info

Response (success)

{
  "file_id": "69e7899c2053abd3fa5433e0",
  "filename": "avatar.png",
  "content_type": "image/png",
  "size": 123456,
  "uploaded_by": "65bc1234567890abcdef1234",
  "uploaded_at": "2026-04-21T14:28:44.787Z",
  "category": "profile_images",
  "tags": ["user", "profile"],
  "description": "sample profile photo"
}

---

4) Download File

• GET /admin/v1/files/{file_id}/download
• GET /api/v1/files/{file_id}/download

Returns file binary stream.

Useful for image URL:

• http://localhost:8080/admin/v1/files/<file_id>/download
• or http://localhost:8080/api/v1/files/<file_id>/download

---

5) Set Admin User Profile Image

Upload does not update user profile automatically.
After upload, call profile update endpoint with the download URL.

Request

• PUT /admin/v1/profile
• Content-Type: application/json

{
  "profile_image": "http://localhost:8080/admin/v1/files/69e7899c2053abd3fa5433e0/download"
}

Response

• Success: standard success envelope with updated user data
• Failure example:

{
  "success": false,
  "message": "Bad Request",
  "error": {
    "code": "BAD_REQUEST",
    "message": "failed to update user"
  }
}

---

6) Verify Profile

• GET /admin/v1/profile

Check:

• data.profile_image is now populated with file URL.

---

Common Errors

• 401 Unauthorized: missing/expired token
• 413 Request Entity Too Large: file too big
• 400 Unsupported file type or validation error
• 404 File not found: wrong file_id

---

Suggested Frontend Flow (Admin)

1. Login -> save access_token
2. Upload image -> get file_id
3. Build URL .../admin/v1/files/{file_id}/download
4. Update profile with profile_image URL
5. Refresh profile screen via GET /admin/v1/profile

---

Customer: Company Documents Upload

Customers can upload company documents using customer auth token.

Upload endpoint

• POST /api/v1/files/upload

Recommended form-data for company docs

• file: actual document file
• category: company_documents
• tags: repeatable. Suggested:
  • company
  • document
  • <doc_type> (example: tax_certificate, registration, license)
• description: human-readable note, example: Company tax certificate 2026

Example curl

CUSTOMER_TOKEN="<customer_access_token>"

curl -X POST "http://localhost:8080/api/v1/files/upload" \
  -H "Authorization: Bearer ${CUSTOMER_TOKEN}" \
  -F "file=@/absolute/path/to/company-doc.pdf" \
  -F "category=company_documents" \
  -F "tags=company" \
  -F "tags=document" \
  -F "tags=tax_certificate" \
  -F "description=Company tax certificate 2026"

Response

{
  "file_id": "69e8abcd2053abd3fa5433e1",
  "filename": "company-doc.pdf",
  "content_type": "application/pdf",
  "size": 245632,
  "message": "File uploaded successfully"
}

Fetch company docs list

Use list with category filter:

• GET /api/v1/files?category=company_documents&limit=50&skip=0

You can also filter by tags:

• GET /api/v1/files?category=company_documents&tags=tax_certificate

Download company doc

• GET /api/v1/files/{file_id}/download

Important current behavior

• Upload works for customers and stores uploaded_by as customer_id.
• Company now supports document_file_ids for mapping GridFS files.

Attach uploaded documents to company

Use admin company update endpoint after collecting uploaded file_id values:

• PUT /admin/v1/companies/{company_id}

Request body includes regular company fields plus document_file_ids:

{
  "name": "Opplens",
  "type": "private",
  "registration_number": "1234567890",
  "tax_id": "1234567890",
  "industry": "Technology",
  "document_file_ids": [
    "69e8abcd2053abd3fa5433e1",
    "69e8abcd2053abd3fa5433e2"
  ]
}

document_file_ids is also returned in:

• GET /admin/v1/companies/{id}
• GET /api/v1/companies (customer "my company" profile)