Document

The document module stores files/documents attached to product entities (charitable cause, commodity financing, investment, transaction) via the polymorphic product_type + product_id columns. The /v1/documents endpoint handles direct upload (multipart) or registers files already uploaded via the file-manager presigned flow. The /v1/official-documents endpoint stores official identities (passport, KTP, SIM, NPWP) separately because the lifecycle and fields differ.

Property	Value
Base URL	{HOST}/v1
Auth	Bearer JWT (header Authorization) or cookie access_token
Content-Type	application/json (or multipart/form-data for direct upload)
Error envelope	{ "message": string | string[], "statusCode": number, "error": string }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true · unknown field → 400
Related modules	file-manager, charitable-cause, commodity-financing, investments, transactions
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

Primary upload path: direct upload (POST /v1/documents/upload, multipart) — the server performs the S3 upload and stores metadata in one transaction. POST /v1/documents still exists for registering an object that was uploaded through another channel (side-channel); most FE callers don’t need it. Once registered, a presigned (expiring) view URL can be retrieved via /v1/documents/:id/view-url. Official identities (KTP, passport, SIM, NPWP) use the separate /v1/official-documents endpoint.

Method	Path	Auth	Summary
POST	/v1/documents/upload	bearer upload-document	Direct upload (multipart) — server-side to S3
POST	/v1/documents	bearer create-document	Register a document for an existing S3 object (side-channel)
GET	/v1/documents	bearer read-document	List all documents
GET	/v1/documents/type/:type	bearer read-document	List documents by type
GET	/v1/documents/:id	bearer read-document	Detail of a single document
GET	/v1/documents/:id/view-url	bearer read-document	Presigned URL to view document contents
PATCH	/v1/documents/:id	bearer update-document	Update document metadata
DELETE	/v1/documents/:id	bearer delete-document	Delete a document record
POST	/v1/official-documents	bearer create-official-document	Create an official identity
GET	/v1/official-documents	bearer read-official-document	List official identities
GET	/v1/official-documents/:id	bearer read-official-document	Detail of a single official identity
PATCH	/v1/official-documents/:id	bearer update-official-document	Update an official identity
DELETE	/v1/official-documents/:id	bearer delete-official-document	Delete an official identity

Notes

• The user profile picture is not part of this module — it is stored directly as a string in users.profile_image. Only artifacts attached to a product live in the documents table.
• The url field stores the S3 file-key (encrypted in DB). public_url in the response is the resolved URL for direct consumption.
• The DTOs for create-official_document and update-official_document are currently empty in the repo — the service layer determines the actual fields. The endpoints are still documented because the routes are active.

Upload flow — polymorphic attachment

Documents attach to a parent via two columns on the documents row: product_type (which kind of parent — charitable_cause, commodity_financing, investment, transaction) and product_id (the parent’s UUID). There is no photo_document_id on the parent — the relationship is reversed. The FE flow is therefore create parent first, then upload docs referencing the parent ID.

Key takeaways

• Create the parent first (cause, financing, investment, transaction). The response contains data.id — that’s product_id for step 2.
• Upload each document with that ID via POST /v1/documents/upload. Repeat per attachment (image, video, regulations PDF, signature, …). One multipart call per file.
• On subsequent GETs of the parent, the server runs DocumentService.findByProductAndType(product_type, product_id) and embeds the matching docs in the response — FE does not need to call /documents separately.
• To display a private doc later outside the parent context, call GET /v1/documents/:id/view-url for a presigned URL (TTL-limited). For public docs use public_url from the original response directly.
• Profile picture is the exception — it’s a plain URL string on users.profile_image, not a row in documents. Don’t use this flow for profile photos.
• Official identity docs (KTP, passport, SIM, NPWP) live in /v1/official-documents, a separate flow (not polymorphic — keyed by user).

Field names that do NOT exist (don't send them)

• CreateCharitableCauseDto does NOT have photo_document_id / video_document_id / signature_document_id — neither do the entity columns. Some stale test fixtures still pass these names; they would be rejected by forbidNonWhitelisted: true at runtime. Do not include them in the create payload.

---

POST /v1/documents/upload bearer upload-document RESOURCE_CREATED

Upload a file directly via multipart. The server performs the S3 upload and stores the document metadata in one transaction (atomic — if S3 fails, no DB row is created).

Request body — UploadDocumentDto (multipart/form-data)

Field	Type	Required	Notes
file	file	yes	Binary file. Limit 50 MB.
document_type	enum DocumentType	yes	legal_agreement, signature, cause_report, donation_certificate, receipt, image, video
product_type	enum ProductType	yes	charitable_cause, commodity_financing, investment, transaction
product_id	UUID	yes	ID of the parent row the document is attached to
visibility	enum DocumentVisibility	optional	public / private (default private)

Example request

POST /v1/documents/upload
Content-Type: multipart/form-data; boundary=...

--boundary
Content-Disposition: form-data; name="file"; filename="receipt.pdf"
Content-Type: application/pdf

<binary>
--boundary
Content-Disposition: form-data; name="document_type"

receipt
--boundary
Content-Disposition: form-data; name="product_type"

transaction
--boundary
Content-Disposition: form-data; name="product_id"

550e8400-e29b-41d4-a716-446655440000
--boundary--

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "Document uploaded successfully",
  "data": {
    "document": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "documents/2026/receipt.pdf",
      "document_type": "receipt",
      "category_id": "550e8400-e29b-41d4-a716-446655440000",
      "public_url": "https://cdn.example.com/documents/receipt.pdf",
      "created_by": "550e8400-e29b-41d4-a716-446655440000",
      "updated_by": "550e8400-e29b-41d4-a716-446655440000",
      "deleted_by": null,
      "created_at": "2026-05-20T08:30:00.000Z",
      "updated_at": "2026-05-20T08:30:00.000Z"
    }
  }
}

Errors

Status	When
400 Bad Request	File not provided, file > 50 MB, or DTO validation failed
401 Unauthorized	Bearer/cookie invalid

---

POST /v1/documents bearer create-document RESOURCE_CREATED

Register a Documents row for an object that already exists in S3 (e.g. uploaded via a side-channel). Most FE callers should use POST /v1/documents/upload instead — this endpoint is only for special cases.

Request body — CreateDocumentDto

Field	Type	Required	Notes
url	string	yes	S3 file key of an object that already exists in the bucket
document_type	enum DocumentType	yes	See enum on the reference slide
product_type	enum ProductType	optional	Parent kind
product_id	UUID	optional	UUID of the parent row

Example request

{
  "url": "legal-agreements/agreement-123.pdf",
  "document_type": "legal_agreement",
  "product_type": "charitable_cause",
  "product_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "document registered successfully",
  "data": {
    "document": { "...": "same shape as the upload response" }
  }
}

Errors

Status	When
400 Bad Request	url empty, unknown enum, invalid UUID
401 Unauthorized	Bearer/cookie invalid

---

GET /v1/documents bearer read-document RESOURCE_FETCHED

List all documents visible to the user. Ownership filtering happens at the service layer.

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "all documents fetched successfully",
  "data": {
    "documents": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "url": "documents/2026/receipt.pdf",
        "document_type": "receipt",
        "category_id": "550e8400-e29b-41d4-a716-446655440000",
        "public_url": "https://cdn.example.com/documents/receipt.pdf",
        "created_by": "550e8400-e29b-41d4-a716-446655440000",
        "updated_by": "550e8400-e29b-41d4-a716-446655440000",
        "deleted_by": null,
        "created_at": "2026-05-20T08:30:00.000Z",
        "updated_at": "2026-05-20T08:30:00.000Z"
      }
    ]
  }
}

Errors

Status	When
401 Unauthorized	Bearer/cookie invalid

---

GET /v1/documents/type/:type bearer read-document RESOURCE_FETCHED

List documents filtered by document_type.

Path params

Param	Type	Notes
type	enum DocumentType	One of legal_agreement, signature, cause_report, donation_certificate, receipt, image, video

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "documents fetched successfully",
  "data": {
    "documents": [ "..." ]
  }
}

Errors

Status	When
401 Unauthorized	Bearer/cookie invalid

---

GET /v1/documents/:id bearer read-document RESOURCE_FETCHED

Detail of a single document by ID.

Path params

Param	Type	Notes
id	UUID	Document ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "document fetched successfully",
  "data": {
    "document": { "...": "DocumentDto shape" }
  }
}

Errors

Status	When
401 Unauthorized	Bearer/cookie invalid
404 Not Found	Document not found

---

GET /v1/documents/:id/view-url bearer read-document RESOURCE_FETCHED

Retrieve a presigned (expiring) S3 URL to display the document contents. Use response.data.view_url as the href for an image/iframe — the link is time-limited.

Path params

Param	Type	Notes
id	UUID	Document ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "presigned url to view document fetched successfully",
  "data": {
    "document_id": "550e8400-e29b-41d4-a716-446655440000",
    "file_key": "documents/2026/passport.pdf",
    "view_url": "https://s3.example.com/documents/passport.pdf?X-Amz-Signature=..."
  }
}

Errors

Status	When
401 Unauthorized	Bearer/cookie invalid
404 Not Found	Document not found

---

PATCH /v1/documents/:id bearer update-document RESOURCE_UPDATED

Update document metadata (e.g. move to another product, change document_type). All fields are optional — send only what changed.

Path params

Param	Type	Notes
id	UUID	Document ID

Request body — UpdateDocumentDto (PartialType of CreateDocumentDto)

Field	Type	Notes
url	string	New file key
document_type	enum DocumentType	Change type
product_type	enum ProductType	Change parent kind
product_id	UUID	Move to a different parent row

Example request

{
  "document_type": "donation_certificate"
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "document updated successfully",
  "data": {
    "document": { "...": "DocumentDto shape" }
  }
}

Errors

Status	When
401 Unauthorized	Bearer/cookie invalid
404 Not Found	Document not found

---

DELETE /v1/documents/:id bearer delete-document RESOURCE_DELETED

Delete a document record (soft delete — deleted_at + deleted_by are set).

Path params

Param	Type	Notes
id	UUID	Document ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "document removed successfully",
  "data": {}
}

Errors

Status	When
401 Unauthorized	Bearer/cookie invalid
404 Not Found	Document not found

---

POST /v1/official-documents bearer create-official-document

Create an official identity record (passport, KTP, SIM, NPWP). The CreateOfficialDocumentDto is currently empty in the repo — the actual fields are determined by the service layer (likely accepts number, type, issue/expiry date, file_key). Confirm with backend before FE implementation.

Request body — CreateOfficialDocumentDto

The DTO is currently empty (no fields). Check the service layer for the actual field conventions.

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "official document created",
  "data": { "...": "shape determined by service" }
}

Errors

Status	When
400 Bad Request	Validation failed
401 Unauthorized	Bearer/cookie invalid

---

GET /v1/official-documents bearer read-official-document

List all accessible official identities.

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "official documents fetched",
  "data": { "official_documents": [ "..." ] }
}

Errors

Status	When
401 Unauthorized	Bearer/cookie invalid

---

GET /v1/official-documents/:id bearer read-official-document

Detail of a single official identity.

Path params

Param	Type	Notes
id	string (numeric)	Official identity ID. Service casts to +id (numeric).

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "official document fetched",
  "data": { "official_document": { "..." } }
}

Errors

Status	When
401 Unauthorized	Bearer/cookie invalid
404 Not Found	Not found

---

PATCH /v1/official-documents/:id bearer update-official-document

Update an official identity. UpdateOfficialDocumentDto = PartialType of the create DTO (currently empty).

Path params

Param	Type	Notes
id	string (numeric)	Official identity ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "official document updated",
  "data": { "official_document": { "..." } }
}

---

DELETE /v1/official-documents/:id bearer delete-official-document

Delete an official identity.

Path params

Param	Type	Notes
id	string (numeric)	Official identity ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "official document removed",
  "data": {}
}

Errors

Status	When
401 Unauthorized	Bearer/cookie invalid
404 Not Found	Not found

---

Reference

Enum: DocumentType

• legal_agreement
• signature
• cause_report
• donation_certificate
• receipt
• image
• video

Enum: ProductType

• charitable_cause
• commodity_financing
• investment
• transaction

Enum: DocumentVisibility

• public
• private (default)

Enum: OfficialDocumentType

• passport
• national_id
• driving_license
• taxpayer_id

Standard error envelope

{
  "message": "Document not found",
  "statusCode": 404,
  "error": "Not Found"
}

message can be an array of strings for multi-field validation errors.

Common HTTP codes

• 400 body/param validation
• 401 invalid Bearer
• 403 permission mismatch
• 404 document not found
• 413 file > 50 MB (direct upload)
• 500 internal — show a generic toast

Upload notes

• Direct upload limit: 50 MB per file.
• The S3 file key in the url column is encrypted at rest. The public_url field in the response is already resolved.