Upload Supplier Invoice Image (v1)

Method & Path

POST /api/v1/workspace/:workspaceId/suppliers/:supplierId/invoice-image

Actual backend path: POST /v1/workspace/:workspaceId/suppliers/:supplierId/invoice-image

Description

Upload a supplier invoice attachment (PNG, JPEG, or WebP). The image is processed (WebP, max dimension 2000px) and stored in workspace object storage. Returns a public HTTPS url to pass as imageUrl when creating or updating a supplier invoice.

Authentication

Required: Workspace JWT.

Persona access

• Workspace Owner: Allowed (suppliers section enabled for workspace).
• Staff: Allowed when suppliers access is granted via workspace menu/permissions; include X-Staff-Id when acting as staff if your client does so for other workspace uploads.
• Admin / Customer: Not applicable for this client workspace API.

Headers

Header	Required	Description
Authorization	Yes	Bearer <workspace_token>
Content-Type	Yes	multipart/form-data (set automatically by the client when using FormData)
X-Staff-Id	No	Staff identifier, if used by your integration

Path Parameters

Parameter	Type	Required	Description
workspaceId	string	Yes	Workspace identifier
supplierId	string	Yes	Supplier identifier (must exist)

Request Body

Multipart form with a single field:

Field	Type	Required	Description
file	file	Yes	Image file (PNG, JPEG, or WebP), max ~5 MiB after server validation (multer limit 10 MiB)

Response 201 Created

{
  "image": {
    "url": "https://storage.googleapis.com/bucket/supplier-financial/.../img-....webp",
    "path": "supplier-financial/.../img-....webp",
    "width": 1200,
    "height": 1600,
    "sizeBytes": 89012,
    "contentType": "image/webp"
  }
}

Common Errors

• 400 Bad Request: Missing file, empty file, or invalid supplier
• 401 Unauthorized: Missing or invalid token
• 403 Forbidden: Workspace access denied
• 404 Not Found: Workspace or supplier not found
• 422 Unprocessable Entity: Unsupported MIME type or file too large
• 500 Internal Server Error: Storage not configured or upload failure