Upload Income Receipt (v1)

Method & Path

POST /api/v1/client/workspace/:workspaceId/incomes/:incomeId/receipt

Description

Upload a receipt image for an income record. The image will be processed, optimized, and stored in cloud storage.

Authentication

Required: Workspace authentication. User must be authenticated as Workspace Owner or Staff with financial permissions.

Headers

Authorization: Bearer <workspace_token>
Content-Type: multipart/form-data

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier
incomeId	string	Yes	Income identifier

Request Body

The request must be sent as multipart/form-data with a file field named file.

Field	Type	Required	Description
file	file	Yes	Receipt image file (max size: 10MB). Supported formats: JPEG, PNG, WebP

Response 201 Created

{
  "url": "https://storage.googleapis.com/bucket/workspace-incomes/income-id/receipt-1234567890-abc123.webp",
  "path": "workspace-incomes/income-id/receipt-1234567890-abc123.webp",
  "width": 1000,
  "height": 1000,
  "sizeBytes": 50000,
  "contentType": "image/webp"
}

Response Fields

• url (string): Public URL to access the receipt image
• path (string): Server path to the receipt image
• width (number | null): Image width in pixels (if available)
• height (number | null): Image height in pixels (if available)
• sizeBytes (number | null): Image file size in bytes (if available)
• contentType (string): MIME type of the image (typically image/webp after processing)

Common Errors

400 Bad Request: Invalid income ID format, missing file, or file too large (>10MB)

401 Unauthorized: Missing or invalid authentication token

403 Forbidden: User does not have permission to upload receipts

404 Not Found: Income or workspace not found

413 Payload Too Large: File size exceeds 10MB limit

422 Unprocessable Entity: Invalid file format or corrupted image

500 Internal Server Error: Server error occurred while processing the request

Notes

• Images are automatically converted to WebP format for optimization
• Maximum file size is 10MB
• The receipt image is linked to the income record and can be updated by uploading a new image
• Workspace storage quota is checked before uploading